BEA Tuxedo. Creating CORBA Server Applications

Transcription

1 BEA Tuxedo Creatig CORBA Server Applicatios BEA Tuxedo Release 8.0 Documet Editio 8.0 Jue 2001

2 Copyright Copyright 2001 BEA Systems, Ic. All Rights Reserved. Restricted Rights Leged This software ad documetatio is subject to ad made available oly pursuat to the terms of the BEA Systems Licese Agreemet ad may be used or copied oly i accordace with the terms of that agreemet. It is agaist the law to copy the software except as specifically allowed i the agreemet. This documet may ot, i whole or i part, be copied, photocopied, reproduced, traslated, or reduced to ay electroic medium or machie-readable form without prior coset, i writig, from BEA Systems, Ic. Use, duplicatio or disclosure by the U.S. Govermet is subject to restrictios set forth i the BEA Systems Licese Agreemet ad i subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clause at FAR ; subparagraph (c)(1)(ii) of the Rights i Techical Data ad Computer Software clause at DFARS , subparagraph (d) of the Commercial Computer Software--Licesig clause at NASA FAR supplemet ; or their equivalet. Iformatio i this documet is subject to chage without otice ad does ot represet a commitmet o the part of BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. Trademarks or Service Marks BEA, WebLogic, Tuxedo, ad Jolt are registered trademarks of BEA Systems, Ic. How Busiess Becomes E-Busiess, BEA WebLogic E-Busiess Platform, BEA Builder, BEA Maager, BEA elik, BEA Weblogic Commerce Server, BEA WebLogic Persoalizatio Server, BEA WebLogic Process Itegrator, BEA WebLogic Collaborate, BEA WebLogic Eterprise, ad BEA WebLogic Server are trademarks of BEA Systems, Ic. All other compay ames may be trademarks of the respective compaies with which they are associated. Creatig CORBA Server Applicatios Documet Editio Date Software Versio 8.0 Jue 2001 BEA Tuxedo 8.0

3 Cotets What You Need to Kow... xii e-docs Web Site... xii How to Prit the Documet... xiii Documetatio Covetios... xiv 1. CORBA Server Applicatio Cocepts The Etities You Create to Build a CORBA Server Applicatio The Implemetatio of the CORBA Objects for Your Server Applicatio1-2 How Iterface Defiitios Establish the Operatios o a CORBA Object How You Implemet the Operatios o a CORBA Object How Cliet Applicatios Access ad Maipulate Your Applicatio s CORBA Objects How You Istatiate a CORBA Object at Ru Time The Server Object Process for Developig CORBA Server Applicatios Geeratig Object Refereces How Cliet Applicatios Fid Your Server Applicatio s Factories 1-10 Creatig a Active Object Referece Maagig Object State About Object State Object Activatio Policies Applicatio-cotrolled Deactivatio Readig ad Writig a Object s Data Available Mechaisms for Readig ad Writig a Object s Durable State Readig State at Object Activatio Creatig CORBA Server Applicatios iii

4 Readig State Withi Idividual Operatios o a Object Stateless Objects ad Durable State Stateful Objects ad Durable State Your Resposibilities for Object Deactivatio Avoidig Uecessary I/O Sample Activatio Walkthrough Usig Desig Patters Process-Etity Desig Patter List-Eumerator Desig Patter Steps for Creatig a BEA Tuxedo CORBA Server Applicatio Summary of the CORBA Server Applicatio Developmet Process Step 1: Compile the OMG IDL File for the Server Applicatio Usig the IDL Compiler Geeratig the Skeleto ad Implemetatio Files Geeratig Tie Classes Step 2: Write the Methods That Implemet Each Iterface s Operatios The Implemetatio File Geerated by the IDL Compiler Implemetig a Factory Step 3: Create the Server Object Iitializig the Server Applicatio Writig the Code That Creates ad Registers a Factory Creatig Servats Releasig the Server Applicatio Step 4: Defie the I-memory Behavior of Objects Specifyig Object Activatio ad Trasactio Policies i the ICF File Step 5: Compile ad Lik the Server Applicatio Step 6: Deploy the Server Applicatio Developmet ad Debuggig Tips Use of CORBA Exceptios ad the User Log Cliet Applicatio View of Exceptios Server Applicatio View of Exceptios Detectig Error Coditios i the Callback Methods Commo Pitfalls of OMG IDL Iterface Versioig ad Modificatio Caveat for State Hadlig i Tobj_ServatBase::deactivate_object() iv Creatig CORBA Server Applicatios

5 Servat Poolig How Servat Poolig Works How You Implemet Servat Poolig Delegatio-based Iterface Implemetatio About Tie Classes i the BEA Tuxedo System Whe to Use Tie Classes How to Create Tie Classes i a CORBA Applicatio Desigig ad Implemetig a Basic CORBA Server Applicatio How the Basic Uiversity Sample Applicatio Works The Basic Uiversity Sample Applicatio OMG IDL Applicatio Startup Browsig Course Syopses Browsig Course Details Desig Cosideratios for the Uiversity Server Applicatio Desig Cosideratios for Geeratig Object Refereces Desig Cosideratios for Maagig Object State The RegistrarFactory Object The Registrar Object The CourseSyopsisEumerator Object Basic Uiversity Sample Applicatio ICF File Desig Cosideratios for Hadlig Durable State Iformatio The Registrar Object The CourseSyopsisEumerator Object Usig the Uiversity Database How the Basic Sample Applicatio Applies Desig Patters Process-Etity Desig Patter List-Eumerator Desig Patter Additioal Performace Efficiecies Built ito the BEA Tuxedo System Preactivatig a Object with State How You Preactivate a Object with State Usage Notes for Preactivated Objects Creatig CORBA Server Applicatios v

6 4. Creatig Multithreaded CORBA Server Applicatios Overview Itroductio Requiremets, Goals, ad Cocepts Threadig Models Reetrat Servats The Curret Object Mechaisms for Supportig Multithreaded CORBA Servers Cotext Services Classes ad Methods i the TP Framework Capabilities i the Build Commads Tools for Admiistratio Ruig Sigle-threaded Server Applicatios i a Multithreaded System Developig ad Buildig Multithreaded CORBA Server Applicatios Usig the buildobjserver Commad Platform-specific Thread Libraries Specifyig Multithreaded Support Specifyig a Alterate Server Class Usig the buildobjcliet Commad Creatig No-reetrat Servats Creatig Reetrat Servats Buildig ad Ruig the Multithreaded Simpapp Sample Applicatio About the Simpapp Multithreaded Sample How the Sample Applicatio Works OMG IDL Code for the Simpapp Multithreaded Sample Applicatio How to Build ad Ru the Sample Applicatio Settig the TUXDIR Eviromet Variable Verifyig the TUXDIR Eviromet Variable Chagig the Settig of the Eviromet Variable Creatig a Workig Directory for the Sample Applicatio Checkig Permissios o All the Files Executig the rume Commad Ruig the Sample Applicatio Step-by-Step vi Creatig CORBA Server Applicatios

7 Shuttig Dow the Sample Applicatio Multithreaded CORBA Server Applicatio Admiistratio Specifyig Thread Pool Size MAXDISPATCHTHREADS MINDISPATCHTHREADS Specifyig a Threadig Model Specifyig the Number of Active Objects Sample UBBCONFIG File Security ad CORBA Server Applicatios Overview of Security ad CORBA Server Applicatios Desig Cosideratios for the Uiversity Server Applicatio How the Security Uiversity Sample Applicatio Works Desig Cosideratios for Returig Studet Details to the Cliet Applicatio Itegratig Trasactios ito a CORBA Server Applicatio Overview of Trasactios i the BEA Tuxedo System Desigig ad Implemetig Trasactios i a CORBA Server Applicatio How the Trasactios Uiversity Sample Applicatio Works Trasactioal Model Used by the Trasactios Uiversity Sample Applicatio Object State Cosideratios for the Uiversity Server Applicatio Object Policies Defied for the Registrar Object Object Policies Defied for the RegistrarFactory Object Usig a XA Resource Maager i the Trasactios Sample Applicatio Cofiguratio Requiremets for the Trasactios Sample Applicatio Itegratig Trasactios i a CORBA Cliet ad Server Applicatio Makig a Object Automatically Trasactioal Eablig a Object to Participate i a Trasactio Prevetig a Object from Beig Ivoked While a Trasactio Is Scoped Excludig a Object from a Ogoig Trasactio Assigig Policies Opeig a XA Resource Maager Creatig CORBA Server Applicatios vii

8 Closig a XA Resource Maager Trasactios ad Object State Maagemet Delegatig Object State Maagemet to a XA Resource Maager Waitig Util Trasactio Work Is Complete Before Writig to the Database Notes o Usig Trasactios i the BEA Tuxedo System User-defied Exceptios Defiig the Exceptio Throwig the Exceptio Wrappig a BEA Tuxedo Service i a CORBA Object Overview of Wrappig a BEA Tuxedo Service Desigig the Object That Wraps the BEA Tuxedo Service Creatig the Buffer i Which to Ecapsulate BEA Tuxedo Service Calls 7-4 Implemetig the Operatios That Sed Messages to ad from the BEA Tuxedo Service Restrictios Desig Cosideratios for the Wrapper Sample Applicatio How the Wrapper Uiversity Sample Applicatio Works Iterface Defiitios for the Billig Server Applicatio Additioal Desig Cosideratios for the Wrapper Sample Applicatio Scalig a BEA Tuxedo CORBA Server Applicatio Overview of the Scalability Features Available i the BEA Tuxedo System Scalig a BEA Tuxedo Server Applicatio OMG IDL Chages for the Productio Sample Applicatio Replicatig Server Processes ad Server Groups Replicated Server Processes Replicated Server Groups Cofigurig Replicated Server Processes ad Groups Scalig the Applicatio Via Object State Maagemet Factory-based Routig How Factory-based Routig Works Cofigurig for Factory-based Routig i the UBBCONFIG file Implemetig Factory-based Routig i a Factory viii Creatig CORBA Server Applicatios

9 Idex What Happes at Ru Time Additioal Desig Cosideratios for the Registrar ad Teller Objects Istatiatig the Registrar ad Teller Objects Esurig That Studet Registratio Occurs i the Correct Server Group Esurig That the Teller Object Is Istatiated i the Correct Server Group How the Productio Server Applicatio Ca Be Scaled Further Choosig Betwee Stateless ad Stateful Objects Whe You Wat Stateless Objects Whe You Wat Stateful Objects Creatig CORBA Server Applicatios ix

10 x Creatig CORBA Server Applicatios

11 About This Documet This documet describes how programmers ca implemet key features i the BEA Tuxedo product to desig ad implemet scalable, high-performace, server applicatios that ru i a BEA Tuxedo domai. The examples i Chapter 3, Desigig ad Implemetig a Basic CORBA Server Applicatio, are based o the sample applicatios described i the Guide to the CORBA Uiversity Sample Applicatios. This documet icludes the followig topics: Chapter 1, CORBA Server Applicatio Cocepts, presets a umber of basic cocepts about creatig BEA Tuxedo server applicatios ad describes the two primary programmig etities you create for a BEA Tuxedo server applicatio. Chapter 2, Steps for Creatig a BEA Tuxedo CORBA Server Applicatio, lists ad describes the basic steps you follow to create a BEA Tuxedo server applicatio. Chapter 3, Desigig ad Implemetig a Basic CORBA Server Applicatio, explais the fudametal cocepts ad processes ivolved with desigig ad implemetig a CORBA server applicatio, based o the Basic Uiversity sample applicatio. Chapter 4, Creatig Multithreaded CORBA Server Applicatios, provides a overview of the requiremets, goals, ad cocepts for creatig multithreaded CORBA server applicatios. Additioally, this chapter outlies the steps for developig ad buildig a multithreaded CORBA server applicatio, describes how to build ad ru the simpapp_mt Sample Applicatio, ad how to admiister a multithreaded CORBA server applicatio. Chapter 5, Security ad CORBA Server Applicatios, explais the role of a CORBA server applicatio i implemetig a security model for a BEA Tuxedo domai. Creatig CORBA Server Applicatios xi

12 Chapter 6, Itegratig Trasactios ito a CORBA Server Applicatio, describes how the BEA Tuxedo system supports trasactios i a BEA Tuxedo domai ad how you ca implemet trasactios ito your server applicatios. Chapter 7, Wrappig a BEA Tuxedo Service i a CORBA Object, describes how to itegrate a BEA Tuxedo applicatio ito a CORBA server applicatio. Chapter 8, Scalig a BEA Tuxedo CORBA Server Applicatio, describes the key scalability features that you ca build ito your BEA Tuxedo applicatios to make them highly scalable, icludig replicated server processes ad groups, factory-based routig, ad object state maagemet. What You Need to Kow This documet is iteded for programmers who are iterested i creatig secure, scalable, trasactio-based server applicatios. It assumes your are kowledgeable with the BEA Tuxedo system, CORBA, ad C++ programmig. e-docs Web Site The BEA Tuxedo product documetatio is available o the BEA Systems, Ic. corporate Web site. From the BEA Home page, click the Product Documetatio butto or go directly to the e-docs Product Documetatio page at xii Creatig CORBA Server Applicatios

13 How to Prit the Documet How to Prit the Documet You ca prit a copy of this documet from a Web browser, oe file at a time, by usig the File >Prit optio o your Web browser. A PDF versio of this documet is available o the BEA Tuxedo documetatio Home page o the e-docs Web site (ad also o the documetatio CD). You ca ope the PDF i Adobe Acrobat Reader ad prit the etire documet (or a portio of it) i book format. To access the PDFs, ope the BEA Tuxedo documetatio Home page, click the PDF Files butto, ad select the documet you wat to prit. If you do ot have Adobe Acrobat Reader istalled, you ca dowload it for free from the Adobe Web site at Related Iformatio For more iformatio about CORBA, BEA Tuxedo, distributed object computig, trasactio processig, C++ programmig, ad Java programmig, see the CORBA Bibliography i the BEA Tuxedo olie documetatio. Cotact Us! Your feedback o the BEA Tuxedo documetatio is importat to us. Sed us at docsupport@bea.com if you have questios or commets. Your commets will be reviewed directly by the BEA professioals who create ad update the BEA Tuxedo documetatio. I your message, please idicate that you are usig the documetatio for the BEA Tuxedo 8.0 release. Creatig CORBA Server Applicatios xiii

14 If you have ay questios about this versio of BEA Tuxedo, or if you have problems istallig ad ruig BEA Tuxedo, cotact BEA Customer Support through BEA WebSUPPORT at You ca also cotact Customer Support by usig the cotact iformatio provided o the Customer Support Card, which is icluded i the product package. Whe cotactig Customer Support, be prepared to provide the followig iformatio: Your ame, address, phoe umber, ad fax umber Your compay ame ad compay address Your machie type ad authorizatio codes The ame ad versio of the product you are usig A descriptio of the problem ad the cotet of pertiet error messages Documetatio Covetios The followig documetatio covetios are used throughout this documet. Covetio boldface text Ctrl+Tab italics Item Idicates terms defied i the glossary. Idicates that you must press two or more keys simultaeously. Idicates emphasis or book titles. xiv Creatig CORBA Server Applicatios

15 Documetatio Covetios Covetio moospace text moospace boldface text moospace italic text UPPERCASE TEXT Item Idicates code samples, commads ad their optios, data structures ad their members, data types, directories, ad fileames ad their extesios. Moospace text also idicates text that you must eter from the keyboard. Examples: #iclude <iostream.h> void mai ( ) the poiter psz chmod u+w * \tux\data\ap.doc tux.doc BITMAP float Idetifies sigificat words i code. Example: void commit ( ) Idetifies variables i code. Example: Strig expr Idicates device ames, eviromet variables, ad logical operators. Examples: LPT1 SIGNON OR { } Idicates a set of choices i a sytax lie. The braces themselves should ever be typed. [ ] Idicates optioal items i a sytax lie. The brackets themselves should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list]... Separates mutually exclusive choices i a sytax lie. The symbol itself should ever be typed. Creatig CORBA Server Applicatios xv

16 Covetio Item... Idicates oe of the followig i a commad lie: That a argumet ca be repeated several times i a commad lie That the statemet omits additioal optioal argumets That you ca eter additioal parameters, values, or other iformatio The ellipsis itself should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list] Idicates the omissio of items from a code example or from a sytax lie. The vertical ellipsis itself should ever be typed. xvi Creatig CORBA Server Applicatios

17 CHAPTER 1 CORBA Server Applicatio Cocepts This topic icludes the followig sectios: The Etities You Create to Build a CORBA Server Applicatio: l The Implemetatio of the CORBA Objects for Your Server Applicatio l The Server Object Process for Developig CORBA Server Applicatios: l Geeratig Object Refereces l Maagig Object State l Readig ad Writig a Object s Data l Usig Desig Patters Each of the chapters i this book gives procedures for ad examples of buildig CORBA server applicatios that take advatage of various BEA Tuxedo software features. For backgroud iformatio about BEA Tuxedo CORBA server applicatios ad how they work, see Gettig Started with BEA Tuxedo CORBA Applicatios. Creatig CORBA Server Applicatios 1-1

18 1 CORBA Server Applicatio Cocepts The Etities You Create to Build a CORBA Server Applicatio To build a CORBA server applicatio, you create the followig two etities: The implemetatio of the CORBA objects that execute your server applicatio s busiess logic. The Server object, which implemets the operatios that iitialize ad release the server applicatio ad istatiate the CORBA objects eeded to satisfy cliet requests. There are also a umber of files that you work with that are geerated by the IDL compiler ad that you build ito a CORBA server applicatio. These files are listed ad described i Chapter 2, Steps for Creatig a BEA Tuxedo CORBA Server Applicatio. The sectios that follow provide itroductory iformatio about these etities. For complete details about how to geerate these compoets, see Chapter 2, Steps for Creatig a BEA Tuxedo CORBA Server Applicatio. The Implemetatio of the CORBA Objects for Your Server Applicatio Havig a clear uderstadig of what CORBA objects are, ad how they are defied, implemeted, istatiated, ad maaged is critical for the perso who is desigig or creatig a CORBA server applicatio. The CORBA objects for which you have defied iterfaces i the Object Maagemet Group Iterface Defiitio Laguage (OMG IDL) cotai the busiess logic ad data for your CORBA server applicatios. All cliet applicatio requests ivolve ivokig a operatio o a CORBA object. The code you write that implemets the operatios defied for a iterface is called a object implemetatio. For example, i C++, the object implemetatio is a C++ class. This topic icludes the followig sectios: 1-2 Creatig CORBA Server Applicatios

19 The Etities You Create to Build a CORBA Server Applicatio How OMG IDL iterface defiitios establish the operatios that ca be ivoked o a CORBA object How you implemet the operatios o a CORBA object How cliet applicatios access ad maipulate your applicatio s CORBA objects How you istatiate a CORBA object with code ad data at ru time i respose to a cliet request How Iterface Defiitios Establish the Operatios o a CORBA Object A CORBA object s iterface idetifies the operatios that ca be performed o it. A distiguishig characteristic of CORBA objects is that a object s iterface defiitio is separate from its implemetatio. The defiitio for the iterface establishes how the operatios o the iterface must be implemeted, icludig what the valid parameters are that ca be passed to ad retured from a operatio. A iterface defiitio, which is expressed i OMG IDL, establishes the cliet/server cotract for a applicatio. That is, for a give iterface, the server applicatio is boud to do the followig: Implemet the operatios defied for that iterface Always use the parameters defied with each operatio How the server applicatio implemets the operatios may chage over time. This is acceptable behavior as log as the server applicatio cotiues to meet the requiremet of implemetig the defied iterface ad usig the defied parameters. I this way, the cliet stub is always a reliable proxy for the object implemetatio o the server machie. This uderscores oe of the key architectural stregths of CORBA that you ca chage how a server applicatio implemets a object over time without requirig the cliet applicatio to be modified or eve to be aware that the object implemetatio has chaged. The iterface defiitio also determies the cotet of both the cliet stub ad the skeleto i the server applicatio; these two etities, i combiatio with the ORB ad the Portable Object Adapter (POA), esure that a cliet request for a operatio o a object ca be routed to the code i the server applicatio that ca satisfy the request. Creatig CORBA Server Applicatios 1-3

20 1 CORBA Server Applicatio Cocepts Oce the system desiger has specified the iterfaces of the busiess objects i the applicatio, the programmer s job is to implemet those iterfaces. This book explais how. For more iformatio about OMG IDL, see Creatig CORBA Cliet Applicatios. How You Implemet the Operatios o a CORBA Object As stated earlier, the code that implemets the operatios defied for a CORBA object s iterface is called a object implemetatio. For C++, this code cosists of a set of methods, oe for each of the operatios defied for the iterfaces i your applicatio s OMG IDL file. The file cotaiig the set of object implemetatios for your applicatio is kow as a implemetatio file. The BEA Tuxedo system provides a IDL compiler, which compiles your applicatio s OMG IDL file to produce several files, oe beig a implemetatio file, show i the followig figure. OMG IDL File IDL Compiler Implemetatio File The geerated implemetatio file cotais method templates, method declaratios, object costructors ad destructors, ad other data that you ca use as a startig place for writig your applicatio s object implemetatios. For example, i C++, the geerated implemetatio file cotais sigatures for each iterface s methods. You eter the busiess logic for each method i this file, ad the provide this file as iput to the commad that builds the executable server applicatio file. How Cliet Applicatios Access ad Maipulate Your Applicatio s CORBA Objects Cliet applicatios access ad maipulate the CORBA objects maaged by the server applicatio via object refereces to those objects. Cliet applicatios ivoke operatios (that is, requests) o a object referece. These requests are set as messages to the server applicatio, which ivokes the appropriate operatios o CORBA objects. The fact that these requests are set to the server applicatio ad ivoked i the server applicatio is completely trasparet to the cliet; cliet applicatios appear simply to be makig ivocatios o the cliet stub. 1-4 Creatig CORBA Server Applicatios

21 The Etities You Create to Build a CORBA Server Applicatio Cliet applicatios may maipulate a CORBA object oly by meas of a object referece. Oe primary desig cosideratio is how to create object refereces ad retur them to the cliet applicatios that eed them i a way that is appropriate for your applicatio. Typically, object refereces to CORBA objects are created i the BEA Tuxedo system by factories. A factory is ay CORBA object that returs, as oe of its operatios, a referece to aother CORBA object. You implemet your applicatio s factories the same way that you implemet other CORBA objects defied for your applicatio. You ca make your factories widely kow to the BEA Tuxedo domai, ad to cliets coected to the BEA Tuxedo domai, by registerig them with the FactoryFider. Registerig a factory is a operatio typically performed by the Server object, which is described i the sectio The Server Object o page 1-8. For more iformatio about desigig factories, see the sectio Geeratig Object Refereces o page 1-9. The Cotet of a Object Referece From the cliet applicatio s perspective, a object referece is opaque; it is like a black box that cliet applicatios use without havig to kow what is iside. However, object refereces cotai all the iformatio eeded for the BEA Tuxedo system to locate a specific object istace ad to locate ay state data that is associated with that object. A object referece cotais the followig iformatio: The iterface ame This is the Iterface Repository ID of the object s OMG IDL iterface. The object ID (OID) The OID uiquely idetifies the istace of the object to which the referece applies. If the object has data i exteral storage, the OID also typically icludes a key that the server machie ca use to locate the object s data. Group ID The group ID idetifies the server group to which the object referece is routed whe a cliet applicatio makes a request usig that object referece. Geeratig a odefault group ID is part of a key BEA Tuxedo feature called factory-based routig, which is described i the sectio Factory-based Routig o page Creatig CORBA Server Applicatios 1-5

22 1 CORBA Server Applicatio Cocepts Note: The combiatio of the three items i the precedig list uiquely idetifies the CORBA object. It is possible for a object with a give iterface ad OID to be simultaeously active i two differet groups, if those two groups both cotai the same object implemetatio. If you eed to guaratee that oly oe object istace of a give iterface ame ad OID is available at ay oe time i your domai, either: use factory-based routig to esure that objects with a particular OID are always routed to the same group, or cofigure your domai so that a give object implemetatio is i oly oe group. This assures that if multiple cliets have a object referece cotaiig a give iterface ame ad OID, the referece is always routed to the same object istace. The Lifetime of a Object Referece Passig Object Istaces For more iformatio about factory-based routig, see the sectio Factory-based Routig o page Object refereces created by server applicatios ruig i a BEA Tuxedo domai typically have a usable lifespa that exteds beyod the life of the server process that creates them. BEA Tuxedo object refereces ca be used by cliet applicatios regardless of whether the server processes that origially created them are still ruig. I this way, object refereces are ot tied to a specific server process. A object referece created with the TP::create_active_object_referece() operatio is valid oly for the lifetime of the server process i which it was created. For more iformatio, see the sectio Preactivatig a Object with State o page The ORB caot marshal a object istace as a object referece. For example, passig a factory referece i the followig code fragmet geerates a CORBA marshal exceptio i the BEA Tuxedo system: coectio::setfactory(this); To pass a object istace, you should create a proxy object referece ad pass the proxy istead, as i the followig example: CORBA::Object myref = TP::get_object_referece(); ResultSetFactory factoryref = ResultSetFactoryHelper::_arrow(myRef); coectio::setfactoryref(factoryref); 1-6 Creatig CORBA Server Applicatios

23 The Etities You Create to Build a CORBA Server Applicatio How You Istatiate a CORBA Object at Ru Time Whe a server applicatio receives a request for a object that is ot mapped i the server machie s memory (that is, the object is ot active), the TP Framework ivokes the Server::create_servat()operatio. The Server::create_servat()operatio is implemeted i the Server object, which, as metioed i the sectio The Implemetatio of the CORBA Objects for Your Server Applicatio o page 1-2, is a compoet of a CORBA server applicatio that you create. The Server::create_servat()operatio causes a istace of the CORBA object implemetatio to be mapped ito the server machie s memory. This istace of the object s implemetatio is called the object s servat. Formally speakig, a servat is a istace of the C++ class that implemets a iterface defied i the applicatio s OMG IDL file. The servat is geerated via the C++ ew statemet that you write i the Server::create_servat()operatio. After the object s servat has bee created, the TP Framework ivokes the Tobj_ServatBase::activate_object() operatio o the servat. The Tobj_ServatBase::activate_object() operatio is a virtual operatio that is defied o the Tobj_ServatBase base class, from which all object implemetatio classes iherit. The TP Framework ivokes the Tobj_ServatBase::activate_object() operatio to tie the servat to a object ID (OID). (Coversely, whe the TP Framework ivokes the Tobj_ServatBase::deactivate_object() operatio o a object, the servat s associatio with the OID is broke.) If your object has data o disk that you wat to read ito memory whe the CORBA object is activated, you ca have that data read by defiig ad implemetig the Tobj_ServatBase::activate_object() operatio o the object. The Tobj_ServatBase::activate_object() operatio ca cotai the specific read operatios required to brig a object s durable state ito memory. (There are circumstaces i which you may prefer istead to have a object s disk data read ito memory by oe or more separate operatios o the object that you may have coded i the implemetatio file. For more iformatio, see the sectio Readig ad Writig a Object s Data o page 1-16.) After the ivocatio of the Tobj_ServatBase::activate_object() operatio is complete, the object is said to be active. This collectio of the object s implemetatio ad data compose the ru-time, active istace of the CORBA object. Creatig CORBA Server Applicatios 1-7

24 1 CORBA Server Applicatio Cocepts Servat Poolig Servat poolig provides your CORBA server applicatio the opportuity to keep a servat i memory after the servat s associatio with a specific OID has bee broke. Whe a cliet request that ca be satisfied with a pooled servat arrives, the TP Framework bypasses the TP::create_servat operatio ad creates a lik betwee the pooled servat ad the OID provided i the cliet request. Servat poolig thus provides the CORBA server applicatio with a meas to miimize the costs of reistatiatig a servat each time a request arrives for a object that ca be satisfied by that servat. For more iformatio about servat poolig ad how to use it, see the sectio Servat Poolig o page Note: Servat poolig was first itroduced i release 4.2 of the WebLogic Eterprise product. The Server Object The Server object is the other programmig code etity that you create for a CORBA server applicatio. The Server object implemets operatios that execute the followig tasks: Performig basic server applicatio iitializatio operatios, which may iclude registerig factories maaged by the server applicatio ad allocatig resources eeded by the server applicatio. If the server applicatio is trasactioal, the Server object also implemets the code that opes a XA resource maager. Istatiatig the CORBA objects eeded to satisfy cliet requests. Performig server process shutdow ad cleaup procedures whe the server applicatio has fiished servicig requests. For example, if the server applicatio is trasactioal, the Server object also implemets the code that closes the XA resource maager. You create the Server object from scratch, usig a commo text editor. You the provide the Server object as iput ito the server applicatio build commad, buildobjserver. For more iformatio about creatig the Server object, see Chapter 2, Steps for Creatig a BEA Tuxedo CORBA Server Applicatio. 1-8 Creatig CORBA Server Applicatios

25 Process for Developig CORBA Server Applicatios Process for Developig CORBA Server Applicatios This sectio presets importat backgroud iformatio about the followig topics, which have a major ifluece o how you desig ad implemet CORBA server applicatios: Geeratig Object Refereces Maagig Object State Readig ad Writig a Object s Data Usig Desig Patters It is ot essetial that you read these topics before proceedig to the ext chapter; however, this iformatio is located here because it applies broadly to fudametal desig ad implemetatio issues for all CORBA server applicatios. Geeratig Object Refereces Oe of the most basic fuctios of a CORBA server applicatio is providig cliet applicatios with object refereces to the objects they eed to execute their busiess logic. CORBA cliet applicatios typically get object refereces to the iitial CORBA objects they use from the followig two sources: The Bootstrap object Factories maaged i the BEA Tuxedo domai Cliet applicatios use the Bootstrap object to resolve iitial refereces to a specific set of objects i the BEA Tuxedo domai, such as the FactoryFider ad the SecurityCurret objects. The Bootstrap object is described i Gettig Started with BEA Tuxedo CORBA Applicatios ad Creatig CORBA Cliet Applicatios. Factories, however, are desiged, implemeted ad registered by you, ad they provide the meas by which cliet applicatios get refereces to objects i the CORBA server applicatio, particularly the iitial server applicatio object. At its simplest, a Creatig CORBA Server Applicatios 1-9

26 1 CORBA Server Applicatio Cocepts factory is a CORBA object that returs a object referece to aother CORBA object. The cliet applicatio typically ivokes a operatio o a factory to obtai a object referece to a CORBA object of a specific type. Plaig ad implemetig your factories carefully is a importat task whe developig CORBA server applicatios. How Cliet Applicatios Fid Your Server Applicatio s Factories Cliet applicatios are able to locate via the FactoryFider the factories maaged by your server applicatio. Whe you develop the Server object, you typically iclude code that registers with the FactoryFider ay factories maaged by the server applicatio. It is via this registratio operatio that the FactoryFider keeps track of your server applicatio s factories ad ca provide object refereces to them to the cliet applicatios that request them. We recommed that you use factories ad register them with the FactoryFider; this model makes it simple for cliet applicatios to fid the objects i your CORBA server applicatio. Creatig a Active Object Referece A active object referece is a feature that gives a alterate meas through which your server applicatio ca geerate object refereces. Active object refereces are ot typically created by factories as described i the previous sectio, ad active object refereces are meat for preactivatig objects with state. The ext sectio discusses object state i more detail. While a object associated with a covetioal object referece is ot istatiated util a cliet applicatio makes a ivocatio o the object, the object associated with a active object referece is created ad activated at the time the active object referece is created. Active object refereces are especially coveiet for specific purposes, such as iterator objects. The sectio Preactivatig a Object with State o page 3-17 provides more iformatio about active object refereces. Note: The active object referece feature was first itroduced i WebLogic Eterprise versio Creatig CORBA Server Applicatios

27 Process for Developig CORBA Server Applicatios Maagig Object State Object state maagemet is a fudametally importat cocer of large-scale cliet/server systems, because it is critical that such systems optimize throughput ad respose time. The majority of high-throughput applicatios, such as applicatios you ru i a BEA Tuxedo domai, ted to be stateless, meaig that the system flushes state iformatio from memory after a service or a operatio has bee fulfilled. Maagig state is a itegral part of writig CORBA-based server applicatios. Typically, it is difficult to maage state i these server applicatios i a way that scales ad performs well. The BEA Tuxedo software provides a easy way to maage state ad simultaeously esure scalability ad high performace. The scalability qualities that you ca build ito a CORBA server applicatio help the server applicatio fuctio well i a eviromet that icludes hudreds or thousads of cliet applicatios, multiple machies, replicated server processes, ad a proportioately greater umber of objects ad cliet ivocatios o those objects. About Object State I a BEA Tuxedo domai, object state refers specifically to the process state of a object across cliet ivocatios o it. The BEA Tuxedo software uses the followig defiitios of stateless ad stateful objects: Object Stateless Behavior Characteristics The object is mapped ito memory oly for the duratio of a ivocatio o oe of the object s operatios, ad is deactivated ad has its process state flushed from memory after the ivocatio is complete; that is, the object s state is ot maitaied i memory after the ivocatio is complete. Creatig CORBA Server Applicatios 1-11

28 1 CORBA Server Applicatio Cocepts Object Stateful Behavior Characteristics The object remais activated betwee ivocatios o it, ad its state is maitaied i memory across those ivocatios. The state remais i memory util a specific evet occurs, such as: The server process i which the object exists is stopped or is shut dow The trasactio i which the object is participatig is either committed or rolled back The object ivokes the TP::deactivateEable() operatio o itself. Each of these evets is discussed i more detail i this sectio. Both stateless ad stateful objects have data; however, stateful objects may have opersistet data i memory that is required to maitai cotext (state) betwee operatio ivocatios o those objects. Thus, subsequet ivocatios o such a stateful object always go to the same servat. Coversely, ivocatios o a stateless object ca be directed by the BEA Tuxedo system to ay available server process that ca activate the object. State maagemet also ivolves how log a object remais active, which has importat implicatios o server performace ad the use of machie resources. The duratio of a active object is determied by object activatio policies that you assig to a object s iterface, described i the sectio that follows. Object state is trasparet to the cliet applicatio. Cliet applicatios implemet a coversatioal model of iteractio with distributed objects. As log as a cliet applicatio has a object referece, it assumes that the object is always available for additioal requests, ad the object appears to be maitaied cotiuously i memory for the duratio of the cliet applicatio iteractio with it. To achieve optimal applicatio performace, you eed to carefully pla how your applicatio s objects maage state. Objects are required to save their state to durable storage, if applicable, before they are deactivated. Objects must also restore their state from durable storage, if applicable, whe they are activated. For more iformatio about readig ad writig object state iformatio, see the sectio Readig ad Writig a Object s Data o page Creatig CORBA Server Applicatios

29 Process for Developig CORBA Server Applicatios Note: BEA Tuxedo Release 8.0 provides support for parallel objects, as a performace ehacemet. This feature allows you to desigate all busiess objects i a particular applicatio as stateless objects. For complete iformatio, see Chapter 3, TP Framework, i the CORBA Programmig Referece. Object Activatio Policies The BEA Tuxedo software provides three object activatio policies that you ca assig to a object s iterface to determie how log a object remais i memory after it has bee ivoked by a cliet request. These policies determie whether the object to which they apply is geerally stateless or stateful. The three policies are listed ad described i the followig table. Policy Method Trasactio Descriptio Causes the object to be active oly for the duratio of the ivocatio o oe of the object s operatios; that is, the object is activated at the begiig of the ivocatio, ad is deactivated at the ed of the ivocatio. A object with this activatio policy is called a method-boud object. The method activatio policy is associated with stateless objects. This activatio policy is the default. Causes the object to be activated whe a operatio is ivoked o it. If the object is activated withi the scope of a trasactio, the object remais active util the trasactio is either committed or rolled back. If the object is activated outside the scope of a trasactio, its behavior is the same as that of a method-boud object. A object with this activatio policy is called a trasactio-boud object. For more iformatio about object behavior withi the scope of a trasactio, ad geeral guidelies about usig this policy, see Chapter 6, Itegratig Trasactios ito a CORBA Server Applicatio. The trasactio activatio policy is associated with stateful objects for a limited time ad uder specific circumstaces. Creatig CORBA Server Applicatios 1-13

30 1 CORBA Server Applicatio Cocepts Policy Process Descriptio Causes the object to be activated whe a operatio is ivoked o it, ad to be deactivated oly uder the followig circumstaces: The server process that maages this object is shut dow. A operatio o this object ivokes the TP::deactivateEable() operatio, which causes this object to be deactivated. (This is part of a key BEA Tuxedo feature called applicatio-cotrolled deactivatio, which is described i the sectio Applicatio-cotrolled Deactivatio o page A object with this activatio policy is called a process-boud object. The process activatio policy is associated with stateful objects. You determie what evets cause a object to be deactivated by assigig object activatio policies. For more iformatio about how you assig object activatio policies to a object s iterface, see the sectio Step 4: Defie the I-memory Behavior of Objects o page Applicatio-cotrolled Deactivatio The BEA Tuxedo software also provides a feature called applicatio-cotrolled deactivatio, which provides a meas for a applicatio to deactivate a object durig ru time. The BEA Tuxedo software provides the TP::deactivateEable() operatio, which a process-boud object ca ivoke o itself. Whe ivoked, the TP::deactivateEable() operatio causes the object i which it exists to be deactivated upo completio of the curret cliet ivocatio o that object. A object ca ivoke this operatio oly o itself; you caot ivoke this operatio o ay object but the object i which the ivocatio is made. The applicatio-cotrolled deactivatio feature is particularly useful whe you wat a object to remai i memory for the duratio of a limited umber of cliet ivocatios o it, ad you wat the cliet applicatio to be able to tell the object that the cliet is fiished with the object. At this poit, the object takes itself out of memory Creatig CORBA Server Applicatios

31 Process for Developig CORBA Server Applicatios Applicatio-cotrolled deactivatio, therefore, allows a object to remai i memory i much the same way that a process-boud object ca: the object is activated as a result of a cliet ivocatio o it, ad it remais i memory after the iitial cliet ivocatio o it is completed. You ca the deactivate the object without havig to shut dow the server process i which the object exists. A alterative to applicatio-cotrolled deactivatio is to scope a trasactio to maitai a coversatio betwee a cliet applicatio ad a object; however, trasactios are iheretly more costly, ad trasactios are geerally iappropriate i situatios where the duratio of the trasactio may be idefiite. A good rule of thumb to use whe choosig betwee applicatio-cotrolled deactivatio ad trasactios for a coversatio is whether there are ay disk writig operatios ivolved. If the coversatio ivolves read-oly operatios, or ivolves maitaiig state oly i memory, the applicatio-cotrolled deactivatio is appropriate. If the coversatio ivolves writig data to disk durig or at the ed of the coversatio, trasactios may be more appropriate. Note: If you use applicatio-cotrolled deactivatio to implemet a coversatioal model betwee a cliet applicatio ad a object maaged by the server applicatio, make sure that the object evetually ivokes the TP::deactivateEable() operatio. Otherwise, the object remais idle i memory idefiitely. (Note that this ca be a risk if the cliet applicatio crashes before the TP::deactivateEable() operatio is ivoked. Trasactios, o the other had, implemet a timeout mechaism to prevet the situatio i which the object remais idle for a idefiite period. This may be aother cosideratio whe choosig betwee the two coversatioal models.) You implemet applicatio-cotrolled deactivatio i a object usig the followig procedure: 1. I the implemetatio file, isert a ivocatio to the TP::deactivateEable() operatio at the appropriate locatio withi the operatio of the iterface that uses applicatio-cotrolled deactivatio. 2. I the Implemetatio Cofiguratio File (ICF file), assig the process activatio policy to the iterface that cotais the operatio that ivokes the TP::deactivateEable() operatio. 3. Build ad deploy your applicatio as described i the sectios Step 5: Compile ad Lik the Server Applicatio o page 2-17 ad Step 6: Deploy the Server Applicatio o page Creatig CORBA Server Applicatios 1-15

32 1 CORBA Server Applicatio Cocepts Readig ad Writig a Object s Data May of the CORBA objects maaged by the server applicatio may have data that is i exteral storage. This exterally stored data may be regarded as the persistet or durable state of the object. You must address durable state hadlig at appropriate poits i the object implemetatio for object state maagemet to work correctly. Because of the wide variety of requiremets you may have for your cliet/server applicatio with regards to readig ad writig a object s durable state, the TP Framework caot automatically hadle durable object state o disk. I geeral, if a object s durable state is modified as a result of oe or more cliet ivocatios, you must make sure that durable state is saved before the object is deactivated, ad you should pla carefully how the object s data is stored or iitialized while the object is active. The sectios that follow describe the mechaisms available to you to hadle a object s durable state, ad give some geeral advice how to read ad write object state uder specific circumstaces. The specific topics preseted iclude: The available mechaisms for readig ad writig a object s durable state Readig state at object activatio Readig state withi idividual operatios o a object Stateless objects ad durable state Stateful objects ad durable state Your resposibilities for object deactivatio Avoidig uecessary I/O How you choose to read ad write durable state ivariably depeds o the specific requiremets of your cliet/server applicatio, especially with regard to how the data is structured. I geeral, your priority should be to miimize the umber of disk operatios, especially where a database cotrolled by a XA resource maager is ivolved. Available Mechaisms for Readig ad Writig a Object s Durable State Table 1-1 ad Table 1-2 describe the available mechaisms for readig ad writig a object s durable state Creatig CORBA Server Applicatios

33 Process for Developig CORBA Server Applicatios Table 1-1 Available Mechaisms for Readig a Object s Durable State Mechaism Tobj_ServatBase:: activate_object() Operatios o the object Descriptio After the TP Framework creates the servat for a object, the TP Framework ivokes the Tobj_ServatBase::activate_object() operatio o that servat. As metioed i the sectio How You Istatiate a CORBA Object at Ru Time o page 1-6, this operatio is defied o the Tobj_ServatBase base class, from which all the CORBA objects you defie for your cliet/server applicatio iherit. You may choose ot to defie ad implemet the Tobj_ServatBase::activate_object() operatio o your object, i which case othig happes regardig specific object state hadlig whe the TP Framework activates your object. However, if you defie ad implemet this operatio, you ca choose to iclude code i this operatio that reads some or all of a object s durable state ito memory. Therefore, the Tobj_ServatBase::activate_object() operatio provides your server applicatio with its first opportuity to read a object s durable state ito memory. Note that if a object s OID cotais a database key, the Tobj_ServatBase::activate_object() operatio provides the oly meas the object has to extract that key from the OID. For more iformatio about implemetig the Tobj_ServatBase::activate_object() operatio, see Step 2: Write the Methods That Implemet Each Iterface s Operatios o page 2-6. For a example of implemetig the Tobj_ServatBase::activate_object() operatio, see Chapter 3, Desigig ad Implemetig a Basic CORBA Server Applicatio. You ca iclude iside the idividual operatios that you defie o the object the code that reads a object s durable state. Creatig CORBA Server Applicatios 1-17

34 1 CORBA Server Applicatio Cocepts Table 1-2 Available Mechaisms for Writig a Object s Durable State Mechaism Tobj_ServatBase:: deactivate_object() Operatios o the object Descriptio Whe a object is beig deactivated by the TP Framework, the TP Framework ivokes this operatio o the object as the fial step of object deactivatio. As with the Tobj_ServatBase::activate_object() operatio, the Tobj_ServatBase::deactivate_object() operatio is defied o the Tobj_ServatBase class. You implemet the deactivate_object() operatio o your object optioally if you have specific object state that you wat flushed from memory or writte to a database. The Tobj_ServatBase::deactivate_object() operatio provides the fial opportuity your server applicatio has to write durable state to disk before the object is deactivated. If your object keeps ay data i memory, or allocates memory for ay purpose, you implemet the Tobj_ServatBase::deactivate_object() operatio so your object has a fial opportuity to flush that data from memory. Flushig ay state from memory before a object is deactivated is critical i avoidig memory leaks. As you may have idividual operatios o the objects that read durable state from disk, you may also have idividual operatios o the object that write durable state back to disk. For method-boud ad process-boud objects i geeral, you typically perform database write operatios withi these operatios ad ot i the Tobj_ServatBase::deactivate_object() operatio. For trasactio-boud objects, however, writig durable state i the Tobj_ServatBase::deactivate_object() operatio provides a umber of object maagemet efficiecies that may make sese for your trasactioal server applicatios Creatig CORBA Server Applicatios

35 Process for Developig CORBA Server Applicatios Note: If you use the Tobj_ServatBase::deactivate_object() operatio to write ay durable state to disk, ay errors that occur while writig to disk are ot reported to the cliet applicatio. Therefore, the oly circumstaces uder which you should write data to disk i this operatio is whe: the object is trasactio-boud (that is, it has the trasactio activatio policy assiged to it), or you scope the disk write operatios withi a trasactio by ivokig the TrasactioCurret object. Ay errors ecoutered while writig to disk durig a trasactio ca be reported back to the cliet applicatio. For more iformatio about usig the Tobj_ServatBase::deactivate_object() operatio to write object state to disk, see the sectio Caveat for State Hadlig i Tobj_ServatBase::deactivate_object() o page Readig State at Object Activatio Usig the Tobj_ServatBase::activate_object() operatio o a object to read durable state may be appropriate whe either of the followig coditios exist: Object data is always used or updated i all the object s operatios. All the object s data is capable of beig read i oe operatio. The advatages of usig the Tobj_ServatBase::activate_object() operatio to read durable state iclude: You write code to read data oly oce, istead of duplicatig the code i each of the operatios that use that data. Noe of the operatios that use a object s data eed to perform ay readig of that data. I this sese, you ca write the operatios i a way that is idepedet of state iitializatio. Readig State Withi Idividual Operatios o a Object With all objects, regardless of activatio policy, you ca read durable state i each operatio that eeds that data. That is, you hadle the readig of durable state outside the Tobj_ServatBase::activate_object()operatio. Cases where this approach may be appropriate iclude the followig: Object state is made up of discrete data elemets that require multiple operatios to read or write. Objects do ot always use or update state data at object activatio. Creatig CORBA Server Applicatios 1-19

36 1 CORBA Server Applicatio Cocepts For example, cosider a object that represets a customer s ivestmet portfolio. The object cotais several discrete records for each ivestmet. If a give operatio affects oly oe ivestmet i the portfolio, it may be more efficiet to allow that operatio to read the oe record tha to have a geeral-purpose Tobj_ServatBase::activate_object() operatio that automatically reads i the etire ivestmet portfolio each time the object is ivoked. Stateless Objects ad Durable State I the case of stateless objects that is, objects defied with the method activatio policy you must esure the followig: That ay durable state eeded by the request is brought ito memory by the time the operatio s busiess logic starts executig. That ay chages to the durable state are writte out by the ed of the ivocatio. The TP Framework ivokes the Tobj_ServatBase::activate_object() operatio o a object at activatio. If a object has a OID that cotais a key to the object s durable state o disk, the Tobj_ServatBase::activate_object() operatio provides the oly opportuity the object has to retrieve that key from the OID. If you have a stateless object that you wat to be able to participate i a trasactio, we geerally recommed that if the object writes ay durable state to disk that it be doe withi idividual methods o the object. However, if you have a stateless object that is always trasactioal that is, a trasactio is always scoped whe this object is ivoked you have the optio to hadle the database write operatios i the Tobj_ServatBase::deactivate_object() operatio, because you have a reliable mechaism i the XA resource maager to commit or roll back database write operatios accurately. Note: Eve if your object is method-boud, you may have to take ito accout the possibility that two server processes are accessig the same disk data at the same time. I this case, you may wat to cosider a cocurrecy maagemet techique, the easiest of which is trasactios. For more iformatio about trasactios ad trasactioal objects, see Chapter 6, Itegratig Trasactios ito a CORBA Server Applicatio Creatig CORBA Server Applicatios

37 Process for Developig CORBA Server Applicatios Servat Poolig ad Stateless Objects Servat poolig is a particularly useful feature for stateless objects. Whe your CORBA server applicatio pools servats, you ca sigificatly reduce the costs of istatiatig a object each time a cliet ivokes it. As metioed i the sectio Servat Poolig o page 1-8, a pooled servat remais i memory after a cliet ivocatio o it is complete. If you have a applicatio i which a give object is likely to be ivoked repeatedly, poolig the servat meas that oly the object s data, ad ot its methods, eeds to be read ito ad out of memory for each cliet ivocatio. If the cost associated with readig a object s methods ito memory is high, servat poolig ca reduce that cost. For iformatio about how to implemet servat poolig, see the sectio Servat Poolig o page Stateful Objects ad Durable State For stateful objects, you should read ad write durable state oly at the poit where it is eeded. This may itroduce the followig optimizatios: I the case of process-boud objects, you avoid the situatio i which a object allocates a large amout of memory over a log period. I the case of trasactio-boud objects, you ca postpoe writig durable state util the Tobj_ServatBase::deactivate_object() operatio is ivoked, whe the trasactio outcome is kow. I geeral, trasactio-boud objects must deped o the XA resource maager to hadle all database write or rollback operatios automatically. Note: For objects that are ivolved i a trasactio, we do ot support havig those objects write data to exteral storage that is ot maaged by a XA resource maager. For more iformatio about objects ad trasactios, see Chapter 6, Itegratig Trasactios ito a CORBA Server Applicatio. Servat Poolig ad Stateful Objects Servat poolig does ot make sese i the case of process-boud objects; however, depedig o your applicatio desig, servat poolig may provide a performace improvemet for trasactio-boud objects. Creatig CORBA Server Applicatios 1-21

38 1 CORBA Server Applicatio Cocepts Your Resposibilities for Object Deactivatio Avoidig Uecessary I/O As metioed i the precedig sectios, you implemet the Tobj_ServatBase::deactivate_object() operatio as a meas to write a object s durable state to disk. You should also implemet this operatio o a object as a meas to flush ay remaiig object data from memory so that the object s servat ca be used to activate aother istace of that object. You should ot assume that a ivocatio to a object s Tobj_ServatBase::deactivate_object() operatio also results i a ivocatio of that object s destructor. Be careful ot to itroduce iefficiecies ito the applicatio by doig uecessary I/O i objects. Situatios to be aware of iclude the followig: If may operatios i a object do ot use or affect object state, it may be iefficiet to read ad write state each time these operatios are ivoked. Desig these objects so that they hadle state oly i the operatios that eed it; i such cases, you may ot wat to have all of the object s durable state read i at object activatio. If object state is made up of data that is read i multiple operatios, try to do oly the ecessary operatios at object activatio by doig oe of the followig: l l Readig oly the state that is commo to all the operatios i the Tobj_ServatBase::activate_object() operatio. Defer the readig of additioal state to oly the operatios that require it. Writig out oly the state that has chaged. You ca do this by maagig flags that idicate the data that was chaged durig a activatio, or by comparig before ad after data images. A geeral optimizatio is to iitialize a dirtystate flag o activatio ad to write data i the Tobj_ServatBase::deactivate_object() operatio oly if the flag has bee chaged while the object was active. (Note that this works oly if you ca be assured that the object is always activated i the same server process.) Sample Activatio Walkthrough For examples of the sequece of activity that takes place whe a object is activated, see Gettig Started with BEA Tuxedo CORBA Applicatios Creatig CORBA Server Applicatios

39 Process for Developig CORBA Server Applicatios Usig Desig Patters It is importat to structure the busiess logic of your applicatio aroud a well-formed desig. The BEA Tuxedo software provides a set of desig patters to address this eed. A desig patter is simply a structured solutio to a specific desig problem. The value of a desig patter lies i its ability to be expressed i a form you ca reuse ad apply to other desig problems. The BEA Tuxedo desig patters are structured solutios to eterprise-class applicatio desig problems. You ca use them to desig successful large-scale cliet/server applicatios. The desig patters summarized here are a guide to usig good desig practices i CORBA cliet ad server applicatios. They are a importat ad itegral part of desigig CORBA cliet ad server applicatios, ad the chapters i this book show examples of usig these desig patters to implemet the Uiversity sample applicatios. Process-Etity Desig Patter The Process-Etity desig patter applies to a large segmet of eterprise-class cliet/server applicatios. This desig patter is referred to as the flyweight patter i Object-Orieted Desig Patters, Gamma et al., ad as the Model-View-Cotroller i other publicatios. I this patter, the cliet applicatio creates a log-lived process object that the cliet applicatio iteracts with to make requests. For example, i the Uiversity sample applicatios, this object might be the registrar that hadles course browsig operatios o behalf of the cliet applicatio. The courses themselves are database etities ad are ot made visible to the cliet applicatio. The advatages of the Process-Etity desig patter iclude: You ca achieve the advatages of a fie-graied object model without implemetig fie-graied objects. Istead, you use CORBA struct datatypes to simulate objects. Machie resource usage is optimized because there is oly a sigle object mapped ito memory: the process object. By cotrast, if each database etity were activated ito memory as a separate object istace, the umber of objects Creatig CORBA Server Applicatios 1-23

40 1 CORBA Server Applicatio Cocepts that would eed to be hadled could overwhelm the machie s resources quickly i a large-scale deploymet. Because they are ot exposed to the cliet applicatio, database etities eed ot be implemeted as CORBA objects. Istead, etities ca be implemeted as local laguage objects i the server process. This is a fudametal priciple of three-tier desigs, but it also accurately models the way i which may busiesses operate (for example, a registrar at a real uiversity). The idividual who serves as the registrar at a uiversity ca hadle a large course database for multiple studets; you do ot eed a idividual registrar for each idividual studet. Thus, the process object state is distict from the etity object state. A example of applyig the Process-Etity desig patter is described i Chapter 3, Desigig ad Implemetig a Basic CORBA Server Applicatio. For complete details o the Process-Etity desig patter, see Techical Articles. List-Eumerator Desig Patter The List-Eumerator desig patter also applies to a large segmet of eterprise-class cliet/server applicatios. The List-Eumerator desig patter leverages a key BEA Tuxedo feature, applicatio-cotrolled object deactivatio, to hadle a cache of data that is stored ad tracked i memory durig several cliet ivocatios, ad the to flush the data from memory whe the data is o loger eeded. A example of applyig the List-Eumerator desig patter is described i Chapter 3, Desigig ad Implemetig a Basic CORBA Server Applicatio. Object preactivatio, which is a especially useful tool for implemetig the List-Eumerator desig, is described i the sectio Preactivatig a Object with State o page Creatig CORBA Server Applicatios

41 CHAPTER 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio This chapter describes the basic steps ivolved i creatig a CORBA server applicatio. The steps show i this chapter are ot defiitive; there may be other steps you may eed to take for your particular server applicatio, ad you may wat to chage the order i which you follow some of these steps. However, the developmet process for every CORBA server applicatio has each of these steps i commo. This topic icludes the followig sectios: Summary of the CORBA Server Applicatio Developmet Process Developmet ad Debuggig Tips Servat Poolig Delegatio-based Iterface Implemetatio This chapter begis with a summary of the steps, ad also lists the developmet tools ad commads used throughout this book. Your particular deploymet eviromet might use additioal software developmet tools, so the tools ad commads listed ad described i this chapter are also ot defiitive. The chapter uses examples from the Basic Uiversity sample applicatio, which is provided with the BEA Tuxedo software. For complete details about the Basic Uiversity sample applicatio, see the Guide to the CORBA Uiversity Sample Applicatios. For complete iformatio about the tools ad commads used throughout this book, see the CORBA Programmig Referece. Creatig CORBA Server Applicatios 2-1

42 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio For iformatio about creatig multithreaded CORBA server applicatios, see Chapter 4, Creatig Multithreaded CORBA Server Applicatios. Summary of the CORBA Server Applicatio Developmet Process The basic steps to create a server applicatio are: Step 1: Compile the OMG IDL File for the Server Applicatio Step 2: Write the Methods That Implemet Each Iterface s Operatios Step 3: Create the Server Object Step 4: Defie the I-memory Behavior of Objects Step 5: Compile ad Lik the Server Applicatio Step 6: Deploy the Server Applicatio The BEA Tuxedo software also provides the followig developmet tools ad commads: Tool IDL compiler geicf buildobjserver tmloadcf tmadmi Descriptio Compiles your applicatio s OMG IDL file. Geerates a Implemetatio Cofiguratio File (ICF file), which you ca revise to specify odefault object activatio ad trasactio policies. Creates the executable image of your CORBA server applicatio. Creates the TUXCONFIG file, a biary file for the CORBA domai that specifies the cofiguratio of your server applicatio. Amog other thigs, creates a log of trasactioal activities, which is used i some of the sample applicatios. 2-2 Creatig CORBA Server Applicatios

43 Step 1: Compile the OMG IDL File for the Server Applicatio Step 1: Compile the OMG IDL File for the Server Applicatio The basic structure of the cliet ad server portios of the applicatio that rus i the BEA Tuxedo domai are determied by statemets i the applicatio s OMG IDL file. Whe you compile your applicatio s OMG IDL file, the IDL compiler geerates some or all of the files show i the followig diagram, depedig upo which optios you specify i the idl commad. The shaded compoets are the geerated files that you modify to create a server applicatio. Cliet Stub File Cliet Stub Header File IDL Compiler Skeleto File Skeleto Header File Implemetatio File Implemetatio Header File Creatig CORBA Server Applicatios 2-3

44 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio The files produced by the IDL compiler are described i Table. Table 2-1 Files Produced by the IDL Compiler File Default Name Descriptio Cliet stub file applicatio_c.cpp Cotais geerated code for sedig a request. Cliet stub header file applicatio_c.h Cotais class defiitios for each iterface ad type specified i the OMG IDL file. Skeleto file applicatio_s.cpp Cotais skeletos for each iterface specified i the OMG IDL file. The skeleto maps cliet requests to the appropriate operatio i the server applicatio durig ru time. Skeleto header file applicatio_s.h Cotais the skeleto class defiitios. Implemetatio file applicatio_i.cpp Cotais sigatures for the methods that implemet the operatios o the iterfaces specified i the OMG IDL file. Implemetatio header file applicatio_i.h Cotais the iitial class defiitios for each iterface specified i the OMG IDL file. Usig the IDL Compiler To geerate the files listed i Table 2-1, eter the followig commad: idl [optios] idl-fileame [icf-fileame] I the idl commad sytax: optios represets oe or more commad-lie optios to the IDL compiler. The commad-lie optios are described i the CORBA Programmig Referece. If you wat to geerate implemetatio files, you eed to specify the -i optio. idl-fileame represets the ame of your applicatio s OMG IDL file. icf-fileame is a optioal parameter that represets the ame of your applicatio s Implemetatio Cofiguratio File (ICF file), which you use to specify object activatio policies or to limit the umber of iterfaces for which you wat skeleto ad implemetatio files geerated. Usig the ICF file is described i the sectio Step 4: Defie the I-memory Behavior of Objects o page Creatig CORBA Server Applicatios

45 Step 1: Compile the OMG IDL File for the Server Applicatio Note: The C++ IDL compiler implemetatio of pragmas chaged i WebLogic Eterprise 5.1 to support CORBA 2.3 fuctioality ad may affect your IDL files. The CORBA 2.3 fuctioality chages the scope that the pragma prefix defiitios ca affect. Pragmas do ot affect defiitios cotaied withi icluded IDL files, or do pragma prefix defiitios made withi icluded IDL files affect objects outside the icluded file. The C++ IDL compiler has bee modified to correct the hadlig of pragma prefixes. This chage ca effect the repository ID of objects, resultig i failures for some operatios, such as a _arrow. To prevet such failures: If you reload your IDL ito the repository, you must also regeerate the cliet stubs ad server skeletos of the applicatio. If you regeerate ay cliet stub or server skeleto, you must regeerate all stubs ad skeletos of the applicatio, ad you must reload the IDL ito the Iterface Repository. For more iformatio about the IDL compiler, icludig details o the idl commad, see the CORBA Programmig Referece. Geeratig the Skeleto ad Implemetatio Files The followig commad lie geerates cliet stub, skeleto, ad iitial implemetatio files, alog with skeleto ad implemetatio header files, for the OMG IDL file uivb.idl: idl -i uivb.idl For more iformatio about the idl commad, see the CORBA Programmig Referece. For more iformatio about geeratig these files for the BEA Tuxedo Uiversity sample applicatios, see the Guide to the CORBA Uiversity Sample Applicatios. Note: If you pla to specify odefault object activatio or trasactio policies, or if you pla to limit the umber of iterfaces for which you wat skeleto ad implemetatio files geerated, you eed to geerate ad modify a Creatig CORBA Server Applicatios 2-5

46 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio Implemetatio Cofiguratio File (ICF) ad pass the ICF file to the IDL compiler. For more iformatio, see Specifyig Object Activatio ad Trasactio Policies i the ICF File o page Geeratig Tie Classes The IDL compiler also provides the -T commad-lie optio, which you ca use for geeratig tie class templates for your iterfaces. For more iformatio about implemetig tie classes i a CORBA applicatio, see the sectio Delegatio-based Iterface Implemetatio o page Step 2: Write the Methods That Implemet Each Iterface s Operatios As the server applicatio programmer, your task is to write the methods that implemet the operatios for each iterface you have defied i your applicatio s OMG IDL file. The implemetatio file cotais: Method declaratios for each operatio specified i the OMG IDL file. Your applicatio s busiess logic, iclude files, ad other data you wat the applicatio to use. Costructors ad destructors for each iterface implemetatio (implemetig these is optioal). Optioally, the Tobj_ServatBase::activate_object() ad Tobj_ServatBase::deactivate_object() operatios. Withi the Tobj_ServatBase::activate_object() ad Tobj_ServatBase::deactivate_object()operatios, you write code that performs ay particular steps related to activatig or deactivatig a object. This icludes readig ad writig the object s durable state from ad to disk, respectively. If you implemet these operatios i your object, you must also 2-6 Creatig CORBA Server Applicatios

47 Step 2: Write the Methods That Implemet Each Iterface s Operatios edit the implemetatio header file ad add the defiitios for these operatios i each implemetatio that uses them. The Implemetatio File Geerated by the IDL Compiler Although you ca create your server applicatio s implemetatio file etirely by had, the IDL compiler geerates a implemetatio file that you ca use as a startig place for writig your implemetatio file. The implemetatio file geerated by the IDL compiler cotais sigatures for the methods that implemet each of the operatios defied for your applicatio s iterfaces. You typically geerate this implemetatio file oly oce, usig the -i optio with the commad that ivokes the IDL compiler. As you iteratively refie your applicatio s iterfaces, ad modify the operatios for those iterfaces, icludig operatio sigatures, you add all the required chages to the implemetatio file to reflect those chages. Implemetig a Factory As metioed i the sectio How Cliet Applicatios Access ad Maipulate Your Applicatio s CORBA Objects o page 1-4, you eed to create factories so that cliet applicatios ca easily locate the objects maaged by your server applicatio. A factory is like ay other CORBA object that you implemet, with the exceptio that you register it with the FactoryFider object. Registerig a factory is described i the sectio Writig the Code That Creates ad Registers a Factory o page The primary fuctio of a factory is to create object refereces, which it does by ivokig the TP::create_object_referece() operatio. The TP::create_object_referece() operatio requires the followig iput parameters: The Iterface Repository ID of the object s OMG IDL iterface The object ID (OID) i strig format Optioally, routig criteria For example, i the Basic Uiversity sample applicatio, the RegistrarFactory iterface specifies oly oe operatio, as follows: Creatig CORBA Server Applicatios 2-7

48 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio Uiversity::Registrar_ptr RegistrarFactory_i::fid_registrar() The fid_registrar() operatio o the RegistrarFactory object cotais the followig ivocatio to the TP::create_object_referece() operatio to create a referece to a Registrar object: CORBA::Object_var v_reg_oref = TP::create_object_referece( Uiversity::_tc_Registrar->id(), object_id, CORBA::NVlist::_il() ); I the previous code example, otice the followig: The followig parameter specifies the Registrar object s Iterface Repository ID by extractig it from its typecode: Uiversity::_tc_Registrar->id() The followig parameter specifies that o routig criteria are used, with the result that a object referece created for the Registrar object is routed to the same group as the RegistrarFactory object that created the object referece: CORBA::NVlist::_il() For iformatio about specifyig routig criteria that affect the group to which object refereces are routed, see Chapter 8, Scalig a BEA Tuxedo CORBA Server Applicatio. Step 3: Create the Server Object Implemetig the Server object is ot like implemetig other laguage objects. The header class for the Server object has already bee created, ad the Server object class has already bee istatiated for you. Creatig the Server object ivolves implemetig a specific set of methods i the prepackaged Server object class. The methods you implemet are described i this sectio. To create the Server object, create a ew file usig a commo text editor ad implemet the followig operatios: 2-8 Creatig CORBA Server Applicatios

49 Step 3: Create the Server Object Operatio Server::iitialize(); Server::create_servat(); Server::release(); Descriptio After the server applicatio is booted, the TP Framework ivokes this operatio as the last step i the server applicatio iitializatio process. Withi this operatio, you perform a umber of iitializatio tasks eeded for your particular server applicatio. What you provide withi this operatio is described i the sectio Iitializig the Server Applicatio o page 2-9. Whe a cliet request arrives that caot be serviced by a existig servat, the TP Framework ivokes this operatio, passig the Iterface Repository ID of the OMG IDL iterface for the CORBA object to be activated. What you provide withi this operatio is described i the sectio Creatig Servats o page The TP Framework ivokes this operatio whe the server applicatio is beig shut dow. This operatio icludes code to uregister ay object factories maaged by the server applicatio ad to perform other shutdow tasks. What you provide withi this operatio is described i the sectio Releasig the Server Applicatio o page There is oly oe istace of the Server object i ay server applicatio. If your server applicatio is maagig multiple CORBA object implemetatios, the Server::iitialize(), Server::create_servat(), ad Server::release() operatios you write must iclude code that applies to all those implemetatios. The code that you write for most of these tasks ivolves iteractio with the TP Framework. The sectios that follow explai the code required for each of these Server object operatios ad shows sample code from the Basic Uiversity sample applicatio. Iitializig the Server Applicatio The first operatio that you implemet i your Server object is the operatio that iitializes the server applicatio. This operatio is ivoked whe the BEA Tuxedo system starts the server applicatio. The TP Framework ivokes the followig operatio i the Server object durig the startup sequece of the server applicatio: CORBA::Boolea Server::iitialize(it argc, char** argv) Creatig CORBA Server Applicatios 2-9

50 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio Ay commad-lie optios specified i the CLOPT parameter for your specific server applicatio i the SERVERS sectio of the BEA Tuxedo domai s UBBCONFIG file are passed to the Server::iitialize() operatio as argc ad argv. For more iformatio about passig argumets to the server applicatio, see Admiisterig a BEA Tuxedo Applicatio at Ru Time. For examples of passig argumets to the server applicatio, see the Guide to the CORBA Uiversity Sample Applicatios. Withi the Server::iitialize() operatio, you iclude code that does the followig, if applicable: Creates ad registers factories Allocates ay machie resources Iitializes ay global variables eeded by the server applicatio Opes the databases used by the server applicatio Opes the XA resource maager Writig the Code That Creates ad Registers a Factory If your server applicatio maages a factory that you wat cliet applicatios to be able to locate easily, you eed to write the code that registers that factory with the FactoryFider object, which is ivoked typically as the fial step of the server applicatio iitializatio process. To write the code that registers a factory maaged by your server applicatio, you do the followig: 1. Create a object referece to the factory. This step ivolves creatig a object referece as described i the sectio Implemetig a Factory o page 2-7. I this step, you iclude a ivocatio to the TP::create_object_referece() operatio, specifyig the Iterface Repository ID of the factory s OMG IDL iterface.the followig example creates a object referece, represeted by the variable s_v_fact_ref, to the RegistrarFactory factory: Uiversity::RegistrarFactory s_v_fact_ref = TP::create_object_referece( Uiversity::_tc_RegistrarFactory->id(), object_id, 2-10 Creatig CORBA Server Applicatios

51 Step 3: Create the Server Object ); CORBA::NVList::_il() 2. Register the factory with the BEA Tuxedo domai. This step ivolves ivokig the followig operatio for each of the factories maaged by the server applicatio: TP::register_factory (CORBA::Object_ptr factory_or, cost char* factory_id); The TP::register_factory() operatio registers the server applicatio s factories with the FactoryFider object. This operatio requires the followig iput parameters: l l The object referece for the factory, created i step 1 above. A strig idetifier, based o the factory object s iterface typecode, used to idetify the Iterface Repository ID of the factory s OMG IDL iterface. The followig example registers the RegistrarFactory factory with the BEA Tuxedo domai: TP::register_factory(s_v_fact_ref.i(), Uiversity::_tc_RegistrarFactory->id()); Notice the parameter Uiversity::_tc_RegistrarFactory->id(). This is the same parameter specified i the TP::create_object_referece() operatio. This parameter extracts the Iterface Repository ID of the object s OMG IDL iterface from its typecode. Creatig Servats After the server applicatio iitializatio process is complete, the server applicatio is ready to begi processig cliet requests. If a request arrives for a operatio o a CORBA object for which there is o servat available i memory, the TP Framework ivokes the followig operatio i the Server object: Tobj_Servat Server::create_servat(cost char* iterfacename) The Server::create_servat() operatio cotais code that istatiates a servat for the object required by the cliet request. For example, i C++, this code icludes a ew statemet o the iterface class for the object. Creatig CORBA Server Applicatios 2-11

52 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio The Server::create_servat() operatio does ot associate the servat with a OID. The associatio of a servat with a OID takes place whe the TP Framework ivokes the Tobj_ServatBase::activate_object() operatio o the servat, which completes the istatiatio of the object. (You caot associate a OID with a object i the object s costructor.) Likewise, the disassociatio of a servat with a OID takes place whe the TP Framework ivokes the deactivate_object() operatio o the servat. This behavior of a servat i the BEA Tuxedo system makes it possible, after a object has bee deactivated, for the TP Framework to make a servat available for aother object istatiatio. Therefore, do ot assume that a ivocatio of a object s Tobj_ServatBase::deactivate_object() operatio results i a ivocatio of that object s destructor. If you use the servat poolig feature i your server applicatio, you ca implemet the TP::applicatio_resposibility() operatio i a object s Tobj_ServatBase::deactivate_object() operatio to pass a poiter to the servat to a servat pool for later reuse. Servat poolig is discussed i the sectio Servat Poolig o page The Server::create_servat() operatio requires a sigle iput argumet. The argumet specifies a character strig cotaiig the Iterface Repository ID of the OMG IDL iterface of the object for which you are creatig a servat. I the code you write for this operatio, you specify the Iterface Repository IDs of the OMG IDL iterfaces for the objects maaged by your server applicatio. Durig ru time, the Server::create_servat()operatio returs the servat eeded for the object specified by the request. The followig code implemets the Server::create_servat() operatio i the Uiversity server applicatio from the Basic Uiversity sample applicatio: Tobj_Servat Server::create_servat(cost char* itf_repos_id) { if (!strcmp(itf_repos_id, Uiversity::_tc_RegistrarFactory->id())) { retur ew RegistrarFactory_i(); } if (!strcmp(itf_repos_id, Uiversity::_tc_Registrar->id())) { retur ew Registrar_i(); } if (!strcmp(itf_repos_id, Uiversity::_tc_CourseSyopsisEumerator->id())) { retur ew CourseSyopsisEumerator_i(); } retur 0; // ukow iterface } 2-12 Creatig CORBA Server Applicatios

53 Step 3: Create the Server Object Releasig the Server Applicatio Whe the BEA Tuxedo system admiistrator eters the tmshutdow commad, the TP Framework ivokes the followig operatio i the Server object of each ruig server applicatio i the BEA Tuxedo domai: void Server::release() Withi the Server::release() operatio, you may perform ay applicatio-specific cleaup tasks that are specific to the server applicatio, such as: Uregisterig object factories maaged by the server applicatio Deallocatig resources Closig ay databases Closig a XA resource maager Oce a server applicatio receives a request to shut dow, the server applicatio ca o loger receive requests from other remote objects. This has implicatios o the order i which server applicatios should be shut dow, which is a admiistrative task. For example, do ot shut dow oe server process if a secod server process cotais a ivocatio i its Server::release() operatio to the first server process. Durig server shutdow, you may wat to iclude the followig ivocatio to uregister each of the server applicatio s factories: TP::uregister_factory (CORBA::Object_ptr factory_or, cost char* factory_id) The ivocatio of the TP::uregister_factory() operatio should be oe of the first actios i the Server::release() implemetatio. The TP::uregister_factory() operatio uregisters the server applicatio s factories. This operatio requires the followig iput argumets: The object referece for the factory. A strig idetifier, based o the factory object s iterface typecode, used to idetify Iterface Repository ID of the object s OMG IDL iterface. The followig example uregisters the RegistrarFactory factory used i the Basic sample applicatio: TP::uregister_factory(s_v_fact_ref.i(), UivB::_tc_RegistrarFactory->id()); Creatig CORBA Server Applicatios 2-13

54 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio I the precedig code example, otice the use of the global variable s_v_fact_ref. This variable was set i the Server::iitialize() operatio that registered the RegistrarFactory object, which is used agai here. Notice also the parameter UivB::_tc_RegistrarFactory->id(). This is also the same as the iterface ame used to register the factory. Step 4: Defie the I-memory Behavior of Objects As stated i the sectio Maagig Object State o page 1-11, you determie what evets cause a object to be deactivated by assigig object activatio policies, trasactio policies, ad, optioally, usig the applicatio-cotrolled deactivatio feature. You specify object activatio ad trasactio policies i the ICF file, ad you implemet applicatio-cotrolled deactivatio via the TP::deactivateEable() operatio. This sectio explais how you implemet both mechaisms, usig the Basic Uiversity sample applicatio as a example. The sectios that follow describe the followig: How to specify object activatio ad trasactio policies i the ICF file How to implemet applicatio-cotrolled deactivatio Specifyig Object Activatio ad Trasactio Policies i the ICF File The BEA Tuxedo software supports the followig activatio policies, described i Object Activatio Policies o page 1-13: 2-14 Creatig CORBA Server Applicatios

55 Step 4: Defie the I-memory Behavior of Objects Activatio Policy method trasactio process Descriptio Causes the object to be active oly for the duratio of the ivocatio o oe of the object s operatios. Causes the object to be activated whe a operatio is ivoked o it. If the object is activated withi the scope of a trasactio, the object remais active util the trasactio is either committed or rolled back. Causes the object to be activated whe a operatio is ivoked o it, ad to be deactivated oly whe oe of the followig occurs: The process i which the server applicatio exists is shut dow. The object has ivoked the TP::deactivateEable() operatio o itself. The BEA Tuxedo software also supports the followig trasactio policies, described i Chapter 6, Itegratig Trasactios ito a CORBA Server Applicatio : Trasactio Policy always optioal ever Descriptio Whe a operatio o this object is ivoked, this policy causes the TP Framework to begi a trasactio for this object, if there is ot already a active trasactio. If the TP Framework starts the trasactio, the TP Framework commits the trasactio if the operatio completes successfully, or rolls back the trasactio if the operatio raises a exceptio. Whe a operatio o this object is ivoked, this policy causes the TP Framework to iclude this object i a trasactio if a trasactio is active. If o trasactio is active, the ivocatio o this object proceeds accordig to the activatio policy defied for this object. This is the default trasactio policy. Causes the TP Framework to geerate a error coditio if this object is ivoked durig a trasactio. Creatig CORBA Server Applicatios 2-15

56 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio Trasactio Policy igore Descriptio If a trasactio is curretly active whe a operatio o this object is ivoked, the trasactio is suspeded util the operatio ivocatio is complete. This trasactio policy prevets ay trasactio from beig propagated to the object to which this trasactio policy has bee assiged. To assig these policies to the objects i your applicatio: 1. Geerate the ICF file by eterig the geicf commad, specifyig your applicatio s OMG IDL file as iput, as i the followig example: # geicf uiversity.idl The precedig commad geerates the file uiversity.icf. 2. Edit the ICF file ad specify the activatio policies for each of your applicatio s iterfaces. The followig example shows the ICF file geerated for the Basic Uiversity sample applicatio. Notice that the default object activatio policy is method, ad that the default trasactio activatio policy is optioal. module POA_UiversityB { implemetatio CourseSyopsisEumerator_i { activatio_policy ( method ); trasactio_policy ( optioal ); implemets ( UiversityB::CourseSyopsisEumerator ); }; }; module POA_UiversityB { implemetatio Registrar_i { activatio_policy ( method ); trasactio_policy ( optioal ); implemets ( UiversityB::Registrar ); }; }; module POA_UiversityB { implemetatio RegistrarFactory_i { activatio_policy ( method ); trasactio_policy ( optioal ); 2-16 Creatig CORBA Server Applicatios

57 Step 5: Compile ad Lik the Server Applicatio }; implemets ( UiversityB::RegistrarFactory ); }; 3. If you wat to limit the umber of iterfaces for which you wat skeleto ad implemetatio files geerated, you ca remove from the ICF file the implemetatio blocks that implemet those iterfaces. Usig the precedig ICF code as a example, to prevet skeleto ad implemetatio files from beig geerated for the RegistrarFactory iterface, remove the followig lies: implemetatio RegistrarFactory_i { activatio_policy ( method ); trasactio_policy ( optioal ); implemets ( UiversityB::RegistrarFactory ); }; 4. Pass the ICF file to the IDL compiler to geerate the skeleto ad implemetatio files that correspod to the specified policies. For more iformatio, see the sectio Geeratig the Skeleto ad Implemetatio Files o page 2-5. Step 5: Compile ad Lik the Server Applicatio After you have fiished writig the code for the Server object ad the object implemetatios, you compile ad lik the server applicatio. You use the buildobjserver commad to compile ad lik CORBA server applicatios. The buildobjserver commad has the followig format: buildobjserver [-o serverame] [optios] I the buildobjserver commad sytax: -o serverame represets the ame of the server applicatio to be geerated by this commad. optios represets the commad-lie optios to the buildobjserver commad. Creatig CORBA Server Applicatios 2-17

58 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio For complete iformatio about compilig ad likig the Uiversity sample applicatios, see the Guide to the CORBA Uiversity Sample Applicatios. For complete details about the buildobjserver commad, see the BEA Tuxedo Commad Referece. There are special cosideratios for desigig ad buildig multithreaded CORBA server applicatios. See Usig the buildobjserver Commad o page Note: If you are ruig the BEA Tuxedo software o IBM AIX systems, you eed to recompile your CORBA applicatios usig the -brtl compiler optio. Step 6: Deploy the Server Applicatio You or the system admiistrator deploy the CORBA server applicatio by usig the procedure summarized i this sectio. For complete details o buildig ad deployig the Uiversity sample applicatios, see the Guide to the CORBA Uiversity Sample Applicatios. To deploy the server applicatio: 1. Place the server applicatio executable file i a appropriate directory o a machie that is part of the iteded BEA Tuxedo domai. 2. Create the applicatio s cofiguratio file, also kow as the UBBCONFIG file, i a commo text editor. 3. Set the followig eviromet variables o the machie from which you are bootig the CORBA server applicatio: l l TUXCONFIG, which eeds to match exactly the TUXCONFIG etry i the UBBCONFIG file. This variable represets the locatio or path of the applicatio s UBBCONFIG file. APPDIR, which represets the directory i which the applicatio s executable file exists Creatig CORBA Server Applicatios

59 Developmet ad Debuggig Tips 4. Set the TUXDIR eviromet variable o all machies that are ruig i the BEA Tuxedo domai or that are coected to the BEA Tuxedo domai. This eviromet variable poits to the locatio where the BEA Tuxedo software is istalled. 5. Eter the followig commad to create the TUXCONFIG file: tmloadcf -y applicatio-ubbcofig-file The commad-lie argumet applicatio-ubbcofig-file represets the ame of your applicatio s UBBCONFIG file. Note that you may eed to remove ay old TUXCONFIG files to execute this commad. 6. Eter the followig commad to start the CORBA server applicatio: tmboot -y You ca reboot a server applicatio without reloadig the UBBCONFIG file. For complete details about cofigurig the Uiversity sample applicatios, see the Guide to the CORBA Uiversity Sample Applicatios. For complete details o creatig the UBBCONFIG file for CORBA applicatios, see Settig Up a BEA Tuxedo Applicatio. Developmet ad Debuggig Tips This topic icludes the followig sectios: Use of CORBA exceptios ad the user log Detectig error coditios i the callback methods Commo pitfalls of OMG IDL iterface versioig ad modificatio Caveat for state hadlig i the Tobj_ServatBase::deactivate_object() operatio Use of CORBA Exceptios ad the User Log This topic icludes the followig sectios: Creatig CORBA Server Applicatios 2-19

60 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio The cliet applicatio view of exceptios The server applicatio view of exceptios Cliet Applicatio View of Exceptios Whe a cliet applicatio ivokes a operatio o a CORBA object, a exceptio may be retured as a result of the ivocatio. The oly valid exceptios that ca be retured to a cliet applicatio are the followig: Stadard CORBA-defied exceptios that are kow to every CORBA-compliat ORB Exceptios that are defied i OMG IDL ad kow to the cliet applicatio via either its stub or the Iterface Repository The BEA Tuxedo system works to esure that these CORBA-defied restrictios are ot violated, which is described i the sectio Server Applicatio View of Exceptios o page Because the set of exceptios exposed to the cliet applicatio is limited, cliet applicatios may occasioally catch exceptios for which the cause is ambiguous. Wheever possible, the BEA Tuxedo system supplemets such exceptios with descriptive messages i the user log, which serves as a aid i detectig ad debuggig error coditios. These cases are described i the followig sectio. Server Applicatio View of Exceptios This topic icludes the followig sectios: Exceptios raised by the BEA Tuxedo system that ca be caught by applicatio code The BEA Tuxedo system s hadlig of exceptios raised by applicatio code durig the ivocatio of operatios o CORBA objects Exceptios Raised by the BEA Tuxedo System That Ca Be Caught by Applicatio Code The BEA Tuxedo system may retur the followig types of exceptios to a applicatio whe operatios o the TP object are ivoked: CORBA-defied system exceptios 2-20 Creatig CORBA Server Applicatios

61 Developmet ad Debuggig Tips CORBA UserExceptios defied i the file TobjS_c.h. The OMG IDL for the exceptios defied i this file is the followig: iterface TobjS { exceptio AlreadyRegistered { }; exceptio ActivateObjectFailed { strig reaso; }; exceptio ApplicatioProblem { }; exceptio CaotProceed { }; exceptio CreateServatFailed { strig reaso; }; exceptio DeactivateObjectFailed { strig reaso; }; exceptio IllegalIterface { }; exceptio IllegalOperatio { }; exceptio IitializeFailed { strig reaso; }; exceptio IvalidDomai { }; exceptio IvalidIterface { }; exceptio IvalidName { }; exceptio IvalidObject { }; exceptio IvalidObjectId { }; exceptio IvalidServat { }; exceptio NilObject { strig reaso; }; exceptio NoSuchElemet { }; exceptio NotFoud { }; exceptio OrbProblem { }; exceptio OutOfMemory { }; exceptio OverFlow { }; exceptio RegistrarNotAvailable { }; exceptio ReleaseFailed { strig reaso; }; exceptio TpfProblem { }; exceptio UkowIterface { }; } The BEA Tuxedo System s Hadlig of Exceptios Raised by Applicatio Code Durig the Ivocatio of Operatios o CORBA Objects A server applicatio ca raise exceptios i the followig places i the course of servicig a cliet ivocatio: I the Server::create_servat, Tobj_ServatBase::activate_object(), ad Tobj_ServatBase::deactivate_object() callback methods. I the implemetatio code for the ivoked operatio. It is possible for the server applicatio to raise ay of the followig types of exceptios: A CORBA-defied system exceptio. Creatig CORBA Server Applicatios 2-21

62 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio A CORBA user-defied exceptio defied i OMG IDL A CORBA user-defied exceptio defied i the file TobjS_c.h. The followig exceptios are iteded to be used i server applicatios to help the BEA Tuxedo system sed messages to the user log, which ca help with troubleshootig: iterface TobjS { exceptio ActivateObjectFailed { strig reaso; }; exceptio CreateServatFailed { strig reaso; }; exceptio DeactivateObjectFailed { strig reaso; }; exceptio IitializeFailed { strig reaso; }; exceptio ReleaseFailed { strig reaso; }; } Ay other C++ exceptio type All exceptios raised by server applicatio code that are ot caught by the server applicatio are caught by the BEA Tuxedo system. Whe these exceptios are caught, oe of the followig occurs: The exceptio is retured to the cliet applicatio without alteratio. The exceptio is coverted to a stadard CORBA exceptio, which is the retured to the cliet applicatio. The exceptio is coverted to a stadard CORBA exceptio, ad the followig actios occur: l l The exceptio is retured to the cliet applicatio Oe or more messages cotaiig descriptive iformatio about the error are set to the user log. The descriptive iformatio may origiate from either the server applicatio code or from the BEA Tuxedo system. The followig sectios show how the BEA Tuxedo system hadles exceptios raised by the server applicatio durig the course of a cliet ivocatio o a CORBA object. Exceptios Raised i the Server::create_servat() Operatio If ay exceptio is raised i the Server::create_servat() operatio, the: The CORBA::OBJECT_NOT_EXIST exceptio is retured to the cliet applicatio. If the exceptio raised is TobjS::CreateServatFailed, the a message is set to the user log. If a reaso strig is supplied i the costructor for the exceptio, the the reaso strig is also writte as part of the message Creatig CORBA Server Applicatios

63 Developmet ad Debuggig Tips Neither the Tobj_ServatBase::activate_object() or Tobj_ServatBase::deactivate_object() operatios are ivoked. The operatio requested by the cliet is ot ivoked. Exceptios Raised i the Tobj_ServatBase::activate_object() Operatio If ay exceptio is raised i the Tobj_ServatBase::activate_object() operatio, the: The CORBA::OBJECT_NOT_EXIST exceptio is retured to the cliet applicatio. If the exceptio raised is TobjS::ActivateObjectFailed, a message is set to the user log. If a reaso strig is supplied i the costructor for the exceptio, the reaso strig is also writte as part of the message. Neither the operatio requested by the cliet or the Tobj_ServatBase::deactivate_object() operatio is ivoked. Exceptios Raised i Operatio Implemetatios The BEA Tuxedo system requires operatio implemetatios to throw either CORBA system exceptios, or user-defied exceptios defied i OMG IDL that are kow to the cliet applicatio. If these types of exceptios are throw by operatio implemetatios, the the BEA Tuxedo system returs them to the cliet applicatio, uless oe of the followig coditios exists: The object has the always trasactio policy, ad the BEA Tuxedo system automatically started a trasactio whe the object was ivoked. I this case, the trasactio is automatically rolled back by the BEA Tuxedo system. Because the cliet applicatio is uaware of the trasactio, the BEA Tuxedo system the raises the CORBA::OBJ_ADAPTER CORBA system exceptio, ad ot the CORBA:: TRANSACTION_ROLLEDBACK exceptio, which would have bee the case had the cliet iitiated the trasactio. The exceptio is defied i the file TobjS_c.h. I this case, the exceptio is coverted to the CORBA::BAD_OPERATION exceptio ad is retured to the cliet applicatio. I additio, the followig message is set to the user log: "WARN: Applicatio did t catch TobjS exceptio. TP Framework throwig CORBA::BAD_OPERATION." If the exceptio is TobjS::IllegalOperatio, the followig supplemetary message is writte to war the developer of a possible codig error i the applicatio: Creatig CORBA Server Applicatios 2-23

64 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio "WARN: Applicatio called TP::deactivateEable() illegally ad did t catch TobjS exceptio." This ca occur if the TP::deactivateEable() operatio is ivoked iside a object that has the trasactio activatio policy. (Applicatio-cotrolled deactivatio is ot supported for trasactio-boud objects.) The BEA Tuxedo system raised a iteral system exceptio followig the cliet ivocatio. I this case, the CORBA::INTERNAL exceptio is retured to the cliet. This usually idicates serious system problems with the process i which the object is active. As defied by the CORBA stadard, a reply set back to the cliet ca either cotai result values from the operatio implemetatio, or a exceptio throw i the operatio implemetatio, but ot both. I the first case that is, if the reply status value is NO_EXCEPTION the reply cotais the operatio s retur value ad ay iout or out argumet values. Otherwise that is, if the reply status value is USER_EXCEPTION or SYSTEM_EXCEPTION all the reply cotais is the ecodig of the exceptio. Exceptios Raised i the Tobj_ServatBase::deactivate_object() Operatio If ay exceptio is raised i the Tobj_ServatBase::deactivate_object() operatio, the followig occurs: The exceptio is ot retured to the cliet applicatio. If the exceptio raised is TobjS::DectivateObjectFailed, a message is set to the user log. If a reaso strig is supplied i the costructor for the exceptio, the reaso strig is also writte as part of the message. A message is set to the user log for exceptios other tha the TobjS::DeactivateObjectFailed exceptio, idicatig the type of exceptio caught by the BEA Tuxedo system. CORBA Marshal Exceptio Raised Whe Passig Object Istaces The ORB caot marshal a object istace as a object referece. For example, passig a factory referece i the followig code fragmet geerates a CORBA marshal exceptio i the BEA Tuxedo system: coectio::setfactory(this); 2-24 Creatig CORBA Server Applicatios

65 Developmet ad Debuggig Tips To pass a object istace, you should create a proxy object referece ad pass the proxy istead, as i the followig example: CORBA::Object myref = TP::get_object_referece(); ResultSetFactory factoryref = ResultSetFactoryHelper::_arrow(myRef); coectio::setfactoryref(factoryref); Detectig Error Coditios i the Callback Methods The BEA Tuxedo system provides a set of predefied exceptios that allow you to specify message strigs that the TP Framework writes to the user log if applicatio code gets a error i ay of the followig callback methods: Tobj_ServatBase::activate_object() Tobj_ServatBase::deactivate_object() Server::create_servat() Server::iitialize() Server::release() You ca use these exceptios as a useful debuggig aid that allows you to sed uambiguous iformatio about why a exceptio is beig raised. Note that the TP Framework writes these messages to the user log oly. They are ot retured to the cliet applicatio. You specify these messages with the followig exceptios, which have a optioal reaso strig: Exceptio ActivateObjectFailed DeactivateObjectFailed CreateServatFailed IitializeFailed ReleaseFailed Callback Methods That Ca Raise This Exceptio Tobj_ServatBase::activate_object() Tobj_ServatBase::deactivate_object() Server::create_servat() Server::iitialize() Server::release() Creatig CORBA Server Applicatios 2-25

66 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio To sed a message strig to the user log, specify the strig i the exceptio, as i the followig example: throw CreateServatFailed("Ukow iterface"); Note that whe you throw these exceptios, the reaso strig parameter is required. If you do ot wat to specify a strig with oe of these exceptios, you must use the double quote characters, as i the followig example: throw ActivateObjectFailed(""); Commo Pitfalls of OMG IDL Iterface Versioig ad Modificatio The Server object s implemetatio of the Server::create_servat() operatio istatiates a object based o its iterface ID. It is crucial that this iterface ID is the same as the oe supplied i the factory whe the factory ivokes the TP::create_object_referece() operatio. If the iterface IDs do ot match, the Server::create_servat() operatio usually raises a exceptio or returs a NULL servat. The BEA Tuxedo system the returs a CORBA::OBJECT_NOT_EXIST exceptio to the cliet applicatio. The BEA Tuxedo system does ot perform ay validatio of iterface IDs i the TP::create_object_referece() operatio. It is possible for this coditio to arise if, durig the course of developmet, differet versios of the iterface are beig developed or may modificatios are beig made to IDL file. Eve if you typically specify strig costats for iterface IDs i OMG IDL ad use these i the factory ad the Server::create_servat() operatio, it is possible for a mismatch to occur if the object implemetatio ad factory are i differet executables. This potetial problem may be difficult to diagose. You may wat to cosider the followig defesive programmig strategies durig developmet to avoid this potetial problem. This code should be icluded oly i debuggig versios of your applicatio, because it itroduces performace iefficiecies that may be uacceptable i the productio versios of your software. Immediately before factory ivokes the TP::create_object_referece() operatio, iclude code that checks the Iterface Repository to see if the required iterface exists. Make sure that all the applicatio OMG IDL is up-to-date ad loaded ito the Iterface Repository. Should this check fail to fid the iterface ID, you ca assume that there is a mismatch Creatig CORBA Server Applicatios

67 Developmet ad Debuggig Tips Followig the ivocatio of the TP::create_object_referece() operatio i your factories, iclude code that pigs the object. That is, the code ivokes ay operatio o the object (typically a operatio that does ot do aythig). If this ivocatio raises the CORBA::OBJECT_NOT_EXIST exceptio, a iterface ID mismatch exists. Note that pigig a object causes the object to be activated, with the overhead associated with the activatio. Caveat for State Hadlig i Tobj_ServatBase::deactivate_object() The Tobj_ServatBase::deactivate_object() operatio is ivoked whe the activatio boudary for a object is reached. You may, optioally, write durable state to disk i the implemetatio of this operatio. It is importat to uderstad that exceptios raised i this operatio are ot retured to the cliet applicatio. The cliet applicatio will be uaware of ay error coditios raised i this operatio uless the object is participatig i a trasactio. Therefore, i cases where it is importat that the cliet applicatio kow whether the writig of state via this operatio is successful, we recommed that trasactios be used. If you decide to use the Tobj_ServatBase::deactivate_object() operatio for writig state, ad the cliet applicatio eeds to kow the outcome of the write operatios, we recommed that you do the followig: Esure that each operatio that affects object state is ivoked withi a trasactio, ad that deactivatio occurs withi the trasactio boudaries. This ca be doe by usig either the method or trasactio activatio policies, ad is possible with the process activatio policy if the TP::deactivateEable() operatio is ivoked withi the trasactio boudary. If a error occurs durig the writig of object state, ivoke the COSTrasactios::Curret::rollback_oly() operatio to esure that the trasactio is rolled back. This esures that the cliet applicatio receives oe of the followig exceptios: l l If the cliet applicatio iitiated the trasactio, the cliet applicatio receives the CORBA::TRANSACTION_ROLLEDBACK exceptio. If the BEA Tuxedo system iitiated the trasactio, the cliet applicatio receives the CORBA::OBJ_ADAPTER exceptio. Creatig CORBA Server Applicatios 2-27

68 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio If trasactios are ot used, we recommed that you write object state withi the scope of idividual operatios o the object, rather tha via the Tobj_ServatBase::deactivate_object() operatio. This way, if a error occurs, the operatio ca raise a exceptio that is retured to the cliet applicatio. Servat Poolig As metioed i the sectio Servat Poolig ad Stateless Objects o page 1-21, servat poolig provides a meas to reduce the cost of object istatiatio for method-boud or trasactio-boud objects. How Servat Poolig Works Normally, durig object deactivatio (that is, whe the TP Framework ivokes the Tobj_ServatBase::deactivate_object() operatio), the TP Framework deletes the object s servat; however, whe servat poolig is used, the TP Framework does ot delete the servat at object deactivatio. Istead, the server applicatio maitais a poiter to the servat i a pool. Whe a subsequet cliet request arrives that ca be satisfied by a servat i that pool, the server applicatio reuses the servat ad assigs a ew object ID. Whe a servat is reused from a pool, the TP Framework does ot create a ew servat. How You Implemet Servat Poolig You implemet servat poolig by doig the followig: 1. I the Server::iitialize() operatio o the Server object, write the code that sets up the servat pool. The pool cosists of a set of poiters to oe or more servats, ad the code for the pool specifies how may servats for a give class are to be maitaied i the pool. 2. I the pooled servat s Tobj_ServatBase::deactive_object() operatio, you implemet the TP::applicatio_resposibility() operatio. I the implemetatio of the TP::applicatio_resposibility() operatio, you 2-28 Creatig CORBA Server Applicatios

69 Delegatio-based Iterface Implemetatio provide code that places a poiter to the servat ito the servat pool at the time that the TP Framework ivokes the Tobj_ServatBase::deactivate_object() operatio. 3. I the Server object s implemetatio of the Server::create_servat() operatio, write code that does the followig whe a cliet request arrives: a. Checks the pool to see if there is a servat that ca satisfy the request. b. If a servat does ot exist, create a servat ad ivoke the Tobj_ServatBase::activate_object() operatio o it. c. If a servat exists, ivoke the Tobj_ServatBase::activate_object() operatio o it, assigig the object ID cotaied i the cliet request. Note: Support for the TP::applicatio_resposibility() operatio has chaged i this release. For complete iformatio, see the CORBA Programmig Referece. Delegatio-based Iterface Implemetatio There are two primary ways i which a object ca be implemeted i a BEA Tuxedo CORBA applicatio: by iheritace, or by delegatio. Whe a object iherits from the POA skeleto class, ad is thus a CORBA object, that object is said to be implemeted by iheritace. However, there may be istaces i which you wat to use a C++ object i a CORBA applicatio i which iheritig from the POA skeleto class is difficult or impractical. For example, you might have a C++ object that would require a major rewrite to iherit from the POA skeleto class. You ca brig this o-corba object ito a CORBA applicatio by creatig a tie class for the object. The tie class iherits from the POA skeleto class, ad the tie class cotais oe or more operatios that delegate to the legacy class for the implemetatio of those operatios. The legacy class is thereby implemeted i the CORBA applicatio by delegatio. Creatig CORBA Server Applicatios 2-29

70 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio About Tie Classes i the BEA Tuxedo System To create a delegatio-based iterface implemetatio, use the -T commad-lie optio of the IDL compiler to geerate tie class templates for each iterface defied i the OMG IDL file. Usig tie classes i a CORBA applicatio also affects how you implemet the Server::create_servat() operatio i the Server object. The followig sectios explai the use of tie classes i the BEA Tuxedo product i more detail, ad also explais how to implemet the Server::create_servat() operatio to istatiate those classes. I BEA Tuxedo CORBA, the tie class is the servat, ad, therefore, serves basically as a wrapper object for the legacy class. The followig figure shows the iheritace characteristics of the iterface Accout, which serves as a wrapper for a legacy object. The legacy object cotais the implemetatio of the operatio op1. The tie class delegates op1 to the legacy class Creatig CORBA Server Applicatios

71 Delegatio-based Iterface Implemetatio OMG IDL Iterface Accout IDL Compiler Skeleto for Accout Skeleto Header for Accout C++ Template Class Accout_tie (Geerated Usig -T) Implemetatio of Accout_tie: op1(_ptr val); Delegates op1 to legacy class, passig val. Tie classes are trasparet to the cliet applicatio. To the cliet applicatio, the tie class appears to be a complete implemetatio of the object that the cliet applicatio ivokes. The tie class delegates all operatios to the legacy class, which you provide. I additio, the tie class cotais the followig: Costructor ad destructor code, which hadles startup ad shutdow procedures for the tie class ad the legacy class Creatig CORBA Server Applicatios 2-31

72 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio Housekeepig code, which implemets operatios such as accessors Whe to Use Tie Classes Tie classes are ot uique to BEA Tuxedo CORBA, ad they are ot the oly way to implemet delegatio i a CORBA applicatio. However, the BEA Tuxedo CORBA coveiece features for tie classes ca greatly reduce the amout of codig you eed to do for the basic costructor, destructor, ad housekeepig operatios for those tie classes. Usig tie classes might be recommeded i oe of the followig situatios: You wat to implemet a object i a CORBA applicatio i which iheritig from the POA skeleto class is difficult or impractical. All the ivocatios o a legacy class istace ca be accomplished from a sigle servat. You are usig a legacy class i your CORBA applicatio, ad you wat to tie the lifetime of a istace of that legacy class to a servat class. Delegatio is the oly purpose of a particular servat; therefore, early all the code i that servat is dedicated to legacy object startup, shutdow, access, ad delegatio. Tie classes are ot recommeded whe: The operatios o a object istace delegate to more tha oe legacy object istace. Delegatio is oly a part of the purpose of a object. How to Create Tie Classes i a CORBA Applicatio To create tie classes i a applicatio i a BEA Tuxedo domai: 1. Create the iterface defiitio for the tie class i a OMG IDL file, as you would for ay object i your applicatio. 2. Compile the OMG IDL file usig the -T optio Creatig CORBA Server Applicatios

73 Delegatio-based Iterface Implemetatio The IDL compiler geerates a C++ template class, which takes the ame of the skeleto, with the strig _tie appeded to it. The IDL compiler adds this template class to the skeleto header file. Note that the IDL compiler does ot geerate the implemetatio file for the tie class; you eed to create this file by had, as described i the ext step. 3. Create a implemetatio file for the tie class. The implemetatio file cotais the code that delegates its operatios to the legacy class. 4. I the Server object s Server::create_servat() operatio, write the code that istatiates the legacy object. I the followig example, the servat for tie class POA_Accout_tie is created, ad the legacy class LegacyAccout is istatiated. Accout * Accout_ptr = ew LegacyAccout(); AccoutFactoryServat = ew POA_Accout_tie<LegacyAccout> (Accout_ptr) Note: Whe compilig tie classes with the Compaq C++ Tru64 compiler for UNIX, you must iclude the -oimplicit_iclude optio i the defiitio of the CFLAGS or CPPFLAGS eviromet variables used by the buildobjserver commad. This optio prevets the C++ compiler from automatically icludig the server skeleto defiitio file (_s.cpp) everywhere the server skeleto header file (_s.h) is icluded, which is ecessary to avoid multiply-defied symbol errors. See Compaq publicatios for additioal iformatio about usig class templates, such as the tie classes, with Tru64 C++. Creatig CORBA Server Applicatios 2-33

74 2 Steps for Creatig a BEA Tuxedo CORBA Server Applicatio 2-34 Creatig CORBA Server Applicatios

75 CHAPTER 3 Desigig ad Implemetig a Basic CORBA Server Applicatio This chapter describes how to desig ad implemet a CORBA server applicatio, usig the Basic Uiversity sample applicatio as a example. The cotet of this chapter assumes that the desig of the applicatio to be implemeted is complete ad is expressed i OMG IDL. This chapter focuses o desig ad implemetatio choices that are orieted to the server applicatio. This topic icludes the followig sectios: How the Basic Uiversity Sample Applicatio Works, which helps provide cotext to the desig ad implemetatio cosideratios Desig Cosideratios for the Uiversity Server Applicatio, which icludes comprehesive discussios about the followig topics: l l l l l Desig Cosideratios for Geeratig Object Refereces Desig Cosideratios for Maagig Object State Desig Cosideratios for Hadlig Durable State Iformatio How the Basic Sample Applicatio Applies Desig Patters Additioal Performace Efficiecies Built ito the BEA Tuxedo System Creatig CORBA Server Applicatios 3-1

76 3 Desigig ad Implemetig a Basic CORBA Server Applicatio l Preactivatig a Object with State How the Basic Uiversity Sample Applicatio Works The Basic Uiversity sample applicatio provides the studet with the ability to browse course iformatio from a cetral Uiversity database. Usig the Basic sample applicatio, the studet ca do the followig: Browse course syopses from the database by specifyig a search strig. The server applicatio the returs syopses for all courses that have a title, professor, or descriptio cotaiig the search strig. (A course syopsis retured to the cliet applicatio icludes oly the course umber ad title.) View detailed iformatio about specific courses. The detailed iformatio available for a specified course icludes the followig, i additio to syopsis iformatio: l l l l l l l Cost Number of credits Class schedule Number of seats Number of registered studets Professor Descriptio The Basic Uiversity Sample Applicatio OMG IDL I its OMG IDL file, the Basic Uiversity sample applicatio defies the followig iterfaces: 3-2 Creatig CORBA Server Applicatios

77 How the Basic Uiversity Sample Applicatio Works Iterface Descriptio Operatios RegistrarFactory Registrar CourseSyopsisEumerator Creates object refereces to the Registrar object Obtais course iformatio from the database Fetches syopses of courses that match the search criteria from the database ad reads them ito memory fid_registrar() get_courses_syopsis() get_courses_details() get_ext_() destroy() The Basic Uiversity sample applicatio is show i Figure 3-1. Figure 3-1 Basic Uiversity Sample Applicatio Uiversity Server Applicatio RegistrarFactory Registrar Cliet Applicatio CourseSyopsis Eumerator Course Database For the purposes of explaiig what happes whe the Basic Uiversity sample applicatio rus, the followig separate groups of evets are described: Creatig CORBA Server Applicatios 3-3

78 3 Desigig ad Implemetig a Basic CORBA Server Applicatio Applicatio startup whe the server applicatio is booted ad the cliet applicatio gets a object referece to the Registrar object Browsig course syopses whe the cliet applicatio seds a request to view course syopses Browsig course details whe the cliet applicatio seds a request to view details o a specific list of courses Applicatio Startup The followig sequece shows a typical set of evets that take place whe the Basic cliet ad server applicatios are started ad the cliet applicatio obtais a object referece to the Registrar object: 1. The Basic cliet ad server applicatios are started, ad the cliet applicatio obtais a referece to the RegistrarFactory object from the FactoryFider. 2. Usig the referece to the RegistrarFactory object, the cliet applicatio ivokes the fid_registrar() operatio o the RegistrarFactory object. 3. The RegistrarFactory object is ot i memory (because o previous request for that object has arrived i the server process), so the TP Framework ivokes the Server::create_servat() operatio i the Server object to istatiate it. 4. Oce istatiated, the RegistrarFactory object s fid_registrar() operatio is ivoked. The RegistrarFactory object creates the Registrar object referece ad returs it to the cliet applicatio. Browsig Course Syopses The followig sequece traces the evets that may occur whe the studet browses a list of course syopses: 1. Usig the object referece to the Registrar object, the cliet applicatio ivokes the get_courses_syopsis() operatio, specifyig: l A search strig to be used for retrievig course syopses from the database. 3-4 Creatig CORBA Server Applicatios

79 How the Basic Uiversity Sample Applicatio Works l A iteger, represeted by the variable umber_to_get, which specifies the size of the syopsis list to be retured. 2. The Registrar object is ot i memory (because o previous request for that object has arrived i the server process), so the TP Framework ivokes the Server::create_servat() operatio, which is implemeted i the Server object. This causes the Registrar object to be istatiated i the server machie s memory. 3. The Registrar object receives the cliet request ad creates a object referece to the CourseSyopsisEumerator object. The CourseSyopsisEumerator object is ivoked by the Registrar object to fetch the course syopses from the database. To create the object referece CourseSyopsisEumerator object, the Registrar object does the followig: a. Geerates a uique ID for the CourseSyopsisEumerator object. b. Geerates a object ID for the CourseSyopsisEumerator object that is a cocateatio of the uique ID geerated i the precedig step ad the search strig specified by the cliet. c. Gets the CourseSyopsisEumerator object s Iterface Repository ID from the iterface typecode. d. Ivokes the TP::create_object_referece() operatio. This operatio creates a object referece to the CourseSyopsisEumerator object eeded for the iitial cliet request. 4. Usig the object referece created i the precedig step, the Registrar object ivokes the get_ext_() operatio o the CourseSyopsisEumerator object, passig the list size. The list size is represeted by the parameter umber_to_get, described i step The TP Framework ivokes the Server::create_servat() operatio o the Server object to istatiate the CourseSyopsisEumerator object. 6. The TP Framework ivokes the activate_object() operatio o the CourseSyopsisEumerator object. This operatio does the followig two thigs: l Extracts the search criteria from its OID. Creatig CORBA Server Applicatios 3-5

80 3 Desigig ad Implemetig a Basic CORBA Server Applicatio l Usig the search criteria, fetches matchig course syopses from the database ad reads them ito the server machie s memory. 7. The CourseSyopsisEumerator object returs the followig iformatio to the Registrar object: l l A course syopsis list, specified i the retur value CourseSyopsisList, which is a sequece cotaiig the first list of course syopses. The umber of matchig course syopses that have ot yet bee retured, specified by the parameter umber_remaiig. 8. The Registrar object returs the CourseSyopsisEumerator object referece to the cliet applicatio, ad also returs the followig iformatio obtaied from that object: l l The iitial course syopsis list The umber_remaiig variable (If the umber_remaiig variable is 0, the Registrar object ivokes the destroy() operatio o the CourseSyopsisEumerator object ad returs a il referece to the cliet applicatio.) 9. The cliet applicatio seds directly to the CourseSyopsisEumerator object its ext request to get the ext batch of matchig syopses. 10. The CourseSyopsisEumerator object satisfies the cliet request, also returig the updated umber_remaiig variable. 11. Whe the cliet applicatio is doe with the CourseSyopsisEumerator object, the cliet applicatio ivokes the destroy() operatio o the CourseSyopsisEumerator object. This causes the CourseSyopsisEumerator object to ivoke the TP::deactivateEable() operatio. 12. The TP Framework ivokes the deactivate_object() operatio o the CourseSyopsisEumerator object. This causes the list of course syopses maitaied by the CourseSyopsisEumerator object to be erased from the server computer s memory so that the CourseSyopsisEumerator object s servat ca be reused for aother cliet request. 3-6 Creatig CORBA Server Applicatios

81 Desig Cosideratios for the Uiversity Server Applicatio Browsig Course Details The followig sequece shows a typical set of evets that take place whe the cliet applicatio browses course details: 1. The studet eters the course umbers for the courses about which he or she is iterested i viewig details. 2. The cliet applicatio ivokes the get_course_details() operatio o the Registrar object, passig the list of course umbers. 3. The Registrar object searches the database for matches o the course umbers, ad the returs a list cotaiig full details for each of the specified courses. The list is cotaied i the CourseDetailsList variable, which is a sequece of structs cotaiig full course details. Desig Cosideratios for the Uiversity Server Applicatio The Basic Uiversity sample applicatio cotais the Uiversity server applicatio, which deals with several fudametal CORBA server applicatio desig issues. This sectio addresses the followig topics: Desig Cosideratios for Geeratig Object Refereces Desig Cosideratios for Maagig Object State Desig Cosideratios for Hadlig Durable State Iformatio How the Basic Sample Applicatio Applies Desig Patters This sectio also addresses the followig two topics: Additioal Performace Efficiecies Built ito the BEA Tuxedo System Preactivatig a Object with State Creatig CORBA Server Applicatios 3-7

82 3 Desigig ad Implemetig a Basic CORBA Server Applicatio Desig Cosideratios for Geeratig Object Refereces The Basic cliet applicatio eeds refereces to the followig objects, which are maaged by the Uiversity server applicatio: The RegistrarFactory object The Registrar object The CourseSyopsisEumerator object The followig table shows how these refereces are geerated ad retured. Object RegistrarFactory Registrar How the Object Referece Is Geerated ad Retured The object referece for the RegistrarFactory object is geerated i the Server object, which registers the RegistrarFactory object with the FactoryFider. The cliet applicatio the obtais a referece to the RegistrarFactory object from the FactoryFider. There is oly oe RegistrarFactory object i the Basic Uiversity server applicatio process. The object referece for the Registrar object is geerated by the RegistrarFactory object ad is retured whe the cliet applicatio ivokes the fid_registrar() operatio. The object referece created for the Registrar object is always the same; this object referece does ot cotai a uique OID. There is oly oe Registrar object i the Basic Uiversity server applicatio process. 3-8 Creatig CORBA Server Applicatios

83 Desig Cosideratios for the Uiversity Server Applicatio Object CourseSyopsisEumerator How the Object Referece Is Geerated ad Retured The object referece for the CourseSyopsisEumerator object is geerated by the Registrar object whe the cliet applicatio ivokes the get_courses_syopsis() operatio. I this way, the Registrar object is the factory for the CourseSyopsisEumerator object. The desig ad use of the CourseSyopsisEumerator object is described later i this chapter. There ca be ay umber of CourseSyopsisEumerator objects i the Basic Uiversity server applicatio process. Note the followig about how the Uiversity server applicatio geerates object refereces: The Server object registers the RegistrarFactory object with the FactoryFider. This is the recommeded way to esure that cliet applicatios ca locate the factories they eed to obtai refereces to the basic objects i the applicatio. The object referece to the Registrar object is created by the RegistrarFactory object. This shows a very commo ad basic way to retur object refereces to the cliet applicatio; amely, that there is a factory dedicated to creatig ad returig refereces to the primary object that is required by the cliet applicatio to execute busiess logic. The object referece to the CourseSyopsisEumerator object is created outside a registered factory. I the Uiversity sample applicatios, this is a good desig because of the way the CourseSyopsisEumerator object is meat to be used; amely, its existece is specific to a particular cliet applicatio operatio. The CourseSyopsisEumerator object returs a specific list ad results that are ot related to the results from other queries. Because the Registrar object creates, i oe of its operatios, a object referece to aother object, the Registrar object is a factory. However, the Registrar object is ot registered as a factory with the FactoryFider; therefore, cliet applicatios caot get a referece to the Registrar object from the FactoryFider. Creatig CORBA Server Applicatios 3-9

84 3 Desigig ad Implemetig a Basic CORBA Server Applicatio Desig Cosideratios for Maagig Object State Each of the three objects i the Basic sample applicatio has its ow state maagemet requiremets. This sectio discusses the object state maagemet requiremets for each. The RegistrarFactory Object The RegistrarFactory object does ot eed to be uique for ay particular cliet request. It makes sese to keep this object i memory ad avoid the expese of activatig ad deactivatig this object for each cliet ivocatio o it. Therefore, the RegistrarFactory object has the process activatio policy. The Registrar Object The Basic sample applicatio is meat to be deployed i a small-scale eviromet. The Registrar object has may qualities similar to the RegistrarFactory object; amely, this object does ot eed to be uique for ay particular cliet request. Also, it makes sese to avoid the expese of cotiually activatig ad deactivatig this object for each ivocatio o it. Therefore, i the Basic sample applicatio, the Registrar object has the process activatio policy. The CourseSyopsisEumerator Object The fudametal desig problem for the Uiversity server applicatio is how to hadle a list of course syopses that is potetially too big to be retured to the cliet applicatio i a sigle respose. Therefore, the solutio ceters o the followig: To begi a coversatio betwee the cliet applicatio ad a object that ca fetch the course syopses from the Uiversity database. To have the object retur a iitial batch of syopses to the cliet applicatio. To keep the remaider of the course syopses i memory so that the cliet applicatio ca retrieve them oe batch at a time. To have the cliet applicatio termiate the coversatio whe fiished, thus freeig machie resources Creatig CORBA Server Applicatios

85 Desig Cosideratios for the Uiversity Server Applicatio The Uiversity server applicatio has the CourseSyopsisEumerator object, which implemets this solutio. Although this object returs a iitial batch of syopses whe it is first ivoked, this object retais a i-memory cotext so that the cliet applicatio ca get the remaider of the syopses i subsequet requests. To retai a i-memory cotext, the CourseSyopsisEumerator object must be stateful; that is, this object stays i memory betwee cliet ivocatios o it. Whe the cliet is fiished with the CourseSyopsisEumerator object, this object eeds a way to be flushed from memory. Therefore, the appropriate state maagemet decisio for the CourseSyopsisEumerator object is to assig it the process activatio policy ad to implemet the CORBA applicatio-cotrolled deactivatio feature. Applicatio-cotrolled deactivatio is implemeted i the destroy() operatio o that object. The followig code example shows the destroy() operatio o the CourseSyopsisEumerator object: void CourseSyopsisEumerator_i::destroy() { // Whe the cliet calls "destroy" o the eumerator, // the this object eeds to be "destructed". // Do this by tellig the TP framework that we re // doe with this object. } TP::deactivateEable(); Basic Uiversity Sample Applicatio ICF File The followig code example shows the ICF file for the Basic sample applicatio: module POA_UiversityB { implemetatio CourseSyopsisEumerator_i { activatio_policy ( process ); trasactio_policy ( optioal ); implemets ( UiversityB::CourseSyopsisEumerator ); }; implemetatio Registrar_i { activatio_policy ( process ); trasactio_policy ( optioal ); Creatig CORBA Server Applicatios 3-11

86 3 Desigig ad Implemetig a Basic CORBA Server Applicatio }; implemets ( UiversityB::Registrar ); }; implemetatio RegistrarFactory_i { activatio_policy ( process ); trasactio_policy ( optioal ); implemets ( UiversityB::RegistrarFactory ); }; Desig Cosideratios for Hadlig Durable State Iformatio Hadlig durable state iformatio refers specifically to readig durable state iformatio from disk at some poit durig or after the object activatio, ad writig it, if ecessary, at some poit before or durig deactivatio. The followig two objects i the Basic sample applicatio hadle durable state iformatio: The Registrar object The CourseSyopsisEumerator object The followig two sectios describe the desig cosideratios for how these two objects hadle durable state iformatio. The Registrar Object Oe of the operatios o the Registrar object returs detailed course iformatio to the cliet applicatio. I a typical sceario, a studet who has browsed dozes of course syopses may be iterested i viewig detailed iformatio o perhaps as few as two or three courses at oe time. To implemet this usage sceario efficietly, the Registrar object is defied to have the get_course_details() operatio. This operatio accepts a iput parameter that specifies a list of course umbers. This operatio the retrieves full course details from the database ad returs the details to the cliet applicatio. Because the object i which this operatio is implemeted is process-boud, this operatio should avoid keepig ay state data i memory after a ivocatio o that operatio is complete Creatig CORBA Server Applicatios

87 Desig Cosideratios for the Uiversity Server Applicatio The Registrar object does ot keep ay durable state i memory. Whe the cliet applicatio ivokes the get_course_details() operatio, this object simply fetches the relevat course iformatio from the Uiversity database ad seds it to the cliet. This object does ot keep ay course data i memory. No durable state hadlig is doe via the activate_object() or deactivate_object() operatios o this object. The CourseSyopsisEumerator Object The CourseSyopsisEumerator object hadles course syopses, which this object retrieves from the Uiversity database. The desig cosideratios, with regard to hadlig state, ivolve how to read state from disk. This object does ot write ay state to disk. There are three importat aspects of how the CourseSyopsisEumerator object works that ifluece the desig choices for how this object reads its durable state: The OID for this object cotais the search criteria provided i the iitial cliet request for syopses. The search criteria work as a key to the database: this object extracts iformatio from the database based o search criteria stored i the OID. All the operatios o this object use the course syopses that this object reads ito memory. This object must flush course syopses from memory whe it is deactivated. Give these three aspects, it makes sese for this object to: Read its durable state iformatio whe activated; amely, via the activate_object() operatio o this object. Flush the course syopses from memory whe deactivated; amely, via the deactivate_object() operatio. Therefore, whe the CourseSyopsisEumerator object is activated, the activate_object() operatio o this object does the followig: 1. Extracts the search criteria from its OID. 2. Retrieves from the database course syopses that match the search criteria. Creatig CORBA Server Applicatios 3-13

88 3 Desigig ad Implemetig a Basic CORBA Server Applicatio Note: If you implemet the Tobj_ServatBase::activate_object() or Tobj_ServatBase::deactivate_object()operatios o a object, remember to edit the implemetatio header file (that is, the applicatio_i.h file) ad add the defiitios for those operatios to the class defiitio template for the object s iterface. Usig the Uiversity Database Note the followig about the way i which the Uiversity sample applicatios use the Uiversity database: All of the Uiversity sample applicatios access the Uiversity database to maipulate course ad studet iformatio. Typically this is a large part of the code you write i the implemetatio files. To make the Uiversity sample implemetatio files simpler, ad to help you focus o CORBA features istead of database code, the samples have wrapped all the code that reads ad writes to the database withi a set of classes. The file samplesdb.h i the utils directory cotais the defiitios of these classes. These classes make all the ecessary SQL calls to read ad write the course ad studet records i the Uiversity database. Note: The BEA Tuxedo Teller Applicatio i the Wrapper ad Productio sample applicatios accesses the accout iformatio i the Uiversity database directly ad does ot use the samplesdb.h file. For more iformatio o the files you build ito the Basic server applicatio, see the Guide to the CORBA Uiversity Sample Applicatios. The CourseSyopsisEumerator object uses a database cursor to fid matchig course syopses from the Uiversity database. Because database cursors caot spa trasactios, the activate_object() operatio o the CourseSyopsisEumerator object reads all matchig course syopses ito memory. Note that the cursor is maaged by a iterator class ad is thus ot visible to the CourseSyopsisEumerator object. For more iformatio about how the Uiversity sample applicatios use trasactios, see Chapter 6, Itegratig Trasactios ito a CORBA Server Applicatio Creatig CORBA Server Applicatios

89 Desig Cosideratios for the Uiversity Server Applicatio How the Basic Sample Applicatio Applies Desig Patters The Basic sample applicatio uses the followig desig patters: Process-Etity List-Eumerator This sectio describes why these two patters are appropriate for the Basic sample applicatio ad how this applicatio implemets them. Process-Etity Desig Patter As metioed i the sectio Process-Etity Desig Patter o page 1-23, this desig patter is appropriate i situatios where you ca have oe process object that hadles data etities eeded by the cliet applicatio. The data etities are ecapsulated as CORBA structs that are maipulated by the process object ad ot by the cliet applicatio. Adaptig the Process-Etity desig patter to the Basic sample applicatio allows the applicatio to avoid implemetig fie-graied objects. For example, the Registrar object is a efficiet alterative to a similarly umerous set of course objects. The processig burde of maagig a sigle, coarse-graied Registrar object is small relative to the potetial overhead of maagig hudreds or thousads of fie-graied course objects. For complete details about the Process-Etity desig patter, see the Desig Patters techical article. List-Eumerator Desig Patter This desig patter is appropriate i situatios where a object has geerated a iteral list of data that is potetially too large to retur to the cliet applicatio i a sigle respose. Therefore, the object must retur a iitial batch of data to the cliet applicatio i oe respose, ad have the ability to retur the remaider of the data i subsequet resposes. Creatig CORBA Server Applicatios 3-15

90 3 Desigig ad Implemetig a Basic CORBA Server Applicatio A list-eumerator object must also simultaeously keep track of how much of the data has already bee retured so that the object ca retur the correct subsequet batch. List-eumerator objects are always stateful (that is, they remai active ad i memory betwee cliet ivocatios o them) ad the server applicatio has the ability to deactivate them whe they are o loger eeded. The list-eumerator desig patter is a excellet choice for the CourseSyopsisEumerator object, ad implemetig this desig patter provides the followig beefits: The Uiversity server applicatio has a meas to retur potetially large lists of course syopses i a way that cliet applicatios ca hadle; amely, i maageable chuks. Each CourseSyopsisEumerator object is uique, ad its cotet is determied by the request that caused this object to be created. (I additio, each CourseSyopsisEumerator object ID is also uique.) Whe the cliet ivokes the get_courses_syopsis() operatio o the Registrar object, the Registrar object returs the followig: l l A iitial list of syopses. A object referece to a CourseSyopsisEumerator object that ca retur the remaider of the syopses. Therefore, all subsequet ivocatios go to the correct CourseSyopsisEumerator object. This is critical i the situatio where the server process has multiple active istaces of the CourseSyopsisEumerator class. Because the get_courses_syopsis() operatio returs a uique CourseSyopsisEumerator object referece, cliet requests ever collide; that is, a cliet request ever mistakely goes to the wrog CourseSyopsisEumerator object. Although the Registrar object has the get_courses_syopsis() operatio o it, the kowledge of the database query ad the syopsis list is embedded etirely i the CourseSyopsisEumerator object. I this situatio, the Registrar object serves oly as a meas for the cliet to get the followig: The iitial list of syopses. A referece to a CourseSyopsisEumerator object that ca retur the remaider of the syopses Creatig CORBA Server Applicatios

91 Desig Cosideratios for the Uiversity Server Applicatio Additioal Performace Efficiecies Built ito the BEA Tuxedo System The BEA Tuxedo system implemets a performace efficiecy i which data marshalig betwee two objects i the same server process is automatically disabled. This efficiecy exists if the followig circumstaces exist: A object referece routes to the same group as the oe cotaiig the server process i which the object referece was created. A object i that server process ivokes a operatio usig that object referece that causes a object to be istatiated i the same process. A example of this is whe the Registrar object creates a object referece to the CourseSyopsisEumerator object ad causes that object to be istatiated. No data marshalig takes place i the requests ad resposes betwee those two objects. Preactivatig a Object with State The preactivate object with state feature allows you to preactivate a object before a cliet applicatio ivokes that object. This feature ca be particularly useful for creatig iterator objects, such as the CourseSyopsisEumerator object i the Uiversity samples. Preactivatig a object with state ceters aroud usig the TP::create_active_object_referece() operatio. Typically, objects are ot created i a CORBA server applicatio util a cliet issues a ivocatio o that object. However, by preactivatig a object ad usig the TP::create_active_object_referece() operatio to pass a referece to that object back to the cliet, your cliet applicatio ca ivoke a object that is already active ad populated with state. Note: The preactivate object with state feature was first itroduced i WebLogic Eterprise versio 4.2. Creatig CORBA Server Applicatios 3-17

92 3 Desigig ad Implemetig a Basic CORBA Server Applicatio How You Preactivate a Object with State The process for usig the preactivatio feature is to write code i the server applicatio that: 1. Icludes a ivocatio of the C++ ew statemet to create a object. 2. Sets the object s state. 3. Ivokes the TP::create_active_object_referece() operatio to obtai a referece for the ewly created object. This object referece ca the be retured to the cliet applicatio. Thus, the preactivated object is created i such a way that the TP Framework ivokes either the Server::create_servat() or the Tobj_ServatBase::activate_object() operatios for that object. Usage Notes for Preactivated Objects Note the followig whe usig the preactivatio feature: Preactivated objects must have the process activatio policy. Therefore, these objects ca be deactivated oly at the ed of the process or by a ivocatio to the TP::deactivateEable() operatio o those objects. The object referece created by the TP::create_active_object_referece() operatio is trasiet. This is because a preactivated object should exist oly for the lifetime of the process i which it was created, ad this object should ot be reactivated agai i aother server process. If a cliet applicatio ivokes o a trasiet object referece after the process i which the object referece was created is shut dow, the TP Framework returs the followig exceptio: CORBA::OBJECT_NOT_EXIST For objects that are preactivated, the state usually caot be recovered if a crash occurs. However, this is acceptable because such objects are typically meat to be used withi the cotext of a specific series of operatios, ad the deleted. Its state has o meaig outside that specific series. To prevet the situatio i which a server has crashed, ad a cliet applicatio subsequetly attempts to ivoke the ow-deleted object, add the 3-18 Creatig CORBA Server Applicatios

93 Desig Cosideratios for the Uiversity Server Applicatio TobjS::ActivateObjectFailed exceptio to the implemetatio of the Tobj_ServatBase::activate_object() operatio to the object meat for preactivatio. The, if a cliet attempts to ivoke such a object after a server crash, i which case the TP Framework ivokes the Tobj_ServatBase::activate_object() operatio o that object, the TP Framework returs the followig exceptio to the cliet applicatio: CORBA::OBJECT_NOT_EXIST Use preactivatio sparigly because, as with all process-boud objects, preactivatio preallocates scarce resources. Creatig CORBA Server Applicatios 3-19

94 3 Desigig ad Implemetig a Basic CORBA Server Applicatio 3-20 Creatig CORBA Server Applicatios

95 CHAPTER 4 Creatig Multithreaded CORBA Server Applicatios This topic icludes the followig sectios: Overview Developig ad Buildig Multithreaded CORBA Server Applicatios Buildig ad Ruig the Multithreaded Simpapp Sample Applicatio Multithreaded CORBA Server Applicatio Admiistratio Creatig CORBA Server Applicatios 4-1

96 4 Creatig Multithreaded CORBA Server Applicatios Overview This topic icludes the followig sectios: Itroductio Mechaisms for Supportig Multithreaded CORBA Servers Ruig Sigle-threaded Server Applicatios i a Multithreaded System Itroductio Desigig a applicatio to use multiple, idepedet threads provides cocurrecy withi a applicatio ad ca improve overall throughput. Usig multiple threads eables applicatios to be structured efficietly with threads servicig several idepedet tasks i parallel. Multithreadig is particularly useful whe: There is a set of legthy operatios that do ot ecessarily deped o other processig. The amout of data to be shared is small ad idetifiable. You ca break the task ito various activities that ca be executed i parallel. There are occasios where objects must be reetrat. Historically, idustry-wide, multithreaded applicatios have bee complicated to desig ad implemet. The support provided by BEA Tuxedo simplifies this complexity by maagig threads withi a CORBA server eviromet. The BEA Tuxedo software supports server applicatios that have the followig multithreadig characteristics (see Figure 4-1): Istaces of server objects ca hadle multiple cliet requests simultaeously. $ÃVHUYHUÃREMHFWÃFDQÃPDNHÃUHFXUVLYHÃLQYRFDWLRQVÃRQÃLWVHOI Server objects ca create ad moitor their ow threads to implemet parallelism withi a servat method. 4-2 Creatig CORBA Server Applicatios

97 Overview Figure 4-1 Multithreaded CORBA Server Applicatio Geerally, the BEA Tuxedo software creates ad maages threads o behalf of a server applicatio. Buildig multithreaded server applicatios affects how you use the TP Framework, implemet servats, ad desig objects that create their ow threads. The BEA Tuxedo software allows you to implemet either the thread-per-request model or a thread-per-object model. Each model is explaied i Threadig Models o page 4-5. Requiremets, Goals, ad Cocepts Some computer operatios take a substatial amout of time to complete. A multithreaded desig ca sigificatly reduce the wait time betwee the request ad completio of operatios. This is true i situatios whe operatios perform a large umber of I/O operatios such as whe accessig a database, ivokig operatios o Creatig CORBA Server Applicatios 4-3

98 4 Creatig Multithreaded CORBA Server Applicatios remote objects, or are CPU-boud o a multiprocessor machie. Implemetig multithreadig i a server process ca icrease the umber of requests a server processes i a fixed amout of time. The primary requiremet for multithreaded server applicatios is the simultaeous hadlig of multiple cliet requests. The motivatios for developig this type of server are to: Simplify program desig This is achieved by allowig multiple server tasks to proceed idepedetly usig covetioal programmig abstractios. Improve throughput This is achieved by takig advatage of the parallel processig capabilities of multiprocessor hardware platforms ad overlappig computatio with commuicatio. Improve perceived respose time By associatig separate threads with differet server tasks, cliets do ot block each other for a exteded period of time. Simplify codig of remote procedure calls ad coversatios Some applicatios are easier to code whe you use separate threads to iteract with differet remote procedure calls (RPCs) ad coversatios. Provide simultaeous access to multiple applicatios Whe wrappig legacy applicatios or databases i a CORBA server, implemetatios ca iteract with more tha oe legacy applicatio at a time. Reduce the umber of servers required Because oe server ca dispatch multiple service threads, the umber of servers your applicatio requires ca be reduced. However, a multithreaded desig is ot without cost. I geeral, multithreaded server applicatios require more complicated sychroizatio strategies tha sigle-threaded servers. A applicatio developer must write thread-safe code. Additioally, the overhead of creatig a thread to hadle a request might be greater tha the potetial beefit of parallelism. The actual performace of a particular cocurrecy model depeds o the followig factors: Characteristics of requests from the cliet 4-4 Creatig CORBA Server Applicatios

99 Overview Are the requests of log or short duratio? How threads are implemeted Are the threads maaged i the operatig system kerel, i a library i user space, or some combiatio of both? Operatig system ad etwork overhead How much additioal overhead is itroduced by repeatedly settig up ad tearig dow coectios? Higher-level system cofiguratio factors Do replicatio, dyamic load balacig, or other factors affect performace? Threadig Models Thread-Per-Request Model While threadig libraries provide the mechaisms for creatig cocurrecy models, developers are ultimately resposible for kowig how to use the mechaisms successfully. By studyig desig patters, applicatio developers ca master the subtle differeces ad make better desig choices for differet situatios. There are a umber of differet models you ca use for desigig cocurrecy i servers. The followig sectios describe the thread-per-request model, the thread-per-object model, the thread pool, ad how the BEA Tuxedo software implemets each model. A specific server is desiged for either the thread-per-request model or the thread-per-object model. I this model, each request from a cliet is processed i a differet thread of cotrol. This model is useful whe a server typically receives requests of log duratio from multiple cliets. It is less useful for requests of short duratio due to the overhead of creatig a ew thread for each request. Each time a ew request arrives, BEA Tuxedo associates that request with a thread ad executes it. Because a multithreaded applicatio server process ca host more tha oe thread at a time, it ca simultaeously execute more tha oe cliet request at a time. BEA Tuxedo cotrols the associatio of a request to a thread, therefore, applicatios do ot eed to explicitly create threads uless the applicatios require a greater degree of cotrol tha that provided by BEA Tuxedo. Creatig CORBA Server Applicatios 4-5

100 4 Creatig Multithreaded CORBA Server Applicatios Thread-Per-Object Model The Thread Pool The thread-per-request model requires that you desig your applicatio servers to be thread-safe, which meas that you must implemet cocurrecy mechaisms to cotrol access to data that might be shared amog multiple server objects. The eed to use cocurrecy cotrol mechaisms icreases the complexity of the applicatios developmet process. Additioally, if may cliets make requests simultaeously, this desig ca cosume a large umber of operatig system resources. The thread-per-object model associates each active object i the server process with a sigle thread at ay oe time. Each request for a object establishes a associatio betwee a dispatch thread ad the object. Serial requests for the same object ca be serviced by differet threads. A specific thread ca be shared by multiple objects. Thread pools are a meas to reduce the cost of maagig threads. At startup ad as eeded, threads are created, assiged, ad released to a pool of available threads where the thread waits util it is eeded agai to process future requests. Thread pools ca be used to support ay of the threadig models previously described. For example, a thread may be allocated for a request i a thread-per-request model, used for the method executio, ad released back to the pool. Allocatig ad deallocatig threads ca be time-cosumig ad expesive, especially for short-lived requests ad objects. Thread pools provide a meas of reducig the cost of maagig threads. Durig startup, or as eeded, threads are created, assiged, ad released by the BEA Tuxedo software to a pool of available threads. A thread exists i the pool ad waits util it is eeded to process future requests. The iitial ad ultimate size of the BEA Tuxedo thread pool for a applicatio server process is cotrolled through settigs i the server cofiguratio file. At startup, the miimum pool size is pre-allocated. As requests arrive to be serviced, the BEA Tuxedo software assigs a thread from the pool to hadle the request. If the pool does ot cotai a available thread to process the request ad the pool has ot bee filled, the BEA Tuxedo software creates a ew thread to hadle the request. If a request arrives whe there are o threads available i the pool, ad o ew threads ca be created, the request will be queued util a thread is available. 4-6 Creatig CORBA Server Applicatios

101 Overview Thread pools are appropriate for situatios i which you wat to limit the amout of system resources that ca be cosumed for server threadig. Whe a thread pool is used, cliet requests are executed cocurretly util the umber of simultaeous requests exceeds the umber of threads i the pool. The BEA Tuxedo thread pool has the followig characteristics ad behavior: You ca set the maximum size of the pool as a BEA Tuxedo admiistratio fuctio. You ca adjust the size of this pool without makig chages to the applicatio itself. The BEA Tuxedo software allocates threads from the pool as ecessary. The threads are used durig the processig of a request, ad are the released back to the pool. Threads ca be serially reused for servicig multiple requests ad multiple objects. Reetrat Servats The BEA Tuxedo software provides the capability for a object to ivoke operatios o itself recursively. Usig this capability requires a great deal of care i how you implemet a object, because the applicatio code must employ the operatig system cocurrecy mechaisms eeded to cotrol access to shared state data. I some cases, such as with objects that implemet the Process or Distributio Adapter desig patters, there is little or o shared state for a object, ad it is relatively easy to support reetracy. BEA Tuxedo software also allows you to eable or prohibit reetrat method ivocatios o a active object. Reetracy is disabled by default. If a request for a active object is received while the object is curretly executig aother request i a differet thread, the followig rules apply: If the _is_reetrat method returs TRUE, a ew thread is allocated from the pool ad the request is dispatched to the appropriate method usig the same servat istace. It is the resposibility of the servat implemetatio code to esure the itegrity of the state of the object whe multiple threads iteract with it. If the _is_reetrat method returs FALSE, a ew istace of the servat is created ad the method is dispatched to the ew istace. This istace is ot automatically deleted. Future reetrat requests may be dispatched to either istace. Creatig CORBA Server Applicatios 4-7

102 4 Creatig Multithreaded CORBA Server Applicatios Note: The reetrat servat mechaism is available oly whe a server is started with the PER_REQUEST cocurrecy strategy specified. For iformatio about usig this method, see the CORBA Programmig Referece. The Curret Object Oe of the most importat attributes of a multithreaded CORBA server applicatio eviromet is esurig that the Curret object is used ad maaged correctly. This esures behavior such as the followig: Idividual threads fuctio withi the correct trasactio ad security cotexts. The Curret object behaves correctly whe accessed from differet threads. The BEA Tuxedo product coforms to the multithreadig model defied by the ORB Portability Specificatio, published by the OMG, which has bee icorporated ito the OMG CORBA specificatio. I the BEA Tuxedo product, operatios o iterfaces derived from CORBA::Curret have access to the state associated with the thread i which operatios are ivoked, ot to the state associated with the thread from which the Curret object was obtaied. The reaso for this behavior is twofold: Prevets oe thread from maipulatig the state of aother thread Avoids the eed to obtai ad arrow a ew Curret object i the thread cotext for each method Whe used i a multithreaded eviromets, the behaviors of the followig objects are cosistet with the ORB Portability Specificatio: CosTrasactios::Curret SecurityLevel1::Curret SecurityLevel2::Curret PortableServer::Curret For example, whe a applicatio passes a trasactio from oe thread to aother, the applicatio should ot use the CosTrasactios::Curret object. Istead, the applicatio passes the CosTrasactios::Cotrol object to the other thread. To pass the CosTrasctios::Curret object would oly allow the receivig thread to gai access to the trasactio state associated with that thread. 4-8 Creatig CORBA Server Applicatios

103 Overview Mechaisms for Supportig Multithreaded CORBA Servers This sectio provides a overview of the followig tools, APIs, ad admiistrative capabilities i BEA Tuxedo CORBA that support multithreaded server applicatios: Cotext Services Classes ad Methods i the TP Framework Capabilities i the Build Commads Tools for Admiistratio Cotext Services You ca choose to create ad maage your ow threads i your object implemetatios. Other threads are maaged automatically by the BEA Tuxedo CORBA software. The BEA Tuxedo CORBA software maitais cotext iformatio iterally for each thread that it creates ad maitais. This required cotext iformatio is used durig the processig of CORBA requests. Sice BEA Tuxedo CORBA has o kowledge of whe a applicatio creates ad deletes its ow threads, the cotext services mechaism allows programmers to iitialize their ow threads correctly, prior to callig BEA Tuxedo services, ad to release ay cotext resources that are o loger eeded whe a thread is deleted. The followig set of ORB methods satisfies the thread maagemet requiremets. Together these are called cotext services: ORB::get_ctx() Whe a object creates a thread, the object ivokes this operatio o the ORB to obtai system cotext iformatio that the object ca pass oto the thread. This operatio must be called from a thread that already has a cotext. For example, the thread i which a method was dispatched will already have a cotext. For iformatio about usig this operatio, see ORB::get_ctx() i the CORBA Programmig Referece. ORB::set_ctx() Whe a object spaws a thread, the spawed thread typically retrieves the cotext iformatio from the thread that ivoked the get_ctx method. The Creatig CORBA Server Applicatios 4-9

104 4 Creatig Multithreaded CORBA Server Applicatios spawed thread the uses the retrieved cotext iformatio whe ivokig ORB::set_ctx to set the system cotext i which the spawed thread should execute. For iformatio about usig this operatio, see ORB::set_ctx() i the CORBA Programmig Referece. ORB::clear_ctx() Whe a spawed thread has completed its work, the thread ivokes this method to dissociate itself from the system cotext. For iformatio about usig this operatio, see ORB::clear_ctx() i the CORBA Programmig Referece. ORB::iform_thread_exit() Whe a thread has completed its work, the thread ivokes this method to iform the BEA Tuxedo system that resources associated with a applicatio-maaged thread ca be released. For iformatio about usig this operatio, see ORB::iform_thread_exit() i the CORBA Programmig Referece. Classes ad Methods i the TP Framework These classes ad methods i the BEA Tuxedo TP Framework support multithreaded server applicatios: ServerBase class To override the default implemetatios of the ServerBase class, a applicatio developer ca create a class that derives from ServerBase. I additio to ServerBase methods already supported, these methods are provided to support the implemetatio of multithreaded server applicatios: l l l create_servat_with_id() thread_iitialize() thread_release() These methods allow you to obtai a high-degree of graularity of cotrol over the multithreadig characteristics of your applicatio. For iformatio o how to use these methods see ServerBase Class i the CORBA Programmig Referece. Tobj_ServatBase class This class provides these methods to support multithreaded server applicatios: l Tobj_ServatBase::_is_reetrat() l Tobj_ServatBase::_add_ref() 4-10 Creatig CORBA Server Applicatios

105 Overview l Tobj_ServatBase::_remove_ref() For iformatio about usig these methods, see Tobj_ServatBase Class i the CORBA Programmig Referece. Capabilities i the Build Commads The buildobjserver ad buildobjcliet commads iclude the followig thread-maagemet capabilities. The buildobjserver commad icludes platform-specific thread library support so that server applicatios are compatible with the multithreadig support i the BEA Tuxedo software. The buildobjserver commad icludes commad-lie optios for buildig multithreaded or sigle-threaded server applicatios. The buildobjcliet commad icludes platform-specific thread library support so that cliet applicatios ca be compatible with the multithreadig support provided i the BEA Tuxedo software. Tools for Admiistratio The BEA Tuxedo system employs cofiguratio files to assemble ad ru applicatios. Typically, the applicatio developer creates these files, ad BEA Tuxedo system admiistrators modify the cotets of the file as ecessary to satisfy applicatio ad system requiremets. The cotrol parameters associated with the support of threads specify the followig: Whether a server should be sigle-threaded or multithreaded The size of the thread pool available for dispatchig methods o objects For more iformatio about threads parameters i the UBBCONFIG file, see Sample UBBCONFIG File o page Creatig CORBA Server Applicatios 4-11

106 4 Creatig Multithreaded CORBA Server Applicatios Ruig Sigle-threaded Server Applicatios i a Multithreaded System The default behavior of the threadig support provided i BEA Tuxedo CORBA is to emulate a sigle-threaded server support eviromet. To ru a sigle-threaded CORBA applicatio i a multithreaded eviromet, you do ot eed to chage the server applicatio code or the cofiguratio files. However, before you ru a existig sigle-threaded applicatio, you must rebuild it usig the buildobjserver ad buildobjcliet commads. If you do ot specifically eable multithreadig for a server applicatio, the applicatio rus as a sigle-threaded server Creatig CORBA Server Applicatios

107 Developig ad Buildig Multithreaded CORBA Server Applicatios Developig ad Buildig Multithreaded CORBA Server Applicatios This topic icludes the followig sectios: Usig the buildobjserver Commad Usig the buildobjcliet Commad Creatig No-reetrat Servats Creatig Reetrat Servats Buildig ad Ruig the Multithreaded Simpapp Sample Applicatio Usig the buildobjserver Commad The buildobjserver commad supports multithreaded CORBA server applicatios through the followig capabilities: Platform-specific Thread Libraries Specifyig Multithreaded Support Specifyig a Alterate Server Class Platform-specific Thread Libraries Server applicatios geerated by the buildobjserver commad are compiled usig the correct platform-specific compiler settigs, ad are liked usig the correct platform-specific thread support libraries. This esures compatibility with the shared libraries provided by the BEA Tuxedo software. Creatig CORBA Server Applicatios 4-13

108 4 Creatig Multithreaded CORBA Server Applicatios Specifyig Multithreaded Support Whe you create a CORBA server applicatio to support multithreadig, you must specify the -t optio o the buildobjserver commad whe you build the applicatio. At ru time, the BEA Tuxedo system verifies compatibility betwee the executable program ad the threadig model selected i the CORBA server applicatio cofiguratio file UBBCONFIG. For iformatio o how to set the threadig model i the UBBCONFIG file, see Sample UBBCONFIG File o page Note: Note: Whe you specify -t i your build of a CORBA server applicatio, you should set the MAXDISPATCHTHREADS parameter i the UBBCONFIG file to a value greater tha 1; otherwise, the CORBA server applicatio will ru as a sigle-threaded server. Multithreaded joit cliet/server implemetatios are ot supported. If you attempt to start a sigle-threaded executable with a icompatible threadig model specificatio i the cofiguratio file, these evets occur: The BEA Tuxedo software records a warig i the log file. The server executable program is started as a sigle-threaded server. Specifyig a Alterate Server Class If you implemet your ow Server class, iheritig from the ServerBase class, you must specify your alterate Server class i the buildobjserver commad usig the -b optio. The buildobjserver commad provides the followig sytax to support the -b optio: buildobjserver [-v] [-o outfile] [-f [-l [-r rmame] [-b bootserverclass] [-t] I the precedig sytax, the value for bootserverclass specifies the C++ class to be used whe the CORBA server applicatio is booted. If you do ot specify the -b optio, the BEA Tuxedo system creates a istace of the class amed Server. Whe you specify the -b optio, the Tuxedo system creates a mai fuctio for the alterate server class, ad your project must supply a header file with the ame you specified for bootserverclass o the -b optio. The header file cotais the defiitio of the alterate C++ class. This alterate Server class must iherit from the ServerBase class Creatig CORBA Server Applicatios

109 Developig ad Buildig Multithreaded CORBA Server Applicatios For example, if the commad lie specifies -b AslaServer, the applicatio project must supply a AslaServer.h file. The AslaServer.h file is a example of a bootserverclass.h file. A bootserverclass file provides logic similar to this code sample: Listig 4-1 Example of a bootserverclass.h File // File ame: AslaServer.h #iclude <Server.h> class AslaServer : public ServerBase { public: CORBA::Boolea iitialize(it argc, char** argv); void release(); Tobj_Servat create_servat(cost char* iterfacename); Tobj_Servat create_servat_with_id(cost char* iterfacename, cost char* stroid); CORBA::Boolea thread_iitialize(it argc, char** argv); void thread_release(); }; Usig the buildobjcliet Commad Whe you use the buildobjcliet commad to create a cliet applicatio executable program, the applicatio is compiled usig the correct platform-specific compiler settigs ad liked usig the correct thread support libraries for your operatig system. This esures that cliets are compatible with the shared libraries provided by the BEA Tuxedo software. Creatig No-reetrat Servats Before you ca ru ay CORBA server applicatio i the BEA Tuxedo CORBA eviromet, you must build it usig the buildobjserver commad. Creatig CORBA Server Applicatios 4-15

110 4 Creatig Multithreaded CORBA Server Applicatios Use the buildobjserver -t optio to iform the BEA Tuxedo system that the CORBA server applicatio is thread safe. The -t optio idicates that the applicatio does ot employ shared cotext data or other programmig costructs that are ot thread safe. If you ru sigle-threaded applicatios that are ot thread safe i a multithreaded eviromet, you risk data corruptio. If you update cofiguratio files for a applicatio to eable multithreadig support, but the applicatio code has ot bee updated to idicate that the servat implemetatio ca support reetracy, ote the followig: Methods are executed i arbitrary threads assiged by the BEA Tuxedo system. Servat implemetatio code does ot ecessarily protect a object from cocurret access to its state. However, active servats are limited to a sigle thread of executio at a time. You caot assume that a method is executed i a specific thread. Do ot use storage that depeds o or is tied to a specific thread. Do ot assume that the servat s activate_object or deactivate_object methods are executed i the same thread as the request i which they were origially ivoked. Additioal applicatio-maaged threads ca be created withi a servat method. Your object implemetatios must esure that threads are created, hadled, ad destroyed properly. A applicatio-maaged thread ca iclude ivocatios o other objects. Do ot use sigals for sychroizatio; the mixig of sigals ad threads is ot supported. Note: The SIGKILL sigal to termiate a process is supported. The use of SIGIO is ot supported i BEA Tuxedo CORBA for sigle or multithreaded applicatios. Request-level iterceptors are ivoked by BEA Tuxedo CORBA through the same thread used by the method Creatig CORBA Server Applicatios

111 Developig ad Buildig Multithreaded CORBA Server Applicatios Creatig Reetrat Servats To create a multithreaded reetrat servat: Build the CORBA server applicatio usig the buildobjserver commad with the -t optio, ad modify the UBBCONFIG server cofiguratio file for the applicatio. Update the CORBA server applicatio code to eable reetracy usig the TobjServatBase::_is_reetrat method. Start the server usig the thread-per-request threadig model, by specifyig CONCURR_STRATEGY = PER_REQUEST i the UBBCONFIG file. If you do create a multithreaded, reetrat servat, the implemetatio code for that object must protect the state of the object, i order to esure its itegrity while multiple threads iteract with it. Cosideratios for Cliet Applicatios There are cosideratios for CORBA cliet applicatios ruig i the BEA Tuxedo eviromet: Multithreaded CORBA cliets usig IIOP are supported. Multithreaded ative CORBA cliets are ot supported. A multithreaded CORBA cliet is limited to a sigle bootstrap object. A multithreaded CORBA cliet is limited to a sigle logo. CORBA cliets usig stub-based ivocatio are supported. CORBA cliets usig the Dyamic Ivocatio Iterface (DII) are ot supported. Creatig CORBA Server Applicatios 4-17

112 4 Creatig Multithreaded CORBA Server Applicatios Buildig ad Ruig the Multithreaded Simpapp Sample Applicatio This topic icludes the followig sectios: About the Simpapp Multithreaded Sample How the Sample Applicatio Works How to Build ad Ru the Sample Applicatio Shuttig Dow the Sample Applicatio About the Simpapp Multithreaded Sample The BEA Tuxedo software provides a multithreaded CORBA sample applicatio, cosistig of a cliet program ad a CORBA server program. The server receives a alphabetic strig from the cliet ad returs the strig i uppercase ad lowercase letters. The multithreadig capability of simpapp_mt provides parallel processig. Through this parallelism, a sigle server process ca hadle cocurret requests from multiple cliets for multiple objects or for a sigle object. Note: The cliet applicatio i the simpapp_mt sample is ot a multithreaded cliet applicatio. How the Sample Applicatio Works The purpose of a multithreaded server is to hadle multiple requests from oe or more cliets i a parallel maer. The simpapp_mt sample applicatio is a CORBA applicatio that demostrates multithreadig fuctioality, by usig the buildobjserver -t commad-lie optio ad usig the UBBCONFIG file to specify cocurrecy strategy Creatig CORBA Server Applicatios

113 Buildig ad Ruig the Multithreaded Simpapp Sample Applicatio The simpapp_mt sample first creates a server process amed SimplePerObject ad secodly a server process amed SimplePerRequest. The cliet commuicates first with the SimplePerRequest server ad the with the SimplePerObject server. The thread-per-request server implemetatio for SimplePerRequest demostrates the use of a user-defied server class that implemets thread iitializatio methods. The SimplePerRequest server process hadles each request from a cliet i a separate thread of cotrol. Each time a ew request arrives, a thread is allocated from the thread pool to hadle the request. Oce the request has bee processed ad the reply set, the thread is released back to the pool. This model is useful for servers that hadle log-duratio requests from multiple cliets. The simpapp_mt sample applicatio provides a implemetatio of a CORBA object that has the followig methods: The to_upper method accepts a strig from the cliet applicatio ad coverts it to uppercase letters. The to_lower method accepts a strig from the cliet applicatio ad coverts it to lowercase letters. The forward_upper method creates a applicatio-maaged thread to aother istace of the server ad forwards the request received from the cliet to the ew server istace to covert the strig to uppercase letters. The forward_lower method creates aother istace of the Simple object ad forwards the request received from the cliet to the ew istace to covert the strig to lowercase letters. Figure 4-2 shows the operatio of the simpapp_mt sample applicatio, employig both the thread-per-object ad thread-per-request threadig models. Creatig CORBA Server Applicatios 4-19

114 4 Creatig Multithreaded CORBA Server Applicatios Figure 4-2 simpapp_mt Sample Applicatio OMG IDL Code for the Simpapp Multithreaded Sample Applicatio The simpapp multithreaded sample applicatio described i this chapter implemets the CORBA iterfaces listed i the followig table. Iterface Descriptio Actio SimplePerRequestFactory Creates object refereces to the Simple object fid_simple() SimplePerObjectFactory Creates object refereces to the Simple object fid_simple() Simple Coverts the case of a strig to_upper() to_lower() forward_upper() forward_lower() Listig 4-2 shows the cotet of the simple.idl file, describig the CORBA iterface i the simpapp_mt sample applicatio Creatig CORBA Server Applicatios

115 Buildig ad Ruig the Multithreaded Simpapp Sample Applicatio Listig 4-2 OMG IDL Code for the simpapp_mt Sample Applicatio #pragma prefix "beasys.com" iterface Simple { //Covert a strig to lower case (retur a ew strig) strig to_lower(i strig val); //Covert a strig to upper case (i place) strig to_upper(i strig val); //Use other server to covert strig to lower case strig forward_lower(i strig val); }; //Use other server to covert strig to upper case strig forward_upper(i strig val); iterface SimplePerRequestFactory { Simple fid_simple(); }; iterface SimplePerObjectFactory { Simple fid_simple(); }; How to Build ad Ru the Sample Applicatio This sectio leads you, step-by-step, through the process of buildig ad ruig the simpapp_mt sample applicatio. The flowchart summarizes the process ad followig sectios explai how to perform the tasks. Creatig CORBA Server Applicatios 4-21

116 4 Creatig Multithreaded CORBA Server Applicatios Figure 4-3 Process for Buildig ad Ruig simpapp_mt Settig the TUXDIR Eviromet Variable Before buildig ad ruig the simpapp_mt sample applicatio, esure that the TUXDIR eviromet variable is set o your system. Typically, the eviromet variable is set durig the istallatio process. You should cofirm that the eviromet variable defies the correct directory locatio. The TUXDIR eviromet variable must be set to the directory path where you istalled the BEA Tuxedo software. For example: 4-22 Creatig CORBA Server Applicatios