BEA Tuxedo. Using the CORBA Name Service

Transcription

1 BEA Tuxedo Usig the CORBA Name Service 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 product ames may be trademarks of the respective compaies with which they are associated. Usig the CORBA Name Service Documet Editio Date Software Versio 8.0 Jue 2001 BEA Tuxedo 8.0

3 Cotets About This Documet What You Need to Kow...v e-docs Web Site... vi How to Prit the Documet... vi Documetatio Covetios... vii 1. Overview of the CORBA Name Service The CORBA Name Service Uderstadig the CORBA Name Service CORBA Name Service Referece CORBA Name Service Commads Capabilities ad Limitatios of the CORBA Name Service Gettig the Iitial Referece to the NameService Evirometal Object The CosNamig Data Structures Used by the CORBA Name Service The NamigCotext Object CosNamig::NamigCotext::ew_cotext() The NamigCotextExt Object The BidigIterator Object Exceptios Raised by the CORBA Name Service Maagig a BEA Tuxedo Namespace Istallig the CORBA Name Service Startig the Server Process for the CORBA Name Service Makig the Namespace Persistet Compressig the Persistet Storage File Removig Orpha NamigCotext Objects Usig the CORBA Name Service iii

4 Federatig the Namespace Iboud Federatio Outboud Federatio Federatio Across BEA Tuxedo Domais Maagig Bidig Iterators Usig the CORBA Name Service i Secure BEA Tuxedo Applicatios Developig a Applicatio That Uses the CORBA Name Service Developmet Steps Step 1: Obtai the OMG IDL for the CosNamig Iterfaces Step 2: Iclude the Declaratios ad Prototypes for the CosNamig Iterfaces Step 3: Coect to the BEA Tuxedo Namespace Step 4: Bid a Object to the BEA Tuxedo Namespace Step 5: Use a Name to Locate a Object i the BEA Tuxedo Namespace Usig the CORBA Name Service Sample Applicatio Idex How the Name Service Sample Applicatio Works Buildig ad Ruig the Name Service Sample Applicatio Step 1: Copy the Files for the Name Service Sample Applicatio ito a Work Directory CORBA C++ Cliet ad Server, ad CORBA Java Cliet Versio of the Name Service Sample Applicatio Step 2: Chage the Protectio Attribute o the Files for the Name Service Sample Applicatio Step 3: Verify the Settigs of the Eviromet Variables Step 4: Execute the rume Commad Usig the Name Service Sample Applicatio iv Usig the CORBA Name Service

5 About This Documet This documet provides iformatio o usig the BEA Tuxedo CORBA Name Service. This documet icludes the followig topics: Chapter 1, Overview of the CORBA Name Service, itroduces the features ad cocepts of the BEA Tuxedo CORBA Name Service. Chapter 2, CORBA Name Service Referece, describes the commads ad applicatio programmig iterfaces (APIs) of the BEA Tuxedo CORBA Name Service. Chapter 3, Maagig a BEA Tuxedo Namespace, describes the admiistratio tasks associated with the BEA Tuxedo CORBA Name Service. Chapter 4, Developig a Applicatio That Uses the CORBA Name Service, explais how to develop a BEA Tuxedo applicatio that uses a amespace for storig refereces to objects. Chapter 5, Usig the CORBA Name Service Sample Applicatio, describes how to build ad ru the CORBA Name Service sample applicatio. What You Need to Kow This documet is iteded for programmers who are developig applicatios with the BEA Tuxedo product ad wat to use the ame service feature. Usig the CORBA Name Service v

6 e-docs Web Site The BEA Tuxedo product documetatio is available o the BEA System, 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 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. vi Usig the CORBA Name Service

7 Documetatio Covetios 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. 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 Item Idicates terms defied i the glossary. Idicates that you must press two or more keys simultaeously. Usig the CORBA Name Service vii

8 Covetio italics moospace text moospace boldface text moospace italic text UPPERCASE TEXT Item Idicates emphasis or book titles. 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]... viii Usig the CORBA Name Service

9 Documetatio Covetios Covetio Item Separates mutually exclusive choices i a sytax lie. The symbol itself should ever be typed.... 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. Usig the CORBA Name Service ix

10 x Usig the CORBA Name Service

11 CHAPTER 1 Overview of the CORBA Name Service This topic icludes the followig sectios: The CORBA Name Service Uderstadig the CORBA Name Service The CORBA Name Service The BEA Tuxedo Name Service (referred to throughout this documet as the CORBA Name Service) allows BEA Tuxedo CORBA server applicatios to advertise object refereces usig logical ames. BEA Tuxedo CORBA cliet applicatios ca the locate a object by askig the CORBA Name Service to look up the ame. The CORBA Name Service provides: A implemetatio of the Object Maagemet Group (OMG) Iteroperable Name Service (INS) specificatio. Applicatio programmig iterfaces (APIs) for mappig object refereces ito a hierarchical amig structure (referred to as a amespace). Commads for displayig bidigs ad for bidig ad ubidig amig cotext objects ad applicatio objects ito the amespace. Usig the CORBA Name Service 1-1

12 1 Overview of the CORBA Name Service The CORBA Name Service is a layered product. The CORBA Name Service is istalled as part of the BEA Tuxedo product. For a complete descriptio of the supported platforms ad the istallatio procedure, see Istallig the BEA Tuxedo System. Whe usig the CORBA Name Service: 1. BEA Tuxedo CORBA server applicatios bid a ame to oe of its applicatio objects or a amig cotext object withi a amespace. 2. BEA Tuxedo CORBA cliet applicatios ca the use the amespace to resolve a ame ad obtai a object referece to the applicatio object or the amig cotext object. Figure 1-1 presets a overview of the CORBA Name Service. Figure 1-1 CORBA Name Service CORBA Server Applicatio 4. Ivoke methods o objects 1. bid(ame, objref) Namespace <ame_1, objref_1> <ame_2, objref_2> <ame_3, objref_3>... <ame_x, objref_x> 3. Resolve returs a object referece 2. resolve(ame) CORBA Cliet Applicatio 1-2 Usig the CORBA Name Service

13 Uderstadig the CORBA Name Service Uderstadig the CORBA Name Service Figure 1-2 shows how a amespace might be used to store objects that make up a order etry applicatio. Figure 1-2 A BEA Tuxedo Namespace New Jersey New Hampshire Califoria Maufacturig Ivetory... Sales Orders Customers Billig... PK Boutique Rose House Order Object The illustrated applicatio orgaizes its amespace by geographic regio, the by departmet. To implemet the amespace usig the objects i the CORBA Name Service, each shadowed box would be implemeted by a NamigCotext object. A NamigCotext object cotais a list of CosNamig::Name data structures that have bee boud to applicatio objects or to other NamigCotext objects. NamigCotext objects are traversed to locate a particular ame. For example, the logical ame Califoria.Maufacturig.Order ca be used to locate the Order object. Usig the CORBA Name Service 1-3

14 1 Overview of the CORBA Name Service A CosNamig::Name data structure is ot simply a strig of alphaumeric characters; it is a sequece of oe or more CosNamig::NameCompoet data structures. Each CosNamig::NameCompoet data structure cotais two strigs, id ad kid. The CORBA Name Service does ot iterpret or maage these strigs, except to esure that each ID is uique withi a give NamigCotext object. BEA Tuxedo CORBA server applicatios use the bid() method of the NamigCotext object to bid a ame to a applicatio object cotaied i the server applicatio. BEA Tuxedo CORBA cliet applicatios use the resolve method of a NamigCotext object to locate a object usig a bidig. The CORBA Name Service also provides a BidigIterator object ad a NamigCotextExt object. The BidigIterator object allows a cliet applicatio to obtai a specified umber of bidigs i each call. The NamigCotextExt object provides methods to use Uiform Resource Locators (URL) ad strigified ames. For a complete descriptio of the objects i the CORBA Name Service ad their iterfaces, see Chapter 2, CORBA Name Service Referece. 1-4 Usig the CORBA Name Service

15 CHAPTER 2 CORBA Name Service Referece This topic icludes the followig sectios: CORBA Name Service Commads Capabilities ad Limitatios of the CORBA Name Service Gettig the Iitial Referece to the NameService Evirometal Object The CosNamig Data Structures Used by the CORBA Name Service The NamigCotext Object The NamigCotextExt Object The BidigIterator Object Exceptios Raised by the CORBA Name Service CORBA Name Service Commads The CORBA Name Service provides the followig commads to maage the server process for the CORBA Name Service, bid ad ubid objects to ames i the amespace, ad display the cotets of the amespace: cs csbid Usig the CORBA Name Service 2-1

16 2 CORBA Name Service Referece csls csubid The followig sectios describe these commads. 2-2 Usig the CORBA Name Service

17 CORBA Name Service Commads cs Syopsis Cotrols the server process for the CORBA Name Service. Sytax cs CLOPT="[-A] [servopts optios] -- [-b bucketcout] [-c] [-d] [-f fileame] [-M maxiterators] [-p [persiststoragefileame] ]" Descriptio The server process for the CORBA Name Service provides a CORBA CosNamig compliat ame service. You eed to defie the server process for the CORBA Name Service ad its optios i the UBBCONFIG file for your BEA Tuxedo applicatio as you do ay other server process used by your BEA Tuxedo applicatio. Eter the cs commad-lie optios after the double dash (--) i the CLOPT parameter of the UBBCONFIG file. The commad-lie optios are as follows: -b bucketcout Specifies the hash table bucket cout used iterally by the server process to locate amig cotexts i-memory. Each amig cotext has its ow hash table. If your BEA Tuxedo applicatio uses a small umber of bidigs i each amig cotext, use a small bucket cout (for example, 4 or 5). If your BEA Tuxedo applicatio uses a large umber of bidigs (for example, 1,000) i each amig cotext, use a larger umber such as 50 for the bucket cout. -c -d Compresses the persistet storage file whe the server process for the CORBA Name Service starts. Over time the persistet storage file ca grow i size as amig cotext ad applicatio objects are added ad removed from the amespace. Compressio reduces the size of the persistet storage file to a miimum. Daglig bidigs are removed durig compressio. Daglig bidigs are left i the amespace after the object the bidig is associated with is deleted from the amespace. The -p commad-lie optio must be specified whe specifyig the -c commad-lie optio. Directs the server process for the CORBA Name Service to delete orpha cotexts whe the server process starts. A orpha cotext is a cotext that is ot boud to ay other cotext. It may ever have bee boud or it may have bee boud to a cotext ad the bidig was destroyed either explicitly or as Usig the CORBA Name Service 2-3

18 2 CORBA Name Service Referece a side-effect of a rebid. The -p commad-lie optio must be specified whe specifyig the -d commad-lie optio. -f fileame Specifies a file ito which the server process for the CORBA Name Service writes the Iteroperable Object Referece (IOR) of the root of the amespace. -M maxiterators Defies the maximum umber of bidig iterators that ca be outstadig at ay oe time. Bidig iterators are created whe a cliet applicatio uses the CosNamig::NamigCotext::list()method. The cliet applicatio should use the CosNamig::BidigIterator::destroy()method to delete a bidig iterator whe the cliet applicatio is doe usig the bidig iterator. If a cliet applicatio does ot specifically delete bidig iterators, the server process for the CORBA Name Service deletes the bidig iterators whe the umber reaches the value specified i the -M commad-lie optio. Oce the maximum umber of bidig iterators is reached, ay attempt to create a ew bidig iterator causes the server process for the CORBA Name Service to destroy a bidig iterator curretly i use by the cliet applicatio. Bidig iterators are deleted usig a least-recetly-used algorithm. The default value is 20. A value of 0 idicates that there is o maximum umber of bidig iterators (meaig bidig iterators are ever destroyed by the server process for the CORBA Name Service ad the associated memory is ot released). If a value of 0 is specified, the cliet applicatio must explicitly use the CosNamig::BidigIterator::destroy() method to delete outstadig bidig iterators. -p [persistetstoragefileame] Directs the server process for the CORBA Name Service to save a copy of the curret amespace to persistet storage usig the specified file. If a fileame is ot specified, the value of the CNS_PERSIST_FILE eviromet variable is used. If the CNS_PERSIST_FILE eviromet variable is ot set, the followig files are used: Widows %APPDIR%\cspersist.dat 2-4 Usig the CORBA Name Service

19 CORBA Name Service Commads UNIX $APPDIR/cspersist.dat The persistet storage file is read whe the server process for the CORBA Name Service starts. The persistet storage file is added to as chages are made to the amespace. If you wat to create a ew amespace, the existig persistet storage file must be deleted or a ew oe must be created o the server process for the CORBA Name Service. Usig the CORBA Name Service 2-5

20 2 CORBA Name Service Referece csbid Syopsis Bids applicatio objects ad amig cotext objects ito the amespace. Note: The csbid commad iteracts with the CosNamig iterfaces. The server process for the CORBA Name Service must be ruig to use this commad. Sytax Descriptio csbid [-C] [-f root_cotext_fileame] [-h] [-N] [-o ior_fileame] [-r] [-T TObjAddr] bid_ame The csbid commad bids ew applicatio ad amig cotext objects ito the amespace usig the CORBA CosNamig iterfaces. This commad facilitates the creatio of a federated amespace. If a exceptio is retured whe the csbid commad is ivoked, the commad exits ad a appropriate message is displayed. The commad-lie optios for the csbid commad are as follows: -C Specifies that the csbid commad creates a cotext usig the bid_ame for the ame ad the ior_fileame specified for the -o commad-lie optio. The -C commad-lie optio is used to federate a amig cotext object from oe amespace ito the specified amespace. -f root_cotext_fileame Specifies the file cotaiig the IOR of the server process for the CORBA Name Service with which the commad iteracts to modify the cotets of the amespace. If this commad-lie optio is ot specified, the commad uses the Tobj_Bootstrap::resolve_iitial_refereces() method with the NameService evirometal object to locate the server process for the CORBA Name Service i the specified BEA Tuxedo domai. The host ad port i the IOR must match the value of TOBJADDR. This commad-lie optio overrides the settig for the TOBJADDR eviromet variable. If the commad-lie optio is ot specified, the TOBJADDR eviromet variable is used. 2-6 Usig the CORBA Name Service

21 CORBA Name Service Commads -h -N Prits the commad sytax. Creates a ew cotext ad bids the ew cotext ito the amespace usig the specified ame. The -o commad-lie optio is ot eeded with the -N commad-lie optio because the csbid commad is creatig a ew cotext. If the -o commad-lie optio is used with the -N commad-lie optio, the iformatio from the -o commad-lie optio is igored. -o ior_fileame Specifies a file that cotais the IOR of the object to be boud ito the amespace specified via the -f commad-lie optio. If the -C commad-lie optio is specified, a object of type cotext is created otherwise a object of type object is created. -r Creates a bidig for a applicatio or amig cotext object eve if the ame already has a bidig. The default behavior of the csbid commad without the -r commad-lie optio is to raise the AlreadyBoud exceptio i the case where a bidig for the specified object already exists. If a AlreadyBoud or ay other exceptio is retured whe the csbid commad is ivoked, the commad exits ad a Error, already boud message is displayed. -T TObjAddr Specifies the host ad port for a BEA Tuxedo domai. Before coectig to a server process for the CORBA Name Service, the csbid commad must log ito the BEA Tuxedo domai i which the server process is ruig. This commad-lie optio overrides the settig for the TOBJADDR eviromet variable. If the commad-lie optio is ot specified, the value of the TOBJADDR eviromet variable is used. The valid format for the TObjAddr specificatio is //hostame:port_umber. bid_ame Specifies the ame to be boud to the applicatio object or ame cotext object added to the amespace relative to either the root amig cotext retrieved from the Tobj_Bootstrap::resolve_iitial_refereces method, or the amig cotext idetified by the strigified IOR obtaied from the -f commad-lie optio. The bid_ame strig should coform to the ame strig form specified i the Object Maagemet Group (OMG) Iteroperable Name Service (INS) specificatio. Examples The followig example illustrates bidig a applicatio object: Usig the CORBA Name Service 2-7

22 2 CORBA Name Service Referece csbid -o./app_obj_ior.txt MyCotext/AppObject1 The followig example illustrates bidig a amig cotext object: csbid -N MyCotext/CtxObject1 The followig example illustrates bidig a federatio poit to aother amespace: csbid -C -o./remote_ior.txt MyCotext/RemoteNSCtx1 2-8 Usig the CORBA Name Service

23 CORBA Name Service Commads csls Syopsis Displays the cotets of the amespace. Note: The csls commad iteracts with the CosNamig iterfaces. The server process for the CORBA Name Service must be ruig to use this commad. Sytax Descriptio csls [-f root_cotext_fileame] [-h] [-s] [-R] [-T TobjAddr] [resolve_ame] The csls commad displays the cotets of the amespace usig the CORBA CosNamig iterfaces. If o-pritig characters are used as part of a NameCompoet data structure, the behavior of the csls commad is udefied. If a exceptio is retured whe the csls commad is ivoked, the commad exits ad a appropriate message is displayed. The commad-lie optios for the csls commad are as follows: -f root_cotext_fileame Specifies the file cotaiig the IOR of the server process for the CORBA Name Service with which the commad iteracts to modify the cotets of the amespace. If this commad-lie optio is ot specified, the commad uses the Tobj_Bootstrap::resolve_iitial_refereces() method with the NameService evirometal object to locate the server process for the CORBA Name Service i the specified BEA Tuxedo domai. The host ad port i the IOR must match the value of TObjAddr. This commad-lie optio overrides the settig for the TOBJADDR eviromet variable. If the commad-lie optio is ot specified, the value of the TOBJADDR eviromet variable is used. -h -s Prits the commad sytax. Displays the strigified IOR for the amespace ame specified i resolve_ame commad-lie optio. Usig the CORBA Name Service 2-9

24 2 CORBA Name Service Referece -R Recursively displays amespace bidigs begiig at resolve_ame. This commad-lie optio may cause the csls commad to cross federatio boudaries with o idicatio whe such a boudary is cross. Also, if cycles exist i the amespace iformatio, this commad-lie optio ca cause the csls commad to eter a loop. -T TObjAddr Specifies the host ad port for a BEA Tuxedo domai. Before coectig to a server process for the CORBA Name Service, the csls commad must log ito the BEA Tuxedo domai i which the server process is ruig. This commad-lie optio overrides the settig for the TOBJADDR eviromet variable. If the commad-lie optio is ot specified, the TOBJADDR eviromet variable is used. resolve_ame Specifies the ame to resolve i the ame service relative to either the root amig cotext retrieved via the Tobj_Bootstrap::resolve_iitial_refereces() method or the amig cotext idetified by the strigified IOR obtaied from the -f commad-lie optio. The resolve_ame strig should coform to the ame strig form specified i the OMG INS specificatio. The backslash (\) character is used to delimit ame compoets ad the period (.) character separates the id ad kid fields. If this commad-lie optio is ot specified, the root cotext is resolved. Example csls -R MyCotext.kid/AotherCotext [cotext] MyCotext.kid/AotherCotext [object] Obj1 [object] Obj2 [cotext] Ctx1 [object] AotherObject 2-10 Usig the CORBA Name Service

25 CORBA Name Service Commads csubid Syopsis Sytax Descriptio Removes bidigs from the amespace. csubid [-D] [-f root_cotext_fileame] [-h] [-T TObjAddr] bid_ame The csubid commad removes bidigs from the amespace. If a exceptio is retured whe the csubid commad is ivoked, the commad exits ad a appropriate message is displayed. The csubid commad-lie optios are as follows: -D Destroys the amig cotext boud to the bid_ame after removig the bidig. Specifyig the -D commad-lie optio whe deletig a cotext prevets the cotext from beig orphaed if it is ot part of aother bidig. This commad-lie optio should be used with care because it ca cause daglig bidigs (for example, if the bidig was boud to multiple amig cotext objects at the same time). -f root_cotext_fileame Specifies the file cotaiig the IOR of the server process for the CORBA Name Service with which the commad iteracts to modify the cotets of the amespace. If this commad-lie optio is ot specified, the commad uses the Tobj_Bootstrap::resolve_iitial_refereces() method with the NameService evirometal object to locate the server process for the specified BEA Tuxedo domai. -h Prits the commad sytax. -T TObjAddr Specifies the host ad port for a BEA Tuxedo domai. Before coectig to a server process for the CORBA Name Service, the csbid commad must log ito the BEA Tuxedo domai i which the server process is ruig. This commad-lie optio overrides the settig for the TOBJADDR eviromet variable. If the commad-lie optio is ot specified, the TOBJADDR eviromet variable is used. Usig the CORBA Name Service 2-11

26 2 CORBA Name Service Referece bid_ame Specifies the ame of the bidig to be removed from the amespace relative to either the root amig cotext retrieved via the Tobj_Bootstrap::resolve_iitial_refereces() method or the amig cotext idetified by the strigified IOR obtaied from the -f commad-lie optio. The bid_ame strig should coform to the ame strig form specified i the OMG INS specificatio. Examples The followig example illustrates removig a bidig from the amespace: csubid MyCotext/CtxObject1 The followig example illustrates removig a bidig from the amespace ad destroyig the object to which it was boud: csubid -D MyCotext/CtxObject1 Capabilities ad Limitatios of the CORBA Name Service The CORBA Name Service has the followig capabilities ad limitatios: A NULL character must oly be used to termiate the id ad kid strigs (empty strigs are cosidered valid). Wide characters are ot supported. The CORBA Name Service imposes o limit o the legth of the strigs i a ame compoet. The CORBA Name Service imposes o maximum o the umber of compoets i a ame. Zero legth ames are illegal. The CORBA Name Service imposes o limit o the umber of bidigs i a cotext. The CORBA Name Service imposes o limit o the umber of bidigs (implemetatio-wide). The CORBA Name Service imposes o limit o the umber of cotexts Usig the CORBA Name Service

27 Gettig the Iitial Referece to the NameService Evirometal Object The CORBA Name Service deletes orphaed amig cotexts ad daglig bidigs whe startig the server process for the CORBA Name Service. The CORBA Name Service deletes orphaed amig cotexts whe startig the server process for the CORBA Name Service. The CORBA Name Service offers the optio of cleaig up bidig iterator objects based o a least-recetly-used algorithm. For more iformatio, see Maagig Bidig Iterators o page 3-8. The CORBA Name Service does ot throw the CaotProceed exceptio. Gettig the Iitial Referece to the NameService Evirometal Object A NameService evirometal object is available for coectig to the root of the amespace. Whe usig the NameService evirometal object, the Object Request Broker (ORB) locates the root of the amespace. Use the Bootstrap object or the CORBA Iteroperable Namig Service (INS) bootstrappig mechaism to get a iitial referece to the NameService evirometal object. Use the BEA proprietary mechaism if you are usig the BEA cliet ORB. Use the CORBA INS mechaism is you are usig a cliet ORB from aother vedor. For more iformatio o coectig to the amespace, see Step 3: Coect to the BEA Tuxedo Namespace. For more iformatio about bootstrappig the BEA Tuxedo domai see Chapter 4, CORBA Bootstrappig Programmig Referece, i the CORBA Programmig Referece i the BEA Tuxedo olie documetatio. Usig the CORBA Name Service 2-13

28 2 CORBA Name Service Referece The CosNamig Data Structures Used by the CORBA Name Service The CORBA Name Service uses the followig CosNamig data structures: CosNamig::BidigList CosNamig::BidigType CosNamig::Istrig CosNamig::Name CosNamig::NameCompoet The NamigCotext Object The NamigCotext object is used to cotai ad maipulate a list of ames that are boud to Object Request Broker (ORB) objects or to other NamigCotext objects. BEA Tuxedo CORBA cliet applicatios use this iterface to resolve or list all the ames withi that cotext. BEA Tuxedo CORBA server applicatios use this object to bid ames to applicatio objects or amig cotext objects. Listig 2-1 shows the OMG IDL for the NamigCotext object. Listig 2-1 OMG IDL for the NamigCotext Object module CosNamig { iterface NamigCotext { void bid(i Name, i Object obj) raises(notfoud, CaotProceed, IvalidName, AlreadyBoud); void rebid(i Name, i Object obj) raises(notfoud, CaotProceed, IvalidName); void bid_cotext(i Name, i NamigCotext c) raises(notfoud, CaotProceed, IvalidName, AlreadyBoud); void rebid_cotext(i Name, i NamigCotext c) raises(notfoud, CaotProceed, IvalidName); Object resolve(i Name ) 2-14 Usig the CORBA Name Service

29 The NamigCotext Object } raises(notfoud, CaotProceed, IvalidName); void ubid(i Name ) raises(notfoud, CaotProceed, IvalidName); NamigCotext ew_cotext NamigCotext bid_ew_cotext(i Name ) raises(notfoud, CaotProceed, IvalidName, AlreadyBoud); void destroy() raises(notempty); void list(i usiged log how_may, out BidigList bl, out BidigIterator bi); } Usig the CORBA Name Service 2-15

30 2 CORBA Name Service Referece CosNamig::NamigCotext::bid() Syopsis C++ Mappig Java Mappig Attempts to bid the specified object to the specified ame by resolvig the cotext associated with the first NameCompoet data structure ad the bidig the object to the ew cotext. void bid(i Name, i Object obj); void bid (NameCompoet [], Object obj); Parameters obj A Name data structure, iitialized with the desired ame of the object. The object to bid to the supplied ame. Exceptios Descriptio Retur Value AlreadyBoud The Name o a bid() or a bid_cotext() method has already bee boud to aother object withi the amig cotext. IvalidName The specified Name has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The Name or oe of its compoets, could ot be foud. Namig cotexts boud with bid do ot participate i ame resolutio whe compoud ames are passed to be resolved. Noe Usig the CORBA Name Service

31 The NamigCotext Object CosNamig::NamigCotext::bid_cotext() Syopsis C++ Mappig Java Mappig This method is similar to the bid() method, except that the supplied Name is associated with a NamigCotext object. void bid_cotext(i Name, i NamigCotext c); void bid_cotext (NameCompoet [], NamigCotext c); Parameters c A Name data structure iitialized with the desired ame for the amig cotext. The first NameCompoet data structure i the sequece must resolve to a amig cotext. The NamigCotext object to be boud to the supplied ame. Exceptios Descriptio Retur Value AlreadyBoud The Name o a bid() or a bid_cotext() method has already bee boud to aother object withi the amig cotext. IvalidName The specified Name has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The Name or oe of its compoets, could ot be foud. BAD_PARAM Idicates the call attempted to bid a NULL cotext. Namig cotexts boud with bid_cotext() participate i ame resolutio whe compoud ames are passed to be resolved. Noe. Usig the CORBA Name Service 2-17

32 2 CORBA Name Service Referece CosNamig::NamigCotext::bid_ew_cotext() Syopsis C++ Mappig Java Mappig Creates a ew cotext ad bids it to the specified Name withi this cotext. NamigCotext bid_ew_cotext(i Name ); bid_ew_cotext (NameCompoet [] ); Parameter A Name data structure, iitialized with the desired ame for the ewly created NamigCotext object. Exceptios Descriptio Retur Value AlreadyBoud The Name o a bid() or a bid_cotext() method has already bee boud to aother object withi the amig cotext. IvalidName The specified Name has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The Name or oe of its compoets could ot be foud. This method combies the CosNamig::NamigCotext::ew_cotext() ad CosNamig::NamigCotext::bid_cotext() methods ito a sigle method. Returs a referece to a ew NamigCotext object Usig the CORBA Name Service

33 The NamigCotext Object CosNamig::NamigCotext::destroy() Syopsis C++ Mappig Java Mappig Parameter Exceptios Descriptio Retur Value Deletes a NamigCotext object. Ay subsequet attempt to ivoke methods o the NamigCotext object raises a CORBA::NO_IMPLEMENT exceptio. void destroy(); void destroy(); Noe. NotEmpty If the NamigCotext object cotais bidigs, the method raises NotEmpty. Before usig this method, all ame objects that have bee boud to the NamigCotext object should be uboud usig the CosNamig::NamigCotext::ubid() method. Noe. Usig the CORBA Name Service 2-19

34 2 CORBA Name Service Referece CosNamig::NamigCotext::list() Syopsis C++ Mappig Java Mappig Parameters Returs all of the bidigs cotaied by this amig cotext. void list(i usiged_log how_may, out BidigList bl, out BidigIterator bi); void list(it how_may, BidigListHolder bl, BidigIteratorHolder bi); how_may The maximum umber of bidigs to be retured i the list. bl bi A list of retured bidigs where each elemet is a bidig cotaiig a Name represetig a sigle NameCompoet object. Each Name is a simple ame, that is, a ame sequece of legth 1. The umber of bidigs i the list does ot exceed the value of how_may. A referece to a BidigIterator object for use i traversig the rest of the bidigs. Exceptios Descriptio Retur Value IvalidName The specified Name has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The Name or oe of its compoets could ot be foud. This method returs a sequece of ame bidigs. If more ame bidigs exist tha ca fit i the bl list, a BidigIterator object is retured. The BidigIterator object ca be used to get the ext set of bidigs. The BidigList (C++) or BidigListHolder (Java) object ca retur less tha the requested umber of bidigs if it is at the ed of the list. If bi returs a NULL referece, the bl cotais all of the bidigs. Noe Usig the CORBA Name Service

35 The NamigCotext Object CosNamig::NamigCotext::ew_cotext() Syopsis C++ Mappig Java Mappig Parameter Exceptios Descriptio Retur Value Creates a ew amig cotext. The ewly created cotext is iitially ot boud to ay Name. NamigCotext ew_cotext(); NamigCotext ew_cotext(); Noe. Noe. Use the CosNamig::NamigCotext::bid_cotext() method to bid the ew amig cotext to a Name. Returs a referece to a ew amig cotext. Usig the CORBA Name Service 2-21

36 2 CORBA Name Service Referece CosNamig::NamigCotext::rebid() Syopsis C++ Mappig Java Mappig This method is similar to the bid() method. The differece is that the rebid method does ot raise the AlreadyBoud exceptio. If the specified Name has already bee boud to aother object, that bidig is replaced by the ew bidig. void rebid(i Name, i Object obj); void rebid(namecompoet [], Object obj); Parameters obj A Name data structure, iitialized with the desired ame for the object. The object to be amed. Exceptios Descriptio Retur Value IvalidName The specified Name data structure has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The Name or oe of its compoets, could ot be foud. If this exceptio is raised because the bidig already exists or the bidig is of the wrog type, the rest_of_ame member of the exceptio has a legth of 1. Namig cotexts boud with the rebid()method do ot participate i ame resolutio whe compoud ames are passed to be resolved. Noe Usig the CORBA Name Service

37 The NamigCotext Object CosNamig::NamigCotext::rebid_cotext() Syopsis C++ Mappig Java Mappig This method is similar to the bid_cotext() method. The differece is that the rebid_cotext method does ot raise the AlreadyBoud exceptio. If the specified Name has already bee boud to aother object, that bidig is replaced by the ew bidig. void rebid_cotext(i Name, i NamigCotext c); void rebid_cotext(namecompoet [], NamigCotext c); Parameters c A Name data structure, iitialized with the desired ame for the object. The NamigCotext object to be reboud. Exceptios Descriptio Retur Value IvalidName The specified Name data structure has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The compoet of a ame does ot idetify a bidig or the type of bidig is icorrect for the operatio beig performed. If this exceptio is raised because a bidig already exists or it is of the wrog type, the rest_of_ame member of the exceptio has a legth of 1. Namig cotexts boud with the rebid_cotext method do ot participate i ame resolutio whe compoud ames are passed to be resolved. Noe. Usig the CORBA Name Service 2-23

38 2 CORBA Name Service Referece CosNamig::NamigCotext::resolve() Syopsis C++ Mappig Java Mappig Attempts to resolve the specified Name. Object resolve(i Name ); Object resolve (NameCompoet ); Parameters A Name data structure, iitialized with the desired ame for the object. Exceptios Descriptio Retur Value IvalidName The specified Name data structure has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The compoet of a ame does ot idetify a bidig or the type of bidig is icorrect for the operatio beig performed. The specified Name must exactly match the ame used to bid the object. The CORBA Name Service does ot retur the type of the object. Cliet applicatios are resposible for arrowig the object to the appropriate type. Returs the object referece for the specified Name Usig the CORBA Name Service

39 The NamigCotextExt Object CosNamig::NamigCotext::ubid() Syopsis C++ Mappig Java Mappig Performs the iverse operatio of the bid() method, removig the bidig associated with the specified Name. void ubid(i Name ); void ubid (NameCompoet [] ); Parameters A Name data structure, iitialized with the desired ame for the object. Exceptios Descriptio Retur Value IvalidName The specified Name data structure has zero ame compoets or oe of the first ame compoets did ot resolve to a amig cotext. NotFoud The compoet of a ame does ot idetify a bidig or the type of bidig is icorrect for the operatio beig performed. This method removes the bidig betwee a ame ad a object. It does ot delete the object. Use the CosNamig::NamigCotext::ubid() method ad the the CosNamig::NamigCotext::destroy() method to delete the object. Noe. The NamigCotextExt Object The NamigCotextExt object provides methods to use URLs ad strigified ames i the CORBA Name Service. The NamigCotextExt object is derived from the NamigCotext object. Note that the root of the CORBA Name Service is a NamigCotextExt object (which meas the root is also a NamigCotext object). No special operatio is eeded to obtai a referece to a NamigCotextExt object. Listig 2-2 shows the OMG IDL for the NamigCotextExt object. Usig the CORBA Name Service 2-25

40 2 CORBA Name Service Referece Listig 2-2 OMG IDL for the NamigCotextExt Object module CosNamig { iterface NamigCotextExt : NamigCotext { typedef strig StrigName; typedef strig Address; typedef strig URLStrig; StrigName to_strig(i Name ) raises(ivalidname); Name to_ame(i StrigName s) raises(ivalidname); exceptio IvalidAddress {}; } } URLStrig to_url(i Address addr, i StrigName s) raises(ivalidaddress, IvalidName); Object resolve_str(i StrigName ) raises(notfoud, CaotProceed, IvalidName, AlreadyBoud); 2-26 Usig the CORBA Name Service

41 The NamigCotextExt Object CosNamig::NamigCotextExt::resolve_str() Syopsis Sytax Parameter Exceptios Descriptio Retur Value Takes a strigified ame, coverts it to a Name, ad resolves it. object resolve_str(i StrigName ); The strigified ame to be resolved. IvalidName The ame is ivalid. A ame of legth zero is ivalid. NotFoud The compoet of the ame does ot idetify a bidig or the type of the bidig is icorrect for the operatio beig performed. This is a coveiece method that performs a resolve i the same maer as the CosNamig:NamigCotext::resolve() method. The method accepts a strigified ame as a argumet istead of a Name object. The method returs errors if the strigified ame is ivalid or if the method caot bid it. A referece to the boud ame. Usig the CORBA Name Service 2-27

42 2 CORBA Name Service Referece CosNamig::NamigCotextExt::to_ame() Syopsis Sytax Takes a strigified ame ad returs a Name object. Name to_ame(i StrigName s); Parameter s The strigified ame to be resolved to a Name object. Exceptios Descriptio Retur Value IvalidName The ame is ivalid. A ame of legth zero is ivalid. This method accepts a strigified ame ad returs a Name object. The method returs errors if the ame is ivalid. Returs a Name object Usig the CORBA Name Service

43 The NamigCotextExt Object CosNamig::NamigCotextExt::to_strig() Syopsis Sytax Accepts a Name object ad returs a strigified ame. StrigName to_strig(i Name ); Parameter The Name object to be coverted to strigified ame Exceptios Descriptio Retur Value IvalidName The ame is ivalid. A ame of legth zero is ivalid. This method accepts a Name object ad returs a strigified ame. It returs errors if the ame is ivalid. Returs a strigified ame. Usig the CORBA Name Service 2-29

44 2 CORBA Name Service Referece CosNamig::NamigCotextExt::to_URL() Syopsis Sytax Combies a URL ad a strigified ame ad returs a URL strig. CosNamig::NamigCotextExt::to_URL() URLStrig to_url(i Address addr, i StrigName s); Parameter addr s A URL. If this parameter is ot defied, the local host ame is used with the IIOP protocol. The strigified ame to be combied with the URL. Exceptios Retur Value IvalidAddress The URL is ivalid. IvalidName The ame is ivalid. A ame of legth zero is ivalid. Returs a URL strig that combies the URL ad the strigified ame. The BidigIterator Object The BidigIterator object allows a cliet applicatio to walk through the ubouded collectio of bidigs retured by the list method of a NamigCotext object. Usig the BidigIterator object, a cliet applicatio ca cotrol the umber of bidigs obtaied with each call. If a amig cotext is modified betwee calls to the methods of a BidigIterator object, the behavior of further calls to the ext_oe() method or the ext_() method is implemetatio specific. If a cliet applicatio creates BidigIterator objects but ever calls the destroy method, the cliet applicatio ca ru out of resources. The CORBA Name Service is free to destroy bidig iterators at ay time ad without warig to the cliet applicatio. Cliet applicatios should be writte to expect the OBJECT_NOT_EXIST excep Usig the CORBA Name Service

45 The BidigIterator Object tio from calls to a BidigIterator object ad to hadle this exceptio gracefully. Listig 2-3 shows the OMG IDL for the BidigIterator object. Listig 2-3 OMG IDL for BidigIterator Object module CosNamig { iterface BidigIterator { boolea ext_oe(out Bidig b); boolea ext_(i usiged log how_may, out BidigList b); void destroy(); }; } Usig the CORBA Name Service 2-31

46 2 CORBA Name Service Referece CosNamig::BidigIterator::destroy() Syopsis C++ Mappig Java Mappig Parameter Exceptios Descriptio Retur Value Destroys the BidigIterator object ad releases the memory associated with the object. Failure to call this method results i icreased memory usage. void destroy(); void destroy(); Noe. Noe. If a cliet applicatio ivokes ay operatio o a BidigIterator object after callig the destroy method, the operatio raises a OBJECT_NOT_EXIST exceptio. Noe Usig the CORBA Name Service

47 The BidigIterator Object CosNamig::BidigIterator::ext_() Syopsis C++ Mappig Java Mappig Parameter Returs a BidigList data structure cotaiig the umber of requested bidigs from the list. The umber of bidigs retured may be less tha the requested amout if the list is exhausted. boolea ext_(i usiged_log how_may, out BidigList bl); boolea ext_(it how_may, BidigListHolder bl); how_may The maximum umber of bidigs to retur. bl A BidigList data structure cotaiig o more tha the requested umber of bidigs. Exceptios Retur Value BAD_PARAM Raised if the how_may parameter has a value of zero. CORBA::FALSE is retured whe the list has bee exhausted. Otherwise, CORBA::TRUE is retured. Usig the CORBA Name Service 2-33

48 2 CORBA Name Service Referece CosNamig::BidigIterator::ext_oe() Syopsis C++ Mappig Java Mappig Returs the ext Bidig object i the list. boolea ext_oe(out Bidig b); boolea ext_oe(bidigholder b); Parameter Exceptios b Noe. The ext Bidig object from the list. Retur Value CORBA::FALSE is retured whe the list has bee exhausted. Otherwise, CORBA::TRUE is retured. Exceptios Raised by the CORBA Name Service This sectio describes the exceptios raised by the CORBA Name Service Usig the CORBA Name Service

49 Exceptios Raised by the CORBA Name Service AlreadyBoud Sytax Parameter Descriptio exceptio AlreadyBoud{}; Noe. This exceptio is raised whe a object is already boud to the supplied ame. Oly oe object ca be boud to a ame i a cotext. Usig the CORBA Name Service 2-35

50 2 CORBA Name Service Referece CaotProceed Sytax Parameters Descriptio exceptio CaotProceed{}; NamigCotext cxt The cotext that the operatio may be able to retry from. Name rest_of_ame The remaider of the o workig ame. This exceptio is raised whe a uexpected exceptio is ecoutered ad the method caot proceed i a meaigful way Usig the CORBA Name Service

51 Exceptios Raised by the CORBA Name Service IvalidAddress Sytax Parameter Descriptio exceptio IvalidAddress{}; Noe. This exceptio is raised if a URL is ivalid. Usig the CORBA Name Service 2-37

52 2 CORBA Name Service Referece IvalidName Sytax Parameter Descriptio exceptio IvalidName{}; Noe. This exceptio is raised if a Name is ivalid. A ame legth of zero is ivalid Usig the CORBA Name Service

53 Exceptios Raised by the CORBA Name Service NotEmpty Sytax Parameter Descriptio exceptio NotEmpty{}; Noe. This exceptio is raised whe the destroy()method is used o a NamigCotext object that cotais bidigs. A NamigCotext object must be empty before it is destroyed. Usig the CORBA Name Service 2-39

54 2 CORBA Name Service Referece NotFoud Sytax Parameters Descriptio exceptio NotFoud{NotFoudReaso why; Name rest_of_ame;}; why The cotext that the operatio may be able to retry from. rest_of_ame The remaider of the o-workig ame. This exceptio is raised whe a compoet of the ame does ot idetify a bidig, or if the type of bidig is icorrect for the operatio beig performed. The why parameter explais the reaso for the error. The rest_of_ame parameter idetifies the cause of the error. The followig causes ca appear: missig_ode the first ame compoet i the rest_of_ame parameter is a bidig that is ot boud uder that ame withi its paret cotext. ot_cotext the first ame compoet i the rest_of_ame parameter is a bidig with a type of object whe the type of cotext was required. ot_object the first ame compoet i the rest_of_ame parameter is a bidig with a type of cotext whe the type of object was required Usig the CORBA Name Service

55 CHAPTER 3 Maagig a BEA Tuxedo Namespace This topic icludes the followig sectios: Istallig the CORBA Name Service Startig the Server Process for the CORBA Name Service Makig the Namespace Persistet Compressig the Persistet Storage File Removig Orpha NamigCotext Objects Federatig the Namespace Maagig Bidig Iterators Istallig the CORBA Name Service You istall the CORBA Name Service whe you istall BEA Tuxedo. For complete iformatio about istallig BEA Tuxedo, see Istallig the BEA Tuxedo System. Usig the CORBA Name Service 3-1

56 3 Maagig a BEA Tuxedo Namespace Startig the Server Process for the CORBA Name Service To start the server process for the CORBA Name Service, you eed to defie the server process i the UBBCONFIG file for your BEA Tuxedo CORBA applicatio. Use the cs commad to start the server process for the CORBA Name Service. List the cs commad-lie optios after the CLOPT parameter i the UBBCONFIG file. Note there ca be oly oe CORBA Name Service server process ruig per BEA Tuxedo domai. Listig 3-1 is a example of the UBBCONFIG etry for the server process for the CORBA Name Service. Listig 3-1 UBBCONFIG File Etry for the CORBA Name Service... # #Server process for BEA Tuxedo CORBA Name Service # cs SRVGRP = SYS_GRP SRVID = 6 RESTART = N CLOPT = "-A -- -f C:\csroot.dat -M 0" For a complete descriptio of the cs commad ad its optios, see Chapter 2, CORBA Name Service Referece. For iformatio about creatig a cofiguratio file, see Settig Up a BEA Tuxedo Applicatio i the BEA Tuxedo olie documetatio. Oce the server process for the CORBA Name Service is started, you ca use the commads listed i Table 3-1 to display the cotets of the amespace ad maage objects i the amespace. For a complete descriptio of the commads ad their optios, see Chapter 2, CORBA Name Service Referece. 3-2 Usig the CORBA Name Service