BEA Tuxedo. Using the CORBA Notification Service

Transcription

1 BEA Tuxedo Usig the CORBA Notificatio Service BEA Tuxedo 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. Usig the CORBA Notificatio Service Documet Editio Date Software Versio 8.0 Jue 2001 BEA Tuxedo 8.0

3 Cotets About This Documet What You Need to Kow...x e-docs Web Site...x How to Prit the Documet...x Related Iformatio... xi Cotact Us!... xi Documetatio Covetios... xii 1. Overview Itroductio Fuctioal Overview Product Compoets CORBA Notificatio Service API Referece Itroductio Quality of Service Obtaiig the Chael Factory Usig Trasactios Structured Evet Fields, Types, ad Filters Desigig Evets Creatig FML Field Table Files for Evets Iteroperability with BEA Tuxedo Applicatios Parameters Used Whe Creatig Subscriptios BEA Simple Evets API TOBJ_SimpleEvets::Chael Iterface Chael::subscribe Chael::usubscribe Usig the CORBA Notificatio Service iii

4 Chael::push_structured_evet Chael::exists TOBJ_SimpleEvets::ChaelFactory Iterface Chael_Factory::fid_chael CosNotificatio Service API Overview of Supported CosNotificatio Service Classes Detailed Descriptios of CosNotificatio Service Classes CosNotifyFilter::Filter::add_costraits CosNotifyFilter::Filter::destroy CosNotifyFilter::FilterFactory::create_filter CosNotifyChaelAdmi::StructuredProxyPushSupplier:: coect_structured_push_cosumer CosNotifyChaelAdmi::StructuredProxyPushSupplier::set_qos CosNotifyChaelAdmi::StructuredProxyPushSupplier::add_filter CosNotifyChaelAdmi::StructuredProxyPushSupplier::get_filter2-43 CosNotifyChaelAdmi::StructuredProxyPushSupplier:: discoect_structured_push_supplier CosNotifyChaelAdmi::StructuredProxyPushSupplier::MyType 2-45 CosNotifyChaelAdmi::StructuredProxyPushCosumer:: coect_structured_push_supplier CosNotifyChaelAdmi::StructuredProxyPushCosumer:: push_structured_evet CosNotifyChaelAdmi::StructuredProxyPushCosumer:: discoect_structured_push_cosumer CosNotifyChaelAdmi::StructuredProxyPushCosumer::MyType CosNotifyChaelAdmi::CosumerAdmi:: obtai_otificatio_push_supplier CosNotifyChaelAdmi::CosumerAdmi::get_proxy_supplier CosNotifyChaelAdmi::SupplierAdmi:: obtai_otificatio_push_cosumer CosNotifyChaelAdmi::EvetChael:: CosumerAdmi default_cosumer_admi CosNotifyChaelAdmi::EvetChael:: CosumerAdmi default_supplier_admi iv Usig the CORBA Notificatio Service

5 CosNotifyChaelAdmi::EvetChael::default_filter_factory CosNotifyChaelAdmi::EvetChaelFactory::get_evet_chael CosNotifyComm::StructuredPushCosumer::push_structured_evet CosNotifyComm::StructuredPushCosumer:: discoect_structured_push_cosumer CosNotifyComm::StructuredPushCosumer::Offer_chage Exceptio Mior Codes Usig the BEA Simple Evets API Developmet Process Desigig Evets Step 1: Writig a Applicatio to Post Evets Gettig the Evet Chael Creatig ad Postig Evets Step 2: Writig a Applicatio to Subscribe to Evets Implemetig the CosNotifyComm::StructuredPushCosumer Iterface. 3-7 Gettig the Evet Chael Creatig a Callback Object Creatig a Subscriptio Step 3: Compilig ad Ruig Notificatio Service Applicatios Geeratig the Cliet Stub ad Skeleto Files Buildig ad Ruig Applicatios Usig the CosNotificatio Service API Developmet Process Desigig Evets Step 1: Writig a Applicatio to Post Evets Gettig the Evet Chael Creatig ad Postig Evets Step 2: Writig a Applicatio to Subscribe to Evets Implemetig the CosNotifyComm::StructuredPushCosumer Iterface. 4-8 Gettig the Evet Chael, CosumerAdmi Object, ad Filter Factory Object Creatig a Callback Object Usig the CORBA Notificatio Service v

6 Creatig a Subscriptio Step 3: Compilig ad Ruig Notificatio Service Applicatios Geeratig the Cliet Stub ad Skeleto Files Compilig ad Likig the Applicatio Code Buildig the Itroductory Sample Applicatio Overview Buildig ad Ruig the Itroductory Sample Applicatio Verifyig the Settigs of the Eviromet Variables Copyig the Files for the Itroductory Sample Applicatio ito a Work Directory Chagig the Protectio Attribute o the Files for the Itroductory Sample Applicatio Settig Up the Eviromet Buildig the Itroductory Sample Applicatio Startig the Itroductory Sample Applicatio Usig the Itroductory Sample Applicatio Shuttig Dow the System ad Cleaig Up the Directory Buildig the Advaced Sample Applicatio Overview Buildig ad Ruig the Advaced Sample Applicatio Verifyig the Settigs of the Eviromet Variables Copyig the Files for the Advaced Sample Applicatio ito a Work Directory Chagig the Protectio Attribute o the Files for the Advaced Sample Applicatio Settig Up the Eviromet Buildig the Advaced Sample Applicatio Startig the Advaced Sample Applicatio Usig the Advaced Sample Applicatio Shuttig Dow the System ad Cleaig Up the Directory CORBA Notificatio Service Admiistratio Itroductio Cofigurig the Notificatio Service vi Usig the CORBA Notificatio Service

7 Idex Cofigurig Data Filters...23 Settig the Host ad Port...25 Creatig a Trasactio Log...27 Creatig Evet Queues...27 Determiig Space Parameters for Trasiet ad Persistet Subscriptios 28 Creatig a Device o Disk for the Queue Space...31 Cofigurig a Queue Space...31 Creatig the Queues...32 Settig IPC Parameters o Microsoft Widows...34 Creatig the UBBCONFIG File ad the TUXCONFIG File...37 Maagig the Notificatio Service...43 Sychroizig Databases...44 Purgig the System of Dead Subscriptios...44 Moitorig Queue Utilizatio...45 Purgig the Queues of Uwated Evets...46 Maagig the Error Queue...46 Notificatio Service Admiistratio Utility ad Commads...47 tsadmi Utility...47 tsadmi...48 tsadmi Commads...49 Usig the tsadmi Utility...52 Notificatio Servers...54 TMNTS...55 TMNTSFWD_T...56 TMNTSFWD_P...57 Usig the CORBA Notificatio Service vii

8 viii Usig the CORBA Notificatio Service

9 About This Documet This documet describes usig the CORBA Notificatio Service i the BEA Tuxedo product. This documet defies cocepts associated with usig the Notificatio Service ad describes the developmet process for CORBA applicatios. I additio, istructios for buildig ad ruig the Notificatio sample applicatios ad descriptios of the Notificatio Service applicatio programmig iterface (API) ad admiistrative tasks ad tools are icluded i this documet. This documet icludes the followig topics: t t t t t t t Chapter 1, Overview, provides a basic descriptio of the Notificatio Service ad its compoets. Chapter 2, CORBA Notificatio Service API Referece, describes the applicatio programmig iterfaces supported by the Notificatio Service software. Chapter 3, Usig the BEA Simple Evets API, describes how to develop Notificatio Service applicatios usig the BEA Simple Evets API i C++ ad Java. Chapter 4, Usig the CosNotificatio Service API, describes how to develop Notificatio Service applicatios usig the CosNotificatio API i C++ ad Java. Chapter 5, Buildig the Itroductory Sample Applicatio, provides a overview of the Itroductory sample applicatio ad describes how to build ad ru it. Chapter 6, Buildig the Advaced Sample Applicatio, provides a overview of the Advaced sample applicatio ad describes how to build ad ru it. Chapter 7, CORBA Notificatio Service Admiistratio, describes the admiistrative tasks ad tools provided with the Notificatio Service software. Usig the CORBA Notificatio Service ix

10 What You Need to Kow This documet is iteded for system admiistrators ad programmers who desig, develop, cofigure, ad maage Notificatio Service applicatios. 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 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 the Adobe Acrobat Reader istalled, you ca dowload it for free from the Adobe Web site at x Usig the CORBA Notificatio Service

11 How to Prit the Documet Related Iformatio For more iformatio about CORBA, BEA Tuxedo, distributed object computig, trasactio processig, C++ programmig, see the BEA Tuxedo 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. 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 Usig the CORBA Notificatio Service xi

12 Documetatio Covetios The followig documetatio covetios are used throughout this documet. Covetio boldface text Ctrl+Tab italics moospace text moospace boldface text moospace italic text UPPERCASE TEXT Item Idicates terms defied i the glossary. Idicates that you must press two or more keys simultaeously. 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 xii Usig the CORBA Notificatio Service

13 Documetatio Covetios Covetio Item { } 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.... 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 Notificatio Service xiii

14 xiv Usig the CORBA Notificatio Service

15 CHAPTER 1 Overview This topic icludes the followig sectios: Itroductio Fuctioal Overview Product Compoets Itroductio The Notificatio Service provides a evet service for the BEA Tuxedo CORBA eviromet. It is ot meat to be a stadaloe product, but rather a layered product o BEA Tuxedo. The Notificatio Service offers similar capabilities to those of the BEA Tuxedo EvetBroker, but with a programmig model ad iterface that is atural for CORBA users. A side effect of this approach is that the majority of the CORBA-based Notificatio Service is ot supported sice it is either icompatible with, or provides capabilities well beyod that of the BEA Tuxedo EvetBroker. The Notificatio Service is a BEA Tuxedo subsystem that receives evet postig messages, filters them, ad distributes them to subscribers. A poster is a BEA Tuxedo CORBA applicatio that detects whe a evet of iterest has occurred ad reports (posts) it to the Notificatio Service. A subscriber is a BEA Tuxedo CORBA applicatio that requests that some otificatio actio be take whe a evet of iterest is posted. Usig the CORBA Notificatio Service 1-1

16 1 Overview The cocept of a aoymous service the Notificatio Service that receives ad distributes messages provides aother cliet-server commuicatio paradigm to BEA Tuxedo CORBA eviromet. Istead of a oe-to-oe relatioship betwee a requester ad a provider, a arbitrary umber of posters ca post a message for a arbitrary umber of subscribers. The posters simply post evets, without kowig who receives the iformatio or what is doe about it. The subscribers ca receive whatever iformatio they are iterested i from the Notificatio Service, without kowig who posted it, ad subscribers ca be otified ad take actio i a variety of ways. Typically, Notificatio Service applicatios are desiged to hadle exceptio evets. The applicatio desiger has to decide what evets i the applicatio eed to be moitored. I a bakig applicatio, for example, a evet might be posted for a uusually large withdrawal trasactio; but it would ot be particularly useful to post a evet for every withdrawal trasactio. Ad ot all users would eed to subscribe to that evet; perhaps just the brach maager, would eed to be otified. The programmig model for the Notificatio Service is based o the CORBA programmig model. There are two sets of iterfaces: oe is a miimal subset of the CORBA-based Notificatio Service iterface (referred to i this documet as the CosNotificatio Service iterface), ad the other is the BEA Simple Evets iterface (a BEA proprietary iterface) desiged to be easy to use. Both iterfaces pass stadard, structured evets, as defied by the CORBA-based Notificatio Service specificatio. The two iterfaces are compatible with each other; that is, evets posted usig the CosNotificatio Service iterface ca be subscribed to by the BEA Simple Evets iterface ad vice versa. Fuctioal Overview The Notificatio Service system comprises three basic compoets (see Figure 1-1): The evet poster, or supplier. The supplier is the producer of evets. It creates evets ad posts them to the Notificatio Service. The Notificatio Service, also kow as the evet chael. The Notificatio Service processes evets. 1-2 Usig the CORBA Notificatio Service

17 Fuctioal Overview The evet subscriber, or cosumer. The cosumer is the recipiet of the evets. It coects to the Notificatio Service ad subscribes to some set of evets. Whe the Notificatio Service receives a evet that matches a cosumer s subscriptio, it attempts to deliver the evet to that cosumer. There ca be may suppliers ad cosumers. Logically, there is oly oe Notificatio Service, eve though the Notificatio Service ca be replicated. Figure 1-1 Notificatio Service Model Evet Poster push Notificatio Service Subscribe push Evet Subscriber Accordig to the CORBA-based Notificatio Service specificatio, evet posters always use the push model. Thus, evet posters push evets to the Notificatio Service by ivokig a operatio. The Notificatio Service takes resposibility for filterig ad deliverig the evet. There is o direct associatio betwee evet posters ad evet subscribers. At ay poit i time there may be zero, oe, or may evet posters or evet subscribers. Also, accordig to the CORBA-based Notificatio Service specificatio, subscribers ca select oe of two evet delivery models, push or pull. Oly the push model is supported i this release of BEA Tuxedo. Thus, the Notificatio Service pushes evets to the cosumer by ivokig a operatio o the cosumer. Depedig o the Quality of Service (QoS) of the matchig subscriptio, the evet might be stored durably, pedig delivery to the cosumer. Usig the CORBA Notificatio Service 1-3

18 1 Overview Product Compoets The BEA Tuxedo CORBA Notificatio Service supports the followig: A BEA Simple Evets applicatio programmig iterface (API) for ease-of-use. A miimal set of operatios defied by the CosNotificatio Service API. Two Qualities of Service (QoS) for subscriptios: trasiet ad persistet. For trasiet subscriptios, the Notificatio Service makes oly oe attempt to deliver the evet to a subscriber. If that attempt fails, the evet is discarded ad if the Notificatio Service determies that the subscriber is shutdow or otherwise ot available, the subscriptio is cacelled. For persistet subscriptios, if the first delivery attempt fails, the Notificatio Service holds the evet ad keeps attemptig to deliver the subscriptio util the cofigurable retry limit is reached. After the retry limit is reached, the Notificatio Service moves the evet to a error queue, where it is held for dispositio by the system admiistrator. The system admiistrator either removes the evet from the error queue, which i effect discards it, or moves it back to the pedig queue so that further attempts to deliver it ca be made. Usig the UBBCONFIG file for iitial cofiguratio of the system, evet queues, ad server processes. Usig the BEA Tuxedo style FML field tables. Through the use of FML field tables, the Notificatio Service ca support: l l Evet data filterig betwee evet posters ad evet subscribers. Iteroperability with BEA Tuxedo EvetBroker such that evets posted by the Notificatio Service ca be cosumed by the Tuxedo EvetBroker ad vice versa. Usig the followig BEA Tuxedo Notificatio Service servers to process evets: l l l TMNTS TMNTSFWD_P TMNTSFWD_T Usig the followig BEA Tuxedo system servers to process evets: 1-4 Usig the CORBA Notificatio Service

19 Product Compoets l l l l TMSYSEVT TMUSREVT TMQUEUE TMQFORWARD Usig the BEA Tuxedo tsadmi admiistrative utility to maage evet queues. Usig the BEA Tuxedo qmadmi admiistrative utility to cofigure ad maage evet queues. Usig the BEA Tuxedo tmadmi admiistrative utility to cofigure ad maage trasactio logs. Usig the CORBA Notificatio Service 1-5

20 1 Overview 1-6 Usig the CORBA Notificatio Service

21 CHAPTER 2 CORBA Notificatio Service API Referece This topic icludes the followig sectios: Itroductio BEA Simple Evets API CosNotificatio Service API Itroductio The BEA Tuxedo CORBA Notificatio Service supports two applicatio programmig iterfaces. Oe is based o the CORBA-based Notificatio Service as defied by the CORBAservices: Commo Object Services Specificatio. This iterface is referred to i this documet as the CosNotificatio Service iterface. The other iterface, called the BEA Simple Evets iterface, is a BEA proprietary iterface desiged as a easier to use alterative. Both iterfaces pass structured evets as defied by the CORBA-based Notificatio Service specificatio ad are compatible with each other; that is, evets posted usig the CosNotificatio Service iterface ca be subscribed to by the BEA Simple Evets iterface ad vice versa. Before usig the Notificatio Service APIs, cosider the followig topics: Quality of Service Usig the CORBA Notificatio Service 2-1

22 2 CORBA Notificatio Service API Referece Obtaiig the Chael Factory Usig Trasactios Structured Evet Fields, Types, ad Filters Creatig FML Field Table Files for Evets Iteroperability with BEA Tuxedo Applicatios Quality of Service Persistet Subscriptios To determie the persistece of the subscriptio ad whether or ot evets delivery is retried followig a failed delivery, subscribers specify a Quality of Service (QoS). There are two Quality of Service settigs: persistet ad trasiet Quality of Service (QoS). The QoS is a property of the subscriptio. Persistet subscriptios provide strog guaratees about evet delivery ad the permaece of the subscriptio. Persistet subscriptios do come with a cost, however, as they cosume more system resources (for example, disk space, CPU cycles, ad so o), ad require more admiistratio (such as maagig queues ad detectig dead subscribers). Persistet subscriptios exhibit the followig properties: The subscriptio is i effect util a usubscribe operatio is performed. This meas that a subscriber applicatio ca be shut dow ad its subscriptio ca still be active. I this case, evets are stored for the subscriber ad, whe the subscriber restarts, are delivered to the subscriber without it havig to recreate the subscriptio. If a evet caot be delivered, evet delivery is retried util the admiistrative retry limit is exceeded.whe the evet retry limit has bee exceeded, the evet is moved from the pedig queue to a error queue. A admiistrator ca move evets from the error queue back to the pedig queue, where delivery attempts will restart. 2-2 Usig the CORBA Notificatio Service

23 Itroductio If a evet is successfully delivered to a subscriber, but the Notificatio Service for some reaso does ot receive the successful delivery retur message, the Notificatio Service may deliver the same evet more tha oce. Trasiet Subscriptios Trasiet subscriptios provide the best performace with the least overhead ad exhibit the followig properties: Oe attempt is made to deliver the evet to each matchig subscriptio. If that attempt fails, the evet is lost. The subscriptio is i effect util a failed evet delivery is detected. O detectio of a failed delivery, the subscriptio is termiated. Normally, the Notificatio Service, for performace reasos, does ot check whether it successfully delivered a evet to a trasiet subscriber. However, occasioally, whe the Notificatio Service delivers a evet to a trasiet subscriber, it checks whether or ot the evet was successfully delivered. If it was ot successfully delivered ad the CORBA::TRANSIENT exceptio is ot retured, the Notificatio Service assumes that the subscriptio has goe away ad cacels the subscriptio. If the Notificatio Service receives the CORBA::TRANSIENT exceptio whe a attempt to deliver fails, it assumes that the subscriber is busy ad discards the evet, but it does ot cacel the subscriptio. The automatic cacellatio of dead trasiet subscriptios provides a cleaup mechaism for trasiet subscribers that forget to usubscribe. Note, however, that the Notificatio Service checks for successful delivery the first time it seds a evet to a subscriber, but does ot perform it agai util five miutes have elapsed ad it delivers aother evet. Therefore, the iterval betwee checks is at least five miutes, but will be loger if there is o evet to deliver whe five miutes have elapsed. The miimum iterval of five miutes is fixed ad caot be chaged. Therefore, evet delivery failure is ot ecessarily detected o the first failed delivery attempt. It is oly detected whe the Notificatio Service checks. Obtaiig the Chael Factory The Chael Factory is used by evet poster applicatios ad subscriber applicatios to fid the evet chael. The evet chael is the used to post evets ad to subscribe, or create subscriptios, ad usubscribe, or cacel subscriptios. Usig the CORBA Notificatio Service 2-3

24 2 CORBA Notificatio Service API Referece Notificatio Service applicatios use the Bootstrap object to obtai a object referece to the evet chael factory. This is doe by usig the Tobj_Bootstrap::resolve_iitial_refereces operatio. The Bootstrap object supports two service IDs for Notificatio Service applicatios, NotificatioService ad Tobj_SimpleEvetsService. The NotificatioService object is used i applicatios that use the CosNotificatio Service API. The Tobj_SimpleEvetsService object is used i applicatios that use the BEA SimpleEvets API. Service ID NotificatioService Tobj_SimpleEvetsService Object Type CosNotifyChaelAdmi::EvetChaelFactory Tobj_SimpleEvets::ChaelFactory Note: Release 8.0 of BEA Tuxedo CORBA cotiues to iclude the BEA cliet evirometal objects provided i previous releases of BEA WebLogic Eterprise for use with the Tuxedo 8.0 CORBA cliets. BEA Tuxedo 8.0 cliets should cotiue to use these evirometal objects to resolve iitial refereces bootstrappig, security ad trasactio objects. I release 8.0 of BEA Tuxedo CORBA, support has bee added for usig the OMG Iteroperable Namig Service (INS) to resolve iitial refereces to bootstrappig, security, ad trasactio objects. For iformatio o INS, see the CORBA Programmig Referece. Usig Trasactios The behavior regardig trasactios is the same for the BEA SimpleEvets API ad the CosNotificatio Service API. The oly operatio that supports trasactioal behavior is push_structured_evet, which is supported by the CosNotifyChaelAdmi::StructuredProxyPushCosumer ad Tobj_SimpleEvets::Chael iterfaces. All other operatios ca be used i the cotext of a trasactio, but work the same regardless of whether they are executed i a trasactio or ot. The behavior whe postig a evet is tied to the QoS of the subscriptio. If a evet is posted i the cotext of a trasactio, ad the evet delivery QoS of the subscriptio is persistet, the delivery will be affected by the outcome of the trasactio; that is, if 2-4 Usig the CORBA Notificatio Service

25 Itroductio the trasactio is committed, the Notificatio Service attempts to deliver the evet to subscribers as it ormally would. If the trasactio is rolled back, the the Notificatio Service does ot attempt to deliver the evet. If a evet is posted i the cotext of a trasactio, ad the evet delivery QoS of the subscriber s subscriptio is trasiet, oe attempt will be made to deliver the evet, regardless of the trasactio outcome. That is, the trasactio has o effect o whether the evet is delivered or ot, ad oe attempt will be made to deliver the evet. Note: There is o trasactio cotext associated with evet delivery. However, i the case of persistet subscriptios, oce the poster s trasactio commits, the Notificatio Service guaratees that the evet will be delivered to the subscriber or put o the error queue to await admiistrative actio. Structured Evet Fields, Types, ad Filters All evets that are either pushed by posters to the Notificatio Service, or delivered to subscribers, are COS Structured Evets; that is, they coform to the defiitio of Structured Evets as specified by the CORBA-based Notificatio Service a service which exteds the CORBAservices Evet Service (see Figure 2-1). If the evets are to be filtered based o cotet (versus filterig o domai ad type), or if the evets are goig to be subscribed to by BEA Tuxedo applicatios, the additioal restrictios apply. The restrictios apply to data types ad filterig based o evet cotet. These restrictios are explaied below. Usig the CORBA Notificatio Service 2-5

26 2 CORBA Notificatio Service API Referece Figure 2-1 Structured Evet Evet Header domai_ame type_ame evet_ame priority Fixed Header Variable Header ame value Evet Body ame ame... value value Filterable Body Fields remaider_of_body Remaiig Body The Fixed Header sectio cosists of three fields that ca be used whe you create structured evets: fixed_header.evet_type.domai_ame ad fixed_header.evet_type.type_ame, ad fixed_header.evet_type.evet_ame. Whe a evet is posted all three of the these fields are passed i the Notificatio Service. However, whe subscriptios are created, oly the first two fields, domai_ame ad type_ame, are used to filter evets. These fields are defied i the subscriptio as regular expressios. The evet_ame field caot be used i subscriptios. The Variable Header cosists of a sigle ame/value (NV) pair, amely Priority. Priority ca take a value i the rage (versus a rage of to as specified i CORBA Notificatio Service specificatio). Priority is used iterally to the system to prioritize the processig of evets. The highest priority is 100. There is o guaratee that higher priority evets will, i fact, be give priority over lower priority evets. The support provided for the Variable Header differs from that specified i the CORBA Notificatio Service specificatio i two ways: first, there is a sigle field supported (Priority) versus the five fields listed i the specificatio; ad secod, user-defied fields are supported, but o actio is take i respose to their cotet. The user-defied fields are merely passed through. The Filterable Body cosists of zero or more NV pairs. The values i these pairs are limited to the followig types: ay, log, usiged log, short, usiged short, octet, char, float, double, strig, boolea, void, ad ull. These fields ca be used i filter expressios. 2-6 Usig the CORBA Notificatio Service

27 Itroductio The Remaiig Body cosists of a sigle ANY. The value is limited to the followig types: ay, log, usiged log, short, usiged short, octet, char, float, double, strig, boolea, void, ad ull. This field caot be used i a filter expressio. Desigig Evets The desig of evets is basic to ay otificatio service. The desig impacts ot oly the volume of iformatio that is delivered to matchig subscriptios, but the efficiecy ad performace of the Notificatio Service as well. Therefore, careful plaig should be doe to esure that your Notificatio Service will be able to hadle your eeds ow ad allow for future growth. The Notificatio Service supports five levels of evet desig: (1) domai ame, (2) type ame, (3) priority, (4) filterable data, ad (5) remaider of body. Whe desigig a evet, you must specify a domai ame ad a type ame; priority ad filterable data are optioal. The domai ame you choose ca relate to your busiess. Hospitals, for example, are i the health care busiess, so for a Notificatio Service applicatio for a hospital you might choose HEALTHCARE as a domai ame. You might wat to categorize the evets by the type of isurace provider, so you may choose HMO or UNINSURED as the type ame. You may wat to further defie the evets by the etity resposible for paymet, so you might choose to use the filterable data to idetify the etity as billig for a specific HMO_Accout or a specific or Patiet_Accout. Listig 2-1 shows a example of this type of evet desig. Listig 2-1 Evet Desig domai_ame = HEALTHCARE type_ame = HMO #Filterable data ame/value pairs. filterable_data.ame = billig filterable_data.value = 4498 filterable_data.ame = patiet_accout filterable_data.value = Usig the CORBA Notificatio Service 2-7

28 2 CORBA Notificatio Service API Referece Obviously, the more specific ad precise you are i desigig the evets that you wat your Notificatio Service applicatio to post ad receive, the fewer will be the evets the Notificatio Service will have to process. This has a direct impact o system resources ad cofiguratio requiremets. Therefore, a lot of thought should be give to evet desig. Creatig FML Field Table Files for Evets You must create Field Maipulatio Laguage (FML) field table files for evets oly if oe of the followig capabilities is required; otherwise FML tables are ot required. Evet data filterig (i additio to domai ad type fields) betwee BEA Tuxedo evet posters ad subscribers Iteroperability betwee the BEA Tuxedo Notificatio Service ad the BEA Tuxedo EvetBroker A structured evet s filterable_data field cotais a list of ame/value (NV) pairs. A evet s data is typically stored i this list. The field ames i the FML field table files must match the ame i the structured evet. The field type ca be ay allowable FML type (log, short, double, float, char, strig) except carray. The value i the structured evet must be the same type as defied i the field table. Table 2-1 shows the CORBA Ay Types supported by BEA Tuxedo, ad which oes ca be used for data filterig ad BEA Tuxedo iteroperability. Table 2-1 Supported CORBA Ay Types CORBA Ay Types short log usiged short usiged log float Supported for Data Filterig ad Tuxedo Iteroperability Yes Yes No No Yes 2-8 Usig the CORBA Notificatio Service

29 Itroductio Table 2-1 Supported CORBA Ay Types (Cotiued) CORBA Ay Types double char boolea octet strig void ull ay Supported for Data Filterig ad Tuxedo Iteroperability Yes Yes No No Yes No No No Listig 2-2 shows a example of a FML field table file. The *base 2000 is the base umber for the fields. The first etry has a field ame of billig, a field umber of 1 relative to the base, ad a field type of log. Usig the CORBA Notificatio Service 2-9

30 2 CORBA Notificatio Service API Referece Listig 2-2 Data Filterig FML Field Table File *base 2000 #Field Name Field # Field Type Flags Commets # billig 1 log - - stock_ame 2 strig - - price_per_share 3 double - - umber_of_shares 5 log - - The followig guidelies ad restrictios apply to BEA Tuxedo FML field table files: The FML fileame caot exceed 15 characters i legth. Because BEA Tuxedo uses FML32, the base umber plus the field umber is restricted to be betwee 101 ad 33,554,431, iclusive. Whe FML is used with other software that also uses fields, additioal restrictios may be imposed o field umbers. For iformatio o how to create ad cofigure FML field table files, see field_tables i the BEA Tuxedo Commad Referece ad the Programmig BEA Tuxedo ATMI Applicatios Usig FML. Iteroperability with BEA Tuxedo Applicatios Applicatios that use the BEA Tuxedo CORBA Notificatio Service are iteroperable with BEA Tuxedo applicatios that use the BEA Tuxedo EvetBroker. A applicatio usig the BEA Tuxedo Notificatio Service ca post evets that are delivered to BEA Tuxedo EvetBroker subscribers, ad ca receive evets that have bee posted by BEA Tuxedo EvetBroker. To achieve this iteroperability, it is ecessary to uderstad the mappig betwee CosNotificatio Structured Evets ad the BEA Tuxedo FML buffer so that the cotets of the FML field tables ca be coordiated by BEA Tuxedo. There are two cases to cosider: postig evets that are to be received by BEA Tuxedo applicatios via BEA Tuxedo EvetBroker; ad receivig evets that have bee posted to the Notificatio Service Evet Chael by BEA Tuxedo applicatios Usig the CORBA Notificatio Service

31 Itroductio Postig Evets For a BEA Tuxedo applicatio to subscribe to evets posted by a BEA Tuxedo applicatio, you must uderstad how a BEA Tuxedo structured evet is mapped to FML32 ad the evet ame at postig time. The mappig is as follows: The domai_ame ad type_ame are assembled ito a strig i the form domai_ame.type_ame to form the evet ame. This is the evet ame (evetame parameter) used o the tppost operatio. Each ame/value (NV) pair i the Filterable Body ad the variable header portio of the structured evet is mapped to a FML32 field of the same ame if the field is also defied i FML. If you set the domai to TMEVT, the the evet ame equals the type ame. Receivig Evets BEA Tuxedo system evets ad user evets ca be received by BEA Tuxedo applicatios. System evets are geerated by the BEA Tuxedo system ot by applicatios. User evets are geerated by BEA Tuxedo applicatios. For a listig of System evets see EVENTS i the BEA Tuxedo Commad Referece. System evets ad user evets are mapped i CosNotificatio Structured Evets as follows: Structured Evet Fields domai_ame type_ame evet_ame Variable Header (Priority) Filterable Body Fields Value Always set to TMEVT Empty strig Empty strig Empty sequece Same as FML field ame Note: Filterable body fields cosist of ame/value pair, where the ame portio is the same as the FML field ame. Remaider of Body Always set to void Usig the CORBA Notificatio Service 2-11

32 2 CORBA Notificatio Service API Referece The BEA Tuxedo system detects ad posts certai predefied evets related to system warigs ad failures. For example, system-geerated evets report o cofiguratio chages, state chages, coectio failures, ad machie partitioig. I order for a BEA Tuxedo applicatio to receive evets posted by a BEA Tuxedo applicatio, it is ecessary to uderstad how a FML buffer cotaiig a BEA Tuxedo evet is used to fabricate a BEA Tuxedo structured evet. It is also ecessary to kow how the domai_ame ad type_ame are related to the BEA Tuxedo evet ame. There are two cases to cosider: system evets ad user evets. Note that BEA Tuxedo uses a leadig dot (".") i the evet ame to distiguish system-geerated evets from applicatio-defied evets. A example of a system evet is.sysnetworkdropped. A example of a user evet is evetsdropped. To subscribe to these evets, the Notificatio Service subscriber applicatio must defie the subscriptio as follows: System evet domai_ame = TMEVT type_ame=.sysnetworkdropped User evet domai_ame = TMEVT type_ame= evetsdropped Whe the evets are received, the Notificatio Service subscriber applicatio parses each evet as follows: domai_ame= TMEVT type_ame= evet_ame= variable_header=empty Filterable_data=(cotet of the FML buffer) Parameters Used Whe Creatig Subscriptios Whe you create subscriptios, you ca specify the followig parameters. These parameters support the BEA Simple Evets API ad the CosNotificatio Service API Usig the CORBA Notificatio Service

33 Itroductio subscriptio_ame Specifies a ame that idetifies the subscriptio to the Notificatio Service ad the subscriber. Applicatios should use ames that are meaigful to a system admiistrator sice this is the primary way that a admiistrator associates a applicatio with a subscriptio ad the evets that are delivered to the subscriber via the subscriptio. This parameter is optioal (that is, a empty strig ca be passed i). More tha oe subscriptio ca use the same ame. The subscriptio_ame must ot exceed 128 characters i legth. domai_type Same parameter as the domai_type field i the Fixed Header portio of a structured evet, as defied by the CORBA-based Notificatio Service specificatio. This field is a strig that is used to idetify a particular vertical idustry domai i which the evet type is defied, for example, Telecommuicatios, Fiace, ad Health Care. Because this parameter is a regular expressio, you ca also use it to set domai patters o which to filter. For example, to subscribe to all domais that begi with the letter F, set the domai to F.*. For iformatio o how to costruct regular expressios, see the recomp commad i the BEA Tuxedo ATMI C Fuctio Referece. type_ame Same parameter as the type_ame field i the Fixed Header portio of a structure evet, as defied i the CORBA-based Notificatio Service specificatio. It is a strig that categorizes the type of evet, uiquely withi the domai, for example, Comm_alarm, StockQuote, ad VitalSigs. Because this parameter is a regular expressio, you ca also use it to set evet type patters o which to filter. For example, to subscribe to all evet types that begi with the letter F, you would set the type to F.*. For iformatio o how to costruct regular expressios, see the recomp commad i the BEA Tuxedo ATMI C Fuctio Referece. data_filter Specifies the values of the fields of filterable data ad variable headers o which you wat to filter. For example, a subscriptio to ews stories may have a domai of News, a type of Sports, ad a data_filter of Scores > 20. This parameter defies the data that the subscriptio must match i Boolea expressios. The followig data types are supported: short, log, char, Usig the CORBA Notificatio Service 2-13

34 2 CORBA Notificatio Service API Referece float, double, ad strig. Table 2-2 lists the Boolea expressio operators that are supported. Table 2-2 Boolea Expressio Operators Expressio Operators uary +, -,!, ~ multiplicative *, /, % additive +, - relatioal <, >, <=, >=, ==,!= equality ad matchig ==,!=, %%,!% exclusive OR logical AND ^ && logical OR To use data filterig, you must set up a FML table, iclude filters i the subscriptio, filter the data, ad post the evet. Listig 2-3 shows a example of these tasks Usig the CORBA Notificatio Service

35 Itroductio Listig 2-3 Data Filterig Requiremets //Settig up the FML Table Field table file *base 2000 *Field Name Field # Field Type Flags Commets StockName 1 strig - - PricePerShare 2 double - - CustomerId 3 log - - CustomerName 4 strig - - //Subscriptio data filterig. 1) "NumberOfShares > 100 && NumberOfShares < 1000" 2) "CustomerId == " 3) "PricePerShare > " 4) "StockName == BEAS " 5) "CustomerName %%.*Joes.* " // CustomerName cotais "Joes" 6) "StockName == BEAS && PricePerShare > " //Postig the evet. // C++ CosNotificatio::StructuredEvet ev;... ev.filterable_data[0].ame = CORBA::strig_dup("StockName"); ev.filterable_data[0].value <<= "BEAS"; ev.filterable_data[1].ame = CORBA::strig_dup("PricePerShare"); ev.filterable_data[1].value <<= CORBA::Double(175.00); ev.filterable_data[2].ame = CORBA::strig_dup("CustomerId"); ev.filterable_data[2].value <<= CORBA::Log( ); ev.filterable_data[3].ame = CORBA::strig_dup("CustomerName"); ev.filterable_data[3].value <<= "Jae Joes"; // Java StructuredEvet ev;... ev.filterable_data[0].ame = "StockName"; ev.filterable_data[0].value.isert_strig("beas"); ev.filterable_data[1].ame = "PricePerShare"; ev.filterable_data[1].value.isert_double(175.00); ev.filterable_data[2].ame = "CustomerId"; ev.filterable_data[2].value.isert_log( ); ev.filterable_data[3].ame = "CustomerName"; ev.filterable_data[3].value.isert_strig("jae Joes"); Usig the CORBA Notificatio Service 2-15

36 2 CORBA Notificatio Service API Referece For more iformatio about filter grammar, see Creatig FML Field Table Files for Evets o page 2-8 ad the sectio Boolea Expressio of fielded Buffers i Programmig BEA Tuxedo ATMI Applicatios Usig FML. push_cosumer Idetifies the callback object that will be used by the Notificatio Service to deliver a structured evet. Subscriber applicatios must implemet the CosNotifyComm::StructuredPushCosumer iterface so that the Notificatio Service ca call it to deliver evets. Note: You ca use either trasiet or persistet object refereces for the callback objects. Both QoS ad applicatio ru times should be take ito cosideratio whe decidig which type of object referece to use. For iformatio to assist you i decidig which type of object referece to use, refer to Table 2-3. Table 2-3 Whe to Use Trasiet Versus Persistet Object Refereces for Joit Cliet/Servers If the subscriptio... The... Will have a trasiet QoS ad will start ad shut dow oce. Will have a persistet QoS ad will start ad shut dow oce. Will have a persistet Qos ad will start ad shut dow multiple times. You should use a trasiet object referece. It this case, BEA Systems, Ic. recommeds the subscriber applicatio usubscribe o shutdow so as to release system resources, however, this is ot a requiremet. You should use a trasiet object referece. You must use a persistet object referece ad store the host ad port so the same host ad port is used each time the subscriber shuts dow ad restarts. I this case, use of the bidirectioal IIOP feature is ot recommeded. Note: If a joit cliet/server is used, it must be remote (outside the BEA Tuxedo domai) because persistet object refereces are ot supported iside the domai. Will have a trasiet QoS ad will start ad shut dow multiple times. You ca use a persistet object referece; however, BEA Systems, Ic. does ot recommed this cofiguratio uless you ca guaratee that o evets for this subscriber will be posted while the subscriber is shut dow. qos (quality of service) Specifies the desired quality of service of the subscriptio. It ca take oe of two values: trasiet or persistet Usig the CORBA Notificatio Service

37 BEA Simple Evets API Note: For trasiet subscriptios, the Notificatio Service makes oly oe attempt to deliver the evet to a subscriber. If that attempt fails, the evet is discarded ad, if the Notificatio Service does ot receive the CORBA::TRANSIENT exceptio, it cocludes that the subscriber is shutdow or otherwise ot available ad cacels the subscriptio. If the Notificatio Service receives the CORBA::TRANSIENT exceptio whe a attempt to deliver fails, it assumes that the subscriber is busy ad discards the evet, but it does ot cacel the subscriptio. For persistet subscriptios, if the first delivery attempt fails, the Notificatio Service holds the evet i the pedig queue ad keeps attemptig to deliver the subscriptio util the cofigurable retry limit is reached. Whe the retry limit is reached, the Notificatio Service moves the evet o a error queue where it is held for dispositio by the system admiistrator. The system admiistrator either removes the evet from the error queue, which i effect discards it, or moves it back to the pedig queue so that further attempts to deliver it ca be made. For persistet subscriptios, the Notificatio Service always does a two-way ivoke o callback objects to deliver evets. If a joit cliet/server does ot activate a callback object (the evet receiver) before it calls orb->ru ad the the Notificatio Service ivokes o the callback object, as far as the POA is cocered, the callback object does ot exist. I this case CORBA::OBJECT_NOT_EXIST exceptio is retured. If the Notificatio Service receives a CORBA::OBJECT_NOT_EXIST exceptio, it drops the subscriptio ad the evet; otherwise, the subscriptio is retaied ad the evet is retried. BEA Simple Evets API Simplicity ad ease-of-use are the defiig characteristics of the BEA Simple Evets applicatio programmig iterface (API). Its capabilities are similar to those of the BEA Tuxedo EvetBroker. The BEA Simple Evets API cosists of the followig iterfaces (see Figure 2-2): Tobj_SimpleEvets::Chael Tobj_SimpleEvets::ChaelFactory Usig the CORBA Notificatio Service 2-17

38 2 CORBA Notificatio Service API Referece CosNotifyComm::StructuredPushCosumer Figure 2-2 BEA Simple Evets Iterfaces Chael Factory Iterface Implemeted i the Subscriber s Callback Object Chael Iterface Push Cosumer Class The Tobj_SimpleEvets::Chael ad the Tobj_SimpleEvets::ChaelFactory iterfaces are implemeted by the Notificatio Service ad are described below. The CosNotifyComm::StructuredPushCosumer iterface is implemeted by the subscribers. For a descriptio of this iterface, see CosNotifyComm::StructuredPushCosumer::push_structured_evet o page Note: Note: The CosNotificatio Service classes referred to i this sectio are fully described i the CosNotificatio Service IDL files, which are located i the tuxdir/iclude directory. If you use class operatios that are ot supported, the CORBA::NO_IMPLEMENT exceptio is raised. TOBJ_SimpleEvets::Chael Iterface The Chael iterface is used: By subscribers to subscribe ad usubscribe to evets ad to determie if a subscriptio exists By posters to post evets to the Notificatio Service 2-18 Usig the CORBA Notificatio Service

39 BEA Simple Evets API This iterface provides these operatios: l l l l subscribe() usubscribe() exists() push_structured_evet() The CORBA IDL for this iterface: module Tobj_SimpleEvets { typedef log SubscriptioID; typedef strig RegularExpressio; typedef strig FilterExpressio; cost SubscriptioType TRANSIENT_SUBSCRIPTION = 0; cost SubscriptioType PERSISTENT_SUBSCRIPTION = 1; iterface Chael { void push_structured_evet( i CosNotificatio::StructuredEvet evet); SubscriptioID subscribe ( i strig subscriptio_ame, i RegularExpressio domai, i RegularExpressio type, i FilterExpressio data_filter, i CosNotificatio::QoSProperties qos, i CosNotifyComm::StructuredPushCosumer push_cosumer); boolea exists( i SubscriptioID id ); void usubscribe( i SubscriptioID id ); }; }; These operatios are described i the followig sectio. Usig the CORBA Notificatio Service 2-19

40 2 CORBA Notificatio Service API Referece Chael::subscribe CORBA IDL SubscriptioID subscribe ( i strig subscriptio_ame, i RegularExpressio domai, i RegularExpressio type, i FilterExpressio data_filter, // The filter expressio must legth 1 ad the ame must // be TRANSIENT_SUBSCRIPTION or PERSISTENT_SUBSCRIPTION. i CosNotificatio::QoSProperties qos, i CosNotifyComm::StructuredPushCosumer push_cosumer ); Parameters Exceptios For a descriptio of the parameters supported by this operatio, see Parameters Used Whe Creatig Subscriptios o page CORBA::BAD_PARAM Idicates oe of the followig problems: Tobj_Evets::SUB_INVALID_FILTER_EXPRESSION Tobj_Evets::SUB_UNSUPPORTED_QOS_VALUE CORBA::IMP_LIMIT Idicates oe of the followig problems: Tobj_Evets::SUB_DOMAIN_BEGINS_WITH_SYSEV Tobj_Evets::SUB_EMPTY_DOMAIN Tobj_Evets::SUB_EMPTY_TYPE Tobj_Evets::SUB_DOMAIN_AND_TYPE_TOO_LONG Tobj_Evets::SUB_FILTER_TOO_LONG Tobj_Evets::SUB_NAME_TO_LONG Tobj_Evets::TRANSIENT_ONLY_CONFIGURATION CORBA::INV_OBJREF Idicates the followig problem: Tobj_Evets::SUB_NIL_CALLBACK_REF Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Use this operatio to subscribe to evets. This operatio is called by a subscriber applicatio o the Notificatio Service to create a subscriptio to a particular evet. The subscriptio ame, domai ame, type ame, data filter, quality of service, ad the object referece of the subscriber s callback object are passed i. The callback object implemets the CosNotifyComm::StructuredPushCosumer IDL iterface. Note: For subscribers that shut dow ad restart, you must write the subscriptio_id to persistet storage Usig the CORBA Notificatio Service

41 BEA Simple Evets API To use data filterig or subscribe to BEA Tuxedo system evets or evets posted by a BEA Tuxedo applicatio, see the sectios Creatig FML Field Table Files for Evets o page 2-8 ad Iteroperability with BEA Tuxedo Applicatios o page Retur Value Returs a uique subscriptio idetifier. The effect of this operatio is ot istataeous. There ca be a delay betwee returig from this operatio ad the actual start of evet delivery. The legth of the delay period may be sigificat depedig o your cofiguratio. For more iformatio o factors impactig this delay period, see Sychroizig Databases o page Note: Notificatio Service applicatios that start ad shut dow oly oce ca use the subscriptio_id to determie if their subscriptio has bee cacelled automatically or by the system admiistrator. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig a Subscriptio o page C++ code example: subscriptio_id = chael->subscribe( subscriptio_ame, "News", // domai Sports, // type "", // No data filter. qos, ews_cosumer.i() ); Java code example: it subscriptio_id = chael.subscribe( subscriptio_ame, "News", // domai Sports, // type "", // o data filter qos, ews_cosumer_impl ); Usig the CORBA Notificatio Service 2-21

42 2 CORBA Notificatio Service API Referece Chael::usubscribe CORBA IDL void usubscribe( i SubscriptioID id ); Parameter Exceptios subscriptio_id The subscriptio idetifier. CORBA::BAD_PARAM Idicates the followig problem: Tobj_Evets::INVALID_SUBSCRIPTION_ID Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Used to usubscribe. Subscriber applicatios use this operatio to termiate subscriptios. O retur from this operatio, o further evets ca be delivered. There is oe iput parameter: SubscriptioID, which you got whe you subscribed. Note: This operatio is ot istataeous. After returig from this operatio, a subscriber may cotiue to receive evets for a period of time. The period of time may be sigificat depedig o your cofiguratio. For more iformatio o factors impactig this period of time, see Sychroizig Databases o page Examples C++ code example: chael->usubscribe(subscriptio_id); Java code example: chael.usubscribe(subscriptio_id); 2-22 Usig the CORBA Notificatio Service

43 BEA Simple Evets API Chael::push_structured_evet CORBA IDL Parameter Exceptios void push_structured_evet( i CosNotificatio::StructuredEvet otificatio ); otificatio This parameter cotais the structured evet as defied by the CosNotificatio Service specificatio. CORBA_IMP_LIMIT Idicates oe of the followig problems with the subscriptio: Tobj_Evets::POST_UNSUPPORTED_VALUE_IN_ANY Tobj_Evets::POST_UNSUPPORTED_PRIORITY_VALUE Tobj_Evets::POST_DOMAIN_CONTAINS_SEPARATOR Tobj_Evets::POST_TYPE_CONTAINS_SEPARATOR Tobj_Evets::POST_SYSTEM_EVENTS_UNSUPPORTED Tobj_Evets::POST_EMPTY_DOMAIN Tobj_Evets::POST_EMPTY_TYPE Tobj_Evets::POST_DOMAIN_AND_TYPE_TOO_LONG Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Used by the poster applicatio to post a evet to the Notificatio Service. Note: This operatio has trasactioal behavior whe used i the cotext of a trasactio. For more iformatio, see the sectio Usig Trasactios o page 2-4. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig ad Postig Evets o page 3-4. C++ code example: chael->push_structured_evet(otificatio); Java code example: chael.push_structured_evet(otificatio); Usig the CORBA Notificatio Service 2-23

44 2 CORBA Notificatio Service API Referece Chael::exists CORBA IDL Parameter Exceptios boolea exists(i SubscriptioID subscriptio_id); subscriptio_id The subscriptio idetifier. CORBA::BAD_PARAM Idicates the followig problem: Tobj_Evets::INVALID_SUBSCRIPTION_ID If the subscriptio_id is for a subscriptio created usig the CosNotificatio Service API, this exceptio is always retured. Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Retur Value Examples Used by subscriber applicatios to determie if a subscriptio exists. Sice the system admiistrator ca delete subscriptios maually ad the Notificatio Service ca delete trasiet subscriptios automatically, a subscriber applicatio might wat to use this operatio so that it ca recreate the subscriptio, if ecessary. The subscriptio_id used i this operatio is the same oe that you got whe you subscribed. Returs Boolea True of the subscriptio exists ad False if it does ot. C++ code example: if chael->exists (subscriptio_id) { // The subscriptio is still valid. } else { // The subscriptio o loger exists. } Java code example: if chael.exists (subscriptio_id) { // The subscriptio is still valid. } else { // The subscriptio o loger exists. } 2-24 Usig the CORBA Notificatio Service

45 BEA Simple Evets API TOBJ_SimpleEvets::ChaelFactory Iterface The ChaelFactory iterface is used to fid evet chaels. This iterface provides a sigle operatio: fid_chael. The CORBA IDL for this iterface: module Tobj_SimpleEvets { typedef log ChaelID; iterface ChaelFactory { Chael fid_chael( i ChaelID chael_id // Must be DEFAULT_CHANNEL ); }; }; Usig the CORBA Notificatio Service 2-25

46 2 CORBA Notificatio Service API Referece Chael_Factory::fid_chael CORBA IDL Parameter Exceptios Chael fid_chael( i ChaelID chael_id ); I this release of BEA Tuxedo, there ca oly be oe evet chael; therefore, the ChaelID that is passed i must be set to Tobj_SimpleEvets::DEFAULT_CHANNEL (for C++) or Tobj_SimpleEvets.DEFAULT_CHANNEL.Value (for Java). CORBA::BAD_PARAM Idicates the followig problem: Tobj_Evets::INVALID_CHANNEL_ID Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Retur Value Used by poster applicatios ad subscriber applicatios. This operatio is used to fid the evet chael so that it ca be used by the poster to post evets ad by the subscriber to subscribe ad usubscribe to evets. Returs the default evet chael s object referece. Examples Note: Code examples show here are abbreviated. For complete code examples, see Gettig the Evet Chael o page 3-3. C++ code example: chael_factory->fid_chael( Tobj_SimpleEvets::DEFAULT_CHANNEL); Java code example: chael_factory.fid_chael(default_channel.value); 2-26 Usig the CORBA Notificatio Service

47 CosNotificatio Service API CosNotificatio Service API This sectio cotais a discussio of the operatios defied by the CosNotificatio Service that are implemeted by the BEA Tuxedo CORBA Notificatio Service. These operatios are oly a subset of the complete set of operatios. This subset is a fuctioally complete API that ca be used as a alterative to the BEA Simple Evets API. This API is more complex the the BEA Simple Evets API. There are two reasos for this. First, the CosNotificatio Service API is more complex. Secod, the BEA Tuxedo implemetatio of the CosNotificatio Service API places additioal restrictios o the operatios that are supported. Because this complexity offers o advatages i terms of performace or flexibility, BEA Systems, Ic. recommeds that you use the BEA Simple Evets API wheever possible. The CosNotificatio API is provided for those who require that a stadard API be used wheever possible for purposes of portability. I regard to fuctioality, this API provides o beefits beyod those offered by the Simple Evets API. Applicatios that are developed usig this API will be mostly, but ot completely, portable. The reaso for this is that ot eough of the CosNotificatio Service API is supported to facilitate portability. For example, the filterig grammar required by the CORBA-based Notificatio Service is based o the COS Trader grammar. Sice BEA Tuxedo does ot support this grammar, but supports a alterative grammar based o the BEA Tuxedo EvetBroker grammar, ay applicatio that requires filterig will ot be portable. The same is true for QoS, that is, the CosNotificatio Service API does ot support the CORBA-based Notificatio Service stadard qualities of service, but it does support alterative qualities of service. Overview of Supported CosNotificatio Service Classes Figure 2-3 shows the CosNotificatio Service classes implemeted, i full or i part, i this release of BEA Tuxedo ad their relatioships. Usig the CORBA Notificatio Service 2-27

48 2 CORBA Notificatio Service API Referece Figure 2-3 Implemeted CosNotificatio Service Classes Evet Chael Factory Class Supplier Admi Class Evet Chael Class Filter Factory Class Implemeted i the Subscriber s Callback Object Cosumer Admi Class Push Cosumer Class Proxy Push Cosumer Class Filter Class Proxy Push Supplier Class The operatios supported by each class are summarized below. For more detailed descriptios, see Detailed Descriptios of CosNotificatio Service Classes o page CosNotifyChaelAdmi::EvetChaelFactory Class This class is used by the evet poster ad subscriber applicatios. It supports the get_chael_factory operatio which is used to get the chael factory whe postig, subscribig, ad usubscribig to evets. CosNotifyChaelAdmi::EvetChael Class This class is used by evet poster ad subscriber applicatios. It supports three operatios: l l default_cosumer_admi used by evet subscriber applicatios to get the cosumer admi object. default_supplier_admi used by evet poster applicatios to get the supplier admi object Usig the CORBA Notificatio Service

49 CosNotificatio Service API l default_filter_factory used by evet subscriber applicatios to get the filter factory object. CosNotifyChaelAdmi::SupplierAdmi Class This class is used by evet poster applicatios. It supports the obtai_otificatio_push_cosumer operatio. Poster applicatios use this operatio to create proxy push cosumer objects which i tur are used to post evets to the Notificatio Service. CosNotifyChaelAdmi::StructuredProxyPushCosumer Class This class is used by evet poster applicatios. It supports the followig operatios: l l l coect_structured_push_supplier used by evet poster applicatios to coect the proxy push supplier to the Notificatio Service evet chael. push_structured_evet used by evet poster applicatios to post the evet to the Notificatio Service evet chael. discoect_structured_push_cosumer used by evet poster applicatios to discoect the proxy push supplier from the Notificatio Service evet chael. CosNotifyFilter::FilterFactory Class This class is used by evet subscriber applicatios to create a filter object. It supports the create_filter operatio. The filter object provides all data filterig icludig domai, type, ad filterable data. CosNotifyFilter::Filter Class This class is used by evet subscriber applicatios. It supports the followig operatios: l l add_cotraits operatio used to set the filter s domai, type, ad data filter. destroy operatio used to destroy the filter object. CosNotifyChaelAdmi::CosumerAdmi Class This class is used by evet subscriber applicatios. It supports the followig operatios: Usig the CORBA Notificatio Service 2-29

50 2 CORBA Notificatio Service API Referece l l obtai_otificatio_push_supplier used by evet subscriber applicatios to create proxy push supplier objects which i tur are used to deliver evets to the subscriber s callback object. get_proxy_supplier used by evet subscriber applicatios to retrieve the object referece for the proxy push supplier object. This operatio is oly used whe the subscriber applicatio shuts dow the restarts ad cacels the subscriptio. This is because subscribers eed to discard the object referece from the first ru ad get it back agai for the ext ru. Subscribers caot reuse object refereces from oe ru to the ext. CosNotifyChaelAdmi::StructuredProxyPushSupplier Class This class is used by evet subscriber applicatios. It supports the followig operatios: l l l l l coect_structured_push_cosumer used by evet subscriber applicatios to coect the subscriber to the proxy push supplier. set_qos used by evet subscriber applicatios to set the quality of service for subscriptios. add_filter used by evet subscriber applicatios to add the filter object to the subscriptio. get_filter used by evet subscriber applicatios whe performig usubscribe operatios to get the filter associated with the subscriptio. This operatio is oly used whe the subscriber applicatio shuts dow the restarts. discoect_structured_push_supplier used by evet subscriber applicatios to usubscribe. CosNotifyComm::StructuredPushCosumer This iterface is implemeted by evet subscriber applicatios. It supports the push_structured_evet operatio. The Notificatio Service ivokes this operatio to deliver evets to the subscriber Usig the CORBA Notificatio Service

51 CosNotificatio Service API Detailed Descriptios of CosNotificatio Service Classes This sectio describes the CosNotificatio Service classes that this release of BEA Tuxedo implemets. These classes are fully described i the CosNotificatio Service IDL files, which are located i the tuxdir/iclude directory. Note: If you use class operatios that are ot supported, the CORBA::NO_IMPLEMENT exceptio is raised. CosNotifyFilter::Filter Class This class is used by evet subscriber applicatios. The OMG IDL for this class is as follows: Module CosNotifyFilter { iterface Filter { CostraitIfoSeq add_costraits ( i CostraitExpSeq costrait) raises (IvalidCostrait); void destroy(); }; }; //CosNotifyFilter Usig the CORBA Notificatio Service 2-31

52 2 CORBA Notificatio Service API Referece CosNotifyFilter::Filter::add_costraits Syopsis Sets the domai, type, ad data filter parameters o the filter object. OMG IDL CostraitIfoSeq add_costraits ( i CostraitExpSeq costrait) raises (IvalidCostrait); Exceptios CosNotifyFilter::IvalidCostrait Never raised. CORBA::BAD_PARAM Idicates the followig problem: Tobj_Evets::SUB_INVALID_FILTER_EXPRESSION. CORBA_IMP_LIMIT Idicates oe of the followig problems: Tobj_Notificatio::SUB_ADD_CONS_ON_TIMED_OUT_FILTER Tobj_Notificatio::SUB_MULTIPLE_CALLS_TO_ADD_CONS Tobj_Notificatio::SUB_MULTIPLE_CONSTRAINTS_IN_LIST Tobj_Notificatio::SUB_MULTIPLE_TYPES_IN_CONSTRAINT Tobj_Notificatio::SUB_SYSTEM_EVENTS_UNSUPPORTED Tobj_Evets::SUB_DOMAIN_BEGINS_WITH_SYSEV Tobj_Evets::SUB_EMPTY_DOMAIN Tobj_Evets::SUB_EMPTY_TYPE Tobj_Evets::SUB_FILTER_TOO_LONG Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Used whe subscribig. This operatio is used i subscriber applicatios to defie the kid of evet to which you wat to subscribe. You set the domai, type, ad data filter parameters o the filter object. For a descriptio of these parameters, see Parameters Used Whe Creatig Subscriptios o page Note: The BEA Tuxedo implemetatio of the add_costraits operatio (1) ca oly be called oce, (2) must be called before the filter is added to the proxy object, ad (3) must cosist of oly a sigle costrait that has a sigle evet type. Retur Value Returs a empty list, which we recommed that the caller igores. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig a Subscriptio o page Usig the CORBA Notificatio Service

53 CosNotificatio Service API C++ code example: // set the filterig parameters // (domai = "News", type, ad o data filter) CosNotifyFilter::CostraitExpSeq costraits; costraits.legth(1); costraits[0].evet_types.legth(1); costraits[0].evet_types[0].domai_ame = CORBA::strig_dup("News"); costraits[0].evet_types[0].type_ame = CORBA::strig_dup ( Sports ); // o data filter costraits[0].costrait_expr = CORBA::strig_dup(""); CosNotifyFilter::CostraitIfoSeq_var add_costraits_results = // igore this retured value filter->add_costraits(costraits); Java code example: // set the filterig parameters // (domai = "News", type, ad o data filter). CostraitExp costraits[] = ew CostraitExp[1]; costraits[0] = ew CostraitExp(); costraits[0].evet_types = ew EvetType[1]; costraits[0].evet_types[0] = ew EvetType(); costraits[0].evet_types[0].domai_ame = "News"; costraits[0].evet_types[0].type_ame = Sports ; costraits[0].costrait_expr = ""; // No data filter. CostraitIfo add_costraits_results[] = filter.add_costraits(costraits); //Igore this retur value. Usig the CORBA Notificatio Service 2-33

54 2 CORBA Notificatio Service API Referece CosNotifyFilter::Filter::destroy Syopsis OMG IDL Exceptios Destroys the filter object. void destroy(); CORBA::BAD_PARAM Idicates the followig problem: Tobj_Evets::SUB_INVALID_FILTER_EXPRESSION. Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Used whe usubscribig. This operatio is used i subscriber applicatios to destroy the target filter object. Note: Do ot destroy the filter object util you are ready to cacel the correspodig subscriptio. CosNotifyFilter::FilterFactory Class This class is used by evet subscriber applicatios. The OMG IDL for this class is as follows: Module CosNotifyFilter { iterface FilterFactory { Filter create_filter ( i strig costrait_grammar) raises (IvalidGrammar); destroy(); }; }; //CosNotifyFilter 2-34 Usig the CORBA Notificatio Service

55 CosNotificatio Service API CosNotifyFilter::FilterFactory::create_filter Syopsis Determies which evets are delivered to a subscriptio. OMG IDL Filter create_filter ( i strig costrait_grammar) raises (IvalidGrammar); Exceptios Descriptio Retur Value CosNotifyFilter::IvalidGrammar Idicates the costrait_grammar is ot supported. Used i the subscriber applicatio to create a ew filter object. This filter is used to determie which evets are delivered to a subscriptio. The subscriber must set up the filter ad add it to the proxy withi five miutes; otherwise, the filter will be destroyed. The filter grammar must be set to Tobj_Notificatio::Costrait_grammar; otherwise, the IvalidGrammar exceptio is raised. Returs the ew filter s object referece. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig a Subscriptio o page C++ code example: filter_factory->create_filter( Tobj_Notificatio::CONSTRAINT_GRAMMAR ); Java code example: filter_factory.create_filter(constraint_grammar.value); Usig the CORBA Notificatio Service 2-35

56 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::StructuredProxyPushSupplier Class This class is used by evet subscriber applicatios. The OMG IDL for this class is as follows: Module CosNotifyChaelAdmi { iterface StructuredProxyPushSupplier : ProxySupplier, CosNotifyComm::StructuredPushSupplier { void coect_structured_push_cosumer ( i CosNotifyComm::StructuredPushCosumer push_cosumer) raises(cosevetchaeladmi::alreadycoected, CosEvetChaelAdmi::TypeError ); }; // The followig operatios are iherited. void set_qos(i QoSProperties qos) raises (UsupportedQoS); FilterID add_filter (i Filter ew_filter ); Filter get_filter( i FilterID filter ) raises ( FilterNotFoud); void discoect_structured_push_supplier(); readoly attribute ProxyType MyType; }; }; //CosNotifyChaelAdmi 2-36 Usig the CORBA Notificatio Service

57 CosNotificatio Service API CosNotifyChaelAdmi::StructuredProxyPushSupplier:: coect_structured_push_cosumer Syopsis Completes a subscriptio. OMG IDL void coect_structured_push_cosumer ( i CosNotifyComm::StructuredPushCosumer push_cosumer) raises(cosevetchaeladmi::alreadycoected, CosEvetChaelAdmi::TypeError ); Exceptios CosEvetChaelAdmi::TypeError Never raised. CORBA::INV_OREF Tobj_Evets::SUB_NIL_CALLBACK_REF CORBA::IMP_LIMIT Idicates oe of the followig problems: Tobj_Evets::SUB_DOMAIN_AND_TYPE_TOO_LONG Tobj_Evets::SUB_NAME_TO_LONG Tobj_Evets::TRANSIENT_ONLY_CONFIGURATION Tobj_Notificatio::SUBSCRIPTION_DOESNT_EXIST. CORBA::OBJECT_NOT_EXIST The proxy does ot exist. CosEvetChaelAdmi::AlreadyCoected Idicates that the coect_structured_push_cosumer operatio has already bee ivoked. Note: For exceptio defiitios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Use this operatio whe subscribig. This operatio is used i subscriber applicatios to subscribe to evets. The push_cosumer parameter idetifies the subscriber s callback object. Oce the coect_structured_push_cosumer has bee called, the Notificatio Service will proceed to sed evets to the subscriber by ivokig the callback object s push_structured_evet operatio. If the coect_structured_push_cosumer has already bee called, the AlreadyCoected exceptio is raised. Note: You must call set_qos ad add_filter before callig coect_structured_push_cosumer. Usig the CORBA Notificatio Service 2-37

58 2 CORBA Notificatio Service API Referece Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig a Subscriptio o page C++ code example: subscriptio->coect_structured_push_cosumer( ews_cosumer.i() ); Java code example: subscriptio.coect_structured_push_cosumer( ews_cosumer_impl ); 2-38 Usig the CORBA Notificatio Service

59 CosNotificatio Service API CosNotifyChaelAdmi::StructuredProxyPushSupplier::set_qos Syopsis OMG IDL Exceptios Sets the QoS for the subscriptio. void set_qos(i QoSProperties qos) raises (UsupportedQoS); UsupportedQoS Never raised. ORBA::IMP_LIMIT Idicates oe of the followig problems: Tobj_Notificatio::SUB_MULTIPLE_CALLS_TO_SET_QOS Tobj_Notificatio::SUB_CANT_SET_QOS_AFTER_CONNECT Tobj_Notificatio::SUBSCRIPTION_DOESNT_EXIST Tobj_Notificatio::SUB_UNSUPPORTED_QOS_VALUE Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Used whe subscribig. This operatio is used i subscriber applicatios to set the QoS for the subscriptio. It takes as a iput parameter a sequece of ame-value pairs which ecapsulates quality-of-service property settigs that the subscriber is requestig. There are two compoets of the QoS: the subscriptio type ad the subscriptio ame. The subscriptio type is set by costructig a ame-value pair where the ame is Tobj_Notificatio::SUBSCRIPTION_TYPE ad the value is either Tobj_Notificatio::PERSISTENT_SUBSCRIPTION, or Tobj_Notificatio::TRANSIENT_SUBSCRIPTION. For more iformatio ad additioal usage details, see Quality of Service o page 2-2. The subscriptio ame is set by costructig a ame-value pair, where the ame is Tobj_Notificatio::SUBSCRIPTION_NAME, ad the value is a user-defied strig. For more iformatio o this parameter, see Parameters Used Whe Creatig Subscriptios o page Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig a Subscriptio o page C++ code example: CosNotificatio::QoSProperties qos; qos.legth(2); Usig the CORBA Notificatio Service 2-39

60 2 CORBA Notificatio Service API Referece qos[0].ame = CORBA::strig_dup(Tobj_Notificatio::SUBSCRIPTION_NAME); qos[0].value <<= MySubsriptio ; qos[1].ame = CORBA::strig_dup(Tobj_Notificatio::SUBSCRIPTION_TYPE); qos[1].value <<= Tobj_Notificatio::TRANSIENT_SUBSCRIPTION; subscriptio->set_qos(qos); Java code example: Property qos[] = ew Property[2]; qos[0] = ew Property(); qos[0].ame = SUBSCRIPTION_NAME.value; qos[0].value = orb.create_ay(); qos[0].value.isert_strig( MySubsriptio ); qos[1] = ew Property(); qos[1].ame = SUBSCRIPTION_TYPE.value; qos[1].value = orb.create_ay(); qos[1].value.isert_short(transient_subscription.value); subscriptio.set_qos(qos); 2-40 Usig the CORBA Notificatio Service

61 CosNotificatio Service API CosNotifyChaelAdmi::StructuredProxyPushSupplier::add_filter Syopsis OMG IDL Exceptios Sets the filter object o the subscriber s callback object. add_filter( i Filter ew_filter ); CORBA::IMP_LIMIT Idicates oe of the followig problems: Tobj_Notificatio::SUB_MULTIPLE_CALLS_TO_SET_FILTER Tobj_Notificatio::SUB_ADD_FILTER_AFTER_CONNECT Tobj_Notificatio::SUB_NIL_FILTER_REF Tobj_Notificatio::SUB_NO_CUSTOM_FILTERS CORBA::OBJECT_NOT_EXIST Idicates that the subscriptio does ot exist. Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Used whe subscribig. This operatio is used i subscriber applicatios to set the filter object to the subscriber s callback object. If the applicatio usig this operatio will be shut dow ad restarted, the filter_id should be writte to persistet storage. Note: Note: This operatio: (1) caot be called after the subscriber callback object is coected (see coect_structured_push_cosumer above), (2) caot be called more tha oce, ad (3) whe it is called, the filter costrait expressio must already be preset i the filter (see CosNotifyFilter::Filter add_costraits). Oly filters created by the evet chael s default filter factory ca be added. Retur Value Returs a filter_id. Usig the CORBA Notificatio Service 2-41

62 2 CORBA Notificatio Service API Referece Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig a Subscriptio o page C++ code example: CosNotifyFilter::FilterID filter_id = subscriptio->add_filter(filter.i()); Java code example: it filter_id = subscriptio.add_filter(filter); 2-42 Usig the CORBA Notificatio Service

63 CosNotificatio Service API CosNotifyChaelAdmi::StructuredProxyPushSupplier::get_filter Syopsis Gets a object referece to the filter curretly associated with the subscriber s callback object. OMG IDL Filter get_filter( i FilterID filter ) raises ( FilterNotFoud); Exceptios Descriptio Restrictios CosNotifyChaelAdmi::FilterNotFoud The filter could ot be foud. Used whe a restartable subscriber wats to usubscribe. This operatio is used i subscriber applicatios to get a object referece to the filter curretly associated with the subscriber s callback object. The FilterID that is passed i must be valid for the subscriber s StructuredProxyPushSupplier object. If the FilterID is ot valid for ay proxy object associated with the evet chael, the a FilterNotFoud exceptio is throw. The operatio is oly used by subscribers that shut dow ad restart. The followig usage restrictios ad guidelies apply to this operatio: a. Filter object refereces that are retured from this operatio caot be used i compariso operatios. b. Filter object refereces retured by this operatio ca be used by the CosNotifyFilter::Filter::destroy operatios but are of little use sice they caot be modified or added to proxy objects. Retur Value Examples Returs a filter object referece to the filter curretly associated with the subscriber s callback object. C++ code example: CosNotify::Filter_var filter = subscriptio->get_filter( filter_id() ); Java code example: Filter filter = subscriptio.get_filter( filter_id() ); Usig the CORBA Notificatio Service 2-43

64 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::StructuredProxyPushSupplier:: discoect_structured_push_supplier Syopsis OMG IDL Exceptios Used to usubscribe. void discoect_structured_push_supplier(); CORBA::OBJECT_NOT_EXIST Idicates that the subscriptio to be discoected does ot exist. Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptio Used by subscriber applicatios whe usubscribig. This operatio is used i subscriber applicatios to termiate a coectio betwee the Notificatio Service ad the subscriber s callback object. Note: This operatio does ot stop evet delivery istataeously. After returig from this operatio, a subscriber may cotiue to receive evets for a period of time. Examples C++ code example: subscriptio->discoect_structured_push_supplier(); Java code example: subscriptio.discoect_structured_push_supplier(); 2-44 Usig the CORBA Notificatio Service

65 CosNotificatio Service API CosNotifyChaelAdmi::StructuredProxyPushSupplier::MyType Syopsis OMG IDL Descriptio Always returs CosNotifyChaelAdmi::PUSH_STRUCTURED proxy. readoly attribute ProxyType MyType Always returs CosNotifyChaelAdmi::PUSH_STRUCTURED proxy. CosNotifyChaelAdmi::StructuredProxyPushCosumer Class This class is used by evet postig applicatios. The OMG IDL for this class is as follows: Module CosNotifyChaelAdmi { iterface StructuredProxyPushCosumer : ProxyCosumer, CosNotifyComm::StructuredPushCosumer { void coect_structured_push_supplier ( i CosNotifyComm::StructuredPushSupplier push_supplier) raises(cosevetchaeladmi::alreadycoected); // The followig operatios are iherited. readoly attribute MyType; void push_structured_evet( i CosNotificatio::StructuredEvet otificatio ) raises( CosEvetComm::Discoected ); void discoect_structured_push_cosumer(); }; }; \\StructuredProxyPushCosumer Usig the CORBA Notificatio Service 2-45

66 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::StructuredProxyPushCosumer:: coect_structured_push_supplier Syopsis Prepares the Notificatio Service to receive a evet. OMG IDL void coect_structured_push_supplier ( i CosNotifyComm::StructuredPushSupplier push_supplier) raises(cosevetchaeladmi::alreadycoected); Exceptio Descriptio CosEvetChaelAdmi::AlreadyCoected Never raised. Used by poster applicatios whe postig evets. You must call this operatio to prepare the Notificatio Service to receive a evet ad you must pass i a NIL whe you use this operatio. The sequece of usage is as follows: 1. Make a proxy. 2. Use this operatio to coect to the Notificatio Service ad pass i a NIL. 3. Post evets. 4. Before exitig the poster program, discoect. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig ad Postig Evets o page 4-4. C++ code example: proxy_push_cosumer->coect_structured_push_supplier( CosNotifyComm::StructuredPushSupplier::_il() ); Java code example: proxy_push_cosumer.coect_structured_push_supplier(ull); 2-46 Usig the CORBA Notificatio Service

67 CosNotificatio Service API CosNotifyChaelAdmi::StructuredProxyPushCosumer:: push_structured_evet Syopsis OMG IDL Exceptios Posts evets to the evet chael. void push_structured_evet( i CosNotificatio::StructuredEvet otificatio ) raises( CosEvetComm::Discoected ); CosEvetComm::Discoected Never raised. CORBA::IMP_LIMIT Idicates oe of the followig problems: Tobj_Evets::POST_UNSUPPORTED_VALUE_IN_ANY Tobj_Evets::POST_UNSUPPORTED_PRIORITY_VALUE Tobj_Evets::POST_DOMAIN_CONTAINS_SEPARATOR Tobj_Evets::POST_TYPE_CONTAINS_SEPARATOR Tobj_Evets::POST_SYSTEM_EVENTS_UNSUPPORTED Tobj_Evets::POST_EMPTY_DOMAIN Tobj_Evets::POST_EMPTY_TYPE Tobj_Evets::POST_DOMAIN_AND_TYPE_TOO_LONG Note: For more iformatio o exceptios ad correspodig mior codes, see Exceptio Mior Codes o page Descriptios Used whe postig evets. This operatio is used i poster applicatios to post evets to the evet chael. Note: This operatio differs from the stadard CORBA defiitio i the followig ways: a. The Priority i the variable header sectio of the evet, if specified, must be short value i the rage of 1 to 100. b. If evet filterable data filterig (versus filterig o domai ad type oly) is required, or if evets are to be received by a BEA Tuxedo subscriber, the additioal restrictios apply. See Structured Evet Fields, Types, ad Filters o page 2-5 ad Iteroperability with BEA Tuxedo Applicatios o page Note: This operatio has trasactioal behavior whe used i the cotext of a trasactio. For more iformatio, see Usig Trasactios o page 2-4. Usig the CORBA Notificatio Service 2-47

68 2 CORBA Notificatio Service API Referece Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig ad Postig Evets o page 4-4. C++ code example: proxy_push_cosumer->push_structured_evet(otificatio); Java code example: proxy_push_cosumer.push_structured_evet(otificatio); 2-48 Usig the CORBA Notificatio Service

69 CosNotificatio Service API CosNotifyChaelAdmi::StructuredProxyPushCosumer:: discoect_structured_push_cosumer Syopsis OMG IDL Descriptios Stops postig evets. void discoect_structured_push_cosumer(); Used whe postig evets. This operatio is used by poster applicatios to stop postig evets. It takes o iput parameters ad returs o values. The recommeded usage sequece is as follows: 1. Make a proxy. 2. Coect ad discoect o every ru of the poster applicatio. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig ad Postig Evets o page 4-4. C++ code example: proxy_push_cosumer->discoect_structured_push_cosumer(); Java code example: proxy_push_cosumer.discoect_structured_push_cosumer(); Usig the CORBA Notificatio Service 2-49

70 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::StructuredProxyPushCosumer::MyType Syopsis OMG IDL Descriptio Always returs CosNotifyChaelAmdmi::PUSH_STRUCTURED proxy. readoly attribute ProxyType MyType Always returs CosNotifyChaelAmdmi::PUSH_STRUCTURED proxy. CosNotifyChaelAdmi::CosumerAdmi Class This class is used by evet subscriber applicatios. The OMG IDL for this class is as follows: Module CosNotifyChaelAdmi { iterface CosumerAdmi : CosNotificatio::QoSAdmi, CosNotifyComm::NotifySubscribe, CosNotifyFilter::FilterAdmi, CosEvetChaelAdmi::CosumerAdmi { ProxySupplier obtai_otificatio_push_supplier ( i ClietType ctype, out ProxyID proxy_id) raises ( AdmiLimitExceeded ) ProxySupplier get_proxy_supplier ( i ProxyID proxy_id ) raises ( ProxyNotFoud ); }; }; //CosNotifyChaelAdmi 2-50 Usig the CORBA Notificatio Service

71 CosNotificatio Service API CosNotifyChaelAdmi::CosumerAdmi:: obtai_otificatio_push_supplier Syopsis Creates proxy push supplier objects. OMG IDL ProxySupplier obtai_otificatio_push_supplier ( i ClietType ctype, out ProxyID proxy_id) raises ( AdmiLimitExceeded ) Exceptios Descriptio CosNotifyChaelAdmi::AdmiLimitExceeded Never raised. CORBA::IMP_LIMIT Idicates the followig problem: Tobj_Notificatio::SUB_UNSUPPORTED_CLIENT_TYPE Used whe subscribig. This operatio is used i subscriber applicatios to create proxy push supplier objects. Oly structured evets are supported (that is, ANY_EVENT ad SEQUENCE_EVENT ClietTypes are ot supported). Therefore, the ClietType iput parameter must be set to CosNotifyComm::STRUCTURED_EVENT. If you shut dow ad restart the subscriber ad subscriptio survives more tha oe ru of your program, the ProxyID retured by this operatio should be durably stored. The subscriber must arrow the proxy supplier to CosNotifyChaelAdmi::StructuredProxyPushSupplier. All required operatios must be completed i five miutes. Note: Notificatio Service applicatios that start ad shut dow oly oce ca use the proxy_id to determie if their subscriptio has bee cacelled automatically or by the system admiistrator. Retur Value This operatio returs the ew proxy s object referece. The ew proxy_id is also retured through the proxy_id out parameter. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig a Subscriptio o page C++ code example: CosNotifyChaelAdmi::ProxySupplier_var geeric_proxy = cosumer_admi->obtai_otificatio_push_supplier( CosNotifyChaelAdmi::STRUCTURED_EVENT, proxy_id ); Usig the CORBA Notificatio Service 2-51

72 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::StructuredProxyPushSupplier_var proxy = CosNotifyChaelAdmi::StructuredProxyPushSupplier::_arrow( geeric_proxy.i () ); Java code example: ProxySupplier geeric_proxy = cosumer_admi.obtai_otificatio_push_supplier( ClietType.STRUCTURED_EVENT, proxy_id ); StructuredProxyPushSupplier proxy = StructuredProxyPushSupplierHelper.arrow( geeric_proxy ); 2-52 Usig the CORBA Notificatio Service

73 CosNotificatio Service API CosNotifyChaelAdmi::CosumerAdmi::get_proxy_supplier Syopsis Returs the proxy push supplier object created usig the cosumer admi object obtai_otificatio_push_supplier operatio. OMG IDL ProxySupplier get_proxy_supplier ( i ProxyID proxy_id ) raises ( ProxyNotFoud ); Exceptios Descriptios Retur Value Examples CosNotifyChaelAdmi::ProxyNotFoud Idicates that the ProxyID could ot be foud. Used whe usubscribig. This operatio is used i subscriber applicatios to retur the proxy push supplier object created usig the cosumer admi object obtai_otificatio_push_supplier operatio. The ProxyID iput parameter uiquely idetifies the proxy object. Callers should be aware that the proxy object ca be destroyed either due to a error i deliverig a trasiet subscriptio or through a tsadmi admiistrative commad. Whe a proxy object is destroyed, the ProxyID associated with it is ivalidated. If the ProxyID is ivalid, a ProxyNotFoud exceptio is raised. The subscriber must arrow the proxy supplier to CosNotifyChaelAdmi::StructuredProxyPushSupplier. Returs the object referece for the existig proxy. C++ code example: CosNotifyChaelAdmi::ProxySupplier_var geeric_proxy = m_cosumer_admi->get_proxy_supplier( m_subscriptio_ifo.ews_proxy_id() ); CosNotifyChaelAdmi::StructuredProxyPushSupplier_var proxy = CosNotifyChaelAdmi::StructuredProxyPushSupplier::_arrow( geeric_proxy.i() ); Java code example: ProxySupplier geeric_subscriptio = m_cosumer_admi.get_proxy_supplier( m_subscriptio_ifo.ews_proxy_id() ); StructuredProxyPushSupplier subscriptio = StructuredProxyPushSupplierHelper.arrow( geeric_proxy); Usig the CORBA Notificatio Service 2-53

74 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::SupplierAdmi Class This class is used by evet poster applicatios. The OMG IDL for this class is as follows: Module CosNotifyChaelAdmi { iterface SupplierAdmi : CosNotificatio::QoSAdmi, CosNotifyComm::NotifyPublish, CosNotifyFilter::FilterAdmi, CosEvetChaelAdmi::SupplierAdmi { ProxyCosumer obtai_otificatio_push_cosumer ( i ClietType ctype, out ProxyID proxy_id) raises ( AdmiLimitExceeded ); }; }; //SupplierAdmi 2-54 Usig the CORBA Notificatio Service

75 CosNotificatio Service API CosNotifyChaelAdmi::SupplierAdmi:: obtai_otificatio_push_cosumer Syopsis Creates proxy push cosumer objects. OMG IDL ProxyCosumer obtai_otificatio_push_cosumer ( i ClietType ctype, out ProxyID proxy_id) raises ( AdmiLimitExceeded ); Exceptios Descriptio CosNotifyChaelAdmi::AdmiLimitExceeded Never raised. CORBA::IMP_LIMIT Idicates the followig problem: Tobj_Notificatio::SUB_UNSUPPORTED_CLIENT_TYPE Used whe postig evets. This operatio is used i poster applicatios to create proxy push cosumer objects. ClietType must be set to CosNotifyChaelAdmi::STRUCTURED_EVENT. The ProxyID retured should be igored. The Proxy Cosumer must be arrowed the proxy supplier to CosNotifyChaelAdmi::StructuredProxyPushCosumer. Note: Notificatio Service applicatios that start ad shut dow oly oce ca use the proxy_id to determie if their subscriptio has bee cacelled automatically or by the system admiistrator. Retur Value This operatio returs the ew proxy s object referece. The ew proxy_id is also retured through the proxy_id out parameter. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig ad Postig Evets o page 4-4. C++ code example: CosNotifyChaelAdmi::ProxyCosumer_var geeric_proxy_cosumer = supplier_admi->obtai_otificatio_push_cosumer( CosNotifyChaelAdmi::STRUCTURED_EVENT, proxy_id ); CosNotifyChaelAdmi::StructuredProxyPushCosumer_var proxy_push_cosumer = CosNotifyChaelAdmi::StructuredProxyPushCosumer::_arrow( geeric_proxy_cosumer ); Usig the CORBA Notificatio Service 2-55

76 2 CORBA Notificatio Service API Referece Java code example: supplier_admi.obtai_otificatio_push_cosumer( ClietType.STRUCTURED_EVENT, proxy_id ); 2-56 Usig the CORBA Notificatio Service

77 CosNotificatio Service API CosNotifyChaelAdmi::EvetChael Class This class is used by evet poster applicatios. The OMG IDL for this class is as follows: Module CosNotifyChaelAdmi { iterface EvetChael : CosNotificatio::QoSAdmi, CosNotificatio::AdmiPropertiesAdmi, CosEvetChaelAdmi::EvetChael { readoly attribute CosumerAdmi default_cosumer_admi; readoly attribute SupplierAdmi default_supplier_admi; readoly attribute CosNotifyFilter::FilterFactory default_filter_factory; }; }; //CosNotifyChaelAdmi Usig the CORBA Notificatio Service 2-57

78 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::EvetChael:: CosumerAdmi default_cosumer_admi Syopsis OMG IDL Descriptio Retur Value Gets the CosumerAdmi object. readoly attribute CosumerAdmi default_cosumer_admi; Used whe subscribig ad usubscribig. This operatio is used i subscriber applicatios to get the CosumerAdmi object. Returs the object referece to the CosumerAdmi object. Examples Note: Code examples show here are abbreviated. For complete code examples, see Gettig the Evet Chael, CosumerAdmi Object, ad Filter Factory Object o page C++ code example: chael->default_cosumer_admi(); Java code example: Note: chael.default_cosumer_admi(); 2-58 Usig the CORBA Notificatio Service

79 CosNotificatio Service API CosNotifyChaelAdmi::EvetChael:: CosumerAdmi default_supplier_admi Syopsis OMG IDL Descriptio Retur Value Gets the SupplierAdmi object. readoly attribute SupplierAdmi default_supplier_admi; Used whe postig evets. This operatio is used i evet poster applicatios to get the SupplierAdmi object. SupplierAdmi object referece. Examples Note: Code examples show here are abbreviated. For complete code examples, see Creatig ad Postig Evets o page 4-4. C++ code example: chael->default_supplier_admi(); Java code example: chael.default_supplier_admi(); Usig the CORBA Notificatio Service 2-59

80 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::EvetChael::default_filter_factory Syopsis OMG IDL Descriptio Retur Value Gets the default FilterFactory object. readoly attribute CosNotifyFilter::FilterFactory default_filter_factory; Used whe subscribig. This operatio is used i subscriber applicatios to get the default FilterFactory object. Default FilterFactory object referece. Examples Note: Code examples show here are abbreviated. For complete code examples, see Gettig the Evet Chael, CosumerAdmi Object, ad Filter Factory Object o page C++ code example: chael->default_filter_factory(); Java code example: chael.default_filter_factory(); 2-60 Usig the CORBA Notificatio Service

81 CosNotificatio Service API CosNotifyChaelAdmi::EvetChaelFactory Class This class is used by evet poster applicatios. The OMG IDL for this class is as follows: Module CosNotifyChaelAdmi { iterface EvetChaelFactory { EvetChael get_evet_chael ( i ChaelID id ) raises (ChaelNotFoud); }; }; //CosNotifyChaelAdmi Usig the CORBA Notificatio Service 2-61

82 2 CORBA Notificatio Service API Referece CosNotifyChaelAdmi::EvetChaelFactory::get_evet_chael Syopsis Gets the EvetChael object. OMG IDL EvetChael get_evet_chael ( i ChaelID id ) raises (ChaelNotFoud); Exceptios Descriptio Retur Value CosNotifyChaelAdmi::ChaelNotFoud Idicates the chael caot be foud. Used whe subscribig, usubscribig, ad postig evets. This operatio is used i applicatios to get the EvetChael object. Whe subscribig, the EvetChael object is used to get the filter factory object ad the CosumerAdmi object. Whe usubscribig, the EvetChael object is used to get the CosumerAdmi object.whe postig a evet, the EvetChael object is used to get the SupplierAdmi object. The ChaelID parameter that is passed i must be set to Tobj_Notificatio::DEFAULT_CHANNEL; otherwise, the ChaelNotFoud exceptio is raised. Returs the default evet chael s object referece. Examples Note: Code examples show here are abbreviated. For complete code examples, see Gettig the Evet Chael o page 4-3 ad Gettig the Evet Chael, CosumerAdmi Object, ad Filter Factory Object o page C++ code example: chael_factory->get_evet_chael( Tobj_Notificatio::DEFAULT_CHANNEL ); Java code example: chael_factory.get_evet_chael(default_channel.value); 2-62 Usig the CORBA Notificatio Service

83 CosNotificatio Service API CosNotifyComm::StructuredPushCosumer Iterface This iterface is used by evet subscriber applicatios for evet delivery. You must implemet this iterface so that the Notificatio Service ca ivoke o it to deliver evets to subscribers. It has three methods which you have to implemet. The OMG IDL for this class is as follows: Module CosNotifyComm { iterface StructuredPushCosumer : NotifyPublish { void push_structured_evet( i CosNotificatio::StructuredEvet evet) raises(cosevetcomm::discoected); void discoect_structured_push_cosumer: //The followig operatios are iherited. void offer_chage( i CosNotificatio::EvetTypeSeq added, i CosNotificatio::EvetTypeSeq removed ) raises ( IvalidEvetType ); }; }; //CosNotifyComm Usig the CORBA Notificatio Service 2-63

84 2 CORBA Notificatio Service API Referece CosNotifyComm::StructuredPushCosumer::push_structured_evet Syopsis OMG IDL Exceptios Descriptio Delivers a structured evet. void push_structured_evet( i CosNotificatio::StructuredEvet evet) raises(cosevetcomm::discoected); CosEvetComm::Discoected The subscriber should ever raise this exceptio. Used whe subscribig. This operatio is implemeted by the subscriber s callback object ad is ivoked by the Notificatio Service each time a structured evet is delivered. This operatio cotais a sigle iput parameter, which is a structured evet. Note: This operatio will ot be called i a trasactio. Also, whe this operatio is called, it must retur quickly because the Notificatio Service might ot start deliverig evets to other subscribers util this operatio returs. Examples Note: Code examples show here are abbreviated. For complete code examples, see Implemetig the CosNotifyComm::StructuredPushCosumer Iterface o page 4-8. C++ code example: virtual void push_structured_evet( cost CosNotificatio::StructuredEvet& otificatio ); { // Process the evet. } Java code example: public void push_structured_evet(structuredevet otificatio) { // Process the evet. } 2-64 Usig the CORBA Notificatio Service

85 CosNotificatio Service API CosNotifyComm::StructuredPushCosumer:: discoect_structured_push_cosumer Syopsis OMG IDL Descriptio Examples Never ivoked. void discoect_structured_push_cosumer; This operatio is ever ivoked. The subscriber applicatio must provide a stubbed-out versio of this operatio. C++ code example: virtual void push_structured_evet( cost CosNotificatio::StructuredEvet& otificatio ); { throw ew CORBA::NO_IMPLEMENT(); } Java code example: public void discoect_structured_push_cosumer() { throw ew CORBA::NO_IMPLEMENT(); } Usig the CORBA Notificatio Service 2-65

86 2 CORBA Notificatio Service API Referece CosNotifyComm::StructuredPushCosumer::Offer_chage Syopsis Never ivoked. OMG IDL void offer_chage( i CosNotificatio::EvetTypeSeq added, i CosNotificatio::EvetTypeSeq removed ) raises ( IvalidEvetType ); Exceptios Descriptio Examples CosNotifyComm::IvalidEvetType The subscriber should ever raise this exceptio. This operatio is ever ivoked. The subscriber applicatio must provide a stubbed-out versio of this operatio. C++ code example: virtual void offer_chage( cost CosNotificatio::EvetTypeSeq& added, cost CosNotificatio::EvetTypeSeq& removed ) { throw CORBA::NO_IMPLEMENT(); } Java code example: public void offer_chage(evettype[] added, EvetType[] removed) { throw ew NO_IMPLEMENT(); } Exceptio Mior Codes This sectio provides iformatio about the Notificatio Service exceptio symbols ad mior codes. The mior codes are i the Tobj_Evets.idl ad Tobj_Notificatio.idl files. These files are located i the tuxdir\iclude directory (for Microsoft Widows systems) ad tuxdir/iclude directory (for UNIX systems). Table 2-4 ad Table 2-5 list the exceptio symbols ad correspodig mior codes for the Tobj_Evets ad Tobj_Notificatio exceptios respectively. CORBA system evets have a mior code field ad those mior codes are also defied i these tables Usig the CORBA Notificatio Service

87 CosNotificatio Service API Note: The exceptio symbols are orgaized withi the tables by the higher-level exceptios (CORBA::IMP_LIMIT, CORBA::CORBA::BAD_PARAM, CORBA::BAD_INV_ORDER, CORBA::INV_OBHJREF, ad CORBA::OBJECT_NOT_EXIST) ad listed i alphabetical order. Table 2-4 Tobj_Evets Exceptio Mior Codes Exceptio Symbols Defiitios Mior Codes (Hexadecimal) CORBA::IMP_LIMIT Exceptios Tobj_Evets:: POST_DOMAIN_AND_TYPE_TOO_LONG This exceptio is raised by: Tobj_SimpleEvets::Chael:: push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Tobj_Evets:: POST_DOMAIN_CONTAINS_SEPARATOR This exceptio is raised by: Tobj_SimpleEvets::Chael:: push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Tobj_Evets::POST_EMPTY_DOMAIN This exceptio is raised by: Tobj_SimpleEvets::Chael:: push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Whe postig a evet, the user specified a domai ame ad type ame whose combied legth was greater tha 31 characters. Whe postig a evet, the user specified a domai ame that cotaied the "." character. Whe postig a evet, the user specified a empty domai ame D B Usig the CORBA Notificatio Service 2-67

88 2 CORBA Notificatio Service API Referece Table 2-4 Tobj_Evets Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Evets::POST_EMPTY_TYPE This exceptio is raised by: Tobj_SimpleEvets::Chael:: push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Tobj_Evets:: POST_SYSTEM_EVENTS_UNSUPPORTED This exceptio is raised by: Tobj_SimpleEvets::Chael:: push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Tobj_Evets:: POST_TYPE_CONTAINS_SEPARATOR This exceptio is raised by: Tobj_SimpleEvets::Chael:: push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Tobj_Evets:: POST_UNSUPPORTED_PRIORITY_VALUE This is exceptio is raised by: Tobj_SimpleEvets:: Chael::push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Whe postig a evet, the user specified a empty type ame. Whe postig a evet, the user tried to post a BEA Tuxedo system evet; that is, the domai ame is "TMEVT" ad the type ame starts with the "." character. Whe postig a evet, the user specified a type ame that cotaied the "." character. Whe postig a evet, the user added a "Priority" field i the variable header. However, the user did ot set the field s value to a "short" i the rage of C Usig the CORBA Notificatio Service

89 CosNotificatio Service API Table 2-4 Tobj_Evets Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Evets:: POST_UNSUPPORTED_VALUE_IN_ANY This exceptio is raised by: Tobj_SimpleEvets:: Chael::push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Tobj_Evets:: SUB_DOMAIN_AND_TYPE_TOO_LONG This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: coect_structured_push_cosumer Tobj_Evets:: SUB_DOMAIN_BEGINS_WITH_SYSEV This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyFilter::Filter:: add_costraits Tobj_Evets::SUB_EMPTY_DOMAIN This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyFilter::Filter:: add_costraits Whe postig a evet, the user put a usupported type (for example, a structure, uio, sequece, etc.) ito oe of the "ays" i the structured evet field. The usupported type is i the variable header s value field, the filterable data s value field, or the remaider_of_body field. Whe subscribig, the user specified a domai ame ad type ame whose combied legth is greater tha 255 characters. Whe subscribig, the user specified a domai ame that begis with the "." character. The user specified a empty domai ame whe subscribig Usig the CORBA Notificatio Service 2-69

90 2 CORBA Notificatio Service API Referece Table 2-4 Tobj_Evets Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Evets::SUB_EMPTY_TYPE This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyFilter::Filter:: add_costraits Tobj_Evets::SUB_FILTER_TOO_LONG This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyFilter::Filter:: add_costraits Tobj_Evets::SUB_NAME_TO_LONG This exceptio is raised by: Tobj_SimpleEvets::Chael:: push_structured_evet CosNotifyChaelAdmi:: StructuredProxyPushCosumer:: push_structured_evet Tobj_Evets:: TRANSIENT_ONLY_CONFIGURATION This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: coect_structured_push_cosumer CORBA::BAD_PARAM Exceptios The user specified a empty type ame whe subscribig. The user specified a data filter expressio loger tha 255 characters. Whe subscribig, the user specified a subscriptio ame loger tha 127 characters. The user tried to create a persistet subscriptio, but the system was cofigured to support trasiet subscriptios oly A E Usig the CORBA Notificatio Service

91 CosNotificatio Service API Table 2-4 Tobj_Evets Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Evets::INVALID_CHANNEL_ID This exceptio is raised by: Tobj_SimpleEvets::ChaelFactory ::fid_chael Tobj_Evets:: INVALID_SUBSCRIPTION_ID This exceptio is raised by: Tobj_SimpleEvets::Chael:: usubscribe CosNotifyChaelAdmi:: CosumerAdmi::get_proxy_ supplier Tobj_SimpleEvets:: Chael::exists Tobj_Evets:: SUB_INVALID_FILTER_EXPRESSION This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyFilter::Filter:: add_costraits Whe lookig up the chael usig the Simple Evets API, the user specified a ivalid chael ID, that is, a chael ID that is ot Tobj_SimpleEvets:: DEFAULT_CHANNEL. Whe usubscribig usig the Simple Evets API, the user specified a ivalid subscriptio ID, that is, a o-existet or a CosNotificatio subscriptio ID. Whe lookig up a subscriptio usig the CosNotificatio Service API, the user specified a ivalid subscriptio ID, that is, a o-existet or a Simple Evets API subscriptio ID. Whe callig the exists operatio usig the BEA Simple Evets API, the user passed i a CosNotificatio subscriptio_id. Whe subscribig, the user specified a ivalid data filter expressio. This either meas that there is a sytax error i the expressio or that oe of the field ames i the expressio is ot defied as a FML field. Check that you have correctly created FML field tables that cotai all fields that you wat to data filter o, ad check that the UBBCONFIG file is properly cofigured so that the field table files ca be foud Usig the CORBA Notificatio Service 2-71

92 2 CORBA Notificatio Service API Referece Table 2-4 Tobj_Evets Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Evets:: SUB_UNSUPPORTED_QOS_VALUE This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: set_qos Whe subscribig, the user specified a ivalid subscriptio quality of service. For the Simple Evets API, this meas that the quality of service specified did ot meet oe of the followig requiremets: The sequece must be of legth oe. The ame must be Tobj_SimpleEvets:: SUBSCRIPTION_TYPE. The value must be either Tobj_SimpleEvets:: TRANSIENT_SUBSCRIPTION or Tobj_SimpleEvets:: PERSISTENT_SUBSCRIPTION. For the CosNotificatio Service API, this meas that the quality of service specified did ot meet oe of the followig requiremets: The quality of service must cotai a ame/value pair where the ame is Tobj_Notificatio:: SUBSCRIPTION_TYPE ad the value is Tobj_Notificatio:: TRANSIENT_SUBSCRIPTION or Tobj_Notificatio:: PERSISTENT_SUBSCRIPTION. The quality of service may cotai a ame/value pair where the ame is Tobj_Notificatio::SUBSCRIPTION_NAME ad the value is a strig cotaiig the subscriptio s admiistrative ame Usig the CORBA Notificatio Service

93 CosNotificatio Service API Table 2-4 Tobj_Evets Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) CORBA::INV_OBHJREF Tobj_Evets:: SUB_NIL_CALLBACK_REF This exceptio is raised by: Tobj_SimpleEvets::Chael:: subscribe CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: coect_structured_push_cosumer Whe subscribig, the user specified a NIL object referece for the callback object which receives evets Table 2-5 Tobj_Notificatio Exceptio Mior Codes Exceptio Symbols Defiitios Mior Codes (Hexadecimal) CORBA::IMP_LIMIT Exceptios Tobj_Notificatio:: SUB_ADD_CONS_ON_TIMED_OUT_FILTER This exceptio is raised by: CosNotifyFilter::Filter:: add_costraits Tobj_Notificatio:: SUB_ADD_CONS_TO_ADDED_FILTER This exceptio is raised by: CosNotifyFilter::Filter:: add_costraits A CosNotificatio subscriber waited more tha five miutes after creatig a filter to call add_costraits o the filter. This meas that the filter has bee destroyed (timed out) ad the subscriber must create a ew filter. A CosNotificatio subscriber called add_costraits o a filter that had already bee added to a proxy E Usig the CORBA Notificatio Service 2-73

94 2 CORBA Notificatio Service API Referece Table 2-5 Tobj_Notificatio Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Notificatio:: SUB_ADDED_TIMED_OUT_FILTER This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: add_filter Tobj_Notificatio:: SUB_ADD_FILTER_AFTER_CONNECT This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: add_filter Tobj_Notificatio:: SUB_CANT_SET_QOS_AFTER_CONNECT This exceptio is raised by: CosNotifyChaelAdmi::Structured ProxyPushSupplier::set_qos Tobj_Notificatio:: SUB_MULTIPLE_CALLS_TO_ADD_CONS This exceptio is raised by: CosNotifyFilter::Filter:: add_costraits Tobj_Notificatio:: SUB_MULTIPLE_CALLS_TO_SET_FILTER This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: add_filter After creatig a filter ad callig "add_costraits" o it, a CosNotificatio subscriber waited more tha five miutes to call add_filter to add the filter to the proxy. This meas that the filter has bee destroyed (timed out) ad that the subscriber must create a ew filter. A CosNotificatio subscriber called add_filter after coectig to the proxy. A CosNotificatio subscriber called set_qos after coectig to the proxy. A CosNotificatio subscriber called add_costraits more tha oce o a filter. A CosNotificatio subscriber called add_filter more tha oce o a proxy D Usig the CORBA Notificatio Service

95 CosNotificatio Service API Table 2-5 Tobj_Notificatio Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Notificatio:: SUB_MULTIPLE_CALLS_TO_SET_QOS This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: set_qos Tobj_Notificatio:: SUB_MULTIPLE_CONSTRAINTS_IN_LIST This exceptio is raised by: CosNotifyFilter::Filter:: add_costraits Tobj_Notificatio:: SUB_MULTIPLE_TYPES_IN_CONSTRAINT This exceptio is raised by: CosNotifyFilter::Filter:: add_costraits Tobj_Notificatio:: SUB_NIL_FILTER_REF This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: add_filter A CosNotificatio subscriber called set_qos more tha oce o a proxy. Whe a CosNotificatio subscriber called add_costraits o a filter, the subscriber passed i a list of costraits that had more tha oe item; that is, the subscriber was tryig to sed i a list of data filters istead of oe data filter. Whe a CosNotificatio subscriber called add_costraits o a filter, the subscriber passed o a costrait that had more tha oe domai/type set; that is, the subscriber was tryig to sed i a list of desired evet types istead of oe evet type. A CosNotificatio subscriber passed a NIL filter object referece ito add_filter A B Usig the CORBA Notificatio Service 2-75

96 2 CORBA Notificatio Service API Referece Table 2-5 Tobj_Notificatio Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Notificatio:: SUB_NO_CUSTOM_FILTERS This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: add_filter Tobj_Notificatio:: SUB_SET_FILTER_NOT_CALLED This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: coect_structured_push_ cosumer Tobj_Notificatio:: SUB_SET_QOS_NOT_CALLED This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: coect_structured_push_ cosumer Tobj_Notificatio:: SUB_SYSTEM_EVENTS_UNSUPPORTED This exceptio is raised by: CosNotifyChaelAdmi:: StructuredProxyPushSupplier:: set_qos A CosNotificatio subscriber passed a filter object that was ot created by the default filter factory ito add_filter. For example, a CosNotificatio subscriber implemeted the CosNotifyFilter::Filter iterface to do some kid of "custom" filterig ad passed oe of those filter objects ito add_filter. A CosNotificatio subscriber did ot call add_filter to the proxy before coectig to the proxy. A CosNotificatio subscriber did ot call add_filter to the proxy before coectig to the proxy. A CosNotificatio subscriber passed i a domai ame of "TMEVT" ad a type ame that begis with "."; that is, the CosNotificatio subscriber was tryig to subscribe to Tuxedo system evets. This is ot supported. It is oly supported by the Simple Evets API C 2-76 Usig the CORBA Notificatio Service

97 CosNotificatio Service API Table 2-5 Tobj_Notificatio Exceptio Mior Codes (Cotiued) Exceptio Symbols Defiitios Mior Codes (Hexadecimal) Tobj_Notificatio:: SUB_UNSUPPORTED_CLIENT_TYPE This is exceptio raised by: CosumerAdmi:: obtai_otificatio_push_ supplier SupplierAdmi:: obtai_otificatio_push_ cosumer CORBA::OBJECT_NOT_EXIST Exceptio Tobj_Notificatio:: SUBSCRIPTION_DOESNT_EXIST This exceptio is raised by: StructuredProxyPushSupplier:: add_filter StructuredProxyPushSupplier:: set_qos StructuredProxyPushSupplier:: coect_structured_push_ cosumer StructuredProxyPushSupplier:: discoect_structured_push_ supplier Note: coect_structured_push_ cosumer ca raise this exceptio sice a user ca create the proxy, the use the tsadmi utility to delete the subscriptio, ad the call coect_structured_push_ cosumer o the proxy. Whe creatig a proxy, a CosNotificatio subscriber or poster passed i a cliet type other tha CosNotifyChaelAdmi::ST RUCTURED_EVENT. A CosNotificatio subscriber called a method o a proxy that had already bee destroyed. The proxy has bee destroyed by oe of the followig actios: The CosNotificatio subscriber discoected the proxy. The CosNotificatio subscriber waited more tha five miutes from creatig the proxy to coectig it; that is, it took loger tha five miutes to complete the subscriptio. The admiistrator used the tsadmi utility to destroy the subscriptio F Usig the CORBA Notificatio Service 2-77

98 2 CORBA Notificatio Service API Referece 2-78 Usig the CORBA Notificatio Service

99 CHAPTER 3 Usig the BEA Simple Evets API This chapter describes the developmet steps required to create Notificatio Service applicatios usig the BEA Simple Evets API ad the C++ ad Java programmig laguages. This topic icludes the followig sectios: Developmet Process Step 1: Writig a Applicatio to Post Evets Step 2: Writig a Applicatio to Subscribe to Evets Step 3: Compilig ad Ruig Notificatio Service Applicatios Developmet Process Table 3-1 outlies the developmet process for creatig Notificatio Service applicatios. Table 3-1 Developmet Process Step Descriptio 1 Desigig evets 2 Writig a applicatio that posts evets Usig the CORBA Notificatio Service 3-1

100 3 Usig the BEA Simple Evets API Table 3-1 Developmet Process (Cotiued) Step Descriptio 3 Writig a applicatio that subscribes to evets 4 Compilig a Notificatio Service applicatio These steps are explaied i detail i subsequet topics. Desigig Evets The desig of evets is basic to ay otificatio service. The desig impacts ot oly the volume of iformatio that is delivered to matchig subscriptios, but the efficiecy ad performace of the Notificatio Service as well. Therefore, careful plaig should be doe to esure that your Notificatio Service will be able to hadle your eeds ow ad allow for future growth. For a discussio of evet desig, see Desigig Evets o page 2-7. Step 1: Writig a Applicatio to Post Evets The followig types of CORBA applicatios ca post evets: Note: BEA Tuxedo 8.0 supports Java cliets ad joit cliet servers, but it does ot support Java servers. Support for Java servers was previously icluded i versios 5.0 ad 5.1 of the BEA WebLogic Eterprise product, however, that support was removed whe BEA WebLogic Eterprise was merged with the BEA Tuxedo i release 8.0. C++ cliets, joit cliet/servers ad servers. Java cliets ad joit cliet/servers. Foreig ORB cliets. 3-2 Usig the CORBA Notificatio Service

101 Step 1: Writig a Applicatio to Post Evets To post evets, a applicatio must, at a miimum, implemet the followig fuctios: Get the evet chael factory object referece ad use it to get the evet chael. Create ad post evets. The followig sectios describe each of these fuctios. Gettig the Evet Chael Before the cliet applicatio ca post a evet, it must first get the evet chael. This developmet step is illustrated i Listig 3-1. Listig 3-1 is based o the Notificatio Service sample applicatios that use the BEA Simple Evets API. To get the evet chael factory object referece, the resolve_iitial_refereces method is ivoked o the Bootstrap object usig the "Tobj_SimpleEvetsService" evirometal object. The object referece is used to get the chael factory, which is i tur is used to get the evet chael. Listig 3-1 ad Listig 3-2 show code examples i C++ ad Java. Listig 3-1 Gettig the Evet Chael (C++) // Get the Simple Evets chael factory object referece. CORBA::Object_var chael_factory_oref = bootstrap.resolve_iitial_refereces( "Tobj_SimpleEvetsService"); Tobj_SimpleEvets::ChaelFactory_var chael_factory = Tobj_SimpleEvets::ChaelFactory::_arrow( chael_factory_oref.i()); // Use the chael factory to get the default chael. Tobj_SimpleEvets::Chael_var chael = chael_factory->fid_chael( Tobj_SimpleEvets::DEFAULT_CHANNEL); Usig the CORBA Notificatio Service 3-3

102 3 Usig the BEA Simple Evets API Listig 3-2 Gettig the Evet Chael (Java) // Get the Simple Evet chael factory object referece. org.omg.corba.object chael_factory_oref = bootstrap.resolve_iitial_refereces( "Tobj_SimpleEvetsService"); // Use the chael factory to get the default chael. ChaelFactory chael_factory = ChaelFactoryHelper.arrow(chael_factory_oref); Chael chael = chael_factory.fid_chael(default_channel.value); Creatig ad Postig Evets Before a evet ca be posted, it must be created. The followig listigs are based o the Notificatio Service sample applicatios. Listig 3-3 ad Listig 3-4 show how this is implemeted i C++ ad Java respectively. To report ews to the evets chael, this applicatio executes the followig steps: 1. Creates a evet ad sets the domai ame ad type ame. I the code samples, the domai ame is set to News ad the evet type is set to Sports. 2. Adds a field to the evet s filterable data to cotai the story, sets the ame of the added field to Story, ad the value of the field to a strig cotaiig the story. 3. Uses the push_structured_evet operatio to post the evet to the Notificatio Service. Listig 3-3 Creatig ad Postig the Evet (C++) // Create a evet. CosNotificatio::StructuredEvet otificatio; // Set the domai to "News". otificatio.header.fixed_header.evet_type.domai_ame = CORBA::strig_dup("News"); 3-4 Usig the CORBA Notificatio Service

103 Step 1: Writig a Applicatio to Post Evets // Set the type to the ews category. otificatio.header.fixed_header.evet_type.type_ame = CORBA::strig_dup( Sports ); // Add oe field, which will cotai the story, to the // evet's filterable data. Set the field's ame to // "Story" ad value to a strig cotaiig the story. otificatio.filterable_data.legth(1); otificatio.filterable_data[0].ame = CORBA::strig_dup("Story"); otificatio.filterable_data[0].value <<= Joh Smith wis agai ; // Post the evet. // Subscribers who subscribed to evets whose domai is // "News" ad whose type matches the ews category will // receive this evet chael->push_structured_evet(otificatio); Listig 3-4 Creatig ad Postig the Evet (Java) // Create a evet. StructuredEvet otificatio = ew StructuredEvet(); // Create the sub structures for the header. otificatio.header = ew EvetHeader(); otificatio.header.fixed_header = ew FixedEvetHeader(); otificatio.header.fixed_header.evet_type = ew EvetType(); // Set the domai to "News". otificatio.header.fixed_header.evet_type.domai_ame = "News"; // Set the type to the ews category. otificatio.header.fixed_header.evet_type.type_ame = Sports ; // Set the evet ame to a empty strig sice this sample // does't use it. otificatio.header.fixed_header.evet_ame = ""; // Empty the variable header sice this sample does't use it. otificatio.header.variable_header = ew Property[0]; // Add oe field, which will cotai the story, to the // evet's filterable data. Set the field's ame to // "Story" ad value to a strig cotaiig the story. otificatio.filterable_data = ew Property[1]; otificatio.filterable_data[0] = ew Property(); otificatio.filterable_data[0].ame = "Story"; Usig the CORBA Notificatio Service 3-5

104 3 Usig the BEA Simple Evets API otificatio.filterable_data[0].value = orb.create_ay(); otificatio.filterable_data[0].value.isert_strig(joh Smith wis agai ); // Set the remaider of body to a ew (empty) ay sice this // sample does't use the remaider of body. otificatio.remaider_of_body = orb.create_ay(); //Post the evet. chael.push_structured_evet(otificatio); Step 2: Writig a Applicatio to Subscribe to Evets The followig types of CORBA applicatios ca subscribe to evets: Note: BEA Tuxedo 8.0 supports Java cliets ad joit cliet servers, but it does ot support Java servers. Support for Java servers was previously icluded i versios 5.0 ad 5.1 of the BEA WebLogic Eterprise product, however, that support was removed whe BEA WebLogic Eterprise was merged with the BEA Tuxedo i release 8.0. C++ joit cliet/servers ad servers. Java joit cliet/servers. Foreig ORB cliets. To subscribe to evets, a applicatio must, at a miimum, implemet the followig fuctios: Implemet a CosNotifyComm OMG IDL iterface that supports the push_structured_evet operatio. Get the evet chael factory object referece ad use it to get the evet chael. Defie ad create a subscriptio that icludes the callback object referece. 3-6 Usig the CORBA Notificatio Service

105 Step 2: Writig a Applicatio to Subscribe to Evets Create a callback object that implemets the CosNotifyComm::StructuredPushCosumer iterface. Implemetig the CosNotifyComm::StructuredPushCosumer Iterface I order for the callback object to receive evets, it must implemet the CosNotifyComm::StructuredPushCosumer iterface that supports the push_structured_evet operatio. Whe a evet occurs that has a matchig subscriptio, the Notificatio Service ivokes this operatio o the callback object to push the evet to the subscriber applicatio. The CosNotifyComm::StructuredPushCosumer iterface also defies the operatios offer_chage ad discoect_structured_push_cosumer. The Notificatio Service ever ivokes these operatios, so you should implemet stubbed out versios that throw CORBA::NO_IMPLEMENT. Listig 3-5 ad Listig 3-6 show how this iterface is implemeted i C++. Listig 3-5 Sample CosNotifyComm::StructuredPushCosumer Iterface Implemetatio (NewsCosumer_i.h) #ifdef _ews_cosumer_i_h #defie _ews_cosumer_i_h #iclude "CosNotifyComm_s.h" // For the servat class to receive ews evets, // it must implemet the CosNotifyComm::StructuredPushCosumer // idl iterface. class NewsCosumer_i : public POA_CosNotifyComm::StructuredPushCosumer { public: // This method will be called whe a ews evet occurs. virtual void push_structured_evet( cost CosNotificatio::StructuredEvet& otificatio ); Usig the CORBA Notificatio Service 3-7

106 3 Usig the BEA Simple Evets API // OMG s CosNotifyComm::StructuredPushCosumer idl // iterface defies the methods "offer_chage" ad // "discoect_structured_push_cosumer". Sice the // Notificatio Service ever ivokes these methods, just // have them throw a CORBA::NO_IMPLEMENT exceptio virtual void offer_chage( cost CosNotificatio::EvetTypeSeq& added, cost CosNotificatio::EvetTypeSeq& removed ) { throw CORBA::NO_IMPLEMENT(); } virtual void discoect_structured_push_cosumer() { throw CORBA::NO_IMPLEMENT(); } }; #edif Listig 3-6 Sample CosNotifyComm::StructuredPushCosumer Iterface Implemetatio (NewsCosumer_i.cpp) #iclude "NewsCosumer_i.h" #iclude <iostream.h> // // Subscriber.cpp creates a simple evets subscriptio to "News" // evets ad has the evets delivered to a NewsCosumer_i // object. Whe a ews evet occurs (this happes whe a user // rus the Reporter applicatio ad reports a ews story), this // method will be ivoked: void NewsCosumer_i::push_structured_evet( cost CosNotificatio::StructuredEvet& otificatio ) { // Extract the story from the first field i the evet s // filterable data. char* story; otificatio.filterable_data[0].value >>= story; // For codig simplicity, assume "story" is ot "ull". // Prit out the evet. cout << " " 3-8 Usig the CORBA Notificatio Service

107 Step 2: Writig a Applicatio to Subscribe to Evets... } << edl << "Category : " << otificatio.header.fixed_header. evet_type.type_ame.i() << edl << "Story : " << story << edl; Listig 3-7 shows how this iterface is implemeted i Java. Listig 3-7 Sample CosNotifyComm::StructuredPushCosumer Iterface Implemetatio (NewsCosumer_i.java) import org.omg.cosnotificatio.*; import org.omg.cosnotifycomm.*; import org.omg.corba.*; // // The servat class to receive ews evets. // It must implemet the CosNotifyComm::StructuredPushCosumer idl // iterface. public class NewsCosumer_i exteds _StructuredPushCosumerImplBase { // Subscriber.java creates a simple evets subscriptio to "News" // evets ad has the evets delivered to a NewsCosumer_i object. // Whe a ews evet occurs (this happes whe a user rus the // Reporter applicatio ad reports a ews story), this method will // be ivoked: public void push_structured_evet(structuredevet otificatio) { // For codig simplicity, assume that: // otificatio.header.fixed_header.evet_type.domai_ame is // "News" // otificatio.header.fixed_header.evet_type.type_ame is the // ews category // otificatio.filterable_data.legth is 1 // otificatio.filterable_data[0].ame is "Story" // otificatio.filterable_data[0].value cotais the story (as // a strig). Usig the CORBA Notificatio Service 3-9

108 3 Usig the BEA Simple Evets API // Extract the story from the first field i the evet s // filterable data. // For codig simplicity, do ot hadle errors idicatig that the // field does ot cotai a strig. Strig story = otificatio.filterable_data[0].value.extract_strig(); // Prit out the evet. System.out.pritl(" "); System.out.pritl("Category : " + otificatio.header.fixed_header.evet_type.type_ame ); System.out.pritl( "Story : " + story ); // At this poit, the mai has called the "wait_for_shutdow" // method o the shutdow object. That method blocks util // the "shutdow" method o the shutdow maager is called. // Call "shutdow" o the shutdow maager. This will cause // "wait_for_shutdow" to retur. Afterwards, the mai will // shutdow the applicatio. m_shutdow_maager.shutdow(); } // OMG s CosNotifyComm::StructuredPushCosumer idl // iterface defies the methods "offer_chage" ad // "discoect_structured_push_cosumer". Sice the // otificatio service ever ivokes these methods, just // have them throw a CORBA::NO_IMPLEMENT exceptio } public void discoect_structured_push_cosumer() { throw ew NO_IMPLEMENT(); } public void offer_chage(evettype[] added, EvetType[] removed) { throw ew NO_IMPLEMENT(); } Gettig the Evet Chael This step is the same for evet posters ad evet subscribers. For a discussio of this step, see Implemetig the CosNotifyComm::StructuredPushCosumer Iterface o page Usig the CORBA Notificatio Service

109 Step 2: Writig a Applicatio to Subscribe to Evets Creatig a Callback Object To receive evets, the applicatio must also be a server; that is, the applicatio must implemet a callback object that ca be ivoked (called back) whe a evet occurs that matches the subscriber s subscriptio. Creatig a callback object icludes the followig steps: Note: The followig steps apply to a BEA Tuxedo CORBA joit cliet/server. BEA Tuxedo CORBA servers ca also subscribe to evets. 1. Create a callback object. Callback objects ca be implemeted usig either the BEAWrapper Callback API or the CORBA Portable Object Adaptor (POA). 2. Create the servat. 3. Create a object referece to the callback servat. For a complete descriptio of the BEAWrapper Callbacks object ad its methods, see the Joit Cliet/Servers chapter i the CORBA Programmig Referece. Note: Usig the BEAWrapper Callback object to create a callback object is discussed below. For a discussio of how to implemet a callback object usig the POA, see Usig CORBA Server-to-Server Commuicatio. Listig 3-8 ad Listig 3-9 show how to use the BEAWrapper Callbacks object to create a callback object i C++ ad Java respectively. I the code examples, the NewsCosumber_i servat is created ad the start_trasiet method is used to create a trasiet object referece. Listig 3-8 Sample Code for Creatig a Callback Object With Trasiet Object Referece (Itroductory Applicatio Subscriber.cpp) // Create a callback wrapper object sice this cliet eeds to // support callbacks. BEAWrapper::Callbacks wrapper(orb.i()); NewsCosumer_i* ews_cosumer_impl = ew NewsCosumer_i; CORBA::Object_var ews_cosumer_oref = wrapper.start_trasiet( ews_cosumer_impl, Usig the CORBA Notificatio Service 3-11

110 3 Usig the BEA Simple Evets API CosNotifyComm::_tc_StructuredPushCosumer->id() ); CosNotifyComm::StructuredPushCosumer_var ews_cosumer = CosNotifyComm::StructuredPushCosumer::_arrow( ews_cosumer_oref.i() ); Listig 3-9 Sample Code for Creatig a Callback Object With Trasiet Object Referece (Itroductory Applicatio Subscriber.java) // Create a callback wrapper object sice this cliet eeds to // support callbacks. Callbacks callbacks = ew Callbacks(orb); // Istatiate the servat that receives the evets. NewsCosumer_i ews_cosumer_impl = ew NewsCosumer_i; // Create a trasiet object referece to the callback servat. callbacks.start_trasiet( ews_cosumer_impl, ews_cosumer_impl._ids()[0] ); Creatig a Subscriptio I order for the subscriber to receive evets, it must subscribe to the Notificatio Service. You ca create either a trasiet subscriptio or a persistet subscriptio. Listig 3-10 ad Listig 3-11, which are from the Itroductory sample applicatio, show how to create a trasiet subscriptio i C++ ad Java respectively. The followig steps must be performed: 1. Set the subscriptio s quality of service (QoS) to either trasiet or persistet. 2. Determie the subscriptio_ame (optioal), domai_ame, type_ame, ad data_filter (optioal) Usig the CORBA Notificatio Service

111 Step 2: Writig a Applicatio to Subscribe to Evets 3. Create the subscriptio. The subscriptio sets the domai_ame, type_ame, ad data_filter (optioal), the Quality of Service (QoS), ad supplies the object referece to the subscriber s callback object to the Notificatio Service. Listig 3-10 Creatig a Trasiet Subscriptio (C++) // Set the quality of service to TRANSIENT. CosNotificatio::QoSProperties qos; qos.legth(1); qos[0].ame = CORBA::strig_dup(Tobj_SimpleEvets::SUBSCRIPTION_TYPE); qos[0].value <<= Tobj_SimpleEvets::TRANSIENT_SUBSCRIPTION; // Set the type to the ews category. cost char* type = Sports ; // Create the subscriptio. Set the domai to "News" ad // the data filter to age greater tha 30. Tobj_SimpleEvets::SubscriptioID subscriptio_id = chael->subscribe( subscriptio_ame, "News", // domai Sports, // type "Age > 30", // Data filter. qos, ews_cosumer.i() ); Listig 3-11 Creatig a Trasiet Subscriptio (Java) // Set the quality of service to TRANSIENT. Property qos[] = ew Property[1]; qos[0] = ew Property(); qos[0].ame = SUBSCRIPTION_TYPE.value; qos[0].value = orb.create_ay(); qos[0].value.isert_short(transient_subscription.value); // Set the type to the ews category. Strig type = "Sports ; // Create the subscriptio. Set the domai to "News" ad // the data filter to age greater tha 30. it subscriptio_id = chael.subscribe( Usig the CORBA Notificatio Service 3-13

112 3 Usig the BEA Simple Evets API ); subscriptio_ame, "News", // domai Sports, // type "Age > 30", // data filter. qos, ews_cosumer_impl Note: Whe you use data filterig, you must also perform some cofiguratio tasks. For a discussio of data filterig cofiguratio requiremets, see Cofigurig Data Filters o page Listig 3-12 ad Listig 3-13, which show code i the Advaced sample applicatio i C++ ad Java, illustrates the codig steps required to create a persistet subscriptio to the Notificatio Service. The steps required to create a persistet subscriptio are the same as those required to create a trasiet subscriptio, as described previously. Note: While the code examples show here assume that the ews_cosumer callback object has a persistet object referece, you ca also create persistet subscriptios with trasiet callback object refereces. For a discussio of trasiet versus persistet callback object refereces, see Table Usig the CORBA Notificatio Service

113 Step 2: Writig a Applicatio to Subscribe to Evets Listig 3-12 Creatig a Persistet Subscriptio (Advaced Subscriber.cpp) CosNotificatio::QoSProperties qos; qos.legth(1); qos[0].ame = CORBA::strig_dup(Tobj_SimpleEvets::SUBSCRIPTION_TYPE); qos[0].value <<= Tobj_SimpleEvets::PERSISTENT_SUBSCRIPTION; CosNotifyComm::StructuredPushCosumer_var ews_cosumer = CosNotifyComm::StructuredPushCosumer::_arrow( ews_cosumer_oref.i() ); Tobj_SimpleEvets::SubscriptioID sub_id = chael->subscribe( subscriptio_ifo.subscriptio_ame(), "News", // domai Sports, // type, // No data filter. qos, ews_cosumer.i() ) ); Listig 3-13 Creatig a Persistet Subscriptio (Advaced Subscriber.java) Property qos[] = ew Property[1]; qos[0] = ew Property(); qos[0].ame = SUBSCRIPTION_TYPE.value; qos[0].value = orb.create_ay(); qos[0].value.isert_short(persistent_subscription.value); it sub_id = chael.subscribe( subscriptio_ifo.subscriptio_ame(), "News", // domai Sports, // type, // No data filter. qos, m_ews_cosumer_impl ) );// Usig the CORBA Notificatio Service 3-15

114 3 Usig the BEA Simple Evets API Threadig Cosideratios for C++ Joit Cliet/Server Applicatios A joit cliet/server applicatio may first fuctio as a cliet applicatio ad the switch to fuctioig as a server applicatio. To do this, the joit cliet/server applicatio turs complete cotrol of the thread to the Object Request Broker (ORB) by makig the followig ivocatio: orb -> ru(); If a method i the server portio of a joit cliet/server applicatio ivokes ORB::shutdow(), all server activity stops ad cotrol is retured to the statemet after ORB::ru() is ivoked i the server portio of the joit cliet/server applicatio. Oly uder this coditio does cotrol retur to the cliet fuctioality of the joit cliet/server applicatio. Sice a cliet applicatio has oly a sigle thread, the cliet fuctioality of the joit cliet/server applicatio must share the cetral processig uit (CPU) with the server fuctioality of the joit cliet/server applicatio. This sharig is accomplished by occasioally checkig with the ORB to see if the joit cliet/server applicatio has server applicatio work to perform. Use the followig code to perform the check with the ORB: if ( orb->work_pedig() ) orb->perform_work(); After the ORB completes the server applicatio work, the ORB returs to the joit cliet/server applicatio, which the performs cliet applicatio fuctios. The joit cliet/server applicatio must remember to occasioally check with the ORB; otherwise, the joit cliet/server applicatio will ever process ay ivocatios. You should be aware that the ORB caot service callbacks while the joit cliet/server applicatio is blockig o a request. If a joit cliet/server applicatio ivokes a object i aother BEA Tuxedo CORBA server applicatio, the ORB blocks while it waits for the respose. While the ORB is blockig, it caot service ay callbacks, so the callbacks are queued util the request is completed Usig the CORBA Notificatio Service

115 Step 3: Compilig ad Ruig Notificatio Service Applicatios Step 3: Compilig ad Ruig Notificatio Service Applicatios The fial step i the developmet of a Notificatio Service applicatio is to compile, build, ad ru the applicatio. To do this, you eed to perform the followig steps. 1. Geerate the required cliet stub ad skeleto files to defie iterfaces betwee the Notificatio Service ad evet poster ad subscriber applicatios. Evet poster applicatios ca be cliets, joit cliet/servers, or servers. Evet subscriber applicatios ca be joit cliet/servers or servers. 2. Compile the applicatio code ad lik agaist the skeleto ad cliet stub files. 3. Build the applicatio. 4. Ru the applicatio. Geeratig the Cliet Stub ad Skeleto Files To geerate the cliet stub ad skeleto files, you must execute the idl commad for each of the Notificatio IDL files that your applicatio uses. Table 3-2 shows the idl commads used for each type of subscriber. Table 3-2 idl Commad Requiremets Laguage BEA Tuxedo CORBA Joit Cliet/Server BEA Tuxedo CORBA Server C++ idl -P idl Java idltojava Not supported i BEA Tuxedo 8.0 ad later The followig is a example of a idl commad: >idl -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl Usig the CORBA Notificatio Service 3-17

116 3 Usig the BEA Simple Evets API Table 3-3 lists the IDL files required by each type of Notificatio Service applicatio that uses the BEA Simple Evets Iterface. Table 3-3 IDL Files Required by Notificatio Service Applicatios Applicatio Type Evet poster (ca be a cliet, a joit cliet/server, or a server). (Stubs are required for all files.) Subscriber (ca be a server or a joit cliet/server). (Stubs are required for all files. Skeleto is required for the CosNotifyComm.idl file.) Required OMG IDL Files CosEvetComm.idl CosNotificatio.idl CosNotifyComm.idl Tobj_Evets.idl Tobj_SimpleEvets.idl CosEvetComm.idl CosNotificatio.idl CosNotifyComm.idl Tobj_Evets.idl Tobj_SimpleEvets.idl Buildig ad Ruig Applicatios The build procedure differs depedig o the type of Notificatio Service applicatio you are buildig. Table 3-4 provides a overview of the commads ad types of files used to build each type of the Notificatio Service applicatio. Table 3-4 Applicatio Build Requiremets Applicatio Type Cliet Joit Cliet/Server Server C++ Evets Poster Use the buildobjcliet commad to compile the applicatio files ad the IDL stubs. Use the buildobjcliet commad with the -P optio to compile the applicatio files ad the IDL stubs. Use the buildobjserver commad to compile the applicatio files ad the IDL cliet stubs. C++ Evets Subscriber Not applicable. Use the buildobjcliet commad with the -P optio to compile the applicatio files, the IDL stubs, the IDL skeletos, ad lik with the BEAWrapper library. Use the buildobjserver commad to compile the applicatio files, the IDL stubs, ad the IDL skeletos Usig the CORBA Notificatio Service

117 Step 3: Compilig ad Ruig Notificatio Service Applicatios Table 3-4 Applicatio Build Requiremets (Cotiued) Applicatio Type Cliet Joit Cliet/Server Server Java Evets Poster Use the javac commad to compile the applicatio files ad the IDL stubs. Use the javac commad to compile the applicatio files ad the IDL files. Not supported i BEA Tuxedo 8.0 ad later. Java Evets Subscriber Not applicable. Use the javac commad to compile the applicatio files, the IDL files, ad the IDL skeletos. Not supported i BEA Tuxedo 8.0 ad later. Listig 3-14 shows the commads used for a C++ poster applicatio (Reporter.cpp) o a Microsoft Widows system. To form a C++ executable, the idl commad is ru o the required IDL file ad the buildobjcliet commad compiles the C++ cliet applicatio file ad the IDL stubs. Listig 3-14 C++ Reporter Applicatio Build ad Ru Commads (Microsoft Widows) # Ru the idl commad. idl -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosNotificatio.idl \ C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\Tobj_Evets.idl \ C:\tuxdir\iclude\Tobj_SimpleEvets.idl # Ru the buildobjcliet commad. buildobjcliet -v -o subscriber.exe -f " \ -DWIN32 \ Reporter.cpp \ CosEvetComm_c.cpp \ CosNotificatio_c.cpp \ CosNotifyComm_c.cpp \ Tobj_Evets_c.cpp \ Tobj_SimpleEvets_c.cpp \ " # Ru the applicatio. is_reporter Usig the CORBA Notificatio Service 3-19

118 3 Usig the BEA Simple Evets API Listig 3-15 ad Listig 3-16 show the commads used for a C++ subscriber applicatio (Subscriber.cpp) o Microsoft Widows ad UNIX respectively. To form a C++ executable, the buildobjcliet commad, with the -P optio, compiles the joit cliet/server applicatio files (Subscriber.cpp ad NewsCosumer_i.cpp), the IDL stubs, ad the IDL skeleto (CosNotifyComm_s.cpp). Listig 3-15 C++ Subscriber Applicatio Build ad Ru Commads (Microsoft Widows) # Ru the idl commad. idl -P -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosNotificatio.idl \ C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\Tobj_Evets.idl \ C:\tuxdir\iclude\Tobj_SimpleEvets.idl # Ru the buildobjcliet commad. buildobjcliet -v -P -o subscriber.exe -f " \ -DWIN32 \ Subscriber.cpp \ NewsCosumer_i.cpp \ CosEvetComm_c.cpp \ CosNotificatio_c.cpp \ CosNotifyComm_c.cpp \ CosNotifyComm_s.cpp \ Tobj_Evets_c.cpp \ Tobj_SimpleEvets_c.cpp \ c:\tuxdir\lib\libbeawrapper.lib \ " # Ru the applicatio. is_subscriber Listig 3-16 C++ Subscriber Applicatio Build ad Ru Commads (UNIX) # Ru the idl commad. idl -P -I/usr/local/tuxdir/iclude /usr/local/tuxdir/iclude/cosevetcomm.idl \ /usr/local/tuxdir/iclude/cosnotificatio.idl \ /usr/local/tuxdir/iclude/cosnotifycomm.idl \ 3-20 Usig the CORBA Notificatio Service

119 Step 3: Compilig ad Ruig Notificatio Service Applicatios /usr/local/tuxdir/iclude/tobj_evets.idl \ /usr/local/tuxdir/iclude/tobj_simpleevets.idl # Ru the buildobjcliet commad. buildobjcliet -v -P -o subscriber -f " \ Subscriber.cpp \ NewsCosumer_i.cpp \ CosEvetComm_c.cpp \ CosNotificatio_c.cpp \ CosNotifyComm_c.cpp \ CosNotifyComm_s.cpp \ Tobj_Evets_c.cpp \ Tobj_SimpleEvets_c.cpp \ -lbeawrapper \ " # Ru the applicatio. is_subscriber Listig 3-17 shows a example of the commads used to lik, build, ad ru remote Java poster applicatios. Listig 3-17 Java Reporter Applicatio Lik, Build, ad Ru Commads # Ru the idltojava commad. idltojava -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosNotificatio.idl C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\Tobj_Evets.idl C:\tuxdir\iclude\Tobj_SimpleEvets.idl # Compile the java files. javac -classpath C:\tuxdir\udataobj\java\jdk\m3evobj.jar Reporter.java # Combie the java.class files ito the java archive (JAR) file. jar cf reporter.jar Reporter.class org\omg\cosevetcomm \ org\omg\cosnotificatio org\omg\cosnotifycomm \ com\beasys\tobj_evets com\beasys\tobj_simpleevets # Ru the reporter applicatio. java -DTOBJADDR=//BEANIE:2359 -classpath \ reporter.jar;c:\tuxdir\udataobj\java\jdk\m3evobj.jar Reporter Usig the CORBA Notificatio Service 3-21

120 3 Usig the BEA Simple Evets API Listig 3-18 shows a example of the commads used to lik, build, ad ru remote Java subscriber applicatios. Listig 3-18 Java Subscriber Applicatio Lik, Build, ad Ru Commads # Ru the idltojava commad. idltojava -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosNotificatio.idl C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\Tobj_Evets.idl C:\tuxdir\iclude\Tobj_SimpleEvets.idl # Compile the java files. javac -classpath C:\tuxdir\udataobj\java\jdk\m3evobj.jar;\ C:\tuxdir\udataobj\java\jdk\wlecliet.jar Subscriber.java # Combie the java.class files ito the java archive (JAR) file. jar cf subscriber.jar Subscriber.class NewsCosumer_i.class \ org\omg\cosevetcomm org\omg\cosnotificatio org\omg\cosnotifycomm \ com\beasys\tobj_evets com\beasys\tobj_simpleevets # Ru the subscriber applicatio. java -DTOBJADDR=//BEANIE:2359 -classpath \ subscriber.jar;c:\tuxdir\udataobj\java\jdk\m3evobj.jar;\ C:\tuxdir\udataobj\java\jdk\wlecliet.jar Subscriber Note: The java commad lie i Listig 3-18 is for a applicatio that either sets the port i the applicatio code or prompts the user to set the port. You ca also set the port i the java commad lie. The followig is a example of a java commad lie that sets the port umber: java -DTOBJADDR=//BEANIE:2359 \ -Dorg.omg.corba.ORBPort=portumber -classpath Usig the CORBA Notificatio Service

121 CHAPTER 4 Usig the CosNotificatio Service API This chapter describes the developmet steps required to create Notificatio Service applicatios usig the CosNotificatio Service API ad the C++ ad Java programmig laguages. This topic icludes the followig sectios: Developmet Process Step 1: Writig a Applicatio to Post Evets Step 2: Writig a Applicatio to Subscribe to Evets Step 3: Compilig ad Ruig Notificatio Service Applicatios Developmet Process Table 4-1 outlies the developmet process for creatig Notificatio Service applicatios. Usig the CORBA Notificatio Service 4-1

122 4 Usig the CosNotificatio Service API Table 4-1 Developmet Process Step Descriptio 1 Desigig evets 2 Writig a applicatio that posts evets 3 Writig a applicatio that subscribes to evets 4 Compilig a Notificatio Service applicatio These steps are explaied i detail i subsequet topics. Desigig Evets The desig of evets is basic to ay otificatio service. The desig impacts ot oly the volume of iformatio that is delivered to matchig subscriptios, but the efficiecy ad performace of the Notificatio Service as well. Therefore, careful plaig should be doe to esure that your Notificatio Service will be able to hadle your eeds ow ad allow for future growth. For a discussio of evet desig, see Desigig Evets o page 2-7. Step 1: Writig a Applicatio to Post Evets The followig types of CORBA applicatios ca post evets: Note: BEA Tuxedo 8.0 supports Java cliets ad joit cliet servers, but it does ot support Java servers. Support for Java servers was previously icluded i versios 5.0 ad 5.1 of the BEA WebLogic Eterprise product, however, that support was removed whe BEA WebLogic Eterprise was merged with the BEA Tuxedo i release Usig the CORBA Notificatio Service

123 Step 1: Writig a Applicatio to Post Evets C++ cliets, joit cliet/servers ad servers. Java cliets ad joit cliet/servers. Foreig ORB cliets. To post evets, a applicatio must, at a miimum, implemet the followig fuctios: Get the evet chael factory object referece ad use it to get the evet chael. Create ad post evets. The followig sectios describe each of these fuctios. Gettig the Evet Chael Before the cliet applicatio ca post a evet, it must get the evet chael. This developmet step is illustrated i Listig 4-1. Listig 4-1 is code from the Reporter.cpp file i the Itroductory sample applicatio that uses the CosNotificatio Service API. To get the evet chael factory object referece, the resolve_iitial_refereces method is ivoked o the Bootstrap object usig the "NotificatioService" evirometal object. The object referece is used to get the chael factory, which is, i tur, is used to get the evet chael. Listig 4-1 ad Listig 4-2 show code examples i C++ ad Java. Listig 4-1 Gettig the Evet Chael (Reporter.cpp) // Get the CosNotificatio chael factory object referece. CORBA::Object_var chael_factory_oref = bootstrap.resolve_iitial_refereces( "NotificatioService" ); CosNotifyChaelAdmi::EvetChaelFactory_var chael_factory = CosNotifyChaelAdmi::EvetChaelFactory::_arrow( chael_factory_oref.i() ); Usig the CORBA Notificatio Service 4-3

124 4 Usig the CosNotificatio Service API // use the chael factory to get the default chael CosNotifyChaelAdmi::EvetChael_var chael = chael_factory->get_evet_chael( Tobj_Notificatio::DEFAULT_CHANNEL ); Listig 4-2 Gettig the Evet Chael (Reporter.java) import org.omg.cosnotificatio.*;//some of the CosNotificatio API. import org.omg.cosnotifychaeladmi.*;import // The rest of the // CosNotificatio API. com.beasys.tobj_notificatio.*; // Proprietary costats eeded // whe usig the CosNotificatio API. import com.beasys.tobj.*; import com.beasys.*; import org.omg.corba.*; import java.io.*; // get the CosNotificatio chael factory object referece org.omg.corba.object chael_factory_oref = bootstrap.resolve_iitial_refereces("notificatioservice"); EvetChaelFactory chael_factory = EvetChaelFactoryHelper.arrow(chael_factory_oref); // use the chael factory to get the default chael EvetChael chael = chael_factory.get_evet_chael(default_channel.value); Creatig ad Postig Evets To post evets, you must get the SupplierAdmi object, use it to create a proxy, create the evet, ad the post the evet to the proxy. Listig 4-3 ad Listig 4-4 show how this is implemeted i C++ ad Java respectively. 4-4 Usig the CORBA Notificatio Service

125 Step 1: Writig a Applicatio to Post Evets Listig 4-3 Creatig ad Postig the Evet (Reporter.cpp) // Sice we are a supplier (that is, we post evets), // get the SupplierAdmi object CosNotifyChaelAdmi::SupplierAdmi_var supplier_admi = chael->default_supplier_admi(); // Use the supplier admi to create a proxy. Evets are posted // to the proxy (ulike the simple evets iterface where evets // are posted to the chael). CosNotifyChaelAdmi::ProxyID proxy_id; CosNotifyChaelAdmi::ProxyCosumer_var geeric_proxy_cosumer = supplier_admi->obtai_otificatio_push_cosumer( CosNotifyChaelAdmi::STRUCTURED_EVENT, proxy_id ); CosNotifyChaelAdmi::StructuredProxyPushCosumer_var proxy_push_cosumer = CosNotifyChaelAdmi::StructuredProxyPushCosumer::_arrow( geeric_proxy_cosumer ); // Coect to the proxy so that we ca post evets. proxy_push_cosumer->coect_structured_push_supplier( CosNotifyComm::StructuredPushSupplier::_il() );... // create a evet CosNotificatio::StructuredEvet otificatio; // set the domai to "News" otificatio.header.fixed_header.evet_type.domai_ame = CORBA::strig_dup("News"); // set the type to the ews category otificatio.header.fixed_header.evet_type.type_ame = CORBA::strig_dup( Sports ); // add oe field, which will cotai the story, to the // evet's filterable data. set the field's ame to // "Story" ad value to a strig cotaiig the story otificatio.filterable_data.legth(1); otificatio.filterable_data[0].ame = CORBA::strig_dup("Story"); otificatio.filterable_data[0].value <<= Joh Smith wis agai ; // post the evet // Subscribers who subscribed to evets whose domai is // "News" ad whose type matches the ews category will // receive this evet proxy_push_cosumer->push_structured_evet(otificatio); Usig the CORBA Notificatio Service 4-5

126 4 Usig the CosNotificatio Service API... // Discoect. proxy_push_cosumer->discoect_structured_push_cosumer(); Listig 4-4 Creatig ad Postig the Evet (Reporter.java) // sice we re a supplier (that is, we post evets) // get the supplier admi object SupplierAdmi supplier_admi = chael.default_supplier_admi(); // use the supplier admi to create a proxy. Evets are posted // to the proxy (ulike the simple evets iterface where evets // are posted to the chael). ItHolder proxy_id = ew ItHolder(); ProxyCosumer geeric_proxy_cosumer = supplier_admi.obtai_otificatio_push_cosumer( ClietType.STRUCTURED_EVENT, proxy_id ); m_proxy_push_cosumer = StructuredProxyPushCosumerHelper.arrow( geeric_proxy_cosumer); // Coect to the proxy so that we ca post evets. m_proxy_push_cosumer.coect_structured_push_supplier(ull);... // create a evet StructuredEvet otificatio = ew StructuredEvet(); otificatio.header = ew EvetHeader(); // create the sub structures for the header otificatio.header.fixed_header = ew FixedEvetHeader(); otificatio.header.fixed_header.evet_type = ew EvetType(); // set the domai to "News" otificatio.header.fixed_header.evet_type.domai_ame = "News"; // set the type to the ews category otificatio.header.fixed_header.evet_type.type_ame = Sports ; // set the evet ame to a empty strig sice this sample // does't use it otificatio.header.fixed_header.evet_ame = ""; // empty the variable header sice this sample does't use it otificatio.header.variable_header = ew Property[0]; 4-6 Usig the CORBA Notificatio Service

127 Step 2: Writig a Applicatio to Subscribe to Evets // add oe field, which will cotai the story, to the // evet s filterable data. set the field s ame to // "Story" ad value to a strig cotaiig the story otificatio.filterable_data = ew Property[1]; otificatio.filterable_data[0] = ew Property(); otificatio.filterable_data[0].ame = "Story"; otificatio.filterable_data[0].value = orb.create_ay(); otificatio.filterable_data[0].value.isert_strig( Joh Smith wis agai ); // set the remaider of body to a ew (empty) ay sice this // sample does't use the remaider of body otificatio.remaider_of_body = orb.create_ay(); m_proxy_push_cosumer.push_structured_evet(otificatio);... // discoect proxy_push_cosumer.discoect_structured_push_cosumer(); Step 2: Writig a Applicatio to Subscribe to Evets The followig types of CORBA applicatios ca subscribe to evets: Note: BEA Tuxedo 8.0 supports Java cliets ad joit cliet servers, but it does ot support Java servers. Support for Java servers was previously icluded i versios 5.0 ad 5.1 of the BEA WebLogic Eterprise product, however, that support was removed whe BEA WebLogic Eterprise was merged with the BEA Tuxedo i release 8.0. C++ joit cliet/servers ad servers. Java joit cliet/servers. Foreig ORB cliets that support callbacks. To subscribe to evets, a applicatio must, at a miimum, support the followig fuctios: Usig the CORBA Notificatio Service 4-7

128 4 Usig the CosNotificatio Service API Implemet a CosNotifyComm OMG IDL iterface that supports the push_structured_evet operatio. Get the evet chael factory object referece ad use it to get the evet chael. Defie ad create a subscriptio that icludes the callback object referece. Create a callback object that implemets the CosNotifyComm::StructuredPushCosumer iterface. Implemetig the CosNotifyComm::StructuredPushCosumer Iterface I order for the callback servat object to receive evets, it must implemet the CosNotifyComm::StructuredPushCosumer iterface that supports the push_structured_evet operatio. Whe a evet occurs that has a matchig subscriptio, the Notificatio Service ivokes this operatio o the servat callback object i the subscriber applicatio to deliver the evet to the subscriber applicatio. The CosNotifyComm::StructuredPushCosumer iterface also defies the operatios offer_chage ad discoect_structured_push_cosumer. The Notificatio Service ever ivokes these operatios, so you should implemet stubbed out versios that throw CORBA::NO_IMPLEMENT. Listig 4-5 ad Listig 4-6 show how this iterface is implemeted i C++. Listig 4-5 Sample CosNotifyComm::StructuredPushCosumer Iterface Implemetatio (NewsCosumer_i.h) #ifdef _ews_cosumer_i_h #defie _ews_cosumer_i_h #iclude "CosNotifyComm_s.h" // For the servat class to receive ews evets, // it must implemet the CosNotifyComm::StructuredPushCosumer // idl iterface class NewsCosumer_i : public POA_CosNotifyComm::StructuredPushCosumer 4-8 Usig the CORBA Notificatio Service

129 Step 2: Writig a Applicatio to Subscribe to Evets { public: // this method will be called whe a ews evet occurs virtual void push_structured_evet( cost CosNotificatio::StructuredEvet& otificatio ); // OMG s CosNotifyComm::StructuredPushCosumer idl // iterface defies the methods "offer_chage" ad // "discoect_structured_push_cosumer". Sice the // Notificatio Service ever ivokes these methods, just // have them throw a CORBA::NO_IMPLEMENT exceptio virtual void offer_chage( cost CosNotificatio::EvetTypeSeq& added, cost CosNotificatio::EvetTypeSeq& removed ) { throw CORBA::NO_IMPLEMENT(); } virtual void discoect_structured_push_cosumer() { throw CORBA::NO_IMPLEMENT(); } }; #edif Usig the CORBA Notificatio Service 4-9

130 4 Usig the CosNotificatio Service API Listig 4-6 Sample CosNotifyComm::StructuredPushCosumer Iterface Implemetatio (NewsCosumer_i.cpp) #iclude "NewsCosumer_i.h" #iclude <iostream.h> // // Subscriber.cpp creates a simple evets subscriptio to "News" // evets ad has the evets delivered to a NewsCosumer_i // object. Whe a ews evet occurs (this happes whe a user // rus the Reporter applicatio ad reports a ews story), this // method will be ivoked: void NewsCosumer_i::push_structured_evet( cost CosNotificatio::StructuredEvet& otificatio ) { // extract the story from the first field i the evet s // filterable data char* story; otificatio.filterable_data[0].value >>= story; // for codig simplicity, assume "story" is ot "ull" // prit out the evet cout << " " << edl << "Category : " << otificatio.header.fixed_header. evet_type.type_ame.i() << edl << "Story : " << story << edl;... } 4-10 Usig the CORBA Notificatio Service

131 Step 2: Writig a Applicatio to Subscribe to Evets Listig 4-7 shows how this iterface is implemeted i Java. Listig 4-7 Sample CosNotifyComm::StructuredPushCosumer Iterface Implemetatio (NewsCosumer_i.java) import org.omg.cosnotificatio.*; import org.omg.cosnotifycomm.*; import org.omg.corba.*; // // The servat class to receive ews evets. // It must implemet the CosNotifyComm::StructuredPushCosumer idl // iterface. public class NewsCosumer_i exteds _StructuredPushCosumerImplBase { // Subscriber.java creates a simple evets subscriptio to "News" // evets ad has the evets delivered to a NewsCosumer_i object. // Whe a ews evet occurs (this happes whe a user rus the // Reporter applicatio ad reports a ews story), this method will // be ivoked: public void push_structured_evet(structuredevet otificatio) { // For codig simplicity, assume that: // otificatio.header.fixed_header.evet_type.domai_ame is // "News" // otificatio.header.fixed_header.evet_type.type_ame is // the ews category // otificatio.filterable_data.legth is 1 // otificatio.filterable_data[0].ame is "Story" // otificatio.filterable_data[0].value cotais the story // (as a strig). // Extract the story from the first field i // the evet s filterable data for codig simplicity, do ot // hadle errors idicatig that the field // does ot cotai a strig. Strig story = otificatio.filterable_data[0].value.extract_strig(); // Prit out the evet. System.out.pritl(" "); System.out.pritl( "Category : " + otificatio.header.fixed_header.evet_type.type_ame ); Usig the CORBA Notificatio Service 4-11

132 4 Usig the CosNotificatio Service API } System.out.pritl( "Story : " + story ); // At this poit, the mai has called the "wait_for_shutdow" // method o the shutdow object. That method blocks util // the "shutdow" method o the shutdow maager is called. // Call "shutdow" o the shutdow maager. This will cause // "wait_for_shutdow" to retur. Afterwards, the mai will // shutdow the applicatio. m_shutdow_maager.shutdow(); // OMG s CosNotifyComm::StructuredPushCosumer idl // iterface defies the methods "offer_chage" ad // "discoect_structured_push_cosumer". Sice the // otificatio service ever ivokes these methods, just // have them throw a CORBA::NO_IMPLEMENT exceptio } public void discoect_structured_push_cosumer() { throw ew NO_IMPLEMENT(); } public void offer_chage(evettype[] added, EvetType[] removed) { throw ew NO_IMPLEMENT(); } Gettig the Evet Chael, CosumerAdmi Object, ad Filter Factory Object Before a applicatio ca create a subscriptio, it must get the evet chael ad the CosumerAdmi ad Filter Factory objects. Listig 4-8 ad Listig 4-9 show how this is implemeted i C++ ad Java respectively. To get the evet chael factory object referece, the resolve_iitial_refereces method is ivoked o the Bootstrap object usig the "NotificatioService" evirometal object. The object referece is used to get the chael factory, which is, i tur, used to get the evet chael. Fially, the evet chael is used to get the CosumerAdmi object ad the FilterFactory object Usig the CORBA Notificatio Service

133 Step 2: Writig a Applicatio to Subscribe to Evets Listig 4-8 Gettig the Evet Chael ad CosumerAdmi ad Filter Factory Objects (Subscriber.cpp) // Get the CosNotificatio chael factory object referece. CORBA::Object_var chael_factory_oref = bootstrap.resolve_iitial_refereces( "NotificatioService" ); CosNotifyChaelAdmi::EvetChaelFactory_var chael_factory = CosNotifyChaelAdmi::EvetChaelFactory::_arrow( chael_factory_oref.i() ); // Use the chael factory to get the default chael. CosNotifyChaelAdmi::EvetChael_var chael = chael_factory->get_evet_chael( Tobj_Notificatio::DEFAULT_CHANNEL ); // Use the chael to get the cosumer admi ad the filter factory. CosNotifyChaelAdmi::CosumerAdmi_var cosumer_admi = chael->default_cosumer_admi(); CosNotifyFilter::FilterFactory_var filter_factory = chael->default_filter_factory(); Usig the CORBA Notificatio Service 4-13

134 4 Usig the CosNotificatio Service API Listig 4-9 Gettig the Evet Chael (Subscriber.java) // get the CosNotificatio chael factory object referece org.omg.corba.object chael_factory_oref = bootstrap.resolve_iitial_refereces("notificatioservice"); EvetChaelFactory chael_factory = EvetChaelFactoryHelper.arrow(chael_factory_oref); // use the chael factory to get the default chael EvetChael chael = chael_factory.get_evet_chael(default_channel.value); // use the chael to get the cosumer admi ad the filter factory CosumerAdmi cosumer_admi = chael.default_cosumer_admi(); FilterFactory filter_factory = chael.default_filter_factory(); Creatig a Callback Object To receive evets, the applicatio must also be a server; that is, the applicatio must implemet a callback object that ca be ivoked (called back) whe a evet occurs that matches the subscriber s subscriptio. Creatig a callback object icludes the followig steps: Note: The followig steps apply to a joit cliet/server. BEA Tuxedo CORBA servers ca also subscribe to evets. 1. Creatig a callback wrapper object. This ca be implemeted usig either the BEAWrapper Callbacks object or the CORBA Portable Object Adaptor (POA). 2. Creatig the servat. 3. Creatig a object referece to the callback servat. For a complete descriptio of the BEAWrapper Callbacks object ad its methods, see the Joit Cliet/Servers chapter i the CORBA Programmig Referece Usig the CORBA Notificatio Service

135 Step 2: Writig a Applicatio to Subscribe to Evets Note: Usig the BEAWrapper Callback object to create a callback object is discussed below. For a discussio of how to implemet a callback object usig the POA, see Usig CORBA Server-to-Server Commuicatio. Listig 4-10 ad Listig 4-11 show how to use the BEAWrapper Callbacks object to create a callback object i C++ ad Java respectively. I the code examples, the NewsCosumber_i servat is created ad the start_trasiet method is used to create a trasiet object referece. Listig 4-10 Sample Code for Creatig a Callback Object with Trasiet Object Referece (Itroductory Applicatio Subscriber.cpp) // Create a callback wrapper object sice this cliet eeds to // support callbacks BEAWrapper::Callbacks wrapper(orb.i()); NewsCosumer_i* ews_cosumer_impl = ew NewsCosumer_i; // Create a trasiet object referece to this servat. CORBA::Object_var ews_cosumer_oref = wrapper.start_trasiet( ews_cosumer_impl, CosNotifyComm::_tc_StructuredPushCosumer->id() ); CosNotifyComm::StructuredPushCosumer_var ews_cosumer = CosNotifyComm::StructuredPushCosumer::_arrow( ews_cosumer_oref.i() ); Usig the CORBA Notificatio Service 4-15

136 4 Usig the CosNotificatio Service API Listig 4-11 Sample Code for Creatig a Callback Object With Trasiet Object Referece (Itroductory Applicatio Subscriber.java) // Create a callback wrapper object sice this cliet eeds to // support callbacks. Callbacks callbacks = ew Callbacks(orb); // Istatiate the servat that receives the evets. NewsCosumer_i ews_cosumer_impl = ew NewsCosumer_i(shutdow_maager); // Create a trasiet object referece to the callback servat. callbacks.start_trasiet( ews_cosumer_impl, ews_cosumer_impl._ids()[0] ); Creatig a Subscriptio I order for the subscriber to receive evets, it must subscribe to the Notificatio Service. You ca create a trasiet subscriptio or a persistet subscriptio. To create a subscriptio, the followig steps must be performed: 1. Create a otificatio proxy push supplier ad use it to create a StructuredProxySupplier object. 2. Set the subscriptio s Quality of Service (QoS). You ca set the QoS to trasiet or persistet. 3. Create a filter object ad assig the domai_ame, type_ame, ad data_filter (optioal) to it. 4. Add the filter to the proxy. 5. Coect to the proxy passig i the subscriptio s callback object referece. Listig 4-12 ad Listig 4-13, which is code from the Itroductory sample applicatio, show how to create a trasiet subscriptio i C++ ad Java respectively Usig the CORBA Notificatio Service

137 Step 2: Writig a Applicatio to Subscribe to Evets Listig 4-12 Creatig a Trasiet Subscriptio // Create a ew subscriptio (at this poit, it is ot complete). CosNotifyChaelAdmi::ProxyID subscriptio_id; CosNotifyChaelAdmi::ProxySupplier_var geeric_subscriptio = cosumer_admi->obtai_otificatio_push_supplier( CosNotifyChaelAdmi::STRUCTURED_EVENT, subscriptio_id ); CosNotifyChaelAdmi::StructuredProxyPushSupplier_var subscriptio = CosNotifyChaelAdmi::StructuredProxyPushSupplier::_arrow( geeric_subscriptio ); s_subscriptio = subscriptio.i(); // Set the quality of service. This sets the subscriptio ame // ad subscriptio type (=TRANSIENT). CosNotificatio::QoSProperties qos; qos.legth(2); qos[0].ame = CORBA::strig_dup(Tobj_Notificatio::SUBSCRIPTION_NAME); qos[0].value <<= subscriptio_ame; qos[1].ame = CORBA::strig_dup(Tobj_Notificatio::SUBSCRIPTION_TYPE); qos[1].value <<= Tobj_Notificatio::TRANSIENT_SUBSCRIPTION; subscriptio->set_qos(qos); // Create a filter (used to specify domai, type ad data filter). CosNotifyFilter::Filter_var filter = filter_factory->create_filter( Tobj_Notificatio::CONSTRAINT_GRAMMAR ); s_filter = filter.i(); // Set the filterig parameters. // (domai = "News", type = Sports, ad o data filter) CosNotifyFilter::CostraitExpSeq costraits; costraits.legth(1); costraits[0].evet_types.legth(1); costraits[0].evet_types[0].domai_ame = CORBA::strig_dup("News"); costraits[0].evet_types[0].type_ame = CORBA::strig_dup( Sports ); costraits[0].costrait_expr = CORBA::strig_dup(""); // No data filter. Usig the CORBA Notificatio Service 4-17

138 4 Usig the CosNotificatio Service API CosNotifyFilter::CostraitIfoSeq_var add_costraits_results = // igore this retured value filter->add_costraits(costraits); // Add the filter to the subscriptio. CosNotifyFilter::FilterID filter_id = subscriptio->add_filter(filter.i()); // Now that we have set the subscriptio ame, type ad filterig // parameters, complete the subscriptio by passig i the // referece of the callback object to deliver the evets to. subscriptio->coect_structured_push_cosumer( ews_cosumer.i() ); Listig 4-13 Creatig a Trasiet Subscriptio (Itroductory Subscriber.java) // Create a ew subscriptio (at this poit, it is ot complete). ItHolder subscriptio_id = ew ItHolder(); ProxySupplier geeric_subscriptio = cosumer_admi.obtai_otificatio_push_supplier( ClietType.STRUCTURED_EVENT, subscriptio_id ); StructuredProxyPushSupplier subscriptio = StructuredProxyPushSupplierHelper.arrow( geeric_subscriptio ); // Set the quality of service. This sets the subscriptio ame // ad subscriptio type (=TRANSIENT) Property qos[] = ew Property[2]; qos[0] = ew Property(); qos[0].ame = SUBSCRIPTION_NAME.value; qos[0].value = orb.create_ay(); qos[0].value.isert_strig(subscriptio_ame); qos[1] = ew Property(); qos[1].ame = SUBSCRIPTION_TYPE.value; qos[1].value = orb.create_ay(); qos[1].value.isert_short(transient_subscription.value); subscriptio.set_qos(qos); // Create a filter (used to specify domai, type ad data filter). Filter filter = filter_factory.create_filter(constraint_grammar.value); // set the filterig parameters // (domai = "News", type = Sports, ad o data filter) 4-18 Usig the CORBA Notificatio Service

139 Step 3: Compilig ad Ruig Notificatio Service Applicatios CostraitExp costraits[] = ew CostraitExp[1]; costraits[0] = ew CostraitExp(); costraits[0].evet_types = ew EvetType[1]; costraits[0].evet_types[0] = ew EvetType(); costraits[0].evet_types[0].domai_ame = "News"; costraits[0].evet_types[0].type_ame = Sports ; costraits[0].costrait_expr = ""; CostraitIfo add_costraits_results[] = filter.add_costraits(costraits); // add the filter to the subscriptio it filter_id = subscriptio.add_filter(filter); // Now that we have set the subscriptio ame, type ad // filterig parameters, complete the subscriptio by passig // i the referece of the callback object to deliver the // evets to. subscriptio.coect_structured_push_cosumer( ews_cosumer_impl ); Step 3: Compilig ad Ruig Notificatio Service Applicatios The fial step i the developmet of a Notificatio Service applicatio is to compile, build, ad ru the applicatio. To do this, you eed to perform the followig steps. 1. Geerate the required cliet stub ad skeleto files to defie iterfaces betwee the Notificatio Service ad evet poster ad subscriber applicatios. Evet poster applicatios ca be cliets, joit cliet/servers, or servers. Evet subscriber applicatios ca be joit cliet/servers or servers. 2. Compile the applicatio code ad lik agaist the skeleto ad cliet stub files. 3. Build the applicatio. 4. Ru the applicatio. Usig the CORBA Notificatio Service 4-19

140 4 Usig the CosNotificatio Service API Geeratig the Cliet Stub ad Skeleto Files To geerate the cliet stub ad skeleto files, you must execute the idl commad for each of the Notificatio IDL files that your applicatio uses. Table 4-2 shows the idl commads used for each type of subscriber. Table 4-2 idl Commad Requiremets Laguage BEA Tuxedo CORBA Joit Cliet/Server BEA Tuxedo CORBA Server C++ idl -P idl Java idltojava Not supported i BEA Tuxedo 8.0 ad later. The followig is a example of a idl commad: >idl -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl Table 4-3 lists the IDL files required by each type of Notificatio Service applicatio. Table 4-3 IDL Files Required by Notificatio Service Applicatios Applicatio Type Evet poster (ca be a cliet, a joit cliet/server, or a server) Subscriber (ca be joit cliet/server or a server) Required OMG IDL Files CosEvetChaelAdmi.idl CosEvetComm.idl CosNotificatio.idl CosNotifyChaelAdmi CosNotifyComm.idl CosNotifyFilter Tobj_Evets.idl Tobj_Notificatio.idl CosEvetChaelAdmi.idl CosEvetComm.idl CosNotificatio.idl CosNotifyChaelAdmi CosNotifyComm.idl CosNotifyFilter Tobj_Evets.idl Tobj_Notificatio.idl 4-20 Usig the CORBA Notificatio Service

141 Step 3: Compilig ad Ruig Notificatio Service Applicatios Compilig ad Likig the Applicatio Code The compilig ad likig procedure differs depedig o the type of Notificatio Service applicatio you are buildig. Table 4-4 provides a overview of the commads ad files used to compile each type of applicatio. Table 4-4 Applicatio Build Requiremets Applicatio Type Cliet Joit Cliet/Server Server C++ Evets Poster Use the buildobjcliet commad to compile the applicatio files ad the IDL stubs. Use the buildobjcliet commad with the -P optio to compile the applicatio files ad the IDL stubs. Use the buildobjserver commad to compile the applicatio files ad the IDL cliet stubs. C++ Evets Subscriber Not applicable. Use the buildobjcliet commad with the -P optio to compile the applicatio files, the IDL stubs, ad the IDL skeletos. Use the buildobjserver commad to compile the applicatio files, the IDL stubs, ad the IDL skeletos. Java Evets Poster Use the javac commad to compile the applicatio files ad the IDL stubs. Use the javac commad to compile the applicatio files ad the IDL files. Not supported i BEA Tuxedo 8.0 ad later. Java Evets Subscriber Not applicable. Use the javac commad to compile the applicatio files, the IDL files, ad the IDL skeletos. Not supported i BEA Tuxedo 8.0 ad later. Listig 4-14 shows the commads used for a C++ Reporter applicatio (Reporter.cpp) o a Microsoft Widows system. To form a C++ executable, the idl commad is ru o the required IDL file ad the buildobjcliet commad compiles the C++ cliet applicatio file ad the IDL stubs. Usig the CORBA Notificatio Service 4-21

142 4 Usig the CosNotificatio Service API Listig 4-14 C++ Reporter Applicatio Build ad Ru Commads # Ru the idl commad. idl -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosEvetChaelAdmi \ C:\tuxdir\iclude\CosNotificatio.idl \ C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\CosNotifyFilter.idl \ C:\tuxdir\iclude\Tobj_Notificatio.idl # Ru the buildobjcliet commad. buildobjcliet -v -o is_reporter.exe -f \ -DWIN32 \ Reporter.cpp \ CosEvetComm_c.cpp \ CosEvetChaelAdmi_c.cpp \ CosNotificatio_c.cpp \ CosNotifyComm_c.cpp \ CosNotifyFilter_c.cpp \ CosNotifyChaelAdmi_c.cpp \ Tobj_Evets_c.cpp \ Tobj_Notificatio_c.cpp # Ru the applicatio. is_reporter Listig 4-15 ad Listig 4-16 show the commads used for a C++ Subscriber applicatio (Subscriber.cpp) o Microsoft Widows ad UNIX, respectively. To form a C++ executable, the buildobjcliet commad, with the -P optio, compiles the joit cliet/server applicatio files (Subscriber.cpp ad NewsCosumer_i.cpp), the IDL stubs, the IDL skeleto (for CosNotifyComm_s.cpp). Listig 4-15 C++ Subscriber Applicatio Build ad Ru Commads (Microsoft Widows) # Ru the idl commad. idl -P -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosEvetChaelAdmi \ C:\tuxdir\iclude\CosNotificatio.idl \ C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\CosNotifyFilter.idl \ 4-22 Usig the CORBA Notificatio Service

143 Step 3: Compilig ad Ruig Notificatio Service Applicatios C:\tuxdir\iclude\CosNotifyChaelAdmi \ \C:\tuxdir\iclude\Tobj_Evets.idl \ \C:\tuxdir\iclude\Tobj_Notificatio # Ru the buildobjcliet commad. buildobjcliet -v -P -o is_subscriber.exe -f " \ -DWIN32 \ Subscriber.cpp \ NewsCosumer_i.cpp \ CosEvetComm_c.cpp \ CosEvetChaelAdmi_c.cpp \ CosNotificatio_c.cpp \ CosNotifyComm_c.cpp \ CosNotifyComm_s.cpp \ CosNotifyFilter_c.cpp \ CosNotifyChaelAdmi_c.cpp \ Tobj_Evets_c.cpp \ Tobj_Notificatio_c.cpp \ C:\tuxdir\lib\libbeawrapper.lib \ " # Ru the applicatio. is_subscriber Listig 4-16 C++ Subscriber Applicatio Build ad Ru Commads (UNIX) # Ru the idl commad. idl -P -I/usr/local/tuxdir/iclude /usr/local/tuxdir/iclude/cosevetchaeladmi \ /usr/local/tuxdir/iclude/cosevetcomm.idl \ /usr/local/tuxdir/iclude/cosnotificatio.idl \ /usr/local/tuxdir/iclude/cosnotifycomm.idl \ /usr/local/tuxdir/iclude/cosnotifyfilter.idl \ /usr/local/tuxdir/iclude/cosnotifychaeladmi \ /usr/local/tuxdir/iclude/tobj_evets.idl \ /usr/local/tuxdir/iclude/tobj_simpleevets.idl # Ru the buildobjcliet commad. buildobjcliet -v -P -o subscriber -f " \ Subscriber.cpp \ NewsCosumer_i.cpp \ CosEvetComm_c.cpp \ CosEvetChaelAdmi_c.cpp \ CosNotificatio_c.cpp \ CosNotifyComm_c.cpp \ CosNotifyComm_s.cpp \ Usig the CORBA Notificatio Service 4-23

144 4 Usig the CosNotificatio Service API CosNotifyFilter_c.cpp \ CosNotifyChaelAdmi_c.cpp \ Tobj_Evets_c.cpp \ Tobj_SimpleEvets_c.cpp \ -lbeawrapper \ " # Ru the applicatio. is_subscriber Listig 4-17 ad Listig 4-18 show a example of the commads used to lik, build, ad ru remote Java Reporter ad Subscriber applicatios. Listig 4-17 Java Reporter Applicatio Lik, Build, ad Ru Commads # Ru the idltojava commad. idltojava -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosEvetChaelAdmi.idl \ C:\tuxdir\iclude\CosNotificatio.idl C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\CosNotifyFilter.idl \ C:\tuxdir\iclude\CosNotifyChaelAdmi.idl \ C:\tuxdir\iclude\Tobj_Evets.idl \ C:\tuxdir\iclude\Tobj_Notificatio.idl # Compile the java files. javac -classpath C:\tuxdir\udataobj\java\jdk\m3evobj.jar Reporter.java # Combie the java.class files ito the java archive (JAR) file. jar cf reporter.jar Reporter.class org\omg\cosevetcomm \ org\omg\cosevetchaeladmi org\omg\cosnotificatio org\omg\cosnotifycomm \ org\omg\cosnotifyfilter org\omg\cosnotifychaeladmi com\beasys\tobj_evets \ com\beasys\tobj_notificatio # Ru the reporter applicatio. java -DTOBJADDR=//BEANIE:2359 -classpath \ reporter.jar;c:\tuxdir\udataobj\java\jdk\m3evobj.jar Reporter 4-24 Usig the CORBA Notificatio Service

145 Step 3: Compilig ad Ruig Notificatio Service Applicatios Listig 4-18 Java Subscriber Applicatio Lik, Build, ad Ru Commads # Ru the idltojava commad. idltojava -IC:\tuxdir\iclude C:\tuxdir\iclude\CosEvetComm.idl \ C:\tuxdir\iclude\CosEvetChaelAdmi.idl \ C:\tuxdir\iclude\CosNotificatio.idl C:\tuxdir\iclude\CosNotifyComm.idl \ C:\tuxdir\iclude\CosNotifyFilter.idl \ C:\tuxdir\iclude\CosNotifyChaelAdmi.idl \ C:\tuxdir\iclude\Tobj_Evets.idl C:\tuxdir\iclude\Tobj_Notificatio.idl # Compile the java files. javac -classpath C:\tuxdir\udataobj\java\jdk\m3evobj.jar;\ C:\tuxdir\udataobj\java\jdk\wlecliet.jar Subscriber.java # Combie the java.class files ito the java archive (JAR) file. jar cf subscriber.jar Subscriber.class NewsCosumer_i.class \ org\omg\cosevetcomm org\omg\cosevetchaeladmi org\omg\cosnotificatio \ org\omg\cosnotifycomm org\omg\cosnotifyfilter org\omg\cosnotifychaeladmi \ com\beasys\tobj_evets com\beasys\tobj_notificatio # Ru the subscriber applicatio. java -DTOBJADDR=//BEANIE:2359 -classpath \ subscriber.jar;c:\tuxdir\udataobj\java\jdk\m3evobj.jar;\ C:\tuxdir\udataobj\java\jdk\wlecliet.jar Subscriber Note: The java commad lie i Listig 4-18 is for a applicatio that either sets the port i the applicatio code or prompts the user to set the port. You ca also set the port i the java commad lie. The followig is a example of a java commad lie that sets the port umber: java -DTOBJADDR=//BEANIE:2359 \ -Dorg.omg.corba.ORBPort=portumber -classpath... Usig the CORBA Notificatio Service 4-25

146 4 Usig the CosNotificatio Service API 4-26 Usig the CORBA Notificatio Service

147 CHAPTER 5 Buildig the Itroductory Sample Applicatio This topic icludes the followig sectios: Overview Buildig ad Ruig the Itroductory Sample Applicatio Overview The Itroductory sample applicatios simulate a ewsroom eviromet i which a ews reporter posts a story ad a ews subscriber cosumes the story. Two implemetatios of the Itroductory sample applicatio are provided: oe i the C++ programmig laguage that uses the BEA Simple Evets applicatio programmig iterface (API), ad aother i Java that uses the CosNotificatio Service API. The Itroductory sample applicatio cosists of the Reporter ad Subscriber applicatios ad the Notificatio Service. The Reporter applicatio implemets a cliet applicatio that prompts the user to eter ews articles, ad the posts the ews articles as evets to the BEA Tuxedo CORBA Notificatio Service. The Subscriber applicatio implemets a joit cliet/server applicatio that acts as cliet whe it Usig the CORBA Notificatio Service 5-1

148 5 Buildig the Itroductory Sample Applicatio subscribes ad usubscribes for evets, ad acts as a server whe it receives evets. To receive evets, the subscriber implemets a callback object which is ivoked by the Notificatio Service whe a evet eeds to be delivered. The Itroductory sample applicatio shows the simplest usage of the Notificatio Service. It demostrates how to use the BEA Simple Evets API, the CosNotificatio API, trasiet subscriptios, ad trasiet object refereces. It does ot demostrate the use of persistet subscriptios or data filterig. For a sample applicatio that uses persistet subscriptios ad data filterig, see Chapter 6, Buildig the Advaced Sample Applicatio. This Itroductory sample applicatio provides two executables (see Figure 5-1): A Reporter applicatio that posts evets to the Notificatio Service. It is a cliet without callback capability. A Subscriber applicatio that subscribes to the Notificatio Service ad receives evets. The subscriber is a joit cliet/server that acts as a cliet whe it subscribes to evets ad acts as a server whe it receives evets. Figure 5-1 Itroductory Sample Applicatio Compoets Reporter (Cliet) Push Evet BEA Tuxedo Domai Subscriber (Joit Cliet/ Server) Subscribe Usubscribe Push Evet Notificatio Cloud Service The evet poster, the Reporter applicatio, uses the structured evet domai_ame, type_ame, ad filterable_data fields to costruct the evet. The domai ame defies the idustry. I this applicatio, domai_ame is set to News. The type_ame defies the kid of evet i the idustry ad it is set to the category of ews story (for example, Sports ). The applicatio user specifies this value. I the filterable_data fields, a field amed Story is added, which cotais the text of the ews story beig posted. This text is also specified by the applicatio user. 5-2 Usig the CORBA Notificatio Service

149 Overview The Subscriber applicatio uses the structured evet domai_ame ad type_ame fields to create a subscriptio to the Notificatio Service. The subscriptio defies the domai_ame as a fixed strig with the cotet of News. At ru time, the Subscriber applicatio queries the user for the News Category ad uses the iput to defie the type_ame field i the subscriptio. Obviously, the users of both applicatios, the reporter ad the subscriber, must collaborate o the News Category strig for the subscriptio to match a evet, otherwise, o evets will be delivered to the subscriber. The subscriptio does ot do ay checkig of the filterable_data field, but rather assumes that the body of the story will be a strig, ad that the story will be i the first Named/Value pair i the filterable_data field of a structured evet. To post evets, the Reporter applicatio uses the push_structured_evet method to push ews evets to the Notificatio Service. For each evet, the Reporter applicatio queries the user for a News category (for example, Sports ) ad a story (a multiple-lie text strig). To subscribe to ews evets, the Subscriber applicatio ivokes the Notificatio Service to subscribe to ews evets. For each subscriptio, the Subscriber applicatio queries the user for a News category (for example, Sports ). The Subscriber applicatio also implemets a callback object (via the NewsCosumer_i servat class) which is used to receive ad process ews evets. Whe the Subscriber subscribes, it gives the Notificatio Service a referece to this callback object. Whe a matchig evet occurs; that is, whe the Reporter posts a evet with a News category that matches the ews category of the subscriptio, the Notificatio Service ivokes the push_structured_evet method o the callback object to deliver the evet to the callback object i the subscriber. This method prits out the evet, ivokes the usubscribe method o the Notificatio Service to cacel the subscriptio, ad shuts dow the Subscriber. For simplicity, the push_structured_evet method assumes that the domai_ame, type_ame, legth, ad ame field match ad the story is i the value field. Note: The News category is just a strig that the Reporter user ad the Subscriber user agree o. There are o fixed categories i this sample. Therefore, both the Reporter user ad the Subscriber user must type the same strig whe prompted for a category (icludig case ad white space). To ru this sample, you must start at least oe Reporter applicatio ad at least oe Subscriber applicatio; however, you may ru multiple Reporters ad Subscribers. Evets posted by ay Reporter will be delivered to all matchig Subscribers (based o News category ). Usig the CORBA Notificatio Service 5-3

150 5 Buildig the Itroductory Sample Applicatio Also, be sure to start ay subscribers before postig evets; otherwise, the evets will be lost. Buildig ad Ruig the Itroductory Sample Applicatio To build ad ru the Itroductory sample applicatio, you must perform these steps: 1. Verify that the "TUXDIR" ad JAVA_HOME eviromet variables are set to the correct directory path. Note: The JAVA_HOME eviromet variable is required for Java applicatios oly. 2. Copy the files for the Itroductory sample applicatio ito a work directory. 3. Chage the protectio attributes o the files to grat write ad execute access. 4. For UNIX, esure the make file is i your path. For Microsoft Widows, esure the make file is i your path 5. Set the applicatio eviromet variables. 6. Build the sample. 7. Boot the system. 8. Ru the Subscriber ad Reporter applicatios. 9. Shut dow the system. 10. Restore the directory to its origial state. These steps are described i detail i the followig sectios. 5-4 Usig the CORBA Notificatio Service

151 Buildig ad Ruig the Itroductory Sample Applicatio Verifyig the Settigs of the Eviromet Variables Before you build ad ru the Itroductory sample applicatio, you eed to esure that the TUXDIR eviromet variable is set o your system. I most cases, this eviromet variable is set as part of the istallatio procedure. However, you eed to check the eviromet variables to esure they reflect correct iformatio. Table 5-1 lists the eviromet variables required to ru the Itroductory sample applicatio. Table 5-1 Required Eviromet Variables for the Itroductory Sample Applicatio Eviromet Variable TUXDIR JAVA_HOME (For Java applicatios oly) Descriptio The directory path where you istalled the BEA Tuxedo software. For example: Widows TUXDIR=c:\tuxdir UNIX TUXDIR=/usr/local/tuxdir The directory path where you istalled the JDK software. For example: Widows JAVA_HOME=c:\JDK1.2.2 UNIX JAVA_HOME=/usr/local/JDK1.2.1 To verify that the iformatio for the eviromet variables defied durig istallatio is correct, perform the followig steps: Widows 1. From the Start meu, select Settigs. 2. From the Settigs meu, select the Cotrol Pael. The Cotrol Pael appears. 3. Click the System ico. The System Properties widow appears. Usig the CORBA Notificatio Service 5-5

152 5 Buildig the Itroductory Sample Applicatio 4. Click the Eviromet tab. The Eviromet page appears. 5. Check the settig for TUXDIR ad JAVA_HOME. UNIX ksh prompt>pritev TUXDIR ksh prompt>pritev JAVA_HOME To chage the settigs, perform the followig steps: Widows 1. O the Eviromet page i the System Properties widow, click the eviromet variable you wat to chage. 2. Eter the correct iformatio for the eviromet variable i the Value field. 3. Click OK to save the chages. UNIX ksh prompt>export TUXDIR=directorypath ksh prompt>export JAVA_HOME=directorypath Or csh> setev TUXDIR=directorypath csh> setev JAVA_HOME=directorypath Copyig the Files for the Itroductory Sample Applicatio ito a Work Directory You eed to copy the files for the Itroductory sample applicatio ad files i the commo directory ito a work directory o your local machie. Note: The applicatio directory ad the commo directory must be copied to the same paret directory. The files are located i the followig directories: 5-6 Usig the CORBA Notificatio Service

153 Buildig ad Ruig the Itroductory Sample Applicatio Widows For the C++ Itroductory sample: drive:\tuxdir\samples\corba\otificatio\itroductory_simple_cxx drive:\tuxdir\samples\corba\otificatio\commo For the Java Itroductory sample: drive:\tuxdir\samples\corba\otificatio\itroductory_cos_java drive:\tuxdir\samples\corba\otificatio\commo UNIX For the C++ Itroductory sample: /usr/local/tuxdir/samples/corba/otificatio/ itroductory_simple_cxx /usr/local/tuxdir/samples/corba/otificatio/commo For the Java Itroductory sample: /usr/local/tuxdir/samples/corba/otificatio/ itroductory_simple_cxx /usr/local/tuxdir/samples/corba/otificatio/commo You use the files listed i Table 5-2 ad Table 5-4 to build ad ru the C++ Itroductory sample applicatio, which is implemeted usig the BEA Simple Evets API. You use the files listed i Table 5-3 ad Table 5-4 to build ad ru the Java Itroductory sample applicatio, which is implemeted usig the CosNotificatio API. Table 5-2 Files Located i the itroductory_sample_c++ Directory File Readme.txt setev.cmd setev.ksh makefile.t makefile.mk makefile.ic Reporter.cpp Descriptio Describes the Itroductory sample applicatio ad provides istructios for settig up the eviromet ad buildig ad ruig the applicatio. Sets the eviromet for Microsoft Widows systems. Sets the eviromet for UNIX systems. Makefile for Microsoft Widows systems. Makefile for UNIX systems. Commo makefile used by the makefile.t ad the makefile.mk files. Code for the reporter. Usig the CORBA Notificatio Service 5-7

154 5 Buildig the Itroductory Sample Applicatio Table 5-2 Files Located i the itroductory_sample_c++ Directory (Cotiued) File Subscriber.cpp NewsCosumer_i.h ad NewsCosumer.cpp Descriptio Code for the subscriber. The callback servat class that subscribers use to receive ews evets. (For the Subscriber applicatio.) Table 5-3 Files Located i the itroductory_cos_java Directory File Readme.txt setev.cmd setev.ksh makefile.t makefile.mk makefile.ic Reporter.java Suscriber.java NewsCosumer_i.java Descriptio Describes the Itroductory sample applicatio ad provides istructios for settig up the eviromet ad buildig ad ruig the applicatio. Sets the eviromet for Microsoft Widows systems. Sets the eviromet for UNIX systems. Makefile for Microsoft Widows systems. Makefile for UNIX systems. Commo makefile used by the makefile.t ad the makefile.mk files. Code for the reporter. Code for the subscriber. The callback servat class that subscribers use to receive ews evets. (For the Subscriber applicatio.) Table 5-4 lists other files that the Itroductory sample applicatio uses. Table 5-4 Other Files the Itroductory Sample Applicatio Uses File Descriptio The followig files are located i the commo directory. commo.t Makefile symbols for Microsoft Widows systems. 5-8 Usig the CORBA Notificatio Service

155 Buildig ad Ruig the Itroductory Sample Applicatio Table 5-4 Other Files the Itroductory Sample Applicatio Uses (Cotiued) File commo.mk itroductory.ic ex.h cliet_ex.h ShutdowMaager.java Descriptio Makefile symbols for UNIX systems. Makefile for admiistrative targets. Utilities to prit exceptios. (For C++ oly.) Cliet utilities to hadle exceptios. (For C++ oly.) Class to help the mai ad the servat i the Notificatio Service Java samples coordiate shuttig dow the server. Note: This file is eeded for the Java applicatio oly. The followig files are located i the \tuxdir\iclude directory. CosEvetComm.idl CosNotificatio.idl CosNotifyComm.idl Tobj_Evets.idl Tobj_SimpleEvets.idl The OMG IDL code that declares the CosEvetComm module. The OMG IDL code that declares the CosNotificatio module. The OMG IDL code that declares the CosNotifyComm module. The OMG IDL code that declares the Tobj_Evets module. The OMG IDL code that declares the Tobj_SimpleEvets module. Note: This file is eeded oly for the applicatio that was developed usig BEA Simple Evets API. The followig files are eeded oly for the applicatio that was developed usig CosNotificatio Service API. CosEvetChaelAdmi.idl The OMG IDL code that declares the CosEvetChaelAdmi module. Usig the CORBA Notificatio Service 5-9

156 5 Buildig the Itroductory Sample Applicatio Table 5-4 Other Files the Itroductory Sample Applicatio Uses (Cotiued) File CosNotifyFilter.idl CosNotifyChaelAdmi.idl Tobj_Notificatio.idl Descriptio The OMG IDL code that declares the CosNotifyFilter module. The OMG IDL code that declares the CosNotifyChaelAdmi module. The OMG IDL code that declares the Tobj_Notificatio module. Chagig the Protectio Attribute o the Files for the Itroductory Sample Applicatio Durig the istallatio of the BEA Tuxedo CORBA software, the sample applicatio files are marked read-oly. Before you ca edit or build the files i the Itroductory sample applicatio, you eed to chage the protectio attribute of the files you copied ito your work directory, as follows: Widows 1. I a DOS widow, chage (cd) to your work directory. 2. prompt>attrib -r drive:\workdirectory\*.* UNIX 1. Chage (cd) to your work directory. 2. prompt>/bi/ksh 3. ksh prompt>chmod u+w /workdirectory/*.* O UNIX systems, you also eed to chage the permissio of setev.ksh to give execute permissio to the file, as follows: ksh prompt>chmod +x setev.ksh 5-10 Usig the CORBA Notificatio Service

157 Buildig ad Ruig the Itroductory Sample Applicatio Settig Up the Eviromet To set up the eviromet, eter the followig commad: Widows prompt>.\setev.cmd UNIX ksh prompt>../setev.ksh Buildig the Itroductory Sample Applicatio Makefile Summary You use the make commad to ru makefiles, which are provided for Microsoft Widows ad UNIX, to build the sample applicatio. For UNIX, use make. For Microsoft Widows, use make. The makefile automates the followig steps: 1. Checks that the set eviromet commad (setev.cmd) has bee ru. If the eviromet variables have ot bee set, the makefile prits a error message to the scree ad exits. 2. Icludes the commo.t (for Microsoft Widows) or commo.mk (for UNIX) commad file. This file defies the makefile symbols used by the samples. These symbols allow the UNIX ad Microsoft Widows makefiles to delegate the build rules to platform-idepedet makefiles. 3. Icludes the makefile.ic commad file. This file builds the is_reporter ad is_subscriber executables, ad cleas up the directory of ueeded files ad directories. 4. Icludes the itroductory.ic commad file. This file creates the UBBCONFIG file ad executes the tmloadcf -y ubb commad to create the TUXCONFIG file. This is a platform-idepedet makefile fragmet that defies the admiistrative build rules commo to the Itroductory sample applicatio. Usig the CORBA Notificatio Service 5-11

158 5 Buildig the Itroductory Sample Applicatio Executig the Makefile Before executig the makefile, you eed to check the followig: Esure that you have the appropriate admiistrative privileges to build ad ru applicatios. O Microsoft Widows, verify that make is i the path of your machie. O UNIX, verify that make is i the path of your machie. To build the Itroductory sample applicatio, eter the make commad as follows: Widows make -f makefile.t UNIX make -f makefile.mk Startig the Itroductory Sample Applicatio To start the Itroductory sample applicatio, eter the followig commads: 1. To boot the BEA Tuxedo system: prompt>tmboot -y This commad starts the followig server processes: l l l l TMSUSREVT A BEA Tuxedo system-provided, EvetBroker server that is used by the Notificatio Service. TMNTS A BEA Tuxedo Notificatio Service server that processes requests for subscriptios ad evet postigs. TMNTSFWD_T A BEA Tuxedo Notificatio Service server that forwards evets to subscribers that have trasiet subscriptios. ISL 5-12 Usig the CORBA Notificatio Service

159 Buildig ad Ruig the Itroductory Sample Applicatio The IIOP Listeer/Hadler process. 2. To start the Subscriber applicatio: For C++: prompt>is_subscriber For Java o Microsoft Widows: prompt>java %IC_SUBSCRIBER% For Java o UNIX: prompt>java $IC_SUBSCRIBER To start aother Subscriber, ope aother widow, chage (cd) to your work directory, set the eviromet variables (by ruig setev.cmd or setev.ksh), ad eter the start commad that is appropriate for your platform. 3. To start the Reporter applicatio, ope aother widow ad eter the followig: For C++: prompt>is_reporter For Java o Microsoft Widows: prompt>java %IC_REPORTER% For Java o UNIX: prompt>java $IC_REPORTER To start aother Reporter, ope aother widow, chage (cd) to your work directory, set the eviromet variables (by ruig setev.cmd or setev.ksh), ad eter the start commad that is appropriate for your platform. Usig the Itroductory Sample Applicatio To use the Itroductory sample applicatio, you must use the Subscriber applicatio to subscribe to a evet ad the Reporter applicatio to post a evet. Be sure to subscribe before you post each evet; otherwise, evets will be lost. Note: The Subscriber applicatio shuts dow after it receives oe evet. Usig the Subscriber Applicatio to Subscribe to Evets Perform these steps: 1. Whe you start the Subscriber applicatio (prompt>is_subscriber), the followig prompts are displayed: Name? Category (or all)? (Eter a ame (without spaces).) (Eter the category of ews you wat or "all".) Usig the CORBA Notificatio Service 5-13

160 5 Buildig the Itroductory Sample Applicatio You may type i ay strig for the ews category; that is, there is o fixed list of ews categories. However, whe you use the Reporter applicatio to post a evet, make sure to specify the same strig for the ews category. 2. The Subscriber applicatio creates a subscriptio the prits Ready whe it is ready to receive evets. After the Subscriber receives oe evet, it shuts dow. Note: You should always use the Subscriber applicatio to subscribe to evets before you use the Reporter applicatio to post evets; otherwise, evets will be lost. Usig the Reporter Applicatio to Post Evets Perform these steps: 1. Whe you start the Reporter applicatio (prompt> is_reporter), the followig prompts are displayed: (r) Report ews (e) Exit Optio? 2. Eter r to report ews. The followig prompt is displayed: Category? 3. Eter the ews category. It must match exactly the category you typed o the Subscriber applicatio (icludig white space ad case). After you eter the ews category, the followig prompt is displayed: Eter story (termiate with. ) 4. Eter your story. It ca spa multiple lies. Fiish the story by typig a period oly (".") o a lie, followed by a carriage retur. Subscribers whose category matches the category of this story will receive, ad prit out the story. Whe a subscriber receives a story, the subscriber automatically shuts dow. 5. To sed ad receive more ews stories, start aother subscriber, the report aother story. Whe you are doe reportig ews, choose the Exit (e) optio. Note: The Subscriber applicatio shuts dow after it receives oe evet. Therefore, always use the Subscriber applicatio to subscribe to evets 5-14 Usig the CORBA Notificatio Service

161 Buildig ad Ruig the Itroductory Sample Applicatio before you use the Reporter applicatio to post a evet; otherwise, evets will be lost. Shuttig Dow the System ad Cleaig Up the Directory Perform the followig steps: Note: Make sure the Reporter ad Subscriber processes have stopped. 1. To shut dow the system, i ay widow, type: prompt>tmshutdow -y 2. To restore the directory to its origial state, i ay widow, type: Widows prompt>make -f makefile.t clea UNIX prompt>make -f makefile.mk clea Usig the CORBA Notificatio Service 5-15

162 5 Buildig the Itroductory Sample Applicatio 5-16 Usig the CORBA Notificatio Service

163 CHAPTER 6 Buildig the Advaced Sample Applicatio This topic icludes the followig sectios: Overview Buildig ad Ruig the Advaced Sample Applicatio Overview The Advaced sample applicatio simulates a ewsroom eviromet i which a ews reporter posts a story, a wire service posts the story as a evet to the Notificatio Service, ad a ews subscriber cosumes the story. Two implemetatios of the Advaced sample applicatio are provided: oe i the Java programmig laguage that uses the BEA Simple Evets applicatio programmig iterface (API), ad aother i C++ that uses the CosNotificatio Service API. The Advaced sample applicatio cosists of the reporter, subscriber, ad wire service applicatios that use the BEA Tuxedo CORBA Notificatio Service. The reporter applicatio implemets a cliet applicatio. This applicatio prompts the user to eter ews articles ad calls the WireService server usig applicatio specific IDL. The WireService server, i tur, posts the evets. The subscriber implemets a joit cliet/server applicatio. This applicatio acts as cliet whe it subscribes ad Usig the CORBA Notificatio Service 6-1

164 6 Buildig the Advaced Sample Applicatio usubscribes for evets, ad acts as a server whe it receives evets. To receive evets, the Subscriber implemets callback objects which are ivoked by the Notificatio Service whe a evet eeds to be delivered. Note: O UNIX systems, you caot immediately restart the subscriber because the port takes some time (the actual time depeds o the platform) to become available agai. If you restart too soo, you will get a CORBA::OBJ_ADAPTER exceptio. If this occurs, just wait ad try agai. O Solaris systems, the port ca take up to 10 miutes to become available. To see if the port is still i use, use this commad: Restart -a grep <the port umber>. This Advaced sample applicatio demostrates how to use the BEA Simple Evets API, the CosNotificatio Service API, trasiet ad persistet subscriptios, ad data filterig. This Advaced sample provides three executables (see Figure 6-1): A WireService applicatio that posts evets. It is a Notificatio Service cliet ad a BEA Tuxedo CORBA server. It implemets a OMG IDL iterface, which the Reporter applicatio uses. A Reporter applicatio that reports ews stories by ivokig methods o the WireService. The WireService, i tur, coverts the stories ito evets ad posts them usig the Notificatio Service. The reporter is a pure cliet. A Subscriber applicatio that subscribes to the Notificatio Service ad receives evets. The subscriber is a joit cliet/server that acts as a cliet whe it subscribes for evets, ad acts as a server whe it receives evets. 6-2 Usig the CORBA Notificatio Service

165 Overview Figure 6-1 Advaced Sample Applicatio Compoets Reporter (Cliet) Report_ews Shutdow Cacel WireSevice Server BEA Tuxedo Domai Push Evet Subscriber (Joit Cliet/ Server) Subscribe Usubscribe Push Evet Cloud Notificatio Service Pedig Evets Qspace Error Evets The evet poster, the WireService applicatio, uses the structured evet domai_ame, type_ame, ad filterable_data fields to costruct three evets: a ews evet, a subscriber shutdow evet, ad a subscriber cacel evet. l l l News evet For this evet, the domai ame is a strig ad is preset by the applicatio as News. The type ame is a strig ad defied by the Reporter applicatio user at ru time. It is set to the category of ews (for example, Sports ). Filterable data cotais a ame/value pair whose ame is Story ad whose value is a strig that cotais the body of the ews story beig posted. Subscriber Shutdow evet For this evet, the domai ame is a strig ad is preset by the applicatio as NewsAdmi. The type ame is a strig ad is preset by the applicatio as Shutdow. The filterable data is ot used. Subscriber Cacel evet For this evet, the domai ame is a strig ad is preset by the applicatio as NewsAdmi. The type ame is a strig ad is preset by the applicatio as Cacel. The filterable data is ot used. Usig the CORBA Notificatio Service 6-3

166 6 Buildig the Advaced Sample Applicatio The Subscriber applicatio uses the structured evet domai_ame, type_ame, ad filterable_data fields to costruct two subscriptios: a ews subscriptio that processes ews stories; ad a shutdow subscriptio that processes Cacel ad Shutdow evets. At ru time, the Subscriber applicatio establishes these two subscriptios with the Notificatio Service. l l News subscriptio The Subscriber applicatio uses the structured evet domai_ame, type_ame, ad filterable_data fields to create a subscriptio to the Notificatio Service. The subscriptio defies the domai ame as a fixed strig with the cotet of News. At ru time, the Subscriber applicatio queries the user for the News Category ad Keyword ad uses the iputs to defie the type_ame ad data_filter fields i the subscriptio. Obviously, the users of both applicatios, the reporter ad the subscriber, must collaborate o the News Category ad keyword strigs for the subscriptio to match a evet, otherwise, o News evets will be delivered to the subscriber. The subscriptio does ot do ay checkig of the filterable_data field, but rather assumes that the body of the story will be a strig, ad that the story will be i the first Named/Value pair i the filterable_data field of a structured evet. Shutdow subscriptio The Subscriber applicatio uses the structured evet domai_ame ad type_ame, fields to create a subscriptio to the Notificatio Service. The subscriptio defies the domai_ame as a fixed strig with the cotet of NewsAdmi, the type_ame as a strig of either Shutdow or Cacel. The filterable_data field is a empty strig. The Reporter applicatio is resposible for implemetig the user iterface for reportig ews as well as for producig Shutdow ad Cacel evets. Rather tha use the Notificatio Service directly to post evets, it calls methods o the WireService server. The WireService server uses the Notificatio Service to post three kids of evets: News evets (used to deliver ews to subscribers) Shutdow evets (used to shut dow subscribers temporarily) Cacel evets (used to shut dow subscribers permaetly) The Notificatio Service, i tur, delivers the evets to the subscribers. 6-4 Usig the CORBA Notificatio Service

167 Overview The subscriber uses the Notificatio Service to create a persistet subscriptio to ews evets. The subscriber implemets a persistet callback object (via the NewsCosumer_i servat class), which is used to receive ad process ews evets. Whe the subscriber subscribes, it gives the Notificatio Service a referece to this callback object. Whe a matchig evet occurs, the Notificatio Service ivokes a push_structured_evet method o this callback object to push the evet to the subscriber. This method prits out the evet. The subscriber also uses the Notificatio Service to create a trasiet subscriptio to Shutdow ad Cacel evets. The subscriber implemets aother callback object (via the ShutdowCosumer_i servat class), which is used to receive ad process these evets. Wheever the subscriber rus, it prompts the user for a ame. The first time this user rus the subscriber program, the subscriber creates a persistet subscriptio to News evets. To do this, the subscriber prompts the user for which kid of ews stories to subscribe to ad which port umber the subscriber should ru o. The subscriber rus o this port, subscribes, the writes the subscriptio ID, the filter ID (if usig the CosNotificatio API), ad the port umber to a file (the ame of the file is <user_ame>.pstore). The ext time the subscriber rus, the subscriber prompts the user for a ame, opes up the file <user_ame>.pstore the reads the subscriptio ID, filter ID (if usig the CosNotificatio API) ad port umber for this user from the file. This satisfies the requiremet that the subscriber rus o the same port umber each time because its ews callback object s object referece is persistet. The Subscriber creates a trasiet subscriptio to receive the Shutdow ad Cacel evets, therefore, the trasiet subscriptio is created ad destroyed every time the subscriber is ru ad shut dow. This subscriptio ID is ot writte out to the file <user_ame>.pstore. Whe the subscriber receives a Shutdow evet, it destroys the shutdow/callback subscriptio but leaves the News subscriptio itact. If News evets are posted after the subscriber is shut dow ad before it is restarted, the the otificatio service will either deliver the evets whe the subscriber is restarted, or will put the evets o the error queue. (You ca use the tsadmi utility to either delete these evets from the error queue or retry deliverig them.) Whether the evet is redelivered or is put o the error queue depeds o whether the subscriber restarts quickly eough. This depeds o the retry parameters of the queue. See advaced.ic (i the otificatio samples commo directory) for the values of the queue retry parameters. Usig the CORBA Notificatio Service 6-5

168 6 Buildig the Advaced Sample Applicatio News evets have two parts: a category (for example, headlie) ad a story (a multiple-lie text strig). The Subscriber applicatio prompts the user to iput a ews category. Next the subscriber subscribes to ews evets whose category matches this strig. The Reporter applicatio prompts the user for a ews category ad a story. Next the reporter (by ivokig a method o the wire service) posts a correspodig ews evet. The evet will oly be delivered to subscribers who subscribed to that category of ews. Note: The category is a strig. The same strig must be used by the Reporter user ad the Subscriber user. There are o fixed categories i this sample. Therefore both users, the Reporter user ad the Subscriber user, must type the same strig whe prompted for a category (icludig case ad white space). This sample also uses data filterig. Whe a user first rus the Subscriber, the user will be prompted for a keyword. Evets whose category matches ad whose story cotais the keyword will be delivered to the subscriber. For example, if the user eters a keyword of oe, data filterig will ot be used (thus the user will receive all evets for the chose ews category). If the user eters a keyword smith, it traslates to Story %%.*smith.*. This keyword specifies that the subscriptio oly accepts evets that have a Story field that cotais a strig, ad that the field starts with ay umber of characters, has a literal strig smith, ad the eds with ay umber of characters. To ru this sample, you eed to ru at least oe Reporter ad at least oe Subscriber; however, you may ru multiple Reporters ad multiple Subscribers. Evets posted by ay Reporter will be delivered to all matchig Subscribers (based o the category). Also, be sure to start ay subscribers before postig evets. Evets posted before the subscribers are started will ot be delivered. Buildig ad Ruig the Advaced Sample Applicatio To build ad ru the Itroductory sample applicatio, you must perform these steps: 1. Verify that the "TUXDIR" ad JAVA_HOME eviromet variables are set to the correct directory path. 6-6 Usig the CORBA Notificatio Service

169 Buildig ad Ruig the Advaced Sample Applicatio Note: The JAVA_HOME eviromet variable is required for Java applicatios oly. 2. Copy the files for the Itroductory sample applicatio ito a work directory. 3. Chage the protectio attributes o the files to grat write ad execute access. 4. For UNIX, esure the make file is i your path. For Microsoft Widows, esure the make file is i your path 5. Set the applicatio eviromet variables. 6. Build the sample. 7. Boot the system. 8. Ru the Subscriber ad Reporter applicatios. 9. Shut dow the system. 10. Restore the directory to its origial state. These steps are described i detail i the followig sectios. Verifyig the Settigs of the Eviromet Variables Before you build ad ru the Advaced sample applicatio, you eed to esure that the TUXDIR eviromet variable is set o your system. I most cases, this eviromet variable is set as part of the istallatio procedure. However, you eed to check the eviromet variables to esure they reflect the correct iformatio. Table 6-1 lists the eviromet variables required to ru the Callback sample applicatio. Usig the CORBA Notificatio Service 6-7

170 6 Buildig the Advaced Sample Applicatio Table 6-1 Required Eviromet Variables for the Callback Sample Applicatio Eviromet Variable TUXDIR JAVA_HOME (For Java applicatios oly) Descriptio The directory path where you istalled the BEA Tuxedo software. For example: Widows TUXDIR=c:\tuxdir UNIX TUXDIR=/usr/local/tuxdir The directory path where you istalled the JDK software. For example: Widows JAVA_HOME=c:\JDK1.2 UNIX JAVA_HOME=/usr/local/JDK1.2 To verify that the iformatio for the eviromet variables defied durig istallatio is correct, perform the followig steps: Widows 1. From the Start meu, select Settigs. 2. From the Settigs meu, select the Cotrol Pael. The Cotrol Pael appears. 3. Click the System ico. The System Properties widow appears. 4. Click the Eviromet tab. The Eviromet page appears. 5. Check the settig for TUXDIR ad JAVA_HOME. UNIX ksh prompt>pritev TUXDIR ksh prompt>pritev JAVA_HOME 6-8 Usig the CORBA Notificatio Service

171 Buildig ad Ruig the Advaced Sample Applicatio To chage the settigs, perform the followig steps: Widows 1. O the Eviromet page i the System Properties widow, click the eviromet variable you wat to chage. 2. Eter the correct iformatio for the eviromet variable i the Value field. 3. Click OK to save the chages. UNIX ksh prompt>export TUXDIR=directorypath ksh prompt>export JAVA_HOME=directorypath Copyig the Files for the Advaced Sample Applicatio ito a Work Directory You eed to copy the files for the Advaced sample applicatio ito a work directory o your local machie. Note: The applicatio directory ad the commo directory must be copied to the same paret directory. The files for the Advaced sample applicatio are located i the followig directories: Widows For the C++ Advaced sample: drive:\tuxdir\samples\corba\otificatio\advaced_cos_cxx drive:\tuxdir\samples\corba\otificatio\commo For the Java Advaced sample: drive:\tuxdir\samples\corba\otificatio\advaced_simple_java drive:\tuxdir\samples\corba\otificatio\commo UNIX For the C++ Advaced sample: /usr/local/tuxdir/samples/corba/otificatio/advaced_cos_cxx /usr/local/tuxdir/samples/corba/otificatio/commo Usig the CORBA Notificatio Service 6-9

172 6 Buildig the Advaced Sample Applicatio For the Java Advaced sample: /usr/local/tuxdir/samples/corba/otificatio/advaced_simple_java /usr/local/tuxdir/samples/corba/otificatio/commo You use the files listed i Table 6-2 ad Table 6-4 to build ad ru the Java Advaced sample applicatio, which is implemeted usig the BEA Simple Evets API. You use the files listed i Table 6-3 ad Table 6-4 to build ad ru the C++ Advaced sample applicatio, which is implemeted usig the CosNotificatio API. Table 6-2 Files Located i the advaced_simple_java Notificatio Directory File Readme.txt setev.cmd setev.ksh makefile.t makefile.mk makefile.ic Reporter.java Subscriber.java NewsCosumer_i.java ShutdowCosumer_i.java WireService.xml WireService_i.java WireServiceFactory_i.java WireServiceServer.java Descriptio Describes the Advaced sample applicatio ad provides istructios for settig up the eviromet ad buildig ad ruig the applicatio. Sets the eviromet for Microsoft Widows systems. Sets the eviromet for UNIX systems. Makefile for Microsoft Widows systems. Makefile for UNIX systems. Commo makefile used by the makefile.t ad the makefile.mk files. Code for the reporter. Code for the subscriber. Callback servat class that subscribers use to receive ews evets. (For the Subscriber applicatio.) Callback servat classes that subscribers use to receive Shutdow ad Cacel evets. (For the Subscriber applicatio.) Server Descriptio file for the WireService server. Implemets the WireService iterfaces. Implemets the WireService factory iterface. Code for the WireService server Usig the CORBA Notificatio Service

173 Buildig ad Ruig the Advaced Sample Applicatio You use the files listed i Table 6-3 ad Table 6-4 to build ad ru the Advaced sample applicatio. Table 6-3 Files Located i the advaced_cos_c++ Notificatio Directory File Readme.txt setev.cmd setev.ksh makefile.t makefile.mk makefile.ic Reporter.cpp Subscriber.cpp NewsCosumer_i.h ad NewsCosumer.cpp ShutdowCosumer_i.h ad ShutdowCosumer.cpp WireServiceServer.cpp News.icf WireService_i.h ad WireService.cpp Descriptio Describes the Advaced sample applicatio ad provides istructios for settig up the eviromet ad buildig ad ruig the applicatio. Sets the eviromet for Microsoft Widows systems. Sets the eviromet for UNIX systems. Makefile for Microsoft Widows systems. Makefile for UNIX systems. Commo makefile used by the makefile.t ad the makefile.mk files. Code for the reporter. Code for the subscriber. Callback servat class that subscribers use to receive ews evets. (For the Subscriber applicatio.) Callback servat classes that subscribers use to receive Shutdow ad Cacel evets. (For the Subscriber applicatio.) Code for the WireService server. ICF file for the WireService iterfaces. Implemets the WireService iterfaces. Table 6-4 lists other files that the Advaced sample applicatio uses. With the exceptio of the IDL files, the files are located i the Notificatio commo directory. Usig the CORBA Notificatio Service 6-11

174 6 Buildig the Advaced Sample Applicatio Table 6-4 Other Files That the Advaced Sample Uses File Descriptio The followig files are located i the commo directory. News.idl ews_flds commo.t commo.mk advaced.ic ex.h cliet_ex.h server_ex.h IDL defiitios for the WireService server. FML field defiitios used to perform data filterig ad ews evets. Makefile symbols for Microsoft Widows systems. Makefile symbols for UNIX systems. Makefile for admiistrative targets. Utilities to prit exceptios (C++ oly). Cliet utilities to hadle exceptios (C++ oly). Server utilities to hadle exceptios. The followig files are located i the \tuxdir\iclude directory. CosEvetComm.idl CosNotificatio.idl CosNotifyComm.idl Tobj_Evets.idl Tobj_SimpleEvets.idl The OMG IDL code that declares the CosEvetComm module. The OMG IDL code that declares the CosNotificatio module. The OMG IDL code that declares the CosNotifyComm module. The OMG IDL code that declares the Tobj_Evets module. The OMG IDL code that declares the Tobj_SimpleEvets module. Note: This file is eeded oly for the applicatio that was developed usig BEA Simple Evets API. The followig files are eeded oly for the applicatio that was developed usig CosNotificatio Service API Usig the CORBA Notificatio Service

175 Buildig ad Ruig the Advaced Sample Applicatio Table 6-4 Other Files That the Advaced Sample Uses (Cotiued) File CosEvetChaelAdmi.idl CosNotifyFilter.idl CosNotifyChaelAdmi.idl Tobj_Notificatio.idl Descriptio The OMG IDL code that declares the CosEvetChaelAdmi module. The OMG IDL code that declares the CosNotifyFilter module. The OMG IDL code that declares the CosNotifyChaelAdmi module. The OMG IDL code that declares the Tobj_Notificatio module. Chagig the Protectio Attribute o the Files for the Advaced Sample Applicatio Durig the istallatio of the BEA Tuxedo software, the Advaced sample applicatio files are marked read-oly. Before you ca edit or build the files i the Advaced sample applicatio, you eed to chage the protectio attribute of the files you copied ito your work directory, as follows: Widows 1. Chage (cd) to your work directory 2. prompt>attrib -r drive:\workdirectory\*.* UNIX 1. Chage (cd) to your work directory 2. prompt>/bi/ksh 3. ksh prompt>chmod u+w /workdirectory/*.* O the UNIX operatig system platform, you also eed to chage the permissio of setev.ksh to give execute permissio to the file, as follows: ksh prompt>chmod +x setev.ksh Usig the CORBA Notificatio Service 6-13

176 6 Buildig the Advaced Sample Applicatio Settig Up the Eviromet To set up the eviromet, eter the followig commad: Widows prompt>.\setev.cmd UNIX prompt>../setev.ksh Buildig the Advaced Sample Applicatio Makefile Summary You use the make commad to ru makefiles, which are provided for Microsoft Widows ad UNIX, to build the sample applicatio. For Microsoft Widows, use make. For UNIX, use make. The makefile automates the followig steps: 1. Checks that the set eviromet commad (setev.cmd) has bee ru. If the eviromet variables have ot bee set, the makefile prits a error message to the scree ad exits. 2. Icludes the commo.t (for Microsoft Widows) or commo.mk (for UNIX) commad file. This file defies the makefile symbols used by the samples. These symbols allow the UNIX ad Microsoft Widows makefiles to delegate the build rules to platform-idepedet makefiles. 3. Icludes the makefile.ic commad file. This file builds the is_reporter, is_subscriber ad AS_WIRESERVICE executables, ad cleas up the directory of uecessary files ad directories. 4. Icludes the advaced.ic commad file. This file executes tmadmi ad qadmi commads to create the trasactio log ad the queues required by the persistet subscriptios. It also creates the UBBCONFIG file ad executes the tmloadcf -y ubb commad to create the TUXCONFIG file Usig the CORBA Notificatio Service

177 Buildig ad Ruig the Advaced Sample Applicatio Executig the Makefile Before executig the makefile, you eed to check the followig: Esure that you have the appropriate admiistrative privileges to build ad ru applicatios. O Microsoft Widows, make sure make is i the path of your machie. O UNIX, make sure make is i the path of your machie. To build the Advaced sample applicatio, eter the make commad as follows: Widows make -f makefile.t UNIX make -f makefile.mk Startig the Advaced Sample Applicatio To start the Advaced sample applicatio, eter the followig commads: 1. To boot the BEA Tuxedo system: prompt>tmboot -y This commad starts the followig server processes: l l l TMSUSREVT A BEA Tuxedo system-provided, EvetBroker server that is used by the Notificatio Service. TMNTS A BEA Tuxedo CORBA Notificatio Service server that processes requests for subscriptios ad evet postigs. TMNTSFWD_T A BEA Tuxedo CORBA Notificatio Service server that forwards evets to subscribers that have trasiet subscriptios. This server is required for trasiet subscriptios. Usig the CORBA Notificatio Service 6-15

178 6 Buildig the Advaced Sample Applicatio l l l l l TMNTSFWD_P A BEA Tuxedo CORBA Notificatio Service server that forwards persistet evets to subscribers that have persistet subscriptios. This server is required for persistet subscriptios. TMQUEUE The message queue maager is a BEA Tuxedo system-provided server that equeues ad dequeues messages o behalf of programs callig tpequeue(3) ad tpdequeue(3), respectively. This server is required for persistet subscriptios. TMQFORWARD The message forwardig server is a BEA Tuxedo system-provided server that forwards messages that have bee stored usig tpequeue(3c) for later processig. This server is required for persistet subscriptios. WIRE_SERVICE_SERVER A server, specifically built for the Advaced sample applicatio, that receives evets from the Reporter applicatio ad posts them to the Notificatio Service. This receive ad server posts three types of evets: News, Shutdow, ad Cacel. ISL The IIOP Listeer/Hadler process. 2. To start the Subscriber applicatio: For C++: prompt>is_subscriber For Java o Microsoft Widows: prompt>java %IC_SUBSCRIBER% For Java o UNIX: prompt>java $IC_SUBSCRIBER To start aother Subscriber, ope aother widow, chage (cd) to your work directory, set the eviromet variables (by ruig setev.cmd or setev.ksh), ad eter the start commad that is appropriate for your platform. 3. To start the Reporter applicatio, ope aother widow ad eter the followig: For C++: prompt>is_reporter For Java o Microsoft Widows: prompt>java %IC_REPORTER% For Java o UNIX: prompt>java $IC_REPORTER To start aother Reporter, ope aother widow, chage (cd) to your work directory, set the eviromet variables (by ruig setev.cmd or setev.ksh), ad eter the start commad that is appropriate for your platform Usig the CORBA Notificatio Service

179 Buildig ad Ruig the Advaced Sample Applicatio Usig the Advaced Sample Applicatio To use the Advaced sample applicatio, you must use the Subscriber applicatio to subscribe to a evet ad the Reporter applicatio to post to a evet. Be sure to subscribe before you post each evet; otherwise, evets will be lost. Usig the Subscriber Applicatio to Subscribe to Evets Perform the followig steps: 1. Whe you start the Subscriber applicatio (prompt>is_subscriber) for the first time, the followig prompts are displayed: Name? (Eter a ame (without spaces).) Port (e.g. 2463) (Eter the port umber that this subscriber should ru o.) Category (or all) (Eter the category of ews you wat or "all.") Keyword (or oe) (Eter a keyword that you wat all delivered stories to cotai.) Note: If the Subscriber applicatio is shut dow by a Shutdow evet from the Reporter applicatio (Shutdow evets do ot cacel persistet subscriptios), o subsequet startups of the Subscriber applicatio, you will oly be prompted for your ame. The Subscriber applicatio retrieves the remaiig iformatio from the <user_ame>.pstore file. This guaratees that the same port umber is used, which is required for persistet subscriptios. If the Subscriber applicatio is shut dow by a Cacel evet from the Reporter applicatio (Cacel evets cacel all subscriptios icludig persistet subscriptios), o subsequet startups of the Subscriber applicatio, you will be prompted for your ame, port umber, category, ad keyword. 2. You may type i ay strig for the ews category, that is, there is o fixed list of ews categories. However, whe you use the Reporter applicatio to post a evet, make sure you specify the same strig for the ews category. Similarly, you may type i a strig for a keyword. There is o fixed list of keywords either so whe you ru the reporter ad eter the story, make sure that the story cotais the same strig; otherwise, the story will ot be delivered to your subscriptio. The first time the Subscriber applicatio is ru for your userame, category (or all), ad keyword (optioal), it creates a ews subscriptio. O subsequet rus, Usig the CORBA Notificatio Service 6-17

180 6 Buildig the Advaced Sample Applicatio the subscriber reuses this subscriptio. I all cases, the Subscriber applicatio prits Ready whe it is ready to receive evets. Note: Note: 6-18 Usig the CORBA Notificatio Service The Subscriber applicatio creates a subscriptio the prits Ready whe it is ready to receive evets. You should always use the Subscriber applicatio to subscribe to evets before you use the Reporter applicatio to post evets; otherwise, evets will be lost. This is because eve though the Subscriber applicatio creates a persistet subscriptio to News evets, that subscriptio is ot created util the Subscriber applicatio is started. You ca start multiple subscribers by opeig aother widow ad repeatig this procedure. Usig the Reporter Applicatio to Post Evets Perform the followig steps: 1. Whe you start the Reporter applicatio (prompt> is_reporter), the followig prompt is displayed: (r) Report ews (s) Shutdow subscribers (c) Cacel Subscribers (e) Exit Optio? 2. Eter r to report ews. The followig prompt is displayed: Category? 3. Eter the ews category. It must match exactly the category you typed o the Subscriber applicatio (icludig white space ad case). After you eter the ews category, the followig prompt is displayed: Eter story (termiate with. ) 4. Eter your story. It ca spa multiple lies. Fiish the story by typig a period oly (".") o a lie, followed by a carriage retur. If you typed i a keyword whe subscribig, make sure the story cotais this strig (icludig white space ad case). Subscribers whose category ad keyword (if specified) matches the category ad a keyword i this story will receive ad prit out the story.

181 Buildig ad Ruig the Advaced Sample Applicatio 5. If you choose the s optio, a Shutdow evet will be posted ad received by all the subscribers ad the subscribers will shut dow. While the subscribers are shut dow, you may post aother ews story (by usig the r optio agai). The Notificatio Service will place the ews story o the pedig queue but the News evet subscriptio is persistet ad, therefore, is still i effect. After you restart the subscribers, they will receive this secod ews story (uless a restart delay caused the evet to be moved to the error queue). This is because the subscriber created a persistet subscriptio for ews stories. Note: You ca use the tsadmi retryerrevets commad to move evets from the error queue back to the pedig queue. 6. If you choose the c optio, a Cacel evet will be posted ad received by all the subscribers. The subscribers will cacel their ews subscriptios ad shut dow. If you try to restart the subscribers, the you will be prompted agai for port, category, ad keyword because you are creatig a ew subscriptio. 7. Whe you are fiished reportig ews, choose the Exit (e) optio. Note: You ca start multiple reporters by opeig aother widow ad repeatig this procedure. Ay ews story reported by ay reporter will be delivered to all matchig subscribers. Make sure you have exited all reporters before shuttig dow the system. Usig the CORBA Notificatio Service 6-19

182 6 Buildig the Advaced Sample Applicatio Shuttig Dow the System ad Cleaig Up the Directory Make sure the Reporter ad Subscriber processes have stopped ad perform the followig steps: 1. To shut dow the system, i ay widow, type: prompt>tmshutdow -y 2. To restore the directory to its origial state, i ay widow, type: Widows prompt>make -f makefile.t clea UNIX prompt>make -f makefile.mk clea 6-20 Usig the CORBA Notificatio Service

183 CHAPTER 7 CORBA Notificatio Service Admiistratio This topic icludes the followig sectios: Itroductio Cofigurig the Notificatio Service. This sectio icludes the followig topics: l Cofigurig Data Filters l Settig the Host ad Port l Creatig a Trasactio Log l Creatig Evet Queues l Creatig the UBBCONFIG File ad the TUXCONFIG File Maagig the Notificatio Service Notificatio Service Admiistratio Utility ad Commads Notificatio Servers Usig the CORBA Notificatio Service 7-21

184 7 CORBA Notificatio Service Admiistratio Itroductio The BEA Tuxedo CORBA Notificatio Service is layered o the BEA Tuxedo EvetBroker ad Queuig systems. This meas that admiisterig the CORBA Notificatio Service requires that you also admiister these other BEA Tuxedo systems. You use the BEA Tuxedo utilities tmadmi, qmadmi, ad tsadmi to admiister the Notificatio Service. Notificatio Service admiistratio is comprised of two related tasks: cofiguratio ad maagemet. Although these areas are discussed separately, they are i fact, iterrelated. Thus, to fully uderstad cofiguratio, you must also uderstad maagemet ad vice versa. Cofigurig the Notificatio Service Before you ca ru evet Notificatio Service applicatios, the followig cofiguratio requiremets must be satisfied: If data filterig or BEA Tuxedo ATMI iteroperability is to be used, create BEA Tuxedo ATMI FML field defiitio files that describe the fields o which to filter or to iteroperate. If persistet subscriptios are to be used: l l l If usig a a joit cliet/server, set the host ad port umber for the callback object refereces. Create a trasactio log. Create queues to hold evets. Create a system cofiguratio file (UBBCONFIG) ad a TUXCONFIG file Usig the CORBA Notificatio Service

185 Cofigurig Data Filters Cofigurig Data Filters If data filterig or BEA Tuxedo ATMI iteroperability is used i subscriber applicatios, you must perform the followig steps to use data filterig i subscriptios: 1. Create the BEA Tuxedo ATMI FML field table defiitio file that describes the fields o which to filter (see Listig 7-2). 2. I the UBBCONFIG file, specify where the FML field table defiitio file is located so that whe the applicatio is started, the locatio of field defiitio files is passed to the Notificatio Service servers (see Listig 7-3). I Listig 7-1, the code that is show i bold text shows how the data filterig is implemeted i a evet poster applicatio. Oly subscriptios that cotai the ame/value pair billig ad patiet_accout will receive the evet. Listig 7-1 Sample Data Filterig Usig the BEA Simple Evets API (C++) CosNotificatio::StructuredEvet otif; otif.header.fixed_header.evet_type.domai_ame = CORBA::strig_dup("HEALTHCARE"); otif.header.fixed_header.evet_type.type_ame = CORBA::strig_dup("HMO"); // Specify a additioal filter, based upo ame ad value // for this evet. otif.filterable_data.legth(2); otif.filterable_data[0].ame = CORBA::strig_dup("billig"); otif.filterable_data[0].value <<= CORBA::Log(1999); otif.filterable_data[1].ame = CORBA::strig_dup("patiet_accout"); otif.filterable_data[1].value <<= CORBA::Log(2345); // Push the structured evet oto the chael. testchael->push_structured_evet(otif); Usig the CORBA Notificatio Service 7-23

186 7 CORBA Notificatio Service Admiistratio Listig 7-2 shows the FML field table defiitios file eeded to use data filterig. Listig 7-2 Data Filterig FML Field Table File *base 2000 #Field Name Field # Field Type Flags Commets # billig 1 log - - patiet_accout 2 log - - Listig 7-3 shows the cotet of eviromet variable file (evfile). The evfile cotais the locatio of the FML field defiitios file. Note: You ca ame the eviromet variable file whatever you wat, but the ame used must match the ame specified for the ENVFILE cofiguratio optio, the SERVERS sectio of the UBBCONFIG file. Listig 7-3 Evfile Specificatio for Data Filterig (evfile) (Microsoft Widows) FLDTBLDIR32=D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_cxx\commo FIELDTBLS32=ews_flds Listig 7-4 shows, i bold text, how the locatio of the FML field table file is specified i the UBBCONFIG file for the Advaced samples. Listig 7-4 Specifyig the FML Field Defiitios File i the UBBCONFIG File *SERVERS TMSYSEVT SRVGRP = NTS_GRP SRVID = 1 TMUSREVT SRVGRP = NTS_GRP>>$@ SRVID = Usig the CORBA Notificatio Service

187 Settig the Host ad Port ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\evfile" TMNTS SRVGRP = NTS_GRP SRVID = 3 ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\evfile" CLOPT = "-A -- -s TMNTSQS" TMNTSFWD_T SRVGRP = NTS_GRP SRVID = 4 ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\evfile" TMNTSFWD_P SRVGRP = NTS_GRP SRVID = 5 ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\evfile" Settig the Host ad Port The object refereces host ad port umber requiremets for the callback object are as follows: For trasiet callback objects, ay port is sufficiet ad ca be obtaied dyamically by the ORB. For persistet callback objects, the ORB must be cofigured to accept requests for the callback object o the same port o which the object referece for the callback object was created. You specify the port umber from the user rage of port umbers, rather tha from the dyamic rage. Assigig port umbers from the user rage prevets joit cliet/server applicatios from usig coflictig ports. The method you use to set the host ad port depeds o the programmig laguage you are usig. Settig Host ad Port o C++ Subscriber Applicatios For C++ subscriber applicatios, to specify a particular port for the joit cliet/server applicatio to use, iclude the followig o the commad lie that starts the process for the joit cliet/server applicatio: -ORBport -IRBid BEA_IIOP Usig the CORBA Notificatio Service 7-25

188 7 CORBA Notificatio Service Admiistratio where is the umber of the port to be used by the ORB whe creatig ivocatios ad listeig for ivocatios o the callback object i the joit cliet/server applicatio. Use this commad whe you wat the object referece for the callback object i a joit cliet/server applicatio to be persistet ad whe you wat to stop ad restart the joit cliet/server applicatio. If this commad is ot used, the ORB uses a radom port. If a radom port is used whe the joit cliet/server applicatio is stopped ad the restarted, ivocatios to persistet callback objects i the joit cliet/server applicatio will fail. The port umber is part of the iput to the argv argumet of the CORBA::orb_iit member fuctio. Whe the argv argumet is passed, the ORB reads that iformatio, establishig the port for ay object refereces created i that process. Settig Host ad Port o Java Subscriber Applicatios For Java subscriber applicatios, you ca pass i properties that set the host ad port. Listig 7-5 illustrates how to do this. Listig 7-5 Settig Host ad Port i Java Subscriber Applicatios Properties prop = ew Properties(); prop.put( "org.omg.corba.orbclass", "com.beasys.corba.iiop.orb" ); prop.put("org.omg.corba.orbsigletoclass", "Com.beasys.CORBA.idl.ORBSigleto"); prop.put( "org.omg.corba.orbport", ); ORB orb = ORB.iit(args, prop); Note: You ca also set the port i the java commad lie. Here is a example of a java commad lie that sets the port umber: java -DTOBJADDR=//BEANIE:2359 \ -Dorg.omg.corba.ORBPort=portumber -classpath Usig the CORBA Notificatio Service

189 Creatig a Trasactio Log Creatig a Trasactio Log Whe you use persistet subscriptios, you must cofigure ad boot the BEA Tuxedo queuig system. The queuig system requires a trasactio log. Listig 7-6 shows how to use the tmadmi utility to create a trasactio log. Listig 7-6 Creatig a Trasactio Log (createtlog) (Microsoft Widows) >tmadmi >crdl -b 100 -z D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\TLOG >crlog -m SITE1 >quit > Creatig Evet Queues Whe you use persistet evets, you must cofigure ad boot the BEA Tuxedo queuig system. Two evet queues must be created: TMNTSFWD_P This is the evet forwardig queue for persistet subscriptios. Evets go to this queue first ad the are forwarded to matchig persistet subscriptios. If a evet caot be delivered o the first attempt, it is held i this queue ad repeated attempts are made to deliver it. If the settable retry limit is reached before the evet ca be successfully delivered, the evet is moved to the error queue. This queue requires the followig cofiguratio parameters: l l l Queuig order (for example, first i, first out). How to hadle out-of-order equeuig. Retry limit (how may retries before movig the evet to the error queue). Usig the CORBA Notificatio Service 7-27

190 7 CORBA Notificatio Service Admiistratio l l l l Retry time iterval. How full the queue ca get before admiistrative itervetio is required. How low the queue ca get after gettig full before admiistrative itervetio is required. Defiitio of the admiistrative itervetio commad. TMNTSFWD_E This is the error queue. This queue receives evets from the TMNTSFWD_P queue that caot be delivered to subscriptios. This queue requires the same cofiguratio parameters as the TMNTSFWD_P forwardig queue, however, the retry limit ad retry time iterval parameters are irrelevat because this is the error queue ad errors are oly removed by admiistrative itervetio. To cofigure these queues, perform the followig steps: 1. Create a device o disk for the queue space. 2. Cofigure a queue space. 3. Create the queues. These steps are described i the followig sectios. Determiig Space Parameters for Trasiet ad Persistet Subscriptios To tue your system for maximum performace, you should determie the optimal values for the followig parameters: The umber of trasiet forwardig servers (TMNTSFWD_T) ad persistet forwardig servers (TMNTSFWD_P). IPC queue space (this is used for trasiet subscriptios). Size of /Q queues (this is used for persistet subscriptios) Usig the CORBA Notificatio Service

191 Creatig Evet Queues IPC Queue Space for Trasiet Subscriptios Proceed as follows to determie space parameters for trasiet subscriptios: 1. Determie how may evets may be i the pipelie for trasiet subscriptios; that is, how may evets may be i the process of beig delivered at ay give time. This equals the umber of evets multiplied by the umber of subscribers receivig them. 2. Determie the size of your evets. For purposes of this discussio, we will assume that they are relatively small about 300 bytes or less. 3. Determie how may trasiet forwardig servers you would like to start, most likely oe or two oe per processor o your machie is a good umber to start with. 4. Determie how much IPC queue space you will eed to hold your trasiet evets. The amout of space you eed is 1000 bytes multiplied by the umber of evets you allow i the pipelie. Divide this umber by the umber IPC queues your trasiet forwarders have. If you use MSSQ sets, the your trasiet forwarders share oe IPC queue; if you do ot, the each forwarder has its ow IPC queue. For example, if you estimate that there will be 10 evets delivered to 50 subscribers i the pipelie, ad you start 2 trasiet forwarders ad they do ot share a IPC queue (that is, you do ot use MSSQ sets), the amout of IPC queue space you eed is: 10 evets * 50 subscribers * 1000 bytes / 2 forwarders = 250,000 bytes 5. Cofigure the IPC queue size to that umber by chagig the etries i the system registry. How you do this is platform-specific. l l For Microsoft Widows systems, see Settig IPC Parameters o Microsoft Widows o page For UNIX systems, refer to the system referece maual supplied with the system. /Q Queue Size Parameter Persistet Subscriptios Proceed as follows to determie space parameters for persistet subscriptios: Usig the CORBA Notificatio Service 7-29

192 7 CORBA Notificatio Service Admiistratio 1. Determie how may evets may be i the pipelie for persistet subscriptios; that is, how may evets may be i the process of beig delivered at ay give time. This equals the umber of evets multiplied by the umber of subscribers receivig them. 2. Determie the size of your evets. For purposes of this discussio, we will assume that they are relatively small about 300 bytes or less. 3. Determie the size your /Q queues eed to be to hold your persistet evets (both for your pedig queue ad error queue). Proceed as follows to do this: a. Determie the size of a disk page. This is platform-specific. For example, o Microsoft Widows, a disk page is 500 bytes. O UNIX machies, a disk page could rage from 500 to 4000 bytes i size. b. Determie how may disk pages you will eed to store oe evet roudig up. For example, if you eed 1000 bytes per evet ad disk pages are 500 bytes, you will eed 2 disk pages per evet. c. Determie how may disk pages you will eed for your evets. For example, if you wat to allow 500 pedig evets ad 200 error evets, ad a evet takes up 2 disk pages, you will eed 1400 disk pages. d. Determie how may disk pages you will eed for your qspace. This is the umber of disk pages you eed for your evets plus some pages for qspace overhead. For example, if you eed 1400 disk pages for evets, the your qspace eeds approximately 1450 disk pages (50 pages of qspace overhead). e. Determie how may pages you will eed for your qspace device. This is the umber of pages you eed for the qspace plus some pages for device overhead. For example, if you eed 1450 disk pages for your qspace, the your device eeds approximately 1500 pages (50 pages of device overhead). 4. Whe you use qmadmi to create the qspace for your persistet evets, the first phase is to create a device. Use the size computed above i step 3e above (approximately 1500 pages). Next, specify the size of the qspace. Use the size computed i step 3d (approximately 1450 pages). Next, specify how may evets ca be i the pedig queue ad how may evets ca be i the error queue. The followig sectios explai how to create ad cofigure qspaces Usig the CORBA Notificatio Service

193 Creatig Evet Queues Creatig a Device o Disk for the Queue Space You use the qmadmi commad utility to create a device o disk for the queue space. Before you create a queue space, you must create a etry for it i the uiversal device list (UDL). Listig 7-7 shows a example of the commads. Listig 7-7 Creatig a Device o Disk for Queue Space (UNIX) prompt>qmadmi d:\smith\reg\que qmadmi - Copyright (c) BEA Systems, Ic. Portios * Copyright RSA Data Security, Ic. All Rights Reserved. Distributed uder licese by BEA Systems, Ic. BEA Tuxedo is a registered trademark. QMCONFIG=d:\smith\reg\QUE > crdl d:\smith\reg\que Created device d:\smith\reg\que, offset 0, size 1100 o d:\smith\reg\que For more iformatio about creatig a device o disk, see Usig the ATMI /Q Compoet. Cofigurig a Queue Space You use the qmdami qspacecreate commad to cofigure queue spaces. A queue space makes use of IPC resources; therefore, whe you defie a queue space you are allocatig a shared memory segmet ad a semaphore. The easiest way to use the qspacecreate commad is to let it prompt you. Listig 7-8 shows a example queue space that is cofigured for the Advaced sample applicatio. Listig 7-8 Creatig Queue Space > qspacecreate Queue space ame: TMNTSQS Usig the CORBA Notificatio Service 7-31

194 7 CORBA Notificatio Service Admiistratio IPC Key for queue space: Size of queue space i disk pages: 1050 Number of queues i queue space: 2 Number of cocurret trasactios i queue space: 10 Number of cocurret processes i queue space: 10 Number of messages i queue space: 500 Error queue ame: TMNTSFWD_E Iitialize extets (y, [default=]): y Blockig factor [default=16]: I the queue space created i Listig 7-8, take ote of the followig size settigs: Number of messages i queue space:500 Settig this parameter to 500 allows room for a total of 500 evets i the pedig ad error queues. Size of queue space i disk pages:1050 O Microsoft Widows, each disk page is 500 bytes ad each evet eeds 1000 bytes. I additio, you must allow 2 disk pages per evet. Sice you estimate that there will be 500 evets i the pedig ad error queues, the you must allow 1000 disk pages to store them (500 * 2). Also, you must allow 50 disk pages for qspace overhead, so the qspace size is set to 1050 disk pages. Fially, the device eeds 50 disk pages of overhead too, so the device size is 1100 disk pages, which you set usig the crdl commad (see Listig 7-7). For more iformatio about creatig queue space, see Usig the ATMI /Q Compoet. Creatig the Queues You must use the qmadmi qcreate commad to create each queue that you ited to use. Before you ca create a queue, you first have to ope the queue space with the qmadmi qope commad. If you do ot provide a queue space ame, qope will prompt for it. Listig 7-9 shows a example of creatig the TMNTSFWD_P ad TMNTSFWD_E queues that are created for the Advaced sample applicatio Usig the CORBA Notificatio Service

195 Creatig Evet Queues Listig 7-9 Creatig Queues > qope Queue space ame: TMNTSQS > qcreate Queue ame: TMNTSFWD_P Queue order (priority, time, fifo, lifo): fifo Out-of-orderig equeuig (top, msgid, [default=oe]): oe Retries [default=0]: 5 Retry delay i secods [default=0]: 3 High limit for queue capacity warig (b for bytes used, B for blocks used, % for percet used, m for messages [default=100%]): 80% Reset (low) limit for queue capacity warig [default=0%]: 0% Queue capacity commad: No default queue capacity commad Queue TMNTSFWD_P created > qcreate Queue ame: TMNTSFWD_E Queue order (priority, time, fifo, lifo): fifo Out-of-orderig equeuig (top, msgid, [default=oe]): oe Retries [default=0]: 2 Retry delay i secods [default=0]: 30 High limit for queue capacity warig (b for bytes used, B for blocks used, % for percet used, m for messages [default=100%]): 80% Reset (low) limit for queue capacity warig [default=0%]: 0% Queue capacity commad: No default queue capacity commad Q_CAT:1438: INFO: Create queue - error queue TMNTSFWD_E created Queue TMNTSFWD_E created > q For more iformatio about creatig queues, see Usig the ATMI /Q Compoet. Usig the CORBA Notificatio Service 7-33

196 7 CORBA Notificatio Service Admiistratio Settig IPC Parameters o Microsoft Widows The BEA Tuxedo software for Microsoft Widows systems provides you with BEA Tuxedo IPC Helper (TUXIPC), a iterprocess commuicatio subsystem, that is istalled with the product. O most machies, IPC Helper rus as istalled; however, you ca use the IPC Resources page of the cotrol pael applet to tue the TUXIPC subsystem ad maximize performace. To display the IPC Resources page of the IPC Cotrol Pael, perform these steps: 1. Click Start >Settigs >Cotrol Pael. The Microsoft Widows Cotrol Pael is displayed (Figure 7-1). Figure 7-1 Microsoft Widows Cotrol Pael 7-34 Usig the CORBA Notificatio Service

197 Creatig Evet Queues 2. Click the BEA Admiistratio ico. The BEA Admiistratio Cotrol Pael is displayed (Figure 7-2). 3. Click o the IPC Resources tab. The IPC Resources Cotrol Pael portio of the BEA Admiistratio Cotrol Pael is displayed (Figure 7-2). Figure 7-2 BEA Tuxedo Software for Microsoft Widows IPC Resources Cotrol Pael To defie IPC settigs for your BEA Tuxedo machie, proceed as follows: 1. I the Curret Resource Default box, click the Use Default IPC Settigs check box to clear it. 2. Click the isert box. 3. Eter the ame of your machie ad press Eter. Usig the CORBA Notificatio Service 7-35

198 7 CORBA Notificatio Service Admiistratio 4. Click the fields ext to the IPC resources you wat to set, eter the desired values, ad click Apply. Clickig Apply saves the chages i the Registry Table. You must the stop ad the restart the tuxipc.exe service for the chages to take effect. 5. Click OK to close the Cotrol Pael. You ca view the performace of a ruig BEA Tuxedo server applicatio o the Performace Moitor. To start the Performace Moitor, click Start >Programs >Admiistratio Tools >Performace Moitor o the taskbar. The Performace Moitor scree is displayed (Figure 7-3). Figure 7-3 BEA Tuxedo Software for Microsoft Widows Performace Moitor 7-36 Usig the CORBA Notificatio Service