BEA WebLogic Application Integration A Component of BEA WebLogic Integration. Adapter Development Guide

Transcription

1 BEA WebLogic Applicatio Itegratio A Compoet of BEA WebLogic Itegratio Adapter Developmet Guide BEA WebLogic Applicatio Itegratio Release 2.0 Documet Editio 2.0 July 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, Operatig System for the Iteret, Liquid Data, BEA WebLogic E-Busiess Platform, BEA Builder, BEA Maager, BEA elik, BEA Campaig Maager for WebLogic, BEA WebLogic Commerce Server, BEA WebLogic Persoalizatio Server, BEA WebLogic Process Itegrator, BEA WebLogic Collaborate, BEA WebLogic Eterprise, BEA WebLogic Server, ad BEA WebLogic Itegratio are trademarks of BEA Systems, Ic. All other product ames may be trademarks of the respective compaies with which they are associated. BEA WebLogic Applicatio Itegratio Documet Editio Part Number Date Software Versio 2.0 N/A July

3 Cotets 1. Itroductio to the ADK Sectio Objectives What is the ADK? What are Adapters? Service Adapters Evet Adapters The Desig-Time GUI The Applicatio View The Packagig Framework Before You Begi Cocepts Rutime vs. Desigtime Ru-time Framework Desig-Time Framework Evets ad Services Evets Services Loggig The Loggig Toolkit The Loggig Framework Iteratioalizatio ad Localizatio Adapter Logical Name Tools Sample Adapter Why Use the Sample Adapter? BEA WebLogic Applicatio Itegratio Adapter Developmet Guide iii

4 What s I the Sample Adapter The GeerateAdapterTemplate Utility ADK Javadoc At-Based Build Process Why Use At? XML Tools Creatig a Custom Developmet Eviromet Adapter Setup Worksheet Usig GeerateAdapterTemplate Step 1. Execute GeerateAdapterTemplate Step 2. Rebuild the Tree Step 3. Deploy the Adapter to Applicatio Itegratio The ADK Loggig Toolkit Loggig Toolkit Loggig Cofiguratio File Loggig Cocepts Message Categories Message Priority Assigig a Priority to a Category Message Appeders Message Layout Puttig the Compoets Together How to Set Up Loggig Loggig Framework Classes com.bea.loggig.ilogger com.bea.loggig.logcotext com.bea.loggig.logmaager Iteratioalizatio ad Localizatio of Log Messages Savig Cotextual Iformatio i a Multi-Threaded Compoet Developig a Service Adapter Service Adapters i the Rutime Eviromet The Flow of Evets Step 1: Developmet Cosideratios iv BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

5 Step 2: Cofigurig the Developmet Eviromet Step 2a: Set Up the File Structure Modifyig the Directory Structure Step 2b: Assig the Adapter Logical Name Step 2c: Settig Up the Build Process build.xml Compoets Step 2d: Create the Message Budle Step 3: Implemetig the SPI How to Use this Sectio Basic SPI Implemetatio MaagedCoectioFactory Trasactio Demarcatio ADK Implemetatios AbstractMaagedCoectioFactory Properties Required at Deploymet MaagedCoectio ADK Implemetatio MaagedCoectioMetaData ADK Implemetatio CoectioEvetListeer ADK Implemetatio CoectioMaager ADK Implemetatio CoectioRequestIfo ADK Implemetatio LocalTrasactio ADK Implemetatio Step 4: Implemetig the CCI How to Use this Sectio Basic CCI Implemetatio Coectio ADK Implemetatio Iteractio ADK Implemetatio Usig XCCI to Implemet the CCI BEA WebLogic Applicatio Itegratio Adapter Developmet Guide v

6 DocumetRecord IDocumet ADK-Supplied XCCI Classes XCCI Desig Patter CoectioFactory ADK Implemetatio CoectioMetaData ADK Implemetatio CoectioSpec ADK Implemetatio IteractioSpec ADK Implemetatio LocalTrasactio Record ADK Implemetatio ResourceAdapterMetaData ADK Implemetatio Step 5: Deployig the Adapter Step 5a: Update the ra.xml File Step 5b: Create the weblogic-ra.xml File Step 5c: Create ad Deploy the.rar File Step 6: Testig the Adapter Usig the Test Haress Test Case Extesios Provided by the ADK sample.spi.nomaagedsceariotestcase sample.evet.offlieevetgeeratortestcase sample.cliet.applicatioviewcliet Developig a Evet Adapter Evet Adapters i the Rutime Eviromet The Flow of Evets Step 1: Developmet Cosideratios Step 2: Cofigurig the Developmet Eviromet Step 2a: Set up the File Structure Step 2b: Assig the Adapter Logical Name vi BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

7 Step 2c: Set Up the Build Process Step 2d: Create the Message Budle Step 2e: Cofigure Loggig Create a Evet Geeratio Loggig Category Step 3: Implemetig the Adapter Step 3a: Create a EvetGeerator How the Data Extractio Mechaism is Implemeted How the EvetGeerator is Implemeted Step 3b: Implemet the Data Trasformatio Method Step 4. Deployig the Adapter Add EvetRouterServlet to.war File Create the EvetRouter.war file Step 5: Testig the Adapter Developig a Desig-Time GUI Itroductio to Desig-Time Form Processig Form Processig Classes RequestHadler CotrollerServlet ActioResult Word ad Its Descedats AbstractIputTagSupport ad Its Descedats Form Processig Sequece Prerequisites Steps i the Sequece Desig-Time Features Java Server Pages JSP Templates The ADK Tag Library JSP Tag Attributes JavaScript Library The Applicatio View File Structure The Flow of Evets Step 1: Developmet Cosideratios BEA WebLogic Applicatio Itegratio Adapter Developmet Guide vii

8 Step 2: Determiig the Scree Flow Scree 1: Loggig I Scree 2. Maagig Applicatio Views Scree 3: Defiig the New Applicatio View Scree 4: Cofigurig the Coectio Scree 5: Admiisterig the Applicatio View Scree 6: Addig a Evet Scree 7: Addig a Service Scree 8: Deployig a Applicatio View Cotrollig User Access Deployig the Applicatio View Savig the Applicatio View Scree 9: Summarizig the Applicatio View Step 3: Cofigurig the Developmet Eviromet Step 3a: Create the Message Budle Step 3b: Cofigure the Eviromet to Update JSPs Without Restartig the WebLogic 6.0 Server Step 4: Implemetig the Desig-Time GUI Exted AbstractDesigTimeRequestHadler Methods to Iclude Step 4a. Supply the MaagedCoectioFactory Class Step 4b. Implemet iitservicedescriptor() Step 4c. Implemet iitevetdescriptor() Step 5: Write the HTML Forms Step 5a: Create the cofco.jsp Form Icludig the ADK Tag Library Postig the CotrollerServlet Displayig the Label for the Form Field Displayig the Text Field Size Displayig a Submit Butto o the Form Implemetig cofco() Step 5b: Create the addevet.jsp form Icludig the ADK Tag Library Postig the CotrollerServlet Displayig the Label for the Form Field viii BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

9 Displayig the Text Field Size Displayig a Submit Butto o the Form Addig Additioal Fields Step 5c: Create the addservc.jsp form Icludig the ADK Tag Library Postig the CotrollerServlet Displayig the Label for the Form Field Displayig the Text Field Size Displayig a Submit Butto o the Form Addig Additioal Fields Step 5d: Create display.jsp Step 5e: Write the WEB-INF/web.xml Web Applicatio Deploymet Descriptor Step 7. Implemetig the Look-ad-Feel A. Adapter Setup Worksheet Adapter Setup Worksheet... A-2 B. The DBMS Sample Adapter Itroductio to the DBMS Sample Adapter...B-1 How the DBMS Sample Adapter Works...B-2 Before You Begi...B-3 Accessig the DBMS Sample Adapter...B-3 A Tour of the DBMS Sample Adapter...B-4 How the DBMS Sample Adapter Was Developed...B-21 Developmet Referece Documetatio...B-21 Step 1: Developmet Cosideratios...B-22 Step 2: Implemetig the Server Provider Iterface Package...B-24 MaagedCoectioFactoryImpl...B-25 MaagedCoectioImpl...B-26 CoectioMetaDataImpl...B-27 LocalTrasactioImpl...B-28 Step 3: Implemetig the Commo Cliet Iterface Package...B-29 CoectioImpl...B-30 IteractioImpl...B-31 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide ix

10 IteractioSpecImpl... B-32 Step 4: Implemetig the Evet Package... B-33 DbmsEvetGeeratorWorker... B-33 Step 5: Deployig the Adapter... B-35 Step 5a: Update the RA.XML File... B-35 Step 5b: Create the.rar File... B-36 Step 5c: Deploy the.rar File... B-36 How the DBMS Adapter Desig-Time GUI was Developed... B-36 Step 1: Developmet Cosideratios... B-37 Step 2: Determie Necessary Java Server Pages... B-37 Step 3: Create the Message Budle... B-38 Step 4: Implemetig the Desig-Time GUI... B-39 Step 5: Writig Java Server Pages... B-40 Custom JSP Tags... B-41 Save a Object s State... B-41 Write the WEB-INF/web.xml Web Applicatio Deploymet Descriptor... B-41 C. The Sample Adapter Itroductio to the Sample Adapter... C-1 How the Sample Adapter Works... C-2 Before You Begi... C-2 Accessig the Sample Adapter... C-3 A Tour of the Sample Adapter... C-4 How the Evet Adapter was Developed... C-13 Developmet Referece Documetatio... C-13 Step 1: Developmet Cosideratios... C-14 Step 2: Implemetig the Server Provider Iterface Package... C-16 MaagedCoectioFactoryImpl... C-17 MaagedCoectio... C-18 CoectioMetaDataImpl... C-19 Step 3: Implemetig the Commo Cliet Iterface Package... C-20 CoectioImpl... C-21 IteractioImpl... C-22 IteractioSpecImpl... C-23 x BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

11 Step 4: Implemetig the Evet Package...C-24 EvetMetaData...C-24 PushEvet...C-25 PushHadler...C-25 PullEvetGeerator...C-26 PushEvetGeerator...C-27 Step 5: Deployig the Adapter...C-28 Step 5a: Update the RA.XML File...C-28 Step 5b: Create the.rar File...C-29 Step 5c: Deploy the.rar File...C-29 Creatig the Adapter Desig-Time GUI...C-30 Step 1: Developmet Cosideratios...C-30 Step 2: Determie Adapter Scree Flow...C-30 Java Server Pages (JSP)...C-31 Step 3: Create the Message Budle...C-31 Step 4: Implemetig the Desig-Time GUI...C-32 Implemetatio...C-32 Step 5: Writig Java Server Pages...C-32 Step 5a: Developers Commets...C-32 Step 5b: Write the WEB-INF/web.xml Web Applicatio Deploymet Descriptor...C-33 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide xi

12 xii BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

13 About This Documet BEA WebLogic Applicatio Itegratio Adapter Developmet Guide is orgaized as follows: Itroductio to the ADK provides a brief backgroud o the BEA WebLogic Applicatio Itegratio Adapter Developmet Kit. It discusses service ad evet adapters, the desig-time GUI, ad what to do before you start buildig a adapter. Cocepts discusses of some of the ADK cocepts relevat to adapter developmet, icludig evets ad services, desigtime vs. rutime, loggig, ad the adapter logical ame. Tools describes the ADK tools provided that you ca use to build adapters. These tools iclude the sample adapter, the GeerateAdapterTemplate utility, the At-based build process, XML tools, ad Javadoc. Creatig a Custom Developmet Eviromet shows how to use the GeerateAdapterTemplate utility to cloe the sample adapter ad customize a developmet eviromet for your ew adapter. The ADK Loggig Toolkit describes how to use the ADK loggig toolkit to implemet loggig. It also icludes a discussio of the Apache log4j specificatio, which is the core of the ADK loggig framework. Developig a Service Adapter shows you how to build a adapter that supports services. It delieates all of the steps required to successfully create the adapter ad shows relevat code samples where ecessary. Developig a Evet Adapter shows you how to build a adapter that supports evets. It delieates all of the steps required to successfully create the adapter ad shows relevat code samples where ecessary. Developig a Desig-Time GUI shows you how to build a graphical user iterface that adapter users eed to defie, deploy, ad test their applicatio BEA WebLogic Applicatio Itegratio Adapter Developmet Guide xiii

14 views. It delieates all of the steps required to successfully create the GUI ad shows relevat code samples where ecessary. Adapter Setup Worksheet is a worksheet that will help you coceptualize the adapter you are buildig before you actually bega to code. It will help you defie such compoets as the adapter logical ame ad the Java package base ame ad help you determie the locales for which you eed to localize message budles. The DBMS Sample Adapter describes how the ADK was used to build a DBMS adapter. It also cotais a simple task-drive example of how to use the DBMS adapter. The Sample Adapter describes how the ADK was used to build a adapter. It also cotais a simple task-drive example of how to use the adapter. What You Need to Kow The BEA WebLogic Applicatio Itegratio Adapter Developmet Guide is desiged primarily for use by adapter developers who will use the ADK to develop service adapters, evet adapters, ad the desig-time GUI that adapter users employ to create applicatio views. e-docs Web Site BEA product documetatio is available o the BEA corporate Web site. From the BEA Home page, click o Product Documetatio or go directly to the e-docs Product Documetatio page at xiv BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

15 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 WebLogic Applicatio Itegratio 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 WebLogic Applicatio Itegratio 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, you ca get it for free from the Adobe Web site at Related Iformatio The followig resources are also available: BEA WebLogic Server documetatio ( BEA WebLogic Process Itegrator documetatio ( XML Schema Specificatio ( The Su Microsystems, Ic. J2EE Coector Architecture Specificatio ( BEA WebLogic Applicatio Itegratio Adapter Developmet Guide xv

16 Cotact Us! Your feedback o the BEA WebLogic Applicatio Itegratio documetatio is importat to us. Sed us at docsupport@beasys.com if you have questios or commets. Your commets will be reviewed directly by the BEA professioals who create ad update the BEA WebLogic Applicatio Itegratio documetatio. I your message, please idicate that you are usig the documetatio for the BEA WebLogic Applicatio Itegratio 2.0 release. If you have ay questios about this versio of BEA WebLogic Applicatio Itegratio, or if you have problems istallig ad ruig BEA WebLogic Applicatio Itegratio, cotact BEA Customer Support through BEA WebSupport at You ca also cotact Customer Support by usig the cotact iformatio provided o the Customer Support Card, which is icluded i the product package. Whe cotactig Customer Support, be prepared to provide the followig iformatio: Your ame, address, phoe umber, ad fax umber Your compay ame ad compay address Your machie type ad authorizatio codes The ame ad versio of the product you are usig A descriptio of the problem ad the cotet of pertiet error messages Documetatio Covetios The followig documetatio covetios are used throughout this documet. Covetio boldface text Item Idicates terms defied i the glossary. xvi BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

17 Covetio Ctrl+Tab italics moospace text moospace boldface text moospace italic text UPPERCASE TEXT Item 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 file ames ad their extesios. Moospace text also idicates text that you must eter from the keyboard. Examples: #iclude <iostream.h> void mai ( ) the poiter psz chmod u+w * \tux\data\ap.doc tux.doc BITMAP float Idetifies sigificat words i code. Example: void commit ( ) Idetifies variables i code. Example: Strig expr Idicates device ames, eviromet variables, ad logical operators. Examples: LPT1 SIGNON OR { } Idicates a set of choices i a sytax lie. The braces themselves should ever be typed. [ ] Idicates optioal items i a sytax lie. The brackets themselves should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list]... BEA WebLogic Applicatio Itegratio Adapter Developmet Guide xvii

18 Covetio Item Separates mutually exclusive choices i a sytax lie. The symbol itself should ever be typed.... Idicates oe of the followig i a commad lie: That a argumet ca be repeated several times i a commad lie That the statemet omits additioal optioal argumets That you ca eter additioal parameters, values, or other iformatio The ellipsis itself should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list] Idicates the omissio of items from a code example or from a sytax lie. The vertical ellipsis itself should ever be typed. xviii BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

19 CHAPTER 1 Itroductio to the ADK Welcome to the BEA WebLogic Applicatio Itegratio Developmet Guide, the how to guide for usig the BEA WebLogic Applicatio Itegratio Adapter Developmet Kit (ADK). This guide will show you how to develop, test, ad deploy evet ad service adapters ad the desig-time user iterface. This sectio provides iformatio o the followig subjects: What is the ADK? What are Adapters? l Service Adapters l The Desig-Time GUI The Desig-Time GUI Before You Begi Sectio Objectives This sectio serves as a overview to usig the ADK to develop evet ad service adapters ad a desig-time GUI. You will lear: What adapters are ad how they are used. Prerequisites you must meet before begiig adapter or GUI developmet. BEA WebLogic Applicatio Itegratio Developmet Guide 1-1

20 1 Itroductio to the ADK Termiology associated with adapter or GUI developmet. What is the ADK? The ADK is the tool set for implemetig the evet ad service protocol of BEA WebLogic Applicatio Itegratio; that is, it is a collectio of frameworks that support the developmet, testig, packagig, ad distributio of resource adapters for the WebLogic platform. Specifically, the ADK is comprised of the followig four frameworks: Desigtime Rutime Loggig Packagig. The ADK provides: Ru-time support for evets ad services. A API to itegrate a adapter s user iterface ito the Applicatio Itegratio Applicatio View Maagemet Cosole. The added value provided by the ADK is that adapters ca become a itegral part of a sigle graphical cosole applicatio that allows busiess users to costruct itegratio solutios. What are Adapters? Resource adapters referred to i this documet as adapters are software that coect oe applicatio to aother whe those applicatios are ot origially desiged to commuicate with each other. For example, a order etry system built by oe compay requires a adapter to commuicate with a customer iformatio system built by aother. 1-2 BEA WebLogic Applicatio Itegratio Developmet Guide

21 What are Adapters? By usig the ADK, you ca create two types of adapters: Service adapters, which cosume messages. Evet adapters, which geerate messages. Service Adapters Service adapters receive a XML request documet from a cliet ad ivoke a specific fuctio i the uderlyig eterprise iformatio system (EIS). They are cosumers of messages ad may or may ot provide a respose. There are two ways to ivoke a service: asychroous ad sychroous. With a asychroous service adapter, the cliet applicatio issues a service request ad the proceeds with its processig. The cliet applicatio does ot wait for the respose. With a sychroous service adapter, the cliet waits for the respose before proceedig with its processig. The Applicatio Itegratio platform supports both of these service adapter ivocatios, relievig you from havig to provide this fuctioality. Service adapters perform the followig four fuctios: Receive service requests from a exteral cliet. Trasform the XML request documet ito the EIS specific format. The request documet coforms to the request XML schema for the service. The request XML schema is based o metadata i the EIS. Ivoke the uderlyig fuctio i the EIS ad wait for its respose. Trasform the respose from the EIS specific data format to a XML documet that coforms to the respose XML schema for the service. The respose XML schema is based o metadata i the EIS. As with evets, the ADK implemets the aspects of these four fuctios that are geeric across all service adapters. To lear how to develop a service adapter, see Developig a Service Adapter. BEA WebLogic Applicatio Itegratio Developmet Guide 1-3

22 1 Itroductio to the ADK Evet Adapters Evet adapters are desiged to propagate iformatio from a EIS ito a Applicatio Itegratio server. These types of adapters ca be described as publishers of iformatio. There are two basic types of evet adapters: i-process ad out-of-process. I-process evet adapters execute withi the same process as the EIS. Out-of-process adapters execute i a separate process. I-process ad out-of-process evet adapters oly differ i how they accomplish the data extractio process. O the ADK itegratio platform, all evet adapters perform the followig three fuctios: Respod to evets deemed to be of iterest to some exteral party that occur iside the ruig EIS ad extract data about the evet from the EIS ito the adapter. Trasform evet data from the EIS specific format to a XML documet that coforms to the XML schema for the evet. The XML schema is based o metadata i the EIS. Propagate the evet to a evet cotext obtaied from the applicatio view. The ADK implemets the aspects of these three fuctios that are geeric across all evet adapters. Cosequetly, you ca focus o the EIS specific aspects of their adapter. This cocept is the same as the cocept behid Eterprise Java Beas (EJB). With EJB, the cotaier provides system-level services for EJB developers so they ca focus o implemetig busiess applicatio logic. To lear how to develop a evet adapter, see Developig a Evet Adapter. The Desig-Time GUI Alog with evet ad service adapters, the ADK s desig-time framework provides the tools you will use to build the web-based GUI that adapter users eed to defie, deploy, ad test their applicatio views. Although each adapter has EIS-specific 1-4 BEA WebLogic Applicatio Itegratio Developmet Guide

23 The Desig-Time GUI fuctioality, all adapters require a GUI for deployig applicatio views. This framework miimizes the effort required to create ad deploy these iterfaces, primarily by usig these two compoets: A web applicatio compoet that allows you to build a HTML-based GUI by usig Java Server Pages (JSP). This compoet is augmeted by tools such as the JSP templates ad tag library ad the JavaScript library. A deploymet helper compoet, called AbstractDesigTimeRequestHadler that provides a simple API for deployig, udeployig, copyig, ad editig applicatio views o a Applicatio Itegratio server. To lear how to develop a desig-time GUI, see Developig a Desig-Time GUI. The Applicatio View A key compoet of the Desig-Time GUI is the applicatio view. The applicatio view represets a busiess-level iterface to the specific fuctioality i a applicatio. A adapter represets a system-level iterface to all the fuctioality i the applicatio. A applicatio view is cofigured for a sigle busiess purpose ad cotais oly the services related to that busiess purpose. These services require oly busiess-relevat data to be specified i the request documet ad retur oly busiess-relevat data i the respose documet. Uder the covers, the applicatio view combies this busiess-relevat data with stored metadata ecessary for the adapter. The adapter takes both the busiess-relevat data ad the stored metadata ad executes a system-level fuctio o the applicatio. I additio, the applicatio view represets both evets ad services that support a busiess purpose. This allows the busiess user to iteract with the applicatio view for all commuicatio with a applicatio. This bidirectioal commuicatio is actually supported by two adapter compoets (the evet adapter ad service adapter). The applicatio view abstracts this fact from the user ad presets them with a uified busiess iterface to the applicatio. For more iformatio about applicatio views, see BEA WebLogic Applicatio Itegratio Product Overview. Refer to Applicatio View. BEA WebLogic Applicatio Itegratio Developmet Guide 1-5

24 1 Itroductio to the ADK The Packagig Framework The ADK packagig framework provides a tool set for packagig a adapter for delivery to a customer. Ideally, all adapters are istalled, cofigured, ad uistalled the same o a Applicatio Itegratio server. Moreover, all service adapters must be J2EE compliat. The packagig framework makes creatig a J2EE adapter archive (.rar) file, web applicatio archive (.war) file, ad Applicatio Itegratio desig eviromet archive easy. Before You Begi Before you ca actually begi developig a adapter, be sure the ADK is istalled o your computer. See the BEA WebLogic Applicatio Itegratio Istallatio ad Cofiguratio Guide ad the BEA WebLogic Applicatio Itegratio Release Notes for more iformatio. 1-6 BEA WebLogic Applicatio Itegratio Developmet Guide

25 CHAPTER 2 Cocepts This sectio describes some of the more importat cocepts with which you should familiarize yourself before attemptig to develop a adapter or desig-time GUI. You will see additioal discussio of all of the followig cocepts at some poit i the adapter/gui developmet procedures. This sectio provides iformatio o the followig subjects: Rutime vs. Desigtime Evets ad Services Loggig l The Loggig Toolkit l The Loggig Framework l Iteratioalizatio ad Localizatio Adapter Logical Name Rutime vs. Desigtime Adapter activity falls withi oe of two coceptual etities: rutime ad desigtime. Rutime refers to fuctioality that occurs whe adapters execute their processes. Desigtime refers to the adapter user s implemetatio of a applicatio view; i essece, desigtime is the act of creatig, deployig, ad testig a applicatio view. BEA WebLogic Applicatio Itegratio Developmet Guide 2-1

26 2 Cocepts Rutime ad desigtime are characterized i the ADK by the ru-time ad desig-time frameworks. The ru-time framework is comprised of the tools used whe developig adapters while the desig-time framework refers to the tools you will use to desig web-based user iterfaces. Rutime ad desigtime are discussed i greater detail below. Note: I this documet, the spellig of desigtime ad rutime will vary depedig upo usage. They are alterately spelled desigtime or rutime (ou) ad desig-time or ru-time (adjective). Ru-time Framework The rutime framework is the set of tools you will use to develop evet ad service adapters. To support evet adapter developmet, the rutime framework provides a basic, extesible evet geerator. For service adapter developmet, the rutime framework provides a complete J2EE-compliat adapter. The classes supplied by the rutime framework provide the followig beefits: They allow you to focus o EIS specifics rather tha J2EE specifics. They miimize the effort eeded to use the ADK loggig framework. They simplify the complexity of J2EE Coector Architecture. They miimize redudat code across adapters. I additio, the rutime framework provides abstract base classes to help you implemet a evet geerator to leverage the evet support provided by the ADK eviromet. A key compoet of the ru-time framework is the ru-time egie, which hosts the adapter compoet resposible for hadlig service ivocatios ad maages: physical coectios to the EIS logi autheticatio trasactio maagemet all i compliace with the J2EE Coector Architecture stadard. 2-2 BEA WebLogic Applicatio Itegratio Developmet Guide

27 Evets ad Services Desig-Time Framework The desig-time framework provides the tools you will use to build the web-based GUI that adapter users eed to defie, deploy, ad test their applicatio views. Although each adapter has EIS-specific fuctioality, all adapters require a GUI for deployig applicatio views. This framework miimizes the effort required to create ad deploy this GUI, primarily by usig these two compoets: A web applicatio compoet that allows you to build a HTML-based GUI by usig JSPs. This compoet is augmeted by tools such as the JSP templates ad tag library ad the JavaScript library. A deploymet helper compoet that provides a simple API for deployig, udeployig, copyig, ad editig applicatio views o a WebLogic server. The desig-time iterface for each adapter is a J2EE web applicatio that is budled as a.war file. A web applicatio is a budle of.jsp,.html, image files, ad so o. The web applicatio descriptor is web.xml. The descriptor istructs the J2EE web cotaier how to deploy ad iitialize the web applicatio. Every web applicatio has a cotext. The cotext is specified durig deploymet ad idetifies resources associated with the web applicatio uder the web cotaier s doc root. Evets ad Services The ADK is used to create two types of adapters: evet adapters ad service adapters. Withi the ADK architecture, services ad evets are defied as a self-describig objects (that is, the ame idicates the busiess fuctio) that use XML schema to defie their iput ad output. BEA WebLogic Applicatio Itegratio Developmet Guide 2-3

28 2 Cocepts Evets A evet is a XML documet published by a applicatio view whe a evet of iterest occurs withi a EIS. Cliets that wat to be otified of evets register their iterest with a applicatio view. The applicatio view the acts as a broker betwee the target applicatio ad the cliet. Whe a cliet has subscribed to evets published by a applicatio view, the applicatio view otifies the cliet wheever a evet of iterest occurs withi the target applicatio. Whe a evet subscriber is otified that a evet of iterest has occurred, it is passed a XML documet that describes the evet. Applicatio views that publish evets ca also provide cliets with the XML schema for the publishable evets. Note: The applicatio view represets a busiess-level iterface to the specific fuctioality i a applicatio. For more iformatio o this feature, please refer to the BEA WebLogic Applicatio Itegratio Product Overview. Services A service is a busiess operatio withi a applicatio that is exposed by the applicatio view. It exists as a request/respose mechaism; that is, whe a applicatio receives a request to ivoke a busiess service, the applicatio view ivokes that fuctioality withi its target applicatio ad the returs (or, respods with) a XML documet that describes the results. To defie a service, you will eed to determie ad defie the iput requiremets, output expectatios, ad the cotet of the iteractio specificatio. A request is submitted i two parts: A iteractio specificatio, cotaiig static secodary metadata about the request. Basic iput, which idetifies the value of ay variables; for example, i a DBMS trasactio, the SQL statemet is icluded i the iteractio specificatio ad the value of the variable i the iput requiremet. The result of the trasactio is cosidered the output expectatio. 2-4 BEA WebLogic Applicatio Itegratio Developmet Guide

29 Loggig Loggig Loggig is a essetial feature of a adapter compoet. Most adapters are used to itegrate differet applicatios ad do ot iteract with ed users while processig data. Ulike the behavior of a frot-ed compoet, whe a adapter ecouters a error or warig coditio, it caot stop processig ad wait for a ed-user to respod. Moreover, the applicatios that adapters coect to are typically missio-critical busiess applicatios. For example, a adapter might be required to keep a audit report of every trasactio with a EIS. Cosequetly, adapter compoets should provide both accurate loggig ad auditig iformatio. The ADK s Loggig Framework is desiged to hadle the eeds of both loggig ad auditig. The Loggig Toolkit The ADK provides the loggig toolkit, which allows you to log iteratioalized messages to multiple output destiatios. The loggig toolkit leverages the work of the ope source project, Apache Log4j. The loggig toolkit wraps the critical classes withi log4j to provide added fuctioality whe you are buildig J2EE-compliat adapters. For the Applicatio Itegratio product, the log toolkit is provided i the logtoolkit.jar file. For iformatio o usig the loggig toolkit, see The ADK Loggig Toolkit. The Loggig Framework With the ADK, loggig of adapter activity is accomplished by implemetig the loggig framework. This framework gives you the ability to log iteratioalized ad localized messages to multiple output destiatios. It provides a rage of cofiguratio parameters you ca use to tailor message category, priority, format, ad destiatio. The loggig framework uses a categorical hierarchy to allow iheritace of loggig cofiguratio by all packages ad classes withi a adapter. The framework allows parameters to be easily modified durig rutime. BEA WebLogic Applicatio Itegratio Developmet Guide 2-5

30 2 Cocepts Iteratioalizatio ad Localizatio The loggig framework allows you to iteratioalize log messages. Iteratioalized applicatios are easy to tailor to the idioms ad laguages of ed users aroud the world without re-factorig the code. Localizatio is the process of adaptig software for a specific regio or laguage by addig locale-specific compoets ad text. The loggig framework uses the iteratioalizatio ad localizatio facilities provided by the Java platform. Adapter Logical Name Each adapter created must have a adapter logical ame; that is, a uique idetifier that represets a idividual adapter ad serves as the orgaizig priciple for all adapters. As such, the adapter logical ame is how a idividual adapter is idetified ad is also used to ame the followig: message budle loggig cofiguratio log categories The adapter logical ame is a combiatio of the vedor ame, the type of EIS coected to the adapter, ad the versio umber of the EIS. By covetio, this iformatio is expressed as vedor_eis-type_eis versio; for example, BEA_WLS_SAMPLE_ADK, where: BEA is the vedor WLS is the EIS-type SAMPLE_ADK is the EIS versio 2-6 BEA WebLogic Applicatio Itegratio Developmet Guide

31 CHAPTER 3 Tools The ADK provides a robust set of tools to assist you i developig adapters ad the desig-time GUI. This sectio icludes iformatio o the followig subjects: Sample Adapter The GeerateAdapterTemplate Utility ADK Javadoc At-Based Build Process XML Tools Sample Adapter The ADK cotais a sample adapter that provides o-eis specific code examples to help you start buildig a adapter. (Do ot cofuse this sample adapter with the ad DBMS example adapters also icluded with Applicatio Itegratio; these example adapters are documeted i The DBMS Sample Adapter ad The Sample Adapter ). You ca fid the sample adapter i <WLAI_HOME>/dev/sample. BEA WebLogic Applicatio Itegratio Developmet Guide 3-1

32 3 Tools Why Use the Sample Adapter? The purpose of the sample adapter is to free you from much of the codig ecessary to build a adapter. It provides cocrete implemetatios of key abstract classes that oly require customizatio for your specific EIS. I additio, the ADK provides the GeerateAdapterTemplate utility with which you ca quickly cloe the sample adapter developmet tree for use by the adapter you are developig. See The GeerateAdapterTemplate Utility. What s I the Sample Adapter Specifically the sample adapter cotais: sample.spi.maagedcoectiofactoryimpl A cocrete extesio to AbstractMaagedCoectioFactory that you ca customize for a specific EIS. sample.spi.maagedcoectioimpl A cocrete extesio to AbstractMaagedCoectio that you ca customize this class for a specific EIS. sample.spi.coectiometadataimpl A cocrete extesio to AbstractCoectioMetaData that you ca customize for a specific EIS. sample.web.desigtimerequesthadler A cocrete extesio to AbstractDesigTimeRequestHadler that shows how to add a evet or service at desigtime. sample.evet.evetgeerator A cocrete extesio to AbstractPullEvetGeerator that shows how to exted the ADK base class to costruct a evet geerator. Note: For more details o the classes exteded by those i the sample adapter, please refer to the ADK Javadocs. 3-2 BEA WebLogic Applicatio Itegratio Developmet Guide

33 The GeerateAdapterTemplate Utility The GeerateAdapterTemplate Utility To facilitate usig the sample adapter, the ADK provides GeerateAdapterTemplate, a commad-lie utility you ca use to cloe the sample adapter developmet tree ad create a ew adapter developmet tree. See Creatig a Custom Developmet Eviromet for complete istructios o usig this tool. ADK Javadoc ADK classes, iterfaces, methods, ad costructors are defied i the developmet kit s Javadocs. Javadocs are icluded with the ADK istallatio ad are stored i <WLAI_HOME>\dev\doc\api. At-Based Build Process The ADK employs a build process based upo At, a 100% pure Java-based build tool. For the ADK, At does the followig: Creates a Java archive (.jar) file for the adapter. Creates a.war file for a adapter s web applicatio. Creates a.rar file for a J2EE-compliat adapter. BEA WebLogic Applicatio Itegratio Developmet Guide 3-3

34 3 Tools Why Use At? Traditioally, build tools are iheretly shell-based. They evaluate a set of depedecies ad the execute commads, ot ulike those you would issue o a shell. While it is simple to exted these tools by usig or writig ay program for your operatig system, you are also limited to that OS, or at least that OS type (for example, Uix). At is preferable to shell-based make tools for the followig reasos: Istead of a model where it is exteded with shell-based commads, it is exteded usig Java classes. Istead of writig shell commads, the cofiguratio files are XML-based, callig out a target tree where various tasks get executed. Each task is ru by a object that implemets a particular task iterface. While this removes some of the expressive power iheret i beig able to costruct a shell commad, it gives your applicatio the ability to be cross-platform. If you wat to execute a shell commad, At has a execute rule that allows differet commads to be executed based o the OS upo which it executig. For complete istructio o settig up At, see Step 2c: Settig Up the Build Process. XML Tools The ADK ships with two XML developmet tools. While ot part of the desig-time compoet, these tools are required for buildig a desig-time GUI. These tools are cosidered part of the metadata support layer for the desig-time framework. These tools are: Schema Object Model (SOM), which is a API for programmatically buildig XML schemas. A adapter calls ito a EIS for specific request/respose metadata, which the eeds to be programatically trasformed ito a XML schema. The SOM is a set of tools that extracts may of the commo details, such as sytactical complexities of schema so that you ca focus o its more fudametal aspects. 3-4 BEA WebLogic Applicatio Itegratio Developmet Guide

35 XML Tools IDocumet, which provides the x-path iterface to a documet object model (DOM) documet. For more iformatio o both of these tools, please refer to their respective Javadocs: For SOM, go to <WLAI_HOME>\dev\doc\com\bea\schema. For idocumet, go to <WLAI_HOME>\dev\doc\com\bea\documet. BEA WebLogic Applicatio Itegratio Developmet Guide 3-5

36 3 Tools 3-6 BEA WebLogic Applicatio Itegratio Developmet Guide

37 CHAPTER 4 Creatig a Custom Developmet Eviromet Warig: We strogly recommed that you do ot directly alter the sample adapter icluded with the ADK. Istead, use the GeerateAdapterTemplate utility described i this chapter. Modifyig the sample adapter by ay other meas might result i uexpected ad usupported behavior. To facilitate usig the sample adapter (see Sample Adapter ), the ADK provides GeerateAdapterTemplate, a commad-lie utility you ca use to cloe the sample adapter developmet tree ad create a ew adapter developmet tree. This sectio provides iformatio o the followig subjects: Adapter Setup Worksheet Usig GeerateAdapterTemplate l Step 1. Execute GeerateAdapterTemplate l Step 2. Rebuild the Tree l Step 3. Deploy the Adapter to Applicatio Itegratio BEA WebLogic Applicatio Itegratio Developmet Guide 4-1

38 4 Creatig a Custom Developmet Eviromet Adapter Setup Worksheet The adapter setup worksheet is a questioaire that will help you idetify ad collect critical iformatio about the adapter you are developig. You ca fid this questioaire i Adapter Setup Worksheet. This worksheet is a set of 20 questios that will help you idetify critical adapter iformatio, such as EIS type, vedor, ad versio, locale ad atioal laguage of the deploymet, the adapter logical ame, ad whether or ot the adapter will supports services. Whe you ru GeerateAdapterTemplate, you will be prompted to eter this iformatio. Whe the iformatio is processed, a custom developmet tree for your adapter will be created. Usig GeerateAdapterTemplate This sectio describes how to use GeerateAdapterTemplate. You will eed to perform the followig steps: Step 1. Execute GeerateAdapterTemplate Step 2. Rebuild the Tree Step 3. Deploy the Adapter to Applicatio Itegratio Step 1. Execute GeerateAdapterTemplate To use this tool, do the followig: 1. Ope a commad-lie from the <WLAI_HOME>/dev/bi directory ad execute oe the followig commads: l For Widows NT: GeerateAdapterTemplate.cmd l For Uix: GeerateAdapterTemplate.sh The system respods: 4-2 BEA WebLogic Applicatio Itegratio Developmet Guide

39 Usig GeerateAdapterTemplate <WLAI_HOME>\dev\bi>geerateadaptertemplate *************************************************************** Welcome! This program helps you geerate a ew adapter developmet tree by cloig the ADK s sample adapter developmet tree. Do you wish to cotiue? (yes or o); default= yes : 2. Select yes by pressig Eter. The system respods: Please choose a ame for the root directory of your adapter developmet tree: 3. Eter a uique, easy-to-remember directory ame (for example dir_ame) ad press Eter. The system respods: created directory d:\wlai\dev\dir_ame (where dir_ame is the ew directory ame.) Note: If you etered a directory ame that already exists, the system will respod: d:\wlai\dev\sample already exists, please choose a ew directory that does ot already exist! Please choose a ame for the root directory of your adapter developmet tree: Eter the EIS type for your adapter: 4. Eter a idetifier for the EIS type to which your adapter will be coectig. Press Eter. The system respods: Eter a short descriptio for your adapter: 5. Eter a short, meaigful descriptio of the adapter you are about to develop ad press Eter. The system respods: Eter the major versio umber for your adapter; default= 1 : 6. Either press Eter to accept the default or eter the appropriate versio umber ad the press Eter. BEA WebLogic Applicatio Itegratio Developmet Guide 4-3

40 4 Creatig a Custom Developmet Eviromet The system respods: Eter the mior versio umber for your adapter; default= 0 : 7. Either press Eter to accept the default or type the appropriate mior versio umber ad the press Eter. The system respods: Eter the vedor ame for your adapter: 8. Eter the vedor s ame ad press Eter. The system respods: Eter a adapter logical ame; default= default_ame : 9. Either press Eter to accept the default or type the adapter logical ame you wat to use. Press Eter. The default adapter logical ame ( default_ame ) is based upo the Applicatio Itegratio recommeded format of vedor ame_eis-type_versio-umber. The system respods: Eter the Java package base ame for your adapter (e.g. sample adapter s is sample): Java package base ame 10. Eter the Java package base ame i package format ad press Eter. Package format is dot-separated ad begis with your URL extesio (.com,.org,.edu, ad so o), followed by the compay ame, the by additioal adapter idetifiers; for example, com.your_co.adapter.eis. The system respods: The followig iformatio will be used to geerate your ew adapter developmet eviromet: EIS Type = SAP R/3 Descriptio = descriptio Major Versio = 1 Mior Versio = 0 Vedor = vedor_ame Adapter Logical Name = adapter_logical_ame Java Package Base = com.java.package.base Are you satisfied with these values? (eter yes or o or q to quit); 4-4 BEA WebLogic Applicatio Itegratio Developmet Guide

41 Usig GeerateAdapterTemplate default= yes : 11. To cofirm the iformatio, press Eter. The system respods with the appropriate build iformatio. Note: If you eter o, you will be routed back to Step 4. If you eter q (quit), the applicatio will termiate. Step 2. Rebuild the Tree After completig the cloe process, chage to the ew directory ad use At, the ADK s build tool to rebuild the etire tree. For more iformatio o At, see At-Based Build Process i Tools. To rebuild the tree by usig At, do the followig: 1. Edit atev.cmd (Widows) or atev.sh (UNIX) i <WLAI_HOME>\dev\project. 2. Set the followig variables to valid paths: l l l l l BEA_HOME - The locatio of your BEA_HOME directory. WLAI_HOME - The locatio of your Applicatio Itegratio istallatio. JAVA_HOME - The locatio of your Java Developmet Kit. WL_HOME - The locatio of your WebLogic 6.0 istallatio. ANT_HOME - The locatio of your At home, typically <WLAI_HOME>\dev\project. Notes: The istaller will perform this step for you; however, you should be aware that these settigs cotrol the At process. O UNIX, the At file i <WLAI_HOME>\dev\project\at eeds to have a execute permissio set. To add the execute permissio, type chmod u+x at. 3. Execute atev from the commad-lie to set the ecessary eviromet variables for your shell. BEA WebLogic Applicatio Itegratio Developmet Guide 4-5

42 4 Creatig a Custom Developmet Eviromet 4. Execute at release from the <WLAI_HOME>\dev\<CLONE>\project directory to build the adapter (<CLONE> is the ame of the ew adapter developmet root). Executig at release will geerate the Javadoc for the adapter. You ca view the Javadoc by goig to: <WLAI_HOME>/dev/<CLONE>/src/overview.html This file provides eviromet specific istructios for deployig your adapter i Applicatio Itegratio. Specifically, it provides cofig.xml etries ad the replacemets for the path already made. I additio, the file provides mappig iformatio. You ca copy the cotets of overview.html directly ito cofig.xml, which will facilitate adapter deploymet, as described i Step 3. Deploy the Adapter to Applicatio Itegratio. Step 3. Deploy the Adapter to Applicatio Itegratio After rebuildig the ew adapter, deploy it ito Applicatio Itegratio. To do so, follow these three basic steps: Note: For more detailed iformatio o adapter deploymet, see Deployig the Adapter i either Developig a Service Adapter or Developig a Evet Adapter. 1. First, declare the adapter's.rar,.war, ad evet router.war files i your domai's cofig.xml file. You will eed to have the XML elemets described i Listig 4-1 i your cofig.xml file: Note: You ca simply copy the code show i Listig 4-1 from <WLAI_HOME>/dev/<CLONE>/src/overview.html ito cofig.xml. Listig 4-1 Sample Code for Deployig a Adapter Created with GeerateAdapterTemplate <!-- This deploys the WebLogic Specific.rar file --> <Applicatio Deployed="true" Name="BEA_WLS_SAMPLE_ADK_WLS.rar.rar" 4-6 BEA WebLogic Applicatio Itegratio Developmet Guide

43 Usig GeerateAdapterTemplate Path="d:\bea\wlai1.0\dev\sample\lib"> <ResourceAdapterCompoet Name="BEA_WLS_SAMPLE_ADK_WLS.rar" Targets="myserver" URI="BEA_WLS_SAMPLE_ADK_WLS.rar.rar"/> </Applicatio> <!-- This deploys the Web applicatio for desig time --> <Applicatio Deployed="true" Name="BEA_WLS_SAMPLE_ADK_Web" Path="d:\bea\wlai1.0\dev\sample\lib"> <WebAppCompoet Name="BEA_WLS_SAMPLE_ADK_Web" ServletReloadCheckSecs="1" Targets="myserver" URI="BEA_WLS_SAMPLE_ADK_Web"/> </Applicatio> <!-- This deploys the evet router Web applicatio --> <Applicatio Deployed="true" Name="BEA_WLS_SAMPLE_ADK_EvetRouter" Path="d:\bea\wlai1.0\dev\sample\lib"> <WebAppCompoet Name="BEA_WLS_SAMPLE_ADK_EvetRouter" Targets="myserver" URI="BEA_WLS_SAMPLE_ADK_EvetRouter.war"/> </Applicatio> BEA WebLogic Applicatio Itegratio Developmet Guide 4-7

44 4 Creatig a Custom Developmet Eviromet Note: Replace all occurreces of <WLAI_HOME>\dev\sample\lib with the correct path to the adapter s lib directory for your eviromet i all elemets show i Listig Provide the mappig of the adapter deploymet to the adapter s desig-time web applicatio. To do this, use this procedure: a. Make a etry ito <WLAI_DEPLOY_HOME>\wlai.properties to map the path to the desig-time web applicatio. <WLAI_DEPLOY_HOME> is the Applicatio Itegratio directory uder your domai. b. Add a property for each adapter you will deploy. The property will poit at the desig-time iterface web applicatio. This should iclude oly the path portio of the URL for the web applicatio (ot the full server ame ad port, etc.). c. Optioally, supply oly the web applicatio cotext (usually the ame of the.war file you place i the applicatio s directory) ad omit the /display.jsp or equivalet. The property should be of the form: wlai.adapter.<vedor ame from.rar>.<display ame from.rar>.webapppath=<web app path> <Vedor ame from.rar> ad <Display ame from.rar> caot cotai the characters. (dot), = (equals), or a blak space. Replace these characters by usig the followig mappigs: - Replace all istaces of. with + (plus) - Replace all blak spaces with _ (uderscore) - Replace all istaces of = with - (dash) For this adapter, the etry should be: wlai.adapter. BEA.BEA_WLS_SAMPLE_ADK.webAppPath= BEA_WLS_SAMPLE_ADK_Web 3. Next, add the.jar file(s) for the ew adapter to the WebLogic server CLASSPATH. The reaso for this is due to a limitatio i WebLogic 6.0 regardig eterprise applicatios. Ideally, usig a.ear file would be a viable solutio; however, the eterprise applicatio facility i WebLogic Server 6.0 SP2 does ot fully support the sharig of a.jar betwee a.war ad.rar. The result of puttig these files i a.ear file ad takig the.jar out of the CLASSPATH is 4-8 BEA WebLogic Applicatio Itegratio Developmet Guide

45 Usig GeerateAdapterTemplate that you ca t test evets or services at desigtime. So, i order to be able to test, you must put the.jar i the CLASSPATH, which reders the creatio of a.ear useless. For this versio of the ADK, you should add the.jar file for your adapter to the ADAPTER_CLASSPATH i wlaiev.cmd/sh, as show i Listig 4-2: Listig 4-2 Sample Code Showig How to Add the.jar File to a Classpath set ADAPTER_CLASSPATH=%WLAI_LIB_HOME%\logtoolkit.jar; %WLAI_LIB_HOME%\adk.jar;%WLAI_HOME%\dev\sample\lib\BEA_WLS_SAMP LE_ADK.jar;%WLAI_HOME%\dev\dbms\lib\BEA_WLS_DBMS_ADK.jar;%WLAI_ HOME%\dev\ \lib\BEA_WLS_ _ADK.jar 4. Go to the Applicatio View Maagemet Cosole at: ad attempt to add a ew applicatio view for your adapter. This will verify that the adapter has bee deployed correctly. For istructios o addig a applicatio view, see Defiig Applicatio Views i the BEA WebLogic Applicatio Itegratio User Guide. 5. Restart WebLogic 6.0. BEA WebLogic Applicatio Itegratio Developmet Guide 4-9

46 4 Creatig a Custom Developmet Eviromet 4-10 BEA WebLogic Applicatio Itegratio Developmet Guide

47 CHAPTER 5 The ADK Loggig Toolkit Loggig is a essetial feature of a adapter compoet. Most adapters are used to itegrate differet applicatios ad do ot iteract with ed users while processig data. Ulike the behavior of a frot-ed compoet, whe a adapter ecouters a error or warig coditio, it caot stop processig ad wait for a ed-user to respod. With the ADK, loggig adapter activity is accomplished by implemetig a loggig framework. This framework gives you the ability to log iteratioalized ad localized messages to multiple output destiatios. It provides a rage of cofiguratio parameters you ca use to tailor message category, priority, format, ad destiatio. This sectio cotais iformatio o the followig subjects: Loggig Toolkit Loggig Cofiguratio File Loggig Cocepts l Message Categories l Message Priority l Message Appeders l Message Layout l Puttig the Compoets Together How to Set Up Loggig Loggig Framework Classes BEA WebLogic Applicatio Itegratio Developmet Guide 5-1

48 5 The ADK Loggig Toolkit l l l com.bea.loggig.ilogger com.bea.loggig.logcotext com.bea.loggig.logmaager Iteratioalizatio ad Localizatio of Log Messages Savig Cotextual Iformatio i a Multi-Threaded Compoet Loggig Toolkit The ADK s loggig toolkit allows you to log iteratioalized messages to multiple output destiatios. The loggig toolkit leverages the work of the ope source project Apache Log4j. This product icludes software developed by the Apache Software Foudatio ( The loggig toolkit is a cotaier that wraps the ecessary Log4j classes to provide added fuctioality for J2EE-compliat adapters. It is provided i the logtoolkit.jar file uder: <WLAI_ROOT>/lib. This.jar file depeds o DOM, XERCES, ad Log4j The XERCES depedecy is satisfied by weblogic.jar ad xmlx.jar provided i the WebLogic 6.0 distributio (<WL_HOME>/lib). The Applicatio Itegratio distributio icludes the required versio of Log4j i (<WLAI_HOME>/resources/Log4j). The Log4j package is distributed uder the Apache Public Licese, a full-fledged ope source licese certified by the ope source iitiative. The latest Log4j versio, icludig full-source code, class files ad documetatio ca be foud at the Apache Log4j Web site. 5-2 BEA WebLogic Applicatio Itegratio Developmet Guide

49 Loggig Cofiguratio File Loggig Cofiguratio File Throughout this sectio, you will see refereces to ad code sippets from the loggig cofiguratio file. This file is a.xml file that is idetified by the adapter logical ame; for example, BEA_WLS_DBMS_ADK.xml. It cotais the base iformatio for the four loggig cocepts discussed i Loggig Cocepts ad ca be modified for your specific adapter. The ADK provides a basic loggig cofiguratio file, BEA_WLS_SAMPLE_ADK.xml, i <WLAI_HOME>/dev/sample/src. To modify this file for your adapter, ru GeerateAdapterTemplate. This utility will customize the sample versio of the loggig cofiguratio file with iformatio pertiet to your ew adapter ad place the customized versio i the ew adapter s developmet eviromet. For more iformatio o GeerateAdapterTemplate, see Creatig a Custom Developmet Eviromet. Loggig Cocepts Prior to usig the loggig toolkit provided with the ADK, you should uderstad a few key cocepts of the loggig framework. Loggig has four mai compoets: Message Categories Message Priority Message Appeders Message Layout These compoets work together to eable you to log messages accordig to message type ad priority, ad to cotrol at rutime how these messages are formatted ad where they are reported. BEA WebLogic Applicatio Itegratio Developmet Guide 5-3

50 5 The ADK Loggig Toolkit Message Categories Categories idetify log messages accordig to criteria you defied ad are a cetral cocept of the loggig framework. I the ADK, a category is idetified by its ame, such as BEA_WLS_SAMPLE_ADK.DesigTime. Categories are hierarchically defied. That is, ay category ca iherit properties from paret categories. The hierarchy is defied thusly: A category is a acestor of aother category if its ame followed by a dot is a prefix of the descedat category ame. A category is a paret of a child category if there are o acestors betwee itself ad the descedat category. For example, BEA_WLS_SAMPLE_ADK.DesigTime is a descedat of BEA_WLS_SAMPLE_ADK, which is a descedat of the root category. For example: ROOT CATEGORY ->BEA_WLS_SAMPLE_ADK ->BEA_WLA_SAMPLE.ADK.DesigTime The root category resides at the top of the category hierarchy; it always exists ad it caot be retrieved by ame. Whe you create categories, you should ame them accordig to compoets i their adapter. For example, if a adapter has a desig-time user iterface compoet, the adapter could have a category, BEA_WLS_SAMPLE_ADK.DesigTime. Message Priority Every message has a priority that idicates its importace. Message priority is determied by the method o the ILogger iterface used to log the message. I other words, callig the debug method o a ILogger istace geerates a debug message. 5-4 BEA WebLogic Applicatio Itegratio Developmet Guide

51 Loggig Cocepts The loggig toolkit supports five possible priorities for a give message, as described i Table 5-1: Table 5-1 Loggig Toolkit Priorities Priority AUDIT ERROR WARN INFO DEBUG Descriptio Idicates a extremely importat log message that relates to the busiess processig performed by a adapter. Messages with this priority will always be writte to the log output. Idicates a error i the adapter. Error messages are iteratioalized/localized for the user. Idicates a situatio that is ot a error, but could cause problems i the adapter. A warig message that is iteratioalized/localized for the user. Idicates a iformatioal message that is iteratioalized/localized for the user. Idicates a debug message, which are used to determie how the iterals of a compoet are workig ad are typically ot iteratioalized. The BEA_WLS_SAMPLE_ADK category has priority DEBUG because of the followig child elemet: <priority value= DEBUG class= com.bea.loggig.logpriority /> The class for the priority must be com.bea.loggig.logpriority. Assigig a Priority to a Category You ca assig a priority to a Category. If a give category is ot assiged a priority, it iherits oe from its closest acestor with a assiged priority; that is, the iherited priority for a give category is equal to the first o-ull priority i the category hierarchy, startig at the give category ad proceedig upwards i the hierarchy towards the root category. A log message will be output to the log destiatio if its priority is higher tha or equal to the priority of its category. Otherwise, the message will ot be writte to the log destiatios. A category without a assiged priority will iherit oe from the hierarchy. To esure that all categories ca evetually iherit a priority, the root BEA WebLogic Applicatio Itegratio Developmet Guide 5-5

52 5 The ADK Loggig Toolkit category always has a assiged priority. A log statemet of priority p i a category with iherited priority q, is eabled if p >= q. This rule assumes that priorities are ordered as follows: DEBUG < INFO < WARN < ERROR < AUDIT. Message Appeders The loggig framework allows a adapter to log to multiple destiatios by usig a iterface called a appeder. Log4j provides appeders for: The cosole Files Remote socket servers NT Evet Loggers Remote UNIX Syslog daemos I additio, the ADK log toolkit provides a WebLogic appeder that you ca specify to output the log message to your WebLogic Server log. A category may refer to multiple appeders. Each eabled loggig request for a give category will be forwarded to all the appeders i that category, as well as the appeders higher i the hierarchy. I other words, appeders are iherited additively from the category hierarchy. For example, if a cosole appeder is added to the root category, the all eabled loggig requests will at least prit o the cosole. If i additio a file appeder is added to category C, the eabled loggig requests for C ad C s childre will prit to a file ad o the cosole. It is possible to override this default behavior so that appeder accumulatio is o loger additive by settig the additivity flag to false. Note: If you ve also added the cosole appeder to directly to C, you will get two messages oe from C ad oe from the root o the cosole. This is because the root category always logs to the cosole. Listig 5-1 shows a appeder for the WebLogic log: 5-6 BEA WebLogic Applicatio Itegratio Developmet Guide

53 Loggig Cocepts Listig 5-1 Sample Code Showig a Appeder for the WebLogic Log <!-- --> A WeblogicAppeder seds log output to the WebLogic log. It ca oly be used if you are ruig iside WebLogic. <appeder ame="weblogicappeder" class="com.bea.loggig.weblogicappeder"> <!-- Use a basic LOG4J patter layout --> <layout class="org.apache.log4j.patterlayout"> <param ame="coversiopatter" value="%-5p %d{date} %c{4} %x - %m%"/> </layout> </appeder> Message Layout By usig Log4j, you ca also customize the format of a log message. This is accomplished by associatig a layout with a appeder. The layout is resposible for formattig a log message while a appeder directs the formatted message to its destiatio. The log toolkit typically uses the PatterLayout to format its log messages. The PatterLayout, part of the stadard Log4j distributio, lets you specify the output format accordig to coversio patters similar to the C laguage pritf fuctio. For example, the PatterLayout with the coversio patter %-5p%d{DATE} %c{4} %x - %m% will output a message like: AUDIT 21 May :00:57,109 BEA_WLS_SAMPLE_ADK - admi opeed coectio to EIS I the patter, %-5p displays the priority of the message; i the example show above, this is AUDIT BEA WebLogic Applicatio Itegratio Developmet Guide 5-7

54 5 The ADK Loggig Toolkit %d{date} displays the date of the message; i the example show above, this is 21 May :00:57,109 %c{4} displays the category for the log message; i the example show above, this is BEA_WLS_SAMPLE_ADK The text after the - is the message of the statemet. Puttig the Compoets Together Listig 5-2 declares a ew category for the sample adapter, sets its priority, ad declares a appeder to output log messages to a file: Listig 5-2 Sample XML Code for Declarig a New Log Category IMPORTANT!!! ROOT Category for the adapter; makig this uique prevets other adapters from loggig to your category --> <category ame= BEA_WLS_SAMPLE_ADK class= com.bea.loggig. LogCategory > <!- <!- --> Default Priority Level; may be chaged at rutime DEBUG meas log all messages from the adapter s code base INFO meas log iformatioals, warigs, errors, ad audits WARN meas log warigs, errors, ad audits ERROR meas log errors ad audits AUDIT meas log audits oly <priority value= DEBUG class= com.bea.loggig.logpriority /> <!-- Associate oe or more output destiatios with this 5-8 BEA WebLogic Applicatio Itegratio Developmet Guide

55 How to Set Up Loggig category; i this case, the appeder is set i a <appeder> elemet called FileAppeder --> <appeder-ref ref= FileAppeder /> </category> Note: You must specify the class as com.bea.loggig.logcategory. How to Set Up Loggig Note: The followig procedure assumes that you ve cloed a developmet eviromet by ruig the GeerateAdapterTemplate utility. For more iformatio o this utility, see Creatig a Custom Developmet Eviromet. Settig up the loggig framework for your adapter is a four-step process. 1. Idetify all of the basic compoets used i the adapter. For example, if your adapter has a EvetGeerator, you might wat to have a EvetGeerator compoet; if it supports a desig-time GUI, you will eed a desig-time compoet. 2. Ope the base log cofiguratio file from the cloed adapter. This file is foud i <WLAI_HOME>/dev/<CLONE>/src/ ad will have the extesio.xml. For example, the DBMS adapter cofiguratio file is i <WLAI_HOME>/dev/dbms/src. It s called BEA_WLS_DBMS_ADK.xml. 3. I the base log cofiguratio file, add the category elemets for all adapter compoets you idetified. For each category elemet, establish a priority. Listig 5-3 shows how a category for a EvetGeerator with a priority of DEBUG is added. BEA WebLogic Applicatio Itegratio Developmet Guide 5-9

56 5 The ADK Loggig Toolkit Listig 5-3 Sample Code Addig a EvetGeerator Log Category with a Priority of DEBUG <category ame= BEA_WLS_DBMS_ADK.EvetGeerator class= com.bea.loggig.logcategory > <priority value= DEBUG class= com.bea.loggig.logpriority /> </category> 4. Determie the appeder ad add it to the cofiguratio file. If ecessary, add message formattig iformatio. Listig 5-4 shows how a basic file appeder is added withi the <appeder> elemet. Istructios withi the <layout> elemet idetify the message format patter. Listig 5-4 Sample Code Addig a File Appeder ad Layout Patter <!-- A basic file appeder --> <appeder ame= FileAppeder class= org.apache.log4j.fileappeder > <!-- Sed output to a file --> <param ame= File value= BEA_WLS_DBMS_ADK.log /> <!-- Trucate existig --> <param ame="apped" value="true"/> <!-- Use a basic LOG4J patter layout --> <layout class= org.apache.log4j.patterlayout > <param ame= CoversioPatter value= %-5p %d{date} %c{4} %x - %m% /> </layout> </appeder> At this poit, you should review these other cofiguratio files to cofirm their settigs BEA WebLogic Applicatio Itegratio Developmet Guide

57 Loggig Framework Classes <CLONE>/src/evetrouter/web-if/web.xml; The AbstractEvetGeerator uses the loggig iformatio etered i the base cofiguratio file to cofigure the log framework at iitializatio time. <CLONE>/src/rar/META-INF/ra.xml ad weblogic-ra.xml; The AbstractMaagedCoectioFactory uses the loggig iformatio etered i the base cofiguratio file to cofigure the log framework at iitializatio time. <CLONE>/src/war/web-if/web.xml; The RequestHadler (the paret of AbstractDesigTimeRequestHadler) uses the loggig iformatio etered i the base cofiguratio file to cofigure the log framework at iitializatio time. Loggig Framework Classes I additio to uderstadig the basic cocepts of the loggig framework, you will also eed to uderstad three mai classes provided i the log toolkit: com.bea.loggig.ilogger com.bea.loggig.logcotext com.bea.loggig.logcotext com.bea.loggig.ilogger This is the mai iterface to the loggig framework. It provides umerous coveiece methods for loggig messages. I How to Set Up Loggig, you saw how you ca cofigure loggig i the base log cofiguratio file. You ca also cofigure loggig programmatically by implemetig the loggig methods listed below: logger.setpriority( DEBUG ); chages the miimum priority of messages prited from the curret ILogger. logger.addrutimedestiatio (writer); adds a additioal appeder used whe the cotaier passes its PritWriter to the adapter. BEA WebLogic Applicatio Itegratio Developmet Guide 5-11

58 5 The ADK Loggig Toolkit logger.war( Some message, true); logs a message with the priority level WARN, without usig the ResourceBudle. The boolea idicates that the strig is a message, ot a key. logger.war( somekey ); logs a message with the priority level WARN, by lookig it up with somekey i the ResourceBudle. logger.ifo( somekey, aobjarray); logs a message with the priority level INFO by lookig up a template with somekey i the ResourceBudle ad fillig i the blaks with the elemets of aobjarray. logger.error(exceptio); logs a message with the priority level ERROR, by passig a exceptio (Throwable) to this method. It will call getmessage(), ad iclude a stack trace. All loggig methods that take a Throwable as a argumet log a stack trace. com.bea.loggig.logcotext This class ecapsulates iformatio eeded to idetify a ILogger istace i the loggig framework. Curretly, a LogCotext ecapsulates a log category ame ad a locale, such as e_us. com.bea.loggig.logmaager This class provides a method to allow you to cofigure the loggig framework ad provides access to ILogger istaces. To properly cofigure the log toolkit for your adapter, the ADK implemets the LogMaager s cofigure() method with the argumets show i Listig 5-5: Listig 5-5 Sample Code for Cofigurig the Log Toolkit public static LogCotext cofigure(strig strlogcofigfile, Strig strrootlogcotext, 5-12 BEA WebLogic Applicatio Itegratio Developmet Guide

59 Loggig Framework Classes Strig strmessagebudlebase, Locale locale, ClassLoader classloader) Table 5-2 describes the argumets passed by cofigure(): Table 5-2 Argumet strlogcofigfile strrootlogcotext strmessagebudlebase locale classloader Descriptio This file cotais the log cofiguratio iformatio for your adapter. The file should exist o the classpath. We recommed that you iclude this file ito your adapter s mai.jar file so that it ca be icluded i the.war ad.rar files for your adapter. This file should coform to the Log4j.dtd. The Log4j.dtd file is provided i the Log4j.jar i the Applicatio Itegratio distributio. This is the ame of the logical root of the category hierarchy for your adapter. For the sample adapter, this value is BEA_WLS_SAMPLE_ADK. This is the base ame for the message budles for your adapter. It is required by the ADK that you use message budles. For the sample adapter, this value is BEA_WLS_SAMPLE_ADK. This idetifies the locale (laguage ad atio). The log toolkit orgaizes categories ito differet hierarchies based o locale. For example, if your adapter supports two locales e_us ad fr_ca, the log toolkit will maitai two category hierarchies, oe for e_us ad oe for fr_ca. This is the ClassLoader the LogMaager should use to load resources, such as ResourceBudles ad log cofiguratio files. Oce the cofiguratio is complete, you ca retrieve ILogger istaces for your adapter by supplyig a LogCotext object: BEA WebLogic Applicatio Itegratio Developmet Guide 5-13

60 5 The ADK Loggig Toolkit Listig 5-6 Sample Code for Supplyig a LogCotext Object LogCotext logcotext = ew LogCotext("BEA_WLS_SAMPLE_ADK", java.util.locale.us); ILogger logger = LogMaager.getLogger(logCotext); logger.debug("i m loggig ow!"); The ADK hides most of the log cofiguratio ad setup for you. The com.bea.adapter.spi.abstractmaagedcoectiofactory class cofigures the log toolkit for service adapters ad the AbstractEvetGeerator cofigures the log toolkit for evet adapters. I additio, all of the CCI ad SPI base classes provided i the ADK provide access to a ILogger ad its associated LogCotext. For other layers i the adapter to access the correct ILogger object, there are two approaches you ca take. Note: Other layers refers to layers i a adapter that support the CCI/SPI layer, such as a socket layer for establishig commuicatio to the EIS. Approach 1: The CCI/SPI layers ca pass the LogCotext object ito the lower layers. This works but also adds overhead. Approach 2: The CCI layer ca establish the LogCotext for the curret ruig thread at the earliest possible place i the code. The ADK's com.bea.adapter.cci.coectiofactoryimpl class sets the LogCotext for the curret ruig thread i the getcoectio() methods. The getcoectio() methods are the first poit of cotact a cliet program has with your adapter. Cosequetly, lower layers i a adapter ca safely access the LogCotext for the curret ruig thread usig the followig code: public static LogCotext getlogcotext(thread t) throws IllegalStateExceptio, IllegalArgumetExceptio Additioally, we supply a coveiece method o the LogMaager: public static ILogger getlogger() throws IllegalStateExceptio This method provides a ILogger for the curret ruig thread. There is oe caveat to usig this approach, lower layers should ot store the LogCotext or ILogger as members. Rather, they should dyamically retrieve them from the 5-14 BEA WebLogic Applicatio Itegratio Developmet Guide

61 Iteratioalizatio ad Localizatio of Log Messages LogMaager. A IllegalStateExceptio is throw if this method is called before a LogCotext is set for the curret ruig thread. Iteratioalizatio ad Localizatio of Log Messages Iteratioalizatio ad Localizatio are cetral cocepts to the ADK loggig framework. All loggig coveiece methods o the ILogger iterface, except the debug methods, allow iteratioalizatio. The implemetatio follows the Java Iteratioalizatio stadards, usig ResourceBudle objects to store locale-specific messages or templates. Su provides a good olie tutorial o usig the I18N ( iteratioalizatio ) ad L10N ( localizatio ) stadards of the Java laguage. Savig Cotextual Iformatio i a Multi-Threaded Compoet Most real-world systems have to deal with multiple cliets simultaeously. I a typical multi-threaded implemetatio of such a system, differet threads will hadle differet cliets. Loggig is especially well suited to trace ad debug complex distributed applicatios. A commo approach to differetiate the loggig output of oe cliet from aother is to istatiate a ew separate category for each cliet. This promotes the proliferatio of categories ad icreases the maagemet overhead of loggig. A lighter techique is to uiquely stamp each log request iitiated from the same cliet iteractio. Neil Harriso described this method i Patters for Loggig Diagostic Messages, i Patter Laguages of Program Desig 3, edited by R. Marti, D. Riehle, ad F. Buschma (Addiso-Wesley, 1997). BEA WebLogic Applicatio Itegratio Developmet Guide 5-15

62 5 The ADK Loggig Toolkit To uiquely stamp each request, the user pushes cotextual iformatio ito the Nested Diagostic Cotext (NDC). The log toolkit provides a separate iterface for accessig NDC methods. The iterface is retrieved from the ILogger by usig the method getndciterface(). NDC pritig is tured o i the XML cofiguratio file (with the symbol %x). Every time a log request is made, the appropriate loggig framework compoet icludes the etire NDC stack for the curret thread i the log output. The user will ot eed to itervee i this process. I fact, the user is resposible oly for placig the correct iformatio i the NDC by usig the push ad pop methods at a few well-defied poits i the code. Listig 5-7 Sample Code public void someadaptermethod(strig acliet) { ILogger logger = getlogger(); INestedDiagosticCotext dc = logger.getndciterface(); // I m keepig track of this cliet ame for all log messages dc.push("user ame=" + acliet); // method body dc.pop(); } A good place to use the NDC is i your adapter s CCI Iteractio object BEA WebLogic Applicatio Itegratio Developmet Guide

63 CHAPTER 6 Developig a Service Adapter Service adapters receive a XML request documet from a cliet ad ivoke the associated fuctio i the uderlyig EIS. They are cosumers of messages ad may or may ot provide a respose. Service adapters perform the followig four fuctios: They receive service requests from a exteral cliet. They trasform the XML request documet ito the EIS specific format. The request documet coforms to the request XML schema for the service. The request XML schema is based o metadata i the EIS. They ivoke the uderlyig fuctio i the EIS ad wait for its respose. They trasform the respose from the EIS specific data format to a XML documet that coforms to the respose XML schema for the service. The respose XML schema is based o metadata i the EIS. This sectio cotais iformatio o the followig subjects: Service Adapters i the Rutime Eviromet The Flow of Evets Step 1: Developmet Cosideratios Step 2: Cofigurig the Developmet Eviromet l Step 2a: Set Up the File Structure l Step 2b: Assig the Adapter Logical Name l Step 2c: Settig Up the Build Process BEA WebLogic Applicatio Itegratio Developmet Guide 6-1

64 6 Developig a Service Adapter Step 2d: Create the Message Budle l How to Use this Sectio l Basic SPI Implemetatio l MaagedCoectioFactory l MaagedCoectio l MaagedCoectioMetaData l CoectioEvetListeer l CoectioMaager l CoectioRequestIfo l LocalTrasactio Step 4: Implemetig the CCI l How to Use this Sectio l Basic CCI Implemetatio l Coectio l Iteractio l Usig XCCI to Implemet the CCI l CoectioMetaData l CoectioSpec l IteractioSpec l LocalTrasactio l Record l ResourceAdapterMetaData l Step 5: Deployig the Adapter Step 5: Deployig the Adapter l Step 5a: Update the ra.xml File l Step 5b: Create the weblogic-ra.xml File l Step 5c: Create ad Deploy the.rar File 6-2 BEA WebLogic Applicatio Itegratio Developmet Guide

65 Service Adapters i the Rutime Eviromet Step 6: Testig the Adapter l Usig the Test Haress l Test Case Extesios Provided by the ADK Service Adapters i the Rutime Eviromet Figure 6-1 ad Figure 6-2 show the processes executed whe a service adapter is used i the rutime eviromet. Figure 6-1shows a asychroous service adapter while Figure 6-2 shows a sychroous adapter. Figure 6-1 A Asychroous Service Adapter i the Rutime Eviromet BEA WebLogic Applicatio Itegratio Developmet Guide 6-3

66 6 Developig a Service Adapter Figure 6-2 A Sychroous Service Adapter i the Rutime Eviromet 6-4 BEA WebLogic Applicatio Itegratio Developmet Guide

67 Service Adapters i the Rutime Eviromet BEA WebLogic Applicatio Itegratio Developmet Guide 6-5

68 6 Developig a Service Adapter The Flow of Evets Figure 6-3 outlies the steps required to develop a Service Adapter. Figure 6-3 Service Adapter Flow of Evets 6-6 BEA WebLogic Applicatio Itegratio Developmet Guide

69 Step 1: Developmet Cosideratios Step 1: Developmet Cosideratios You will eed to cosider the items listed below before commecig with service adapter developmet. The Adapter Setup Worksheet will provide much of this iformatio. See Adapter Setup Worksheet. Determie the EIS ad the appropriate service. You eed to idetify the EIS ad the type of service required for this adapter; that is, based upo your kowledge of the EIS, you must idetify the iterface to the back-ed fuctioality. Determie the expesive coectio object. You eed to determie the expesive coectio object required to ivoke a fuctio withi the EIS. The expesive coectio object is a resource required to commuicate with the EIS ad requires the allocatio of system resources; for example, a socket coectio or DBMS coectio. A valuable asset of J2EE Coector Architecture is that the applicatio server provides poolig of these objects. Therefore, you must determie this object for your adapter, as it will eed to be pooled by the applicatio server. Determie the security eeds. You eed to cosider ad uderstad how to pass coectio autheticatio across the coectio request path. To do this, your adapter will eed to implemet a coectiorequestifo class. The ADK provides the class CoectioRequestIfoMap to map authorizatio iformatio, such as userame ad password, to the coectio to facilitate CoectioRequestIfo implemetatio. The ADK coforms to the J2EE Coector Architecture Specificatio. For more iformatio o coectio architecture security, please refer to Security i that documet. Go to to dowload the specificatio. The J2EE Coector Architecture Specificatio will dowload as a.pdf file. Determie trasactio support. You eed to idetify which type of trasactio demarcatio support to implemet with the adapter: BEA WebLogic Applicatio Itegratio Developmet Guide 6-7

70 6 Developig a Service Adapter l Local trasactio demarcatio l XA-compliat trasactio demarcatio Note: For more iformatio o trasactio demarcatio support, please see Trasactio Demarcatio or: trasactio_maagemet/platform/idex.html Step 2: Cofigurig the Developmet Eviromet This step describes the processes you must complete to prepare your computer for adapter developmet. Step 2a: Set Up the File Structure Table 6-1 ADK File Structure Istallig the Applicatio Itegratio creates the file structure ecessary ot oly to ru a adapter, but also to use the ADK. The ADK files appear uder <WLAI_HOME>\dev\, where <WLAI_HOME> is the directory where you istalled the Applicatio Itegratio distributio. You eed to verify that, upo istallatio, the ecessary directories ad files appear i your <WLAI_HOME> directory. The file structure that follows uder <WLAI_HOME>/ is described i Table 6-1: File Path/Fileame dev dev/adk/src/war Descriptio This directory cotais the ADK. All files uder this directory should be icluded i the.war file for a adapter. This directory cotais.jsp files,.html files, images, etc. 6-8 BEA WebLogic Applicatio Itegratio Developmet Guide

71 Step 2: Cofigurig the Developmet Eviromet Table 6-1 ADK File Structure (Cotiued) File Path/Fileame dev/bi dev/dbms dev/ dev/doc dev/doc/api dev/project dev/sample dev/sample/docs dev/sample/docs/api dev/sample/docs/api_iteral dev/sample/lib dev/sample/project Descriptio This directory cotais a file used by the build process to timestamp.jar files. This directory cotais a sample J2EE-compliat adapter built with the ADK. This directory cotais a sample J2EE-compliat adapter built with the ADK. This directory should cotai the user guide, release otes, ad istallatio guide for a adapter. This directory cotais Javadoc for a adapter, the ADK, ad related classes. This directory cotais the primary make file (Makefile) for the ADK make process ad its related MakeOptios files. You should cosult MakeOptios.mak for istructios o usig the make process. This directory cotais a sample adapter that you ca use to start developig their ow adapter. This directory should cotai the user guide, release otes, ad istallatio guide for a the sample adapter. This directory cotais Javadoc for the sample adapter, the ADK, ad related classes. A directory for iteral API documetatio. This directory cotais adapter related.jar,.rar, ad.war files. This directory cotais the Apache Jakarta At build file build.xml. This file cotais build iformatio for compilig the source code, geeratig the.jar,.rar, ad.war files, ad geeratig Javadoc iformatio. See Step 2c: Settig Up the Build Process for details o how to build the adapter. BEA WebLogic Applicatio Itegratio Developmet Guide 6-9

72 6 Developig a Service Adapter Table 6-1 ADK File Structure (Cotiued) File Path/Fileame dev/sample/src dev/sample/src/bea_wls_sample_ ADK.properties dev/sample/src/bea_wls_ SAMPLE_ADK.xml dev/sample/src/ evetrouter/web-inf/ web.xml dev/sample/src/rar/meta- INF/ra.xml dev/sample/src/rar/meta- INF/weblogic-ra.xml dev/sample/src/sample dev/sample/src/war dev/sample/src/war/web- INF/web.xml dev/sample/src/war/web-inf/ weblogic.xml Descriptio This directory cotais all the source code for a adapter. It is up to you to decide to provide source code with your adapter. This file cotais messages used by the adapter for iteratioalizatio ad localizatio. This file provides a basic cofiguratio file for the loggig framework. You should use this file to develop their ow adapter loggig cofiguratio file. This is the cofiguratio file for the evet router web applicatio. This file cotais cofiguratio iformatio about a J2EE-compliat adapter. You should use this file as a guide o which parameters eeded by the ADK s rutime framework. This file cotais cofiguratio iformatio about a J2EE-compliat adapter that is specific to the WebLogic 6.0 J2EE egie. You should use this file as a example for settig up the weblogic-ra.xml file for their adapter. It is required for WebLogic 6.0 This directory cotais the source code for the adapter. All files uder this directory should be icluded i the web applicatio archive (.war) file for a adapter. This directory cotais.jsp files,.html files, images, etc. For more iformatio o web applicatios for WebLogic 6.0, look here The web applicatio descriptor The weblogic.xml file cotais WebLogic-specific attributes for a Web Applicatio BEA WebLogic Applicatio Itegratio Developmet Guide

73 Step 2: Cofigurig the Developmet Eviromet Modifyig the Directory Structure Whe you cloe a developmet tree by usig GeerateAdapterTemplate, the file paths ad files uder dev/sample are automatically cloed ad updated to reflect the ew developmet eviromet. The chages are reflected i the file dev/<clone>/api/idex.html (where <CLONE> is the ame of the ew developmet directory). This file also cotais code that you ca copy ad paste ito the cofig.xml file ad the <DEPLOYMENT_HOME>/wlai.properties files for the ew adapter that will setup Applicatio Itegratio to host the adapter. Step 2b: Assig the Adapter Logical Name Next, you eed to assig the adapter s logical ame. By covetio, this ame is comprised of the vedor ame, the type of EIS coected to the adapter, ad the versio umber of the EIS ad is expressed as vedor_eis-type_eis versio. For example: BEA_WLS_SAMPLE_ADK Step 2c: Settig Up the Build Process The ADK employs a build process based upo At, a 100% pure Java-based build tool. For more iformatio o At, please see At-Based Build Process. For more iformatio o usig At, see The sample adapter shipped with the ADK (located i <WLAI_HOME>\dev\bi\ sample) cotais the file build.xml. This is the At build file for the sample adapter. It cotais the tasks eeded to build a J2EE-compliat adapter. Ruig the GeerateAdapterTemplate utility to cloe a developmet tree for your adapter creates a build.xml file specifically for that adapter. This will free you from havig to customize the sample build.xml ad will esure that the code is correct. For iformatio o usig the GeerateAdapterTemplate utility, see Creatig a Custom Developmet Eviromet. BEA WebLogic Applicatio Itegratio Developmet Guide 6-11

74 6 Developig a Service Adapter build.xml Compoets If you edit build.xml ad review its compoets, you will better uderstad how this file works. This sectio describes the promiet elemets of build.xml. Note: The followig examples are take from the sample adapter, ot a cloed versio thereof. 1. The first lie you ecouter: <project ame= BEA_WLS_SAMPLE_ADK default= all basedir=. > sets the ame attribute of the root project elemet. 2. Listig 6-1sets the archive file (.jar,.war, ad.rar) ames. Listig 6-1 Settig Archive File Names <property ame= JAR_FILE value= BEA_WLS_SAMPLE_ADK.jar /> <property ame= RAR_FILE value= BEA_WLS_SAMPLE_ADK.rar /> <property ame= WLS_RAR_FILE value= BEA_WLS_SAMPLE_ADK_ WLSRAR.rar /><property ame= WAR_FILE value= BEA_WLS_SAMPLE_ ADK_Web.war /> 3. Listig 6-2 shows a list of stadard properties for the ADK. You should t eed to alter them. Listig 6-2 Stadard ADK Properties <property ame= PROJECT_DIR value=. /> <property ame= ROOT value= ${PROJECT_DIR}/../.. /> <property ame= SRC_DIR value= ${PROJECT_DIR}/../src /> <property ame= LIB_DIR value= ${PROJECT_DIR}/../lib /> <property ame= DOC_DIR value= ${PROJECT_DIR}/../docs/api /> <property ame= RESOURCE_DIR value= ${ROOT}/../resources /> <property ame= XALAN_JAR value= ${RESOURCE_DIR}/xml/xala.jar /> 6-12 BEA WebLogic Applicatio Itegratio Developmet Guide

75 Step 2: Cofigurig the Developmet Eviromet <property ame= XERCES_JAR value= ${RESOURCE_DIR}/xml/xerces_dp1.jar /> <property ame= METAMATA_JAR value= ${RESOURCE_DIR}/metamata/metamata.jar /> <property ame= OROMATCHER_JAR value= ${RESOURCE_DIR}/OROMatcher-1.1.0a/oromatcher.jar /> <property ame= JAAS_JAR value= ${RESOURCE_DIR}/jaas1.0/jaas.jar /> <property ame= J2EECA_DIR value= ${RESOURCE_DIR}/j2eeca1.0 /> <property ame= J2EECA_JAR value= ${J2EECA_DIR}/coector.jar /> <property ame= JDK13_JAR value= ${RESOURCE_DIR}/jre1.3/rt.jar /> <property ame= J2EE_JAR value= ${RESOURCE_DIR}/j2eesdk1.2/j2ee.jar /> <property ame= LICENSE_JAR value= ${RESOURCE_DIR}/licese/licese.jar /> <property ame= LOG4J_JAR value= ${RESOURCE_DIR}/ log4j/log4j.jar /> <property ame= WLAI_LIB_DIR value= ${ROOT}/../lib /> <property ame= ADK value= ${WLAI_LIB_DIR}/adk.jar /> <property ame= ADK_WEB value= ${WLAI_LIB_DIR}/adk-web.jar /> <property ame= ADK_EVENTGENERATOR value= ${WLAI_LIB_DIR}/adk-evetgeerator.jar /> <property ame= BEA value= ${WLAI_LIB_DIR}/bea.jar /> <property ame= LOGTOOLKIT value= ${WLAI_LIB_DIR}/logtoolkit.jar /> <property ame= WEBTOOLKIT value= ${WLAI_LIB_DIR}/webtoolkit.jar /> <property ame= WLAI_CLIENT value= ${WLAI_LIB_DIR}/wlaicliet.jar /> <property ame= WLAI_CLIENT_EJB value= ${WLAI_LIB_DIR}/wlaicliet-ejb.jar /> <property ame= WLAI_COMMON value= ${WLAI_LIB_DIR}/wlai-commo.jar /> <property ame= WLAI_EJB value= ${WLAI_LIB_DIR}/wlai-ejb.jar /> BEA WebLogic Applicatio Itegratio Developmet Guide 6-13

76 6 Developig a Service Adapter <property ame= WLAI_EJB_CLIENT value= ${WLAI_LIB_DIR}/wlai-ejb-cliet.jar /> <property ame= WLAI_EVENTROUTER value= ${WLAI_LIB_DIR}/wlai-evetrouter.jar /> <property ame= WLAI_EVENTROUTER_CLIENT value= ${WLAI_LIB_DIR}/wlai-evetrouter-cliet.jar /> <property ame= WLAI_SERVLET_CLIENT value= ${WLAI_LIB_DIR}/wlai-servlet-cliet.jar /> <property ame= XMLTOOLKIT value= ${WLAI_LIB_DIR}/xmltoolkit.jar /> <property ame= XCCI value= ${WLAI_LIB_DIR}/xcci.jar /> To the list i Listig 6-2, you ca add ay additioal.jar files ad/or classes that are specific to your adapter. 4. Listig 6-3 sets up the classpath for compilig: Listig 6-3 Sample for Settig the Classpath <path id= CLASSPATH > <pathelemet locatio= ${SRC_DIR} /> <pathelemet path= ${ADK}:${ADK_WEB}:${BEA}:${LOGTOOLKIT}: ${WEBTOOLKIT}:${WLAI_COMMON}:${XCCI}:${XMLTOOLKIT} /> <pathelemet path= ${J2EECA_JAR}:${JAAS_JAR}:${J2EE_JAR} /> <pathelemet path= ${XERCES_JAR}:${XALAN_JAR} /> <pathelemet path= ${LOG4J_JAR} /> </path> To this iformatio, you ca add code that will produce the followig: l All the biaries ad archives for the adapter: <target ame= all depeds= rar,weblogic_rar,war /> l All the biaries ad archives for the adapter, as well as the Javadoc: 6-14 BEA WebLogic Applicatio Itegratio Developmet Guide

77 Step 2: Cofigurig the Developmet Eviromet <target ame= release depeds= all,apidoc /> l A versio_ifo file for iclusio ito archives, as show i Listig 6-4: Listig 6-4 Sample versio_ifo File <target ame= versio_ifo > <java classame= GeerateVersioIfo > <classpath> <pathelemet path= ${ROOT}/bi:${XERCES_JAR} /> </classpath> </java> </target> 5. Listig 6-5 produce the.jar file for the adapter. This fileset elemet specifies what is icluded ito the.jar file. Ru-time aspects of the adapter are icluded i the mai jar, while additioal classes, such as the desig-time GUI support classes, are icluded i the.war or other jar files. Listig 6-5 Sample Settig.jar File Cotets <target ame= jar depeds= packages,versio_ifo > <delete file= ${LIB_DIR}/${JAR_FILE} /> <jar jarfile= ${LIB_DIR}/${JAR_FILE} > 6. Listig 6-6 icludes the icludes list from the adapter's source directory. For the adapter described i these code samples, all the classes i the sample/cci ad sample/spi packages are icluded, as well as the loggig cofiguratio file ad message budles. Listig 6-6 Sample Code for Icludig the Icludes List <fileset dir= ${SRC_DIR} BEA WebLogic Applicatio Itegratio Developmet Guide 6-15

78 6 Developig a Service Adapter icludes= sample/cci/*.class,sample/ spi/*.class,*.xml,*. properties /> 7. Listig 6-7 icludes versio iformatio about the.jar file: Listig 6-7 Settig.jar File Versio Iformatio <fileset dir= ${PROJECT_DIR} icludes= versio_ifo.xml /> </jar> </target> 8. Listig 6-8 produces the J2EE adapter archive (.rar) file. The.rar file should cotai all classes ad JARs that the adapter eeds. This.rar ca be deployed ito ay J2EE-compliat applicatio server that the adapter depeds upo. This example icludes the followig targets: l l l l l l The adapter s mai.jar file. Versio iformatio for this.rar file. The deploymet descriptor for the adapter. The required ADK.jar files used by the adapter, the ADK. The Apache log4j.jar used by the loggig toolkit. The XML tools eeded by the adapter ad the ADK. Listig 6-8 Sample Code for Creatig the Coectio Architecture.rar File <target ame= rar depeds= jar > <delete file= ${LIB_DIR}/${RAR_FILE} /> <mkdir dir= ${LIB_DIR} /> <jar jarfile= ${LIB_DIR}/${RAR_FILE} > 6-16 BEA WebLogic Applicatio Itegratio Developmet Guide

79 Step 2: Cofigurig the Developmet Eviromet <!-- Iclude the adapter s mai jar file --> <fileset dir= ${LIB_DIR} icludes= ${JAR_FILE} /> <!-- Iclude versio iformatio for this RAR file --> <fileset dir= ${PROJECT_DIR} icludes= versio_ifo.xml /> <!-- Iclude the deploymet descriptor for the resource adapter --> <fileset dir= ${SRC_DIR}/rar icludes= META-INF/ra.xml /> <!-- Iclude the required WLIF jars used by the adapter, ADK etc. --> <fileset dir= ${WLAI_LIB_DIR} icludes= adk.jar,bea.jar,logtoolkit. jar,wlai-commo.jar,wlai-ejb-cliet.jar,xcci.jar,xmltoolkit.jar /> <!-- Iclude the Apache LOG4J jar used by the loggig toolkit --> <fileset dir= ${RESOURCE_DIR}/log4j icludes= log4j.jar /> </jar> </target> 9. Listig 6-9 produces the.rar file specific for the WebLogic 6.0 platform. This file cotais the weblogic-ra.xml file for the adapter. Otherwise, the fileset is the same for the stadard.rar. Listig 6-9 Creatig the WebLogic 6.0-Specific.rar File <target ame= weblogic_rar depeds= jar > <delete file= ${LIB_DIR}/${WLS_RAR_FILE} /> <jar jarfile= ${LIB_DIR}/${WLS_RAR_FILE} > <fileset dir= ${LIB_DIR} icludes= ${JAR_FILE} /> <fileset dir= ${PROJECT_DIR} icludes= versio_ifo. xml /> BEA WebLogic Applicatio Itegratio Developmet Guide 6-17

80 6 Developig a Service Adapter <fileset dir= ${SRC_DIR}/rar icludes= META-INF/ ra.xml,meta-inf/weblogic-ra.xml /> <fileset dir= ${WLAI_LIB_DIR} icludes= adk.jar,bea. jar,logtoolkit.jar,wlai-commo.jar,wlai-ejb-cliet.jar,xcci.jar, xmltoolkit.jar /> </jar> </target> <fileset dir= ${RESOURCE_DIR}/log4j icludes= log4j. jar /> <fileset dir= ${RESOURCE_DIR}/xml icludes= xerces_dp1. jar /> <fileset dir= ${RESOURCE_DIR}/xml icludes= xala.jar /> 10. Listig 6-10 produces the J2EE web applicatio archive (.war) file. It also icludes code that cleas up the existig eviromet: Listig 6-10 Sample Code Producig the.war File <target ame= war depeds= jar > <!-- Clea-up existig eviromet --> <delete file= ${LIB_DIR}/${WAR_FILE} /> <delete dir= ${SRC_DIR}/war/WEB-INF/lib /> <delete dir= ${SRC_DIR}/war/WEB-INF/classes /> <war warfile= ${LIB_DIR}/${WAR_FILE} webxml= ${SRC_DIR}/war/WEB-INF/web.xml > <fileset dir= ${PROJECT_DIR} icludes= versio_ifo.xml /> <!-- IMPORTANT! Exclude the WEB-INF/web.xml file from the WAR as it already gets icluded via the webxml attribute above --> <fileset dir= ${SRC_DIR}/war excludes= WEB-INF/web.xml /> <!-- IMPORTANT! Iclude the ADK desig time framework ito the 6-18 BEA WebLogic Applicatio Itegratio Developmet Guide

81 Step 2: Cofigurig the Developmet Eviromet adapter s desig time Web applicatio. --> <fileset dir= ${ROOT}/adk/src/war /> <!-- Iclude classes from the adapter that support the desig time UI --> <classes dir= ${SRC_DIR} icludes= sample/web/*.class /> <!-- Iclude all JARs required by the Web applicatio uder the WEB-INF/lib directory of the WAR file --> <lib dir= ${LIB_DIR} icludes= ${JAR_FILE} /> <lib dir= ${WLAI_LIB_DIR} icludes= adk.jar,adk-web.jar,bea.jar,logtoolkit.jar,webtoolkit.jar,wlai-commo.jar,wlai-ejb-cliet.jar,xcci.jar,xmltoolkit.ja r /> <lib dir= ${RESOURCE_DIR}/log4j icludes= log4j.jar /> <lib dir= ${RESOURCE_DIR}/OROMatcher-1.1.0a icludes= oromatcher.jar /> </war> 11. Listig 6-11 icludes all.jar files required by the web applicatio uder the WEB-INF/lib directory of the.war file. Listig 6-11 Sample Code to Iclude JARs Required by Web Applicatio <lib dir= ${LIB_DIR} icludes= ${JAR_FILE} /> <lib dir= ${WLAI_LIB_DIR} icludes= adk.jar,adk-web.jar,bea.jar,logtoolkit.jar,webtoolkit.jar,wlai-commo.jar,wlai-ejb-cliet.jar,xcci.jar,xmltoolkit.ja r /> <lib dir= ${RESOURCE_DIR}/log4j icludes= log4j.jar /> <lib dir= ${RESOURCE_DIR}/OROMatcher-1.1.0a icludes= oromatcher.jar /> <lib dir= ${RESOURCE_DIR}/xml icludes= xerces_dp1.jar /> BEA WebLogic Applicatio Itegratio Developmet Guide 6-19

82 6 Developig a Service Adapter <lib dir= ${RESOURCE_DIR}/xml icludes= xala.jar /> </war> </target> 12. Listig 6-12 compiles all the Java source files for this project: Listig 6-12 Sample Code for Compilig Java Source <target ame= packages > <javac srcdir= ${SRC_DIR} > <classpath refid= CLASSPATH /> </javac> </target> 13. Listig 6-13 geerates the Javadoc. Listig 6-13 Sample Code for Geeratig Javadocs <target ame= apidoc > <mkdir dir= ${DOC_DIR} /> <javadoc sourcepath= ${SRC_DIR} destdir= ${DOC_DIR} packageames= sample.* author= true versio= true use= true widowtitle= WebLogic Sample Adapter API Documetatio doctitle= WebLogic Sample Adapter API Documetatio header= WebLogic Sample Adapter 6-20 BEA WebLogic Applicatio Itegratio Developmet Guide

83 Step 2: Cofigurig the Developmet Eviromet bottom= Built usig the WebLogic Adapter Developmet Kit (ADK) > <classpath refid= CLASSPATH /> </javadoc> </target> 14. Listig 6-14 shows the targets that clea the files created by their couterparts: Listig 6-14 Sample Code for Icludig Clea-Up Code <target ame= clea_release depeds= clea_all,clea_apidoc /> <target ame= clea_all depeds= clea_rar,clea_weblogic_rar, clea_war /> <target ame= clea_rar depeds= clea_jar > <delete file= ${LIB_DIR}/${RAR_FILE} /> </target> <target ame= clea_weblogic_rar depeds= clea_jar > <delete file= ${LIB_DIR}/${WLS_RAR_FILE} /> </target> <target ame= clea_war depeds= clea_jar > <delete file= ${LIB_DIR}/${WAR_FILE} /> </target> <target ame= clea_jar depeds= clea_packages, clea_versio_ifo > <delete file= ${LIB_DIR}/${JAR_FILE} /> </target> <target ame= clea_versio_ifo > <delete file= ${PROJECT_DIR}/versio_ifo.xml /> </target> <target ame= clea_packages > <delete> BEA WebLogic Applicatio Itegratio Developmet Guide 6-21

84 6 Developig a Service Adapter <fileset dir= ${SRC_DIR} icludes= **/*.class /> </delete> </target> <target ame= clea_apidoc > <delete dir= ${DOC_DIR} /> </target> </project> Step 2d: Create the Message Budle Ay message destied for the ed-user should be placed i a message budle. The message budle is simply a.properties text file that cotais key=value pairs that allow you to iteratioalize messages. Whe a locale ad atioal laguage are specified at rutime, the cotets of the message is iterpreted, based upo the key=value pair, ad the message is preseted to the user i the correct laguage for his or her locale. For istructios o creatig a message budle, please refer to the JavaSoft tutorial o iteratioalizatio at: Step 3: Implemetig the SPI The Service Provider Iterface (SPI) cotais the objects that provide ad maage coectivity to the EIS, establish trasactio demarcatio, ad provide a framework for service ivocatio. All J2EE-compliat adapters must provide a implemetatio for these iterfaces i the javax.resource.spi package BEA WebLogic Applicatio Itegratio Developmet Guide

85 Step 3: Implemetig the SPI How to Use this Sectio Step 3: Implemetig the SPI cotais descriptios of the iterfaces you ca use to implemet the SPI. A miimum of three iterfaces are ecessary to complete the task (see Basic SPI Implemetatio ). Each of these are described i detail, followed by a discussio of how they were exteded i the sample adapter icluded with the ADK. Followig the three required iterfaces, the additioal iterfaces are described i detail, icludig iformatio regardig why you might use them ad what beefit they are to a adapter. Basic SPI Implemetatio To implemet the SPI for your adapter, you eed to exted at least these three iterfaces: MaagedCoectioFactory, which supports coectio poolig by providig methods for matchig ad creatig a MaagedCoectio istace. MaagedCoectio, which represets a physical coectio to the uderlyig EIS. MaagedCoectioMetaData, which provides iformatio about the uderlyig EIS istace associated with a MaagedCoectio istace. Ideally, you will implemet these iterfaces i the order specified above. I additio to these three iterfaces, you ca implemet ay of the other iterfaces described i this step, as your adapter eeds dictate. MaagedCoectioFactory javax.resource.spi.maagedcoectiofactory MaagedCoectioFactory istace is a factory of both MaagedCoectio ad EIS-specific coectio factory istaces. This iterface supports coectio poolig by providig methods for matchig ad creatig a MaagedCoectio istace. BEA WebLogic Applicatio Itegratio Developmet Guide 6-23

86 6 Developig a Service Adapter Trasactio Demarcatio A critical compoet of the MaagedCoectioFactory is trasactio demarcatio. You will eed to determie which statemets i your program are icluded i a sigle trasactio. J2EE defies a trasactio maagemet cotract betwee a applicatio server ad a adapter (ad its uderlyig resource maager). The trasactio maagemet cotract has two parts, depedig of the type of trasactio: XA-compliat Trasactio Local Trasactio XA-compliat Trasactio Local Trasactio A javax.trasactio.xa.xaresource-based cotract occurs betwee a trasactio maager ad a resource maager i a distributed trasactio processig (DTP) eviromet. A JDBC driver or a JMS provider implemets this iterface to support associatio betwee a global trasactio ad a database or message service coectio. The XAResource iterface ca be supported by ay trasactioal resource that is iteded for use by applicatio programs i a eviromet where trasactios are cotrolled by a exteral trasactio maager; for example a database maagemet system where a applicatio accesses data through multiple database coectios. Each database coectio is elisted with the trasactio maager as a trasactioal resource. The trasactio maager obtais a XAResource for each coectio participatig i a global trasactio. The trasactio maager uses the start() method to associate the global trasactio with the resource; it uses the ed() method to disassociate the trasactio from the resource. The resource maager associates the global trasactio to all work performed o its data betwee the start() ad ed() method ivocatio. At trasactio commit time, the resource maagers are iformed by the trasactio maager to prepare, commit, or rollback a trasactio accordig to the two-phase commit protocol. A local trasactio maagemet cotract occurs whe a adapter implemets the javax.resource.spi.localtrasactio iterface to provide support for local trasactios that are performed o the uderlyig resource maager. These cotracts 6-24 BEA WebLogic Applicatio Itegratio Developmet Guide

87 Step 3: Implemetig the SPI ADK Implemetatios eable a applicatio server to provide the ifrastructure ad rutime eviromet for trasactio maagemet. Applicatio compoets rely o this trasactio ifrastructure to support their compoet-level trasactio model. For more iformatio o trasactio demarcatio support, please refer to: platform/idex.html The ADK provides a abstract foudatio for a adapter, the AbstractMaagedCoectioFactory. This foudatio provides the followig feature: Provides basic support for iteratioalizatio/localizatio of exceptio ad log messages for a adapter. Provides hooks ito the log toolkit. Provides getter ad setter methods for stadard coectio properties (userame, password, server, coectiourl, port) Provides access to adapter metadata gathered from a java.util.resourcebudle for a adapter. Allows adapter providers to plug i licese checkig ito the iitializatio process for the factory. If the licese verificatio fails, the cliet applicatios caot get a coectio to the uderlyig EIS, thus makig the adapter useless. Provides state verificatio checkig to support JavaBeas-style post-costructor iitializatio. createcoectiofactory() There are several key methods that you must supply implemetatios for. The followig paragraphs describe these methods. createcoectiofactory(), show i Listig 6-15, is resposible for costructig the factory for applicatio-level coectio hadles for the adapter. I other words, cliets of your adapter will use the object retured by this method to obtai a coectio hadle to the EIS. BEA WebLogic Applicatio Itegratio Developmet Guide 6-25

88 6 Developig a Service Adapter If the adapter supports a CCI iterface, it is recommeded that you retur a istace of com.bea.adapter.cci.coectiofactoryimpl or a extesio of this class. The key to implemetig this method correctly is to propagate the CoectioMaager, LogCotext, ad ResourceAdapterMetaData ito the cliet API. Listig 6-15 createcoectiofactory() Example protected Object createcoectiofactory(coectiomaager coectiomaager, Strig stradaptername, Strig stradapterdescriptio, Strig stradapterversio, Strig strvedorname) throws ResourceExceptio createmaagedcoectio() createmaagedcoectio(), show i Listig 6-16, is resposible for costructig a MaagedCoectio istace for your adapter. The MaagedCoectio istace ecapsulates the expesive resources eeded to commuicate with the EIS. This method is called by the CoectioMaager whe it determies a ew MaagedCoectio is required to satisfy a cliet s request. A commo desig patter with adapters is to ope the resources eeded to commuicate with the EIS i this method ad the pass the resources ito a ew MaagedCoectio istace. Listig 6-16 createmaagedcoectio() Example public MaagedCoectio createmaagedcoectio(subject subject, CoectioRequestIfo ifo) throws ResourceExceptio 6-26 BEA WebLogic Applicatio Itegratio Developmet Guide

89 Step 3: Implemetig the SPI checkstate() checkstate() gets called by the AbstractMaagedCoectioFactory before it attempts to perform ay of its factory resposibilities. Use this method to verify that all members that eed to be iitialized before the MaagedCoectioFactory ca perform its SPI resposibilities have bee iitialized correctly. Implemet this method as show here: protected boolea checkstate() equals() equals() tests the object argumet for equality. It is importat to implemet this method correctly as it is used by the CoectioMaager for maagig the coectio pools. This method should iclude all importat members i its equality compariso. Implemet this method as show here: public boolea equals(object obj) hashcode() hashcode() provides a hash code for the factory. It is also used by the CoectioMaager for maagig the coectio pools. Cosequetly, this method should geerate a hashcode based upo properties that determie the uiqueess of the object. Implemet this method as show here: public it hashcode() matchmaagedcoectios() Lastly, the MaagedCoectioFactory must supply a implemetatio of the matchmaagedcoectios() method. The AbstractMaagedCoectioFactory provides a implemetatio of the matchmaagedcoectios() method that relies upo the comparecredetials method o AbstractMaagedCoectio. I order to provide logic that will match maaged coectios, you will eed to override AbstractMaagedCoectio s comparecredetials() method. This method is ivoked whe the MaagedCoectioFactory attempts to match a coectio with a coectio request for the CoectioMaager. BEA WebLogic Applicatio Itegratio Developmet Guide 6-27

90 6 Developig a Service Adapter Curretly, AbstractMaagedCoectioFactory s implemetatio extracts a PasswordCredetial from the supplied Subject/CoectioRequestIfo parameters. If both parameters are ull, this method returs true because it has already bee established that the MaagedCoectioFactory for this istace is correct. Listig 6-17 shows this implemetatio: Listig 6-17 comparecredetials() Implemetatio public boolea comparecredetials(subject subject, CoectioRequestIfo ifo) throws ResourceExceptio { ILogger logger = getlogger(); Next, you eed to extract a PasswordCredetial from either the JAAS Subject or the SPI CoectioRequestIfo usig the ADK s MaagedCoectioFactory. A example is show i Listig 6-18: Listig 6-18 Extractig a PasswordCredetial PasswordCredetial pc = getfactory(). getpasswordcredetial(subject, ifo); if (pc == ull) { logger.debug(this.tostrig() + ": comparecredetials I the example show i Listig 6-18, JAAS Subject ad CoectioRequestIfo are ull, which assumes a match. This method will ot get ivoked uless it has already bee established that the factory for this istace is correct. Cosequetly, if the Subject ad CoectioRequestIfo are both ull, the the credetials match by default; therefore, the result of pigig this coectio determies the outcome of the compariso. Listig 6-19 shows how to programmatically pig the coectio BEA WebLogic Applicatio Itegratio Developmet Guide

91 Step 3: Implemetig the SPI Listig 6-19 Pigig a Coectio } retur pig(); boolea busernamematch = true; Strig strpcusername = pc.getusername(); if (m_strusername!= ull) { logger.debug(this.tostrig() + ": comparecredetials >>> comparig my userame ["+m_strusername+"] with cliet userame ["+strpcusername+"]"); Next, you eed to see if the user supplied i either the Subject or the CoectioRequestIfo is the same as our user. We do ot support re-autheticatio i this adapter, so if they do ot match, this istace caot satisfy the request. The followig lie of code does that: busernamematch = m_strusername.equals(strpcusername); If userames match, pig the coectio to determie if this is still a good coectio. Otherwise, there is o match ad o reaso to pig. The followig lie of code does that: retur busernamematch? pig() : false; Explaatio of the Implemetatio Uder a maaged sceario, the applicatio server ivokes the matchmaagedcoectios() method o the MaagedCoectioFactory for a adapter. The specificatio does ot idicate how the applicatio server determies which MaagedCoectioFactory to use to satisfy a coectio request. The ADK s AbstractMaagedCoectioFactory implemets matchmaagedcoectios(). The first step i this implemetatio is to compare this (that is, the MaagedCoectioFactory istace o which the CoectioMaager ivoked matchmaagedcoectios) to the MaagedCoectioFactory o each MaagedCoectio i the set supplied by the applicatio server. For each BEA WebLogic Applicatio Itegratio Developmet Guide 6-29

92 6 Developig a Service Adapter MaagedCoectio i the set that has the same MaagedCoectioFactory, the implemetatio ivokes the comparecredetials() method. This method allows each MaagedCoectio object to determie if it ca satisfy the request. matchmaagedcoectios() gets called by the CoectioMaager (as show i Listig 6-20) to try to fid a valid coectio i the pool it is maagig. If this method returs ull, the the CoectioMaager will allocate a ew coectio to the EIS via a call to createmaagedcoectio(). Listig 6-20 matchmaagedcoectios() Method Implemetatio public MaagedCoectio matchmaagedcoectios(set coectioset, Subject subject, CoectioRequestIfo ifo) throws ResourceExceptio This class uses the followig approach to matchig a coectio: 1. It iterates over the <code>coectioset</code>, for each object i the set (util a match is foud) it determies whether to ot it s a AbstractMaagedCoectio. 2. If it is, the this is compared to the MaagedCoectioFactory for the AbstractMaagedCoectio from the set. 3. If the factories are equal, the the comparecredetials() method is ivoked o the AbstractMaagedCoectio. 4. If this method returs true, the the istace is retured BEA WebLogic Applicatio Itegratio Developmet Guide

93 Step 3: Implemetig the SPI AbstractMaagedCoectioFactory Properties Required at Deploymet To use the base implemetatio of AbstractMaagedCoectioFactory, you eed to provide the followig properties at deploymet time: Table 6-2 AbstractMaagedCoectioFactory Properties Property Name Property Type Applicable Values Descriptio Default LogLevel java.lag.st rig ERROR, WARN, INFO, DEBUG Logs verbosity level. WARN LaguageCode java.lag.st rig valid ISO Laguage Code, see edu/pub/ietf/http/ related/iso639.txt Determies the desired locale for log messages e CoutryCode java.lag. Strig valid ISO Coutry Code, see fu-berli.de/ diverse/doc/iso_3166. html Determies the desired locale for log messages US MessageBudleBase java.lag. Strig Ay valid Java Class ame or file ame Determies the message budle for log messages oe, required LogCofigFile java.lag.st rig Ay valid file ame Cofigures the LOG4J system oe, required RootLogCotext java.lag.st rig Ay valid Java Strig Categorizes log messages from this coectio factory. oe, required AdditioalLog Cotext java.lag.st rig Ay valid Java Strig Adds additioal iformatio to uiquely idetify messages from this factory. oe, optioal BEA WebLogic Applicatio Itegratio Developmet Guide 6-31

94 6 Developig a Service Adapter Other Key MaagedCoectioFactory Features i the ADK I the ADK sample adapter, the class sample.spi.maagedcoectiofactoryimpl is provided. This class exteds AbstractMaagedCoectioFactory. Use this class as a example of how to exted the ADK s base class. For the complete sample adapter MaagedCoectioFactory implemetatio code listig, see: <WLAI_HOME>\dev\sample\src\sample\spi\MaagedCoectioFactory Impl.java MaagedCoectio ADK Implemetatio javax.resource.spi.maagedcoectio The MaagedCoectio object is resposible for ecapsulatig all expesive resources eeded to establish coectivity to the EIS. A MaagedCoectio istace represets a physical coectio to the uderlyig EIS. MaagedCoectio objects are pooled by the applicatio server i a maaged eviromet. The ADK provides a abstract implemetatio of this iterface. The base class provides logic for maagig coectio evet listeers ad multiple applicatio-level coectio hadles per MaagedCoectio istace. Whe implemetig the MaagedCoectio iterface, you eed to determie the trasactio demarcatio support provided by the uderlyig EIS. For more iformatio o trasactio demarcatio, see Trasactio Demarcatio. The ADK provides AbstractMaagedCoectio, a abstract implemetatio for the javax.resource.spi.maagedcoectio iterface that: Provides access to the ADK loggig framework. Maages a collectio coectio evet listeers. Provides coveiece methods for otifyig all coectio evet listeers of coectio related evets BEA WebLogic Applicatio Itegratio Developmet Guide

95 Step 3: Implemetig the SPI Simplifies clea-up ad destructio of a MaagedCoectio istace. The sample adapter that comes with the ADK icludes MaagedCoectioImpl, which exteds AbstractMaagedCoectio. For the complete sample adapter MaagedCoectio implemetatio code listig, see: <WLAI_HOME>\dev\sample\src\sample\spi\MaagedCoectioFactory Impl.java MaagedCoectioMetaData ADK Implemetatio javax.resource.spi.maagedcoectiometadata The MaagedCoectioMetaData iterface provides iformatio about the uderlyig EIS istace associated with a MaagedCoectio istace. A applicatio server uses this iformatio to get rutime iformatio about a coected EIS istace. The ADK provides AbstractMaagedCoectioMetaData, a abstract implemetatio of the javax.resource.spi.maagedcoectiometadata ad javax.resource.cci.coectiometadata iterfaces that: Simplifies exceptio hadlig. Provides access to a AbstractMaagedCoectio istace. Allows you to focus o implemetig EIS-specific logic. Prevets you from havig a separate metadata class for the CCI ad SPI implemetatios. The sample adapter that comes with the ADK icludes MaagedCoectioMetaDataImpl, which exteds AbstractMaagedCoectioMetaData. For the complete code listig, see: <WLAI_HOME>\dev\sample\src\sample\spi\MaagedCoectioMetaDataIm pl. java BEA WebLogic Applicatio Itegratio Developmet Guide 6-33

96 6 Developig a Service Adapter CoectioEvetListeer ADK Implemetatio javax.resource.spi.coectioevetlisteer The CoectioEvetListeer iterface provides a evet callback mechaism that eables a applicatio server to receive otificatios from a MaagedCoectio istace. The ADK provides two cocrete implemetatios of this iterface: com.bea.adapter.spi.coectioevetlogger, which logs coectio-related evets to the adapter s log by usig the ADK loggig framework. com.bea.adapter.spi.nomaagedcoectioevetlisteer, which destroys javax.resource.spi.maagedcoectio istaces whe the adapter is ruig i a o-maaged eviromet. This implemetatio: l l Logs coectio-related evets usig the ADK loggig framework. Destroys MaagedCoectio istaces whe a coectio related error occurs. I most cases, the implemetatios provided by the ADK are sufficiet; you should ot eed to provide your ow implemetatio of this iterface. CoectioMaager javax.resource.spi.coectiomaager The CoectioMaager iterface provides a hook for the adapter to pass a coectio request to the applicatio server BEA WebLogic Applicatio Itegratio Developmet Guide

97 Step 3: Implemetig the SPI ADK Implemetatio The ADK provides a cocrete implemetatio of this iterface, com.bea.adapter.spi.nomaagedcoectiomaager. This implemetatio provides a basic coectio maager for adapters ruig i a o-maaged eviromet. I a maaged eviromet, this iterface is provided by the applicatio server. I most cases, you ca use the implemetatio provided by the ADK. NoMaagedCoectioMaager is a cocrete implemetatio of the javax.resource.spi.coectiomaager iterface. It serves as the CoectioMaager i the o-maaged sceario for a adapter; it does ot provide ay coectio poolig or ay other quality of service. CoectioRequestIfo ADK Implemetatio javax.resource.spi.coectiorequestifo The CoectioRequestIfo iterface eables a adapter to pass its ow request specific data structure across the coectio request flow. A adapter exteds the empty iterface to support its ow data structures for a coectio request. The ADK provides a cocrete implemetatio of this iterface called CoectioRequestIfoMap. This is a cocrete implemetatio of the javax.resource.spi.coectiorequestifo iterface ad provides a java.util.map iterface to such coectio request iformatio as userame ad password. LocalTrasactio javax.resource.spi.localtrasactio The LocalTrasactio iterface provides support for trasactios that are maaged iteral to a EIS resource maager, ad do ot require a exteral trasactio maager. BEA WebLogic Applicatio Itegratio Developmet Guide 6-35

98 6 Developig a Service Adapter ADK Implemetatio The ADK provides a abstract implemetatio of this iterface called AbstractLocalTrasactio. This implemetatio allows you to focus o implemetig the EIS-specific aspects of a LocalTrasactio. This implemetatio: Simplifies exceptio hadlig. Allows adapter providers to focus o implemetig EIS-specific trasactio logic. Prevets you from havig a separate metadata class for the CCI ad SPI implemetatios. Step 4: Implemetig the CCI The cliet iterface allows a J2EE-compliat applicatio to coect to ad access back-ed systems. The cliet iterface maages the flow of data betwee the cliet applicatio ad the back-ed system ad does ot have ay visibility ito what either the cotaier or the applicatio server are doig with the adapter. The cliet iterface specifies the format of the request ad respose records for a give iteractio with the EIS. First, you must determie if your adapter must support the J2EE-compliat Commo Cliet Iterface (CCI). Although ot a requiremet i the 1.0 J2EE specificatio, it is likely to be a requiremet i the ext versio. Cosequetly, the ADK focuses o helpig you implemet a CCI iterface for your adapter. How to Use this Sectio Step 4: Implemetig the CCI describes some of the iterfaces you ca use to implemet the CCI. A miimum of two iterfaces are ecessary to complete the task (see Basic CCI Implemetatio ). Each of these is described i detail, followed by a discussio of how they were exteded i the sample adapter icluded with the ADK BEA WebLogic Applicatio Itegratio Developmet Guide

99 Step 4: Implemetig the CCI Followig the two required iterfaces, the additioal iterfaces are described i detail, icludig iformatio regardig why you might use them ad what beefit they provide to a adapter. Basic CCI Implemetatio To implemet the CCI for your adapter, you eed to exted at least these two iterfaces: Coectio, which represets a applicatio-level hadle that is used by a cliet to access the uderlyig physical coectio. Iteractio, which eables a compoet to execute EIS fuctios. Ideally, you will implemet these iterfaces i the order specified above. I additio to these iterfaces, you ca implemet ay of the other iterfaces described i this step, as your adapter eeds dictate. These iterfaces are: CoectioFactory CoectioMetaData CoectioSpec IteractioSpec LocalTrasactio Record ResourceAdapterMetaData Coectio javax.resource.cci.coectio A Coectio represets a applicatio-level hadle that is used by a cliet to access the uderlyig physical coectio. The actual physical coectio associated with a Coectio istace is represeted by a MaagedCoectio istace. BEA WebLogic Applicatio Itegratio Developmet Guide 6-37

100 6 Developig a Service Adapter ADK Implemetatio A cliet gets a Coectio istace by usig the getcoectio method o a CoectioFactory istace. A coectio ca be associated with zero or more Iteractio istaces. The ADK provides a abstract implemetatio of this iterface called AbstractCoectio. This iterface provides the followig fuctioality: Access to the ADK loggig framework. Access to a AbstractMaagedCoectio istace State maagemet ad assertio checkig. You will eed to exted this class by providig a implemetatio for: public Iteractio createiteractio() throws ResourceExceptio This method creates a iteractio associated with this coectio. A iteractio eables a applicatio to execute EIS fuctios. This method: Returs: Iteractio istace. Throws: ResourceExceptio - Exceptio if the create operatio fails. Iteractio javax.resource.cci.iteractio The javax.resource.cci.iteractio eables a compoet to execute EIS fuctios. A Iteractio istace supports the followig ways of iteractig with a EIS istace: A execute() method that takes a iput Record, output Record, ad a IteractioSpec. This method executes the EIS fuctio represeted by the IteractioSpec ad updates the output Record A execute() method that takes a iput Record ad a IteractioSpec. This method implemetatio executes the EIS fuctio represeted by the IteractioSpec ad produces the output Record as a retur value BEA WebLogic Applicatio Itegratio Developmet Guide

101 Step 4: Implemetig the CCI ADK Implemetatio A iteractio istace is created from a coectio ad is required to maitai its associatio with the Coectio istace. The close() method releases all resources maitaied by the adapter for the iteractio. The close of a iteractio istace should ot close the associated coectio istace. The ADK provides a implemetatio of this iterface called AbstractIteractio. This iterface: Provides access to the ADK loggig framework. Maages warigs. execute() Versio 1 You must supply a cocrete extesio to AbstractIteractio that implemets execute(). Use at least oe of the followig versios of execute(): The execute() method declared i Listig 6-21 shows a iteractio represeted by the IteractioSpec. This form of ivocatio takes a iput record ad updates the output record. This method: Returs true if executio of the EIS fuctio has bee successful ad output Record has bee updated; otherwise it returs false. Throws ResourceExceptio - Exceptio if execute operatio fails Listig 6-21 execute() Versio 1 Code Example public boolea execute(iteractiospec ispec, Record iput, Record output) throws ResourceExceptio BEA WebLogic Applicatio Itegratio Developmet Guide 6-39

102 6 Developig a Service Adapter The parameters for execute() versio 1 are: Table 6-3 execute() Versio 1 Parameters Parameters ispec iput output Descriptio IteractioSpec represetig a target EIS data/fuctio module Iput Record Output Record execute() Versio 2 The execute() method declared i Listig 6-22 also executes a iteractio represeted by the IteractioSpec. This form of ivocatio takes a iput Record ad returs a output record if the executio of the Iteractio has bee successful. This method: Returs a output record if executio of the EIS fuctio has bee successful; otherwise it throws a exceptio. Throws ResourceExceptio - Exceptio if execute operatio fails. If a exceptio occurs, this method will otify its coectio, which will take the appropriate actio, icludig closig itself. Listig 6-22 execute() Versio 2 Code Example public Record execute(iteractiospec ispec, Record iput) throws ResourceExceptio 6-40 BEA WebLogic Applicatio Itegratio Developmet Guide

103 Step 4: Implemetig the CCI The parameters for execute() versio 2 are: Table 6-4 execute() Versio 2 Parameters Parameter ispec Descriptio IteractioSpec represetig a target EIS data/fuctio module iput Iput Record Usig XCCI to Implemet the CCI XCCI (XML-CCI) It is a dialect of CCI that uses XML-based record formats to represet data. It provides the tools ad framework for supportig this record format. There are two primary compoets of XCCI: Services ad DocumetRecords. A service represets fuctioality available i a EIS ad is comprised of four compoets: Uique Busiess Name Every service has a uique busiess ame that idicates its role i a itegratio solutio. For example, i a itegratio solutio ivolvig a Customer Relatioship Maagemet (CRM) system, you may have a service amed CreateNewCustomer. It is importat to uderstad that the service ame should reflect the busiess purpose of the service; it is a abstractio from the ame of the fuctio(s) your service ivokes i the EIS Request Documet Defiitio The request documet defiitio describes the iput requiremets for a service. The com.bea.documet.idocumetdefiitio iterface embodies all the metadata about a documet type. It icludes the documet schema (structure ad usage), ad the root elemet ame for all documets of this type. The root elemet ame is eeded because a XML schema ca defie more tha oe possible root elemet. Respose Documet Defiitio The respose documet defiitio describes the output for a service. Additioal Metadata BEA WebLogic Applicatio Itegratio Developmet Guide 6-41

104 6 Developig a Service Adapter DocumetRecord IDocumet A service is a higher-order compoet i a itegratio solutio that hides most of the complexity ivolved i executig fuctioality i a EIS. I other words, a service does ot expose may of the details required to iteract with the EIS i its public iterface. This implies that some of the iformatio required to ivoke a fuctio i a EIS is ot provided by the cliet i the request. Cosequetly, most services eed to store additioal metadata. I Applicatio Itegratio, this additioal metadata is ecapsulated by a adapter s javax.resource.cci.iteractiospec implemetatio class. com.bea.coector.documetrecord At rutime, the XCCI layer expects DocumetRecord objects as iput to a service ad returs DocumetRecord objects as output from a service. DocumetRecord implemets the javax.resource.cci.record ad the com.bea.documet.idocumet iterfaces. See Record for a descriptio of that iterface. IDocumet, which facilitates XML iput ad output from the CCI layer i a adapter, is described i the followig sectio. com.bea.documet.idocumet A IDocumet is a higher-order wrapper aroud the W3C Documet Object Model (DOM). The primary value-add of the IDocumet iterface is it provides a XPath iterface to elemets i a XML documet. I other words, IDocumet objects are queryable ad updatable usig XPath strigs. For example, The XML documet show i Listig 6-23 describes a perso amed Bob ad some of the details about Bob. Listig 6-23 XML Example <Perso ame="bob"> <Home squarefeet="2000"/> <Family> <Child ame="jimmy"> <Stats sex="male" hair="brow" eyes="blue"/> 6-42 BEA WebLogic Applicatio Itegratio Developmet Guide

105 Step 4: Implemetig the CCI </Child> <Child ame="susie"> <Stats sex="female" hair="blode" eyes="brow"/> </Child> </Family> </Perso> By usig IDocumet, you ca retrieve Jimmy s hair color usig the code show i Listig 6-24: Listig 6-24 IDocumet Data Retrieval Code Sample System.out.pritl("Jimmy s hair color: " + perso.getstrigfrom("//perso[@ame=\"bob\"]/family/child[@ame= \"Jimmy\"]/Stats/@hair"); O the other had, if you used DOM, you would eed to eter the code show i Listig 6-25: Listig 6-25 DOM Data Retrieval Code Sample Strig strjimmyshaircolor = ull; org.w3c.dom.elemet root = doc.getdocumetelemet(); if (root.gettagname().equals("perso") && root.getattribute("ame").equals("bob") { org.w3c.dom.nodelist list = root.getelemetsbytagname("family"); if (list.getlegth() > 0) { org.w3c.dom.elemet family = (org.w3c.dom.elemet)list.item(0); org.w3c.dom.nodelist childlist = family.getelemetsbytagname("child"); BEA WebLogic Applicatio Itegratio Developmet Guide 6-43

106 6 Developig a Service Adapter for (it i=0; i < childlist.getlegth(); i++) { org.w3c.dom.elemet child = childlist.item(i); if (child.getattribute("ame").equals("jimmy")) { org.w3c.dom.nodelist statslist = child.getelemetsbytagname("stats"); } } } } if (statslist.getlegth() > 0) { } org.w3c.dom.elemet stats = statslist.item(0); strjimmyshaircolor = stats.getattribute("hair"); ADK-Supplied XCCI Classes As you ca see, by usig IDocumet, you ca simplify your code. The ADK provides several classes that will help you implemet XCCI for your adapters. This sectio describes those classes. AbstractDocumetRecordIteractio com.bea.adapter.cci.abstractdocumetrecorditeractio This class exteds the ADK s abstract base Iteractio, com.bea.adapter.cci.abstractiteractio. The purpose of this class is to provide coveiece methods for maipulatig DocumetRecords ad to reduce the amout of error hadlig the you eed to implemet. Specifically, this class declares: protected abstract boolea execute(iteractiospec ixspec, DocumetRecord iputdoc, DocumetRecord outputdoc) throws ResourceExceptio ad 6-44 BEA WebLogic Applicatio Itegratio Developmet Guide

107 Step 4: Implemetig the CCI DocumetDefiitioRecord ServiceIteractioSpecImpl XCCI Desig Patter protected abstract DocumetRecord execute(iteractiospec ixspec, DocumetRecord iputdoc) throws ResourceExceptio These methods will ot be ivoked o the cocrete implemetatio util the parameters have bee verified that they are DocumetRecord objects. com.bea.adapter.cci.documetdefiitiorecord This class allows the adapter to retur a IDocumetDefiitio from its DocumetRecordIteractio implemetatio. This class is useful for satisfyig desig-time requests to create the request ad/or respose documet defiitios for a service. com.bea.adapter.cci.serviceiteractiospecimpl This class allows you to save the request documet defiitio ad respose documet defiitio for a service ito the IteractioSpec provided to the execute method at rutime. This is useful whe the Iteractio for a adapter eeds access to the XML schemas for a service at rutime. A commo desig patter that emerges whe usig the XCCI approach is to support the defiitio of services i the Iteractio implemetatio. I other words, the javax.resource.cci.iteractio implemetatio for a adapter allows a cliet program to retrieve metadata from the uderlyig EIS i order to defie a Applicatio Itegratio service. Specifically, this meas that the iteractio must be able to geerate the request ad respose XML schemas ad additioal metadata for a service. Additioally, the Iteractio could also allow a cliet program to browse a catalog of fuctios provided by the EIS. This approach facilitates a thi cliet architecture for your adapter. The ADK provides the com.bea.adapter.cci.desigtimeiteractiospecimpl class to help you implemet this desig patter. The sample.cci.iteractioimpl class demostrates how to implemet this desig patter usig the DesigTimeIteractioSpecImpl class. BEA WebLogic Applicatio Itegratio Developmet Guide 6-45

108 6 Developig a Service Adapter CoectioFactory ADK Implemetatio javax.resource.cci.coectiofactory CoectioFactory provides a iterface for gettig coectio to a EIS istace. A implemetatio of CoectioFactory iterface is provided by a adapter. The applicatio code looks up a CoectioFactory istace from JNDI amespace ad uses it to get EIS coectios. A implemetatio class for CoectioFactory is required to implemet java.io.serializable ad javax.resource.refereceableiterfaces to support JNDI registratio. The ADK provides CoectioFactoryImpl, a cocrete implemetatio of the javax.resource.cci.coectiofactory iterface that provides the followig fuctioality: Access to the ADK loggig framework. Access to adapter metadata. Implemetatio of the getcoectio() method. Typically, you will ot eed to exted this class ad ca use it outright. CoectioMetaData javax.resource.cci.coectiometadata CoectioMetaData provides iformatio about a EIS istace coected through a Coectio istace. A compoet calls the method Coectio.getMetaData to get a CoectioMetaData istace BEA WebLogic Applicatio Itegratio Developmet Guide

109 Step 4: Implemetig the CCI ADK Implemetatio By default, the ADK provides a implemetatio of this class via the com.bea.adapter.spi.abstractcoectiometadata class. You will eed to exted this abstract class ad implemet its four abstract methods for your adapter. CoectioSpec ADK Implemetatio javax.resource.cci.coectiospec CoectioSpec is used by a applicatio compoet to pass coectio request-specific properties to the CoectioFactory.getCoectio() method. It is recommeded that you implemet the CoectioSpec iterface as a JavaBea so that it ca support tools. The properties o the CoectioSpec implemetatio class must be defied through the getter ad setter methods patter. The CCI specificatio defies a set of stadard properties for a CoectioSpec. The properties are defied either o a derived iterface or a implemetatio class of a empty CoectioSpec iterface. I additio, a adapter may defie additioal properties specific to its uderlyig EIS. Sice the CoectioSpec implemetatio must be a JavaBea, the ADK does ot supply a implemetatio for this class. IteractioSpec javax.resource.cci.iteractiospec A IteractioSpec holds properties for drivig a iteractio with a EIS istace. It is used by a iteractio to execute the specified fuctio o a uderlyig EIS. The CCI specificatio defies a set of stadard properties for a IteractioSpec. A IteractioSpec implemetatio is ot required to support a stadard property if that property does ot apply to its uderlyig EIS. BEA WebLogic Applicatio Itegratio Developmet Guide 6-47

110 6 Developig a Service Adapter The IteractioSpec implemetatio class must provide getter ad setter methods for each of its supported properties. The getter ad setter methods covetio should be based o the JavaBeas desig patter. The IteractioSpec iterface must be implemeted as a JavaBea i order to support tools. A implemetatio class for IteractioSpec iterface is required to implemet the java.io.serializable iterface. The Iteractio spec cotais iformatio that is ot i Record but helps determie what EIS fuctio to ivoke. The stadard properties are described i Table 6-5: Table 6-5 Stadard IteractioSpec Properties Property FuctioName IteractioVerb ExecutioTimeout Name of a EIS fuctio Descriptio Mode of iteractio with a EIS istace: SYNC_SEND, SYNC_SEND_RECEIVE, SYNC_RECEIVE The umber of millisecods a Iteractio will wait for a EIS to execute the specified fuctio The followig stadard properties are used to give hits to a iteractio istace about the ResultSet requiremets: FetchSize FetchDirectio MaxFieldSize ResultSetType ResultSetCocurrecy A CCI implemetatio ca provide additioal properties beyod that described i the IteractioSpec iterface. Note: The format ad type of the additioal properties is specific to a EIS ad is outside the scope of the CCI specificatio BEA WebLogic Applicatio Itegratio Developmet Guide

111 Step 4: Implemetig the CCI ADK Implemetatio The ADK cotais a cocrete implemetatio of javax.resource.cci.iteractiospec called IteractioSpecImpl. This iterface provides a base implemetatio for you to exted by usig getter ad setter methods for the stadard iteractio properties described i Table 6-5. LocalTrasactio javax.resource.cci.localtrasactio The LocalTrasactio iterface is used for applicatio-level local trasactio demarcatio. It defies a trasactio demarcatio iterface for resource maager local trasactios. The system cotract level LocalTrasactio iterface (as defied i the javax.resource.spi package) is used by the cotaier for local trasactio maagemet. A local trasactio is maaged iteral to a resource maager. There is o exteral trasactio maager ivolved i the coordiatio of such trasactios. A CCI implemetatio ca (but is ot required to) implemet the LocalTrasactio iterface. If the LocalTrasactio iterface is supported by a CCI implemetatio, the the method Coectio.getLocalTrasactio should retur a LocalTrasactio istace. A compoet ca the use the retured LocalTrasactio to demarcate a resource maager local trasactio (associated with the Coectio istace) o the uderlyig EIS istace. The com.bea.adapter.spi.abstractlocaltrasactio class also implemets this iterface. For more iformatio o local trasactios, see Trasactio Demarcatio. BEA WebLogic Applicatio Itegratio Developmet Guide 6-49

112 6 Developig a Service Adapter Record javax.resource.cci.record The javax.resource.cci.record iterface is the base iterface for represetig a iput or output to the execute() methods defied o a Iteractio. For more iformatio o the execute() methods, see execute() Versio 1 ad execute() Versio 2. A MappedRecord or IdexedRecord ca cotai aother Record. This meas that you ca use MappedRecord ad IdexedRecord to create a hierarchical structure of ay arbitrary depth. A basic Java type is used as the leaf elemet of a hierarchical structure represeted by a MappedRecord or IdexedRecord. The Record iterface ca be exteded to form oe of the represetatios show i Table 6-6: Table 6-6 Record Iterface Represetatios Represetatio MappedRecord IdexedRecord JavaBea based represetatio of a EIS abstractio javax.resource.cci. ResultSet Descriptio A key-value pair based collectio represetig a record. This iterface is based o the java.util.map A ordered ad idexed collectio represetig a record. This iterface is based o the java.util.list. A example is a custom record geerated to represet a purchase order i a ERP system. This iterface exteds both java.sql.resultset ad javax.resource.cci.record. A ResultSet represets tabular data. Assumig the adapter implemets a CCI iterface, the ext cosideratio is the record format for a service. A service has a request record format ad a respose record format. The request record provides iput to the service ad the respose record provides the EIS respose BEA WebLogic Applicatio Itegratio Developmet Guide

113 Step 4: Implemetig the CCI ADK Implemetatio The ADK focuses o helpig you implemet a XML-based record format i the CCI layer. To this ed, the ADK provides the DocumetRecord class. I additio, you ca use BEA s schema toolkit to develop schemas to describe the request ad respose documets for a service. The ADK provides RecordImpl, a cocrete implemetatio of the javax.resource.cci.record iterface that provides getter ad setter methods for record ame ad descriptio. If a adapter provider wats to use a XML-based record format (which is highly recommeded), the ADK also provides the com.bea.adapter.cci.abstract DocumetRecordIteractio class. This class esures that the cliet passes DocumetRecord objects. I additio, this class provides coveiece methods for accessig cotet i a DocumetRecord. ResourceAdapterMetaData javax.resource.cci.resourceadaptermetadata The iterface javax.resource.cci.resourceadaptermetadata provides iformatio about capabilities of a adapter implemetatio. A CCI cliet uses a CoectioFactory.getMetaData to get metadata iformatio about the adapter. The getmetadata() method does ot require establishmet of a active coectio to a EIS istace. The ResourceAdapterMetaData iterface ca be exteded to provide more iformatio specific to a adapter implemetatio. Note: This iterface does ot provide iformatio about a EIS istace that is coected through the adapter. ADK Implemetatio The ADK provides ResourceAdapterMetaDataImpl that ecapsulates adapter metadata ad provides getters ad setters for all properties. BEA WebLogic Applicatio Itegratio Developmet Guide 6-51

114 6 Developig a Service Adapter Step 5: Deployig the Adapter After implemetig the SPI ad CCI iterfaces for a adapter, you deploy it. To deploy your adapter, you eed to complete these tasks: Update the ra.xml file Create the.rar File Deploy the.rar File This sectio describes these tasks. Step 5a: Update the ra.xml File Table 6-7 RA.XML Properties To deploy a adapter, you first must supply a adapter descriptor file. This file must be icluded i the adapter s.rar file as META-INF/ra.xml. The ADK provides a base implemetatio for this file with the sample adapter. If the adapter provider exteds AbstractMaagedCoectioFactory, you will eed to supply the followig properties i the ra.xml file: Property LogLevel Example This property specifies the log verbosity for this coectio factory. Possible values are: DEBUG, INFO, WARN, ERROR, ad AUDIT; for example: <cofig-property> <cofig-property-ame>loglevel</cofig- property-ame> <cofig-property-type>java.lag.strig </cofig-property-type> <cofig-property-value>warn</cofig- property-value> </cofig-property> 6-52 BEA WebLogic Applicatio Itegratio Developmet Guide

115 Step 5: Deployig the Adapter Table 6-7 RA.XML Properties Property LaguageCode Example This property specifies the desired laguage code for log messages. This property is used with the CoutryCode property to idetify the correct message budle from which to retrieve messages. <cofig-property> <cofig-property-ame>laguagecode</cofig-propertyame> <cofig-property-type>java.lag.strig </cofig-property-type> <cofig-property-value>e</cofig-property-value> </cofig-property> CoutryCode This property specifies the desired coutry code for log messages. <cofig-property> <cofig-property-ame>coutrycode</cofigproperty-ame> <cofig-property-type>java.lag.strig </cofig-property-type> <cofig-property-value>us</cofig-property- value> </cofig-property> MessageBudleBase This property specifies the base ame for all message budles supplied with a adapter. The ADK always uses the adapter logical ame for its sample adapters. However, you are free to chose your ow amig covetio for message budles. <cofig-property> <cofig-property-ame>messagebudlebase</cofigproperty-ame> <cofig-property-type>java.lag.strig </cofig-property-type> <cofig-property-value>sample</cofig-property-value> </cofig-property> BEA WebLogic Applicatio Itegratio Developmet Guide 6-53

116 6 Developig a Service Adapter Table 6-7 RA.XML Properties Property LogCofigFile Example This property specifies the log cofiguratio file for the adapter. <cofig-property> <cofig-property-ame>logcofigfile</cofig-propertyame> <cofig-property-type>java.lag.strig</cofigproperty-type> <cofig-property-value>sample.xml</cofig-propertyvalue> </cofig-property> RootLogCotext This property specifies the root log cotext. Log cotext helps categorize log messages accordig to modules i a program. The ADK uses the adapter logical ame for the root log cotext so that all messages from a specific adapter will be categorized accordigly. <cofig-property> <cofig-property-ame>rootlogcotext </cofig-property-ame> <cofig-property-type>java.lag.strig</cofigproperty-type> <cofig-property-value>sample</cofig-property-value> </cofig-property> AdditioalLogCotext This property allows the user to add additioal log cotext iformatio to help categorize messages. Typically, this is the ame of the associated applicatio view. <cofig-property> <cofig-property-ame>additioallogcotext</cofigproperty- ame> <cofig-property-type>java.lag.strig</cofigproperty-type> </cofig-property> 6-54 BEA WebLogic Applicatio Itegratio Developmet Guide

117 Step 5: Deployig the Adapter You ca see a example of a fuctioig ra.xml file for either a DBMS adapter or a adapter i oe of the followig locatios: <WLAI_HOME>\dev\ \src\rar\META-INF\ <WLAI_HOME>\dev\dbms\src\rar\META-INF\ Or, you ca see a example for the cloed sample adapter at: <WLAI_HOME>\dev\sample\src\rar\META-INF\ Step 5b: Create the weblogic-ra.xml File The weblogic-ra.xml file is a deploymet descriptor that cotais essetially the same iformatio as the CoectioFactory descriptor, but i the form expected by the WebLogic J2EE egie. This file also cotais a referece back to the base.rar deploymet for the adapter. This referece allows the ew.rar to use the code ad other resources deployed i the base deploymet, ad frees it from cotaiig itself. The referece to the base deploymet also allows the ew.rar to iherit ay pool or coectio parameters specified for base deploymet. Whe a user defies ad starts to deploy a applicatio view, a CoectioFactory descriptor is created that cotais the EIS coectio parameters ad coectio pools parameters that the user etered. The CoectioFactory descriptor also cotais the JNDI ame to which the ew coectio factory will be boud. This ame is automatically geerated based o the applicatio view's qualified ame. This CoectioFactory descriptor is the deployed to the Applicatio Itegratio egie, which, i tur, creates a ew.rar file cotaiig oly a weblogic-ra.xml file. A versio of the weblogic-ra.xml file is icluded with the sample adapter at <WLAI_HOME>\dev\sample\src\rar\META-INF\ Whe you ru the GeerateAdapterTemplate utility, a versio of this file tailored for you ew adapter will be created. You ca see a example of a weblogic-ra.xml file for a DBMS adapter at: <WLAI_HOME>\dev\dbms\src\rar\META-INF\ BEA WebLogic Applicatio Itegratio Developmet Guide 6-55

118 6 Developig a Service Adapter Step 5c: Create ad Deploy the.rar File Class files, loggig cofiguratio, ad message budle(s) should be budled ito a.jar file. This.jar file ad META-INF/ra.xml should the be budled ito.rar file. The At build.xml file demostrates how to properly costruct the.rar file. See Step 2c: Settig Up the Build Process. Listig 6-26 shows a example of a.rar file: Listig 6-26 <Applicatio Deployed="true" Name="BEA_WLS_SAMPLE_ADK_WLSRAR.rarPath="d:\wlai\dev\sample\lib"> <ResourceAdapterCompoet Descriptio=" BEA_Sample_Descriptio " Name="BEA_WLS_SAMPLE_ADK_WLSRAR" Targets="myserver" URI="BEA_WLS_SAMPLE_ADK_WLSRAR.rar"/> </Applicatio> Deploy the.rar file ito the J2EE-compliat cotaier i the applicatio server. The deploymet procedure will be differet o every server. Step 6: Testig the Adapter The ADK provides a test haress that leverages JUit, a ope-source tool for uit testig. You ca fid more iformatio o JUit at com.bea.adapter.test.testharess does the followig: Reads a properties file cotaiig test cofiguratio iformatio. Iitializes the log toolkit. Iitializes JUit TestSuite BEA WebLogic Applicatio Itegratio Developmet Guide

119 Step 6: Testig the Adapter Loads test classes ad executes them usig JUit. Allows you to test code off-lie ad outside of WebLogic 6.0. Usig the Test Haress To use the test haress i the ADK, complete the followig steps: 1. Create a class that exteds juit.framework.testcase. The class must provide a static method amed suite that returs a ew juit.framework.testsuite. See the sample adapter for details. 2. Implemet test methods; ame of methods should begi with test 3. Create/alter the test.properties i the project directory (if you cloe the sample adapter, the your adapter will already have a base test.properties i the project directory). The properties file should cotai ay cofiguratio properties eeded for your test case. 4. Ivoke the test usig At. Your At build.xml file will eed a test target that ivokes the com.bea.adapter.test.testharess class with the properties file for your adapter. For example, the sample adapter uses the At target show i Listig 6-27: Listig 6-27 At Target Specified i the Sample Adapter <target ame= test depeds= packages > <java classame= com.bea.adapter.test.testharess > <arg value= -DCONFIG_FILE=test.properties /<classpath refid= CLASSPATH /> </java> </target> This target ivokes the JVM with mai class com.bea.adapter.test.testharess usig the classpath established for the sample adapter ad passes the commad-lie argumet: BEA WebLogic Applicatio Itegratio Developmet Guide 6-57

120 6 Developig a Service Adapter -DCONFIG_FILE=test.properties Test Case Extesios Provided by the ADK The sample adapter ships with two basic TestCase extesios: sample.spi.nomaagedsceariotestcase sample.evet.offlieevetgeeratortestcase sample.spi.nomaagedsceariotestcase NoMaagedScearioTestCase allows you to test your SPI ad CCI classes i a o-maaged sceario. Specifically, this class tests the followig: Iitializatio of the MaagedCoectioFactory implemetatio. Serializatio/De-serializatio of the MaagedCoectioFactory istace. Opeig a coectio to the EIS. Closig a coectio to the EIS; you ca make sure all associated resources are gettig closed whe a coectio is closed. sample.evet.offlieevetgeeratortestcase sample.evet.offlieevetgeeratortestcase allows you to test the ier workigs of your evet geerator outside of the WebLogic Server. Specifically, this class tests the followig for the evet geerator: It simulates the evet router ad istatiates a ew istace of the adapter s evet geerator. It passes the test.properties to the evet geerator for iitializatio; this allows you to test your iitializatio logic. It refreshes the evet geerator radomly; this allows you to test your setupnewtypes() ad removedeadtypes() methods. It receives evet postigs ad displays them to the log file for the adapter BEA WebLogic Applicatio Itegratio Developmet Guide

121 Step 6: Testig the Adapter sample.cliet.applicatioviewcliet sample.cliet.applicatioviewcliet offers a additioal way of test your adapter. This class is a Java program that demostrates how to ivoke a service ad liste for a evet o a applicatio view. The At build.xml provides the cliet target to allow you to use the ApplicatioViewCliet program. Executig at cliet will provide the usage for the program. To see a example of sample.cliet.applicatioviewcliet, go to <WLAI_HOME>/dev/sample/ src/sample/cliet. Note: sample.cliet.applicatioviewcliet is ot itegrated with the test haress. BEA WebLogic Applicatio Itegratio Developmet Guide 6-59

122 6 Developig a Service Adapter 6-60 BEA WebLogic Applicatio Itegratio Developmet Guide

123 CHAPTER 7 Developig a Evet Adapter Evet adapters propagate iformatio from a EIS ito the Applicatio Itegratio eviromet. These types of adapters ca be described as publishers of iformatio. O the Applicatio Itegratio itegratio platform, all evet adapters perform the followig three fuctios: They respod to evets that occur iside the ruig EIS ad extract data about the evet from the EIS ito the adapter. They trasform evet data from the EIS specific format to a XML documet that coforms to the XML schema for the evet. The XML schema is based o metadata i the EIS. They propagate the evet ito the Applicatio Itegratio eviromet by usig the evet router. The Applicatio Itegratio implemets the aspects of these three fuctios that are geeric across all evet adapters. You oly eed to focus o the EIS specific aspects of your adapter. This sectio cotais iformatio o the followig subjects: Evet Adapters i the Rutime Eviromet The Flow of Evets Step 1: Developmet Cosideratios Step 2: Cofigurig the Developmet Eviromet l Step 2a: Set up the File Structure l Step 2b: Assig the Adapter Logical Name BEA WebLogic Applicatio Itegratio Developmet Guide 7-1

124 7 Developig a Evet Adapter l l l Step 2c: Set Up the Build Process Step 2d: Create the Message Budle Step 2e: Cofigure Loggig Step 3: Implemetig the Adapter l Step 3a: Create a EvetGeerator l Step 3b: Implemet the Data Trasformatio Method Step 4. Deployig the Adapter Step 5: Testig the Adapter Evet Adapters i the Rutime Eviromet The behavior of a Evet i the rutime eviromet is depicted i Figure BEA WebLogic Applicatio Itegratio Developmet Guide

125 Evet Adapters i the Rutime Eviromet Figure 7-1 Evet Adapters i the Rutime Eviromet BEA WebLogic Applicatio Itegratio Developmet Guide 7-3

126 7 Developig a Evet Adapter The Flow of Evets Figure 7-2 outlies the steps required to develop a Evet Adapter. Figure 7-2 Evet Adapter Flow of Evets 7-4 BEA WebLogic Applicatio Itegratio Developmet Guide

127 Step 1: Developmet Cosideratios Step 1: Developmet Cosideratios These are the items you eed to cosider before commecig with evet adapter developmet. The Adapter Setup Worksheet will provide much of this iformatio. See Adapter Setup Worksheet. 1. Determie the evet types. You eed to idetify what exactly comprises the evet: l What will its cotets be? l How will it be defied i the XML schema? l What will trigger it? 2. Determie the data extractio method. Next, you eed to decide which method of data extractio will be used: l Push, wherei the EIS otifies the adapter of a evet. l Pull, where the adapter polls the EIS ad pulls evet data from it. Use the pull method whe your adapter eeds to poll the EIS to determie a chage-of-state. Use a push evet whe you wat to implemet a evet geeratio that works more like a publish/subscribe model. Step 2: Cofigurig the Developmet Eviromet This step describes the processes you must complete to prepare your computer for adapter developmet. BEA WebLogic Applicatio Itegratio Developmet Guide 7-5

128 7 Developig a Evet Adapter Step 2a: Set up the File Structure The file structure ecessary to build a evet adapter is the same as that required for service adapters. See Step 2a: Set up the File Structure i Developig a Service Adapter. Step 2b: Assig the Adapter Logical Name Next, you eed to assig the adapter s logical ame. By covetio, this ame is comprised of the vedor ame, the type of EIS coected to the adapter, ad the versio umber of the EIS ad is expressed as vedor_eis-type_eis versio. For example, BEA_WLS_SAMPLE_ADK, where: BEA is the vedor WLS is the EIS-type SAMPLE_ADK is the EIS versio Step 2c: Set Up the Build Process The Applicatio Itegratio employs a build process based upo At, a 100% pure Java-based build tool. For more iformatio o At, please see At-Based Build Process. For more iformatio o usig At, see The sample adapter shipped with BEA WebLogic Applicatio Itegratio (located i <WLAI_HOME>\dev\bi\ sample) cotais the file build.xml. This is the At build file for the sample adapter. It cotais the tasks eeded to build a J2EE-compliat adapter. Ruig the GeerateAdapterTemplate utility to cloe a developmet tree for your adapter creates a build.xml file specifically for that adapter. This will free you from havig to customize the sample build.xml ad will esure that the code is correct. For iformatio o usig the GeerateAdapterTemplate utility, see Creatig a Custom Developmet Eviromet. For more iformatio o the build process, see Step 2c: Settig Up the Build Process i Developig a Service Adapter. 7-6 BEA WebLogic Applicatio Itegratio Developmet Guide

129 Step 2: Cofigurig the Developmet Eviromet Step 2d: Create the Message Budle Ay message destied for the ed-user should be placed i a message budle. The message budle is simply a.properties text file that cotais key=value pairs that allow you to iteratioalize messages. Whe a locale ad atioal laguage are specified at rutime, the cotets of the message is iterpreted, based upo the key=value pair, ad the message is preseted to the user i the correct laguage for his or her locale. For istructios o creatig a message budle, please refer to the JavaSoft tutorial o iteratioalizatio at: Step 2e: Cofigure Loggig The fial step i cofigurig your developmet eviromet is to cofigure loggig. Before you begi, read more about loggig i Cocepts. Loggig is accomplished usig the loggig tool log4j, developed as part of the Apache Jakarta project. For iformatio o usig this tool, please see The ADK Loggig Toolkit. Create a Evet Geeratio Loggig Category For evet adapters, you will eed to create a loggig category specifically for evet geeratio (for more iformatio o loggig categories, see Message Categories ). Edit the loggig cofiguratio file for the specific adapter (adapter_logical_ame.xml i the /src/ directory for that adapter) by addig the followig lie: Listig 7-1 Sample Code Creatig a Evet Geeratio Loggig Category <category ame= BEA_WLS_SAMPLE_ADK.EvetGeerator class= com.bea. loggig.logcategory > </category> BEA WebLogic Applicatio Itegratio Developmet Guide 7-7

130 7 Developig a Evet Adapter By ot settig ay specific parameters for this category, it will iherit all of the paret category s property settigs. I this example, the paret category is BEA_WLS_SAMPLE_ADK. Step 3: Implemetig the Adapter Implemetig a evet adapter is a two-step process. You eed to: Create a EvetGeerator. This process implemets the data extractio method (that is, will you extract data by a push or a pull mechaism) ad the IEvetGeerator iterface. This iterface is used by the EvetRouter to drive the evet geeratio process. Implemet the data trasformatio method. This sectio shows you how to accomplish these tasks. Step 3a: Create a EvetGeerator The evet geeratio provides adapter with a mechaism to either receive otificatio from a EIS or poll a EIS for the specific occurrece of a evet. The evet geeratio provided by the BEA WebLogic Applicatio Itegratio egie is very powerful i that a sigle EvetGeerator ca support multiple types of evets. A evet type is defied by the cofiguratio properties for a evet. Typically evet properties are defied by the properties associated with a evet at desigtime. Whe cofigurig a evet adapter, the adapter may have oe or more web pages that it uses to collect evet properties. These properties are saved with the applicatio view Descriptor ad passed back to the evet at rutime. The Applicatio Itegratio egie uses the properties ad the source applicatio view to determie how to route back to the listeers. For istace, two separate deploymets of the same EvetGeerator with idetical properties will result i oly a sigle IEvetDefiitio beig created by the Applicatio Itegratio egie. Whereas, a sigle IEvetDefiitio will be created for every deploymet of a sigle evet adapter where 7-8 BEA WebLogic Applicatio Itegratio Developmet Guide

131 Step 3: Implemetig the Adapter the properties are differet. It is the resposibility of the EvetGeerator to determie which IEvetDefiitio to use i the routig process. This is typically doe based o property values ad specific evet occurreces. The IEvetDefiitio objects are used by your implemetatio of the EvetGeerator to route specific evets back to their listeer. As discussed before, the Applicatio Itegratio egie will create IEvetDefiitio objects for deployed applicatio views cotaiig evets. You will use the IEvetDefiitio objects to extract specific properties regardig the deploymet of a applicatio view, or to access schema ad routig objects. You eed to employ these attributes whe routig a evet. How the Data Extractio Mechaism is Implemeted Applicatio Itegratio supports two mechaisms for data extractio: Pull evet geeratio. A state chage is recogized whe the object geeratig evets pushes a otificatio to the EvetGeerator. Whe the Push Evet geerator receives the evet, the Applicatio Itegratio egie the routes to a deployed applicatio view. The push EvetGeerator uses a publish/subscribe model. Push evet geeratio, which is used whe pollig is ecessary to accomplish the determiatio of a state havig chaged. A process cotiually queries a object util it has determied a chage i state, at which poit it creates a evet, which the BEA WebLogic Applicatio Itegratio egie the routes to a deployed applicatio view. The Pull Mechaism The mechaism relies o a pollig techique to determie if a evet has take place. To implemet a Pull sceario you must derive your EvetGeerator from the AbstractPullEvetGeerator i the com.bea.adapter.evet package. Note: adk-evetgeerator.jar file must be icluded i your.war make file. adk-evetgeerator.jar cotais the ADK base classes required to implemet a EvetGeerator. BEA WebLogic Applicatio Itegratio Developmet Guide 7-9

132 7 Developig a Evet Adapter The ADK supplies several abstract methods i the AbstractPullEvetGeerator that you must override i your implemetatio. These methods are described i Table 7-1. Table 7-1 AbstractPullEvetGeerator Methods Method postevets() setupnewtypes() removedeadtypes() doiit() docleaupoquit() Descriptio The postevets method is called from the ru method i the AbstractPullEvetGeerator at a iterval that is determied by the Evet Router cofiguratio files. The postevets() method is where you add ay pollig ad routig code. The postevets method is the cotrol method for the rest of your evet geeratio, message trasformatio, ad routig code. The setupnewtypes() method is used to preprocess ay IEvetDefiitio object beig deployed. Oly valid ew IEvetDefiitio objects are passed to the setupnewtypes method. The removedeadtypes method is used to hadle ay clea up required for IEvetDefiitio objects that are beig u-deployed. The Applicatio Itegratio egie calls removedeadtypes whe applicatio views with associated evets are beig u-deployed. doiit() is called while the EvetGeerator is beig costructed. Durig the iitializatio process the EvetGeerator ca use pre-defied cofiguratio values to setup the ecessary state or coectios for the evet geeratio process. docleaupoquit() is called before edig the thread drivig the evet geeratio process. Use this method to free ay resources allocated by your evet geeratio process. The Push Mechaism The Push sceario uses otificatio to trigger the routig of a evet. To implemet the Push sceario you must derive your EvetGeerator from the AbstractPushEvetGeerator class i the com.bea.adapter.evet package. There are several other supportig classes icluded i the evet package. These classes are described i Table BEA WebLogic Applicatio Itegratio Developmet Guide

133 Step 3: Implemetig the Adapter Note: adk-evetgeerator.jar must be icluded i your.war make file. adk-evetgeerator.jar cotais the Applicatio Itegratio base classes required to implemet a EvetGeerator. Table 7-2 AbstractPushEvetGeerator Classes Class AbstractPushEvetGeerator IPushHadler PushEvet EvetMetaData Descriptio The AbstractPushEvetGeerator class cotais the same abstract ad cocrete methods as the AbstractPullEvetGeerator. These methods are iteded to be used i the same maer as the AbstractPullEvetGeerator implemetatio. See Table 7-1 for a list of these methods ad resposibilities. The IPushHadler is a iterface provided primarily to abstract the geeratio of a evet from the routig of a evet; however, it is ot required to implemet a Push sceario. The IPushHadler is iteded to be tightly coupled with the PushEvetGeerator. It is the PushEvetGeerator that will iitialize, subscribe, ad clea up the PushHadler implemetatio. The IPushHadler provides a simple iterface to abstract the geeratio logic. The iterface provides methods to iitialize, subscribe to Push evets, ad clea up resources. The PushEvet is a evet object derived from java.util.evetobject. The PushEvet is iteded to wrap a EIS otificatio ad be set to ay IPushEvetListeer objects. The EvetMetaData class is iteded to wrap ay data ecessary for evet geeratio. The EvetMetaData class is passed to the IPushHadler o iitializatio. To see a sample usage for these objects refer to the sample code. BEA WebLogic Applicatio Itegratio Developmet Guide 7-11

134 7 Developig a Evet Adapter How the EvetGeerator is Implemeted A EvetGeerator implemetatio typically follows this flow of cotrol: doiit(); This method creates ad validates coectios to the EIS. setupnewtypes(); This method processes IEvetDefiitio objects creatig ay required structures for processig. postevets(); This method iteratively ivokes oe of the two data extractio mechaisms: l l Push: Poll the EIS for a Evet. If the Evet exists, determie which IEvetDefiitio objects will receive the evet. Trasform evet data ito a IDocumet object usig the associated schema. Route the IDocumet object usig the IEvet associated with the IEvetDefiitio object. Pull: Whe otified of a evet the postevets method will extract the evet data from the PushEvet object ad trasform the evet data to a IDocumet object. The IDocumet object is created based o the schema associated with the evet adapter. Whe the IDocumet cotais the ecessary evet data it is routed to the correct IEvetDefiitio objects. removedeadtypes(); This method removes the dead IEvetDefiitio objects from ay data structures beig used for evet processig. Free ay resources associated. IEvetDefiitio objects are cosidered dead whe the applicatio view is udeployed. docleaupoquit(); This method removes ay resources allocated durig evet processig. The followig is a series of code samples that implemet a EvetGeerator with a Pull mechaism. Listig 7-2 shows the class declaratio for the sample adapter s (Pull) EvetGeerator. Note: The AbstractPullEvetGeerator implemets a ru-able iterface; that is, it s a thread. Listig 7-2 Sample Code Implemetig a Pull Data Extractio Mechaism public class EvetGeerator exteds AbstractPullEvetGeerator 7-12 BEA WebLogic Applicatio Itegratio Developmet Guide

135 Step 3: Implemetig the Adapter Sample EvetGeerator Listig 7-3 shows the simple costructor for a EvetGeerator. You must ivoke the paret s costructor so that the paret s members get iitialized correctly. The listig the shows how the doiit() method receives cofiguratio iformatio from the map variable ad validates the parameters. The sample cotais ay parameters associated with the EvetGeerator at desigtime. Listig 7-3 Sample Costructor for a EvetGeerator public EvetGeerator() { super(); } protected void doiit(map map) { throws java.lag.exceptio ILogger logger = getlogger(); m_strusername = (Strig)map.get("UserName"); { if (m_strusername == ull m_strusername.legth() == 0) Strig strerrormsg = logger.geti18nmessage("evet_geerator_o_username"); } logger.error(strerrormsg); throw ew IllegalStateExceptio(strErrorMsg); m_strpassword = (Strig)map.get("Password"); if (m_strpassword == ull m_strpassword.legth() == 0) { BEA WebLogic Applicatio Itegratio Developmet Guide 7-13

136 7 Developig a Evet Adapter Strig strerrormsg = logger.geti18nmessage ("evet_geerator_o_password"); } logger.error(strerrormsg); throw ew IllegalStateExceptio(strErrorMsg); postevets() is called from the ru method of our paret class, as show i Listig 7-4. This method polls the EIS to determie whe a ew evet occurs. This method will be ivoked at a fixed iterval, which is defied i the web.xml file for the EvetRouter. Listig 7-4 Sample Code Implemetatio of the postevets() Method */ protected void postevets(ievetrouter router) throws java.lag.exceptio { ILogger logger = getlogger(); // TODO: a real adapter would eed to call ito the EIS to // determie ifay ew evets occured sice the last time this // method was ivoked. For the sake of example, we ll just post // a sigle evet every time this method gets ivoked...the // evet data will be the curret time o the // system formatted accordig to the evet defiitio...we ll // look for several evet types... Iterator evettypesiterator = getevettypes(); if (evettypesiterator.hasnext()) { do { // The evet router is still iterested i this type of evet 7-14 BEA WebLogic Applicatio Itegratio Developmet Guide

137 Step 3: Implemetig the Adapter IEvetDefiitio evetdef = (IEvetDefiitio) evettypesiterator.ext(); logger.debug("geeratig evet for " + evetdef.getname()); // Create a default evet (just blak/default data) IEvet evet = evetdef.createdefaultevet(); // Get the format for the evet java.util.map evetpropertymap = evetdef.getpropertyset(); Strig strformat = (Strig)evetPropertyMap.get("Format"); if( logger.isdebugeabled() ) logger.debug("format for evet type "+evetdef. getname()+" is "+strformat+" "); java.text.simpledateformat sdf = ew java.text.simpledateformat(strformat); IDocumet payload = evet.getpayload(); payload.setstrigifirst("/systemtime", sdf.format(ew Date())); // let s log a audit message for this... try { logger.audit(tostrig() + ": postevets >>> postig evet ["+payload.toxml()+"] to router"); } catch (Exceptio exc) { } logger.war(exc); // This call actually posts the evet to the IEvetRouter router.postevet(evet); } while (evettypesiterator.hasnext()); BEA WebLogic Applicatio Itegratio Developmet Guide 7-15

138 7 Developig a Evet Adapter } }// ed of postevets Addig New Evet Types A real adapter would eed to call ito the EIS to determie if ay ew evets occurred sice the last time this method was ivoked. You ca see a cocrete example of this i the DBMS adapter icluded with the ADK. Refer to the postevet() method i DbmsEvetGeeratorWorker.java, which is i: <WLAI_HOME>dev/dbms/com/bea/adapter/dbms/evet/ setupnewtypes() gets called durig refresh to hadle ay ew evet types. This allows us to perform ay setup we eed to hadle a ew type. The paret class has already saity-checked the listofnewtypes() ad logged it; so you do t eed to do that here. Listig 7-5 Sample Code Showig the Template for setupnewtypes() protected void setupnewtypes(java.util.list listofnewtypes) { Iterator iter = listofnewtypes.iterator(); while (iter.hasnext()) { IEvetDefiitio evettype = (IEvetDefiitio)iter.ext(); } } 7-16 BEA WebLogic Applicatio Itegratio Developmet Guide

139 Step 3: Implemetig the Adapter Removig Evet Types for Applicatio Views that are Udeployed removedeadtypes() is called durig refresh to hadle ay evet types for applicatio views that have bee udeployed. You will eed to perform a cleaup process to esure that this evet type is o loger hadled, such as closig resources eeded to hadle this specific evet type. Listig 7-6 shows how removedeadtypes() is implemeted. Listig 7-6 Sample Code Showig the Template for removedeadtypes() protected void removedeadtypes(java.util.list listofdeadtypes) { Iterator iter = listofdeadtypes.iterator(); while (iter.hasnext()) { IEvetDefiitio evettype = (IEvetDefiitio)iter.ext(); Removig Resources Fially, docleaupoquit() gets called whe the EvetGeerator is shuttig dow, This method removes ay resources allocated durig evet processig. The sample adapter stubs i this method. The template for implemetig this method is show i Listig 7-7. Listig 7-7 Sample Code Showig docleaupoquit() Method Call protected void docleaupoquit() throws java.lag.exceptio { ILogger logger = getlogger(); logger.debug(this.tostrig() + ": docleaupoquit"); } BEA WebLogic Applicatio Itegratio Developmet Guide 7-17

140 7 Developig a Evet Adapter } Step 3b: Implemet the Data Trasformatio Method Data trasformatio is the process of takig data from the EIS ad trasformig it ito a XML schema that ca be read by the applicatio server. For each evet, a schema will defie what the XML output looks like. This is accomplished by usig the SOM ad Documet class libraries. The followig code listigs show the data trasformatio sequece: Listig 7-8 shows the code used to trasform data from the EIS ito XML schema. Listig 7-9 shows the XML schema created by the code i Listig 7-8. Listig 7-10 shows the valid XML documet created by the schema show i Listig 7-9. Listig 7-8 Sample Code for Trasformig EIS Data ito XML Schema SOMSchema schema = ew SOMSchema(); SOMElemet root = ew SOMElemet("SENDINPUT"); SOMComplexType mailtype = ew SOMComplexType(); root.settype(mailtype); SOMSequece sequece = mailtype.addsequece(); SOMElemet to = ew SOMElemet("TO"); to.setmioccurs("1"); to.setmaxoccurs("ubouded"); sequece.add(to); SOMElemet from = ew SOMElemet("FROM"); from.setmioccurs("1"); from.setmaxoccurs("1"); 7-18 BEA WebLogic Applicatio Itegratio Developmet Guide

141 Step 3: Implemetig the Adapter sequece.add(from); SOMElemet cc = ew SOMElemet("CC"); cc.setmioccurs("1"); cc.setmaxoccurs("ubouded"); sequece.add(cc); SOMElemet bcc = ew SOMElemet("BCC"); bcc.setmioccurs("1"); bcc.setmaxoccurs("ubouded"); sequece.add(bcc); SOMElemet subject = ew SOMElemet("SUBJECT"); subject.setmioccurs("1"); subject.setmaxoccurs("1"); sequece.add(bcc); SOMElemet body = ew SOMElemet("BODY"); if (template == ull) { body.setmioccurs("1"); body.setmaxoccurs("1"); }else { Iterator iter = template.gettags(); if (iter.hasnext()) { SOMComplexType bodycomplex = ew SOMComplexType(); body.settype(bodycomplex); SOMAll all = ew SOMAll(); while (iter.hasnext()) { SOMElemet enew = ew SOMElemet((Strig)iter.ext()); all.add(enew); }//edwhile BEA WebLogic Applicatio Itegratio Developmet Guide 7-19

142 7 Developig a Evet Adapter bodycomplex.setgroup(all); }//edif }//edif sequece.add(body); schema.addelemet(root); Listig 7-9 XML Schema Created by Code i Listig 7-8 <xsd:schema xmls:xsd=" <xsd:elemet ame="sendinput"> <xsd:complextype> <xsd:sequece> <xsd:elemet ame="to" maxoccurs="ubouded" type="xsd: strig"/> <xsd:elemet ame="from" type="xsd:strig"/> <xsd:elemet ame="cc" maxoccurs="ubouded" type= "xsd:strig"/> <xsd:elemet ame="bcc" maxoccurs="ubouded" type= "xsd:strig"/> <xsd:elemet ame="bcc" maxoccurs="ubouded" type= "xsd:strig"/> <xsd:elemet ame="body" type="xsd:strig"/> </xsd:sequece> </xsd:complextype> </xsd:elemet> Listig 7-10 Valid XML Documet Created by Schema i Listig 7-9 </xsd:schema> 7-20 BEA WebLogic Applicatio Itegratio Developmet Guide

143 Step 4. Deployig the Adapter <?xml versio="1.0"?> <!DOCTYPE SENDINPUT> <SENDINPUT> <TO/> <FROM/> <CC/> <BCC/> <BCC/> <BODY/> </SENDINPUT> <xsd:schema xmls:xsd=" Step 4. Deployig the Adapter To deploy the evet adapter, you eed to deploy the EvetGeerator o a J2EE servlet egie outside of the BEA WebLogic Applicatio Itegratio egie. To do this, you eed to budle the EvetGeerator as a web applicatio, WEB-INF/web.xml. Rather tha create this file from scratch, we recommed that you use the GeerateAdapterTemplate utility to cloe ad customize a developmet eviromet for your adapter. Ruig this utility will modify the web.xml file i the sample adapter for use with the adapter you are developig. For more iformatio o usig GeerateAdapterTemplate, see Creatig a Custom Developmet Eviromet. Add EvetRouterServlet to.war File The EvetRouter is a.war file used to deploy your EvetGeerator ad is required for ay adapter supportig evets. It will be the URL that you will use i the desig-time iterface to deploy the evet adapter. Because it is a.war file, it requires a associated web.xml file for deploymet. BEA WebLogic Applicatio Itegratio Developmet Guide 7-21

144 7 Developig a Evet Adapter The EvetRouterServlet is resposible for iitializig ad startig the Applicatio Itegratio evet process. The web.xml file cotais iitializatio parameters for the EvetRouterServlet, some of which are show i Table Listig 7-11 EvetRouterServlet Elemet of web.xml <servlet> <servlet-ame>evetrouterservlet</servlet-ame> <descriptio>provides access to evet router withi WLAI</descriptio> <servlet-class>com.bea.wlai.evet.evetrouterservlet</servlet-c lass> <!-- Or jsp-file --> <iit-param> <param-ame>evetgeeratorclassname</param-ame> <param-value> .evet.pullevetgeerator</param-value> <descriptio>the fully qualified class ame of the IEvetGeerator implemetatio class</descriptio> </iit-param> <iit-param> <param-ame>wlsuserid</param-ame> <param-value>system</param-value> <descriptio>the user id o the WLAI server that this evet router will talk to to get schemas, etc.</descriptio> </iit-param> <iit-param> <param-ame>wlspassword</param-ame> <param-value>weblogic</param-value> <descriptio>the password for wlsuserid</descriptio> </iit-param> 7-22 BEA WebLogic Applicatio Itegratio Developmet Guide

145 Step 4. Deployig the Adapter... <load-o-startup>1</load-o-startup> </servlet> You eed to assig values to several iitializatio parameters prior to creatig the EvetRouter. These parameters are described i Table 7-3. Table 7-3 Evet Router Iitializatio Parameters Parameter Descriptio Value EvetRouterServlet evetgeeratorclassname wlsuserid wlspassword username Class ame for the evet router servlet. Do ot chage this value. Class ame for the EvetGeerator. This is the fully qualified class ame for your EvetGeerator. User ID for Weblogic Server. This user ID will be used to coect to weblogic i order to retrieve the Schema s associated with this evet adapter. Password for Weblogic Server. This is the user ame for the EIS the EvetGeerator will be coectig to. com.bea.wlai.evet.evetrouter- Servlet .evet.pushevetgeerator system weblogic userame BEA WebLogic Applicatio Itegratio Developmet Guide 7-23

146 7 Developig a Evet Adapter Table 7-3 Evet Router Iitializatio Parameters (Cotiued) Parameter Descriptio Value password coectiourl RootLogCotext AdditioalLogCotext LogCofigFile MessageBudleBase Password for the EIS coectio. URL describig the locatio for the EIS Base log cotext. If o additioal log cotext is specified this will be the cotext for the EvetGeerator. Used to further sub-categorize the loggig messages. The additioal log cotext ca be used to idetify loggig messages from a specific cotext. The AdditioalLogCotext is used i cojuctio with the RootLogCotext to idetify a ew Log Cotext; that is: (root.additioall og- Cotext) The log cofiguratio file for this adapter. The log cofiguratio file cotais a XML documet with setup parameters for the log utility. Base ame for message budles. Base ame ad laguage code are used to idetify a specific istace of a message budle. password server.domai.com adapterlogicname sub-category fileame.xml fileame 7-24 BEA WebLogic Applicatio Itegratio Developmet Guide

147 Step 4. Deployig the Adapter Table 7-3 Evet Router Iitializatio Parameters (Cotiued) Parameter Descriptio Value LaguageCode CoutryCode sleepcout Preferred laguage code for log messages Preferred coutry code for log messages. Cout betwee iteratios. This is the time betwee calls to the postevets method for the PullEvetGeerator. This cout is give i millisecods. e US 5000 The web.xml file also cotais servlet directives ad security costraits. Refer to the WebLogic documetatio for a descriptio of these attributes. Create the EvetRouter.war file To make the EvetRouter.war file you must iclude the followig.jar files i your.war file: log4j.jar wlai-commo.jar wlai-ejb-cliet.jar wlai-evetrouter.jar wlai-servlet-cliet.jar logtoolkit.jar adk-evetgeerator.jar Also add ay other.jar file upo which your EvetGeerator is depedet. These are specified i the <evetrouter> target i the build.xml file, as show i Listig BEA WebLogic Applicatio Itegratio Developmet Guide 7-25

148 7 Developig a Evet Adapter Listig 7-12 Addig.jar Files to the evetrouter Target of build.xml <target ame= evetrouter_war depeds= jar,evetrouter_jar > <delete file= ${LIB_DIR}/${EVENTROUTER_WAR_FILE} /> <delete dir= ${SRC_DIR}/evetrouter/WEB-INF/lib /> <war warfile= ${LIB_DIR}/${EVENTROUTER_WAR_FILE} webxml= ${SRC_DIR}/evetrouter/WEB-INF/web.xml > <fileset dir= ${PROJECT_DIR} icludes= versio_ifo.xml /> <fileset dir= ${SRC_DIR}/evetrouter excludes= WEB-INF/ web.xml /> <lib dir= ${LIB_DIR} icludes= ${JAR_FILE}, ${EVENTROUTER_JAR_FILE} /> <lib dir= ${WLAI_LIB_DIR} icludes= adk.jar,adkevetgeerator.jar,bea.jar,logtoolkit.jar,wlai-commo.jar,wlai-ej b-cliet.jar,wlai-evetrouter.jar,wlai-servlet-cliet.jar,xmltool kit.jar /> <lib dir= ${RESOURCE_DIR}/log4j icludes= log4j.jar /> </war> </target> Step 5: Testig the Adapter You ca test the adapter by usig the adapter test haress provided with the Applicatio Itegratio. See Step 6: Testig the Adapter i Developig a Service Adapter for a complete descriptio of this tool ad istructios for usig it BEA WebLogic Applicatio Itegratio Developmet Guide

149 CHAPTER 8 Developig a Desig-Time GUI The ADK s desig-time framework provides the tools you will use to build the web-based GUI that adapter users eed to defie, deploy, ad test their applicatio views. Although each adapter has EIS-specific fuctioality, all adapters require a GUI for deployig applicatio views. The desig-time framework miimizes the effort required to create ad deploy these iterfaces, primarily by usig these two compoets: A web applicatio compoet that allows you to build a HTML-based GUI by usig Java Server Pages (JSP). This compoet is augmeted by tools such as the JSP templates ad tag library ad the JavaScript library. The abstractdesigtimerequesthadler class, which provides a simple API for deployig, udeployig, copyig, ad editig applicatio views o a Applicatio Itegratio server. This sectio icludes iformatio o the followig subjects: Itroductio to Desig-Time Form Processig Desig-Time Features l Java Server Pages l JSP Templates l The ADK Tag Library l JavaScript Library l The Applicatio View File Structure BEA WebLogic Applicatio Itegratio Developmet Guide 8-1

150 8 Developig a Desig-Time GUI The Flow of Evets Step 1: Developmet Cosideratios Step 2: Determiig the Scree Flow l l l l l l l l l Scree 1: Loggig I Scree 2. Maagig Applicatio Views Scree 3: Defiig the New Applicatio View Scree 4: Cofigurig the Coectio Scree 5: Admiisterig the Applicatio View Scree 6: Addig a Evet Scree 7: Addig a Service Scree 8: Deployig a Applicatio View Scree 9: Summarizig the Applicatio View Step 3: Cofigurig the Developmet Eviromet l l Step 3a: Create the Message Budle Step 3b: Cofigure the Eviromet to Update JSPs Without Restartig the WebLogic 6.0 Server Step 4: Implemetig the Desig-Time GUI l l Step 4a. Supply the MaagedCoectioFactory Class Step 4b. Implemet iitservicedescriptor() Step 5: Write the HTML Forms l l l l l Step 5a: Create the cofco.jsp Form Step 5b: Create the addevet.jsp form Step 5c: Create the addservc.jsp form Step 5d: Create display.jsp Step 5e: Write the WEB-INF/web.xml Web Applicatio Deploymet Descriptor Step 7. Implemetig the Look-ad-Feel 8-2 BEA WebLogic Applicatio Itegratio Developmet Guide

151 Itroductio to Desig-Time Form Processig Itroductio to Desig-Time Form Processig There are a variety of approaches to processig forms usig Java Servlets ad JSPs. The basic requiremets of ay form processig approach are: 1. Display a HTML form. To accomplish this task, you must: l Geerate the form layout usig HTML. l Idicate to the user which fields are madatory. l Prepopulate fields with defaults, if ay. 2. Whe the user submits the form data, validate the field values i the HTTP request. To accomplish this task, you must: l Supply logic to determie if all madatory fields have a value. l For each value submitted, validate it agaist a set of costraits; for example, seeig if a age field is a valid iteger betwee 1 ad If ay field values are ivalid, the form must be redisplayed to the user with a error message ext to each erroeous field o the form. The error message should be localized for the user s preferred locale if the web applicatio supports multiple locales. I additio, the user s last iput should be redisplayed so they do ot have to re-iput ay valid iformatio. The web applicatio should cotiue with Step 2 ad loop as may times as eeded util all fields submitted are valid. 4. Oce all fields have passed coarse-graied validatio, the form data must be processed. While processig the form data, a error coditio may be ecoutered that does ot relate to idividual field validatio, such as a Java exceptio. The form will eed to be re-displayed to the user with a localized error message at the top of the page. As with step 3, all iput fields should be saved so the user does ot have to re-eter ay valid iformatio. To accomplish this task, the web applicatio developer must: l Determie which object or method implemets the form processig API. BEA WebLogic Applicatio Itegratio Developmet Guide 8-3

152 8 Developig a Desig-Time GUI l Determie how ad whe to advace the user to the ext page i the web applicatio. 5. If the form processig succeeds, the ext page i the web applicatio is displayed to the user. Form Processig Classes RequestHadler CotrollerServlet As you ca imagie, or have experieced, implemetig all these steps for every form i a web applicatio is quite a tedious ad error proe developmet process. The ADK Desig Time Framework simplifies this process by usig a Model-View-Cotroller paradigm. There are five classes ivolved i the form processig mechaism: com.bea.web.requesthadler This class provides HTTP request processig logic. This class is the Model compoet of the MVC-based mechaism. This object is istatiated by the CotrollerServlet ad saved i the HTTP sessio uder the key hadler. The ADK provides the com.bea.adapter.web.abstractdesigtimerequesthadler. This abstract base class implemets fuctioality eeded to deploy a applicatio view that is commo across all adapters. You will eed to exted this class to supply adapter/eis specific logic. com.bea.web.cotrollerservlet This class is resposible for receivig a HTTP request, validatig each value i the request, delegatig the request to a RequestHadler for processig, ad determiig which page to display to the user. The CotrollerServlet uses Java reflectio to determie which method to ivoke o the RequestHadler. The CotrollerServlet looks for a HTTP request parameter amed doactio to idicate the ame of the method that implemets the form processig logic. If this parameter is ot available, the CotrollerServlet does ot ivoke ay methods o the RequestHadler. 8-4 BEA WebLogic Applicatio Itegratio Developmet Guide

153 Itroductio to Desig-Time Form Processig The CotrollerServlet is cofigured i the web.xml file for the web applicatio. The CotrollerServlet is resposible for delegatig HTTP requests to a method o a RequestHadler. You do t eed to provide ay code to use the CotrollerServlet. However, you must supply the iitial parameters listed i Table 8-5: ActioResult com.bea.web.actioresult Word ad Its Descedats ActioResult ecapsulates iformatio about the outcome of processig a request. Also provides iformatio to the CotrollerServlet to help it determie the ext page to display to the user. com.bea.web.validatio.word All fields i a web applicatio require some validatio. The com.bea.web.validatio.word ad its descedats supply logic to validate form fields. If ay fields are ivalid, the Word object uses a message budle to retrieve a iteratioalized/localized error message for the field. The ADK supplies the custom validators described i Table 8-1. Table 8-1 Custom Validators for Word Object Validator Iteger Float/Double Idetifier Perl 5 Regular Expressio URL Descriptio Determies if the value for a field is a iteger withi a specified rage. Determies if the value for a field is a floatig poit value withi a specified rage. Determies if the value for a field is a valid Java idetifier. Determies if the value for a field matches a Perl 5 regular expressio. Determies if the supplied value is a valid URL Determies if the supplied value cotais a list of valid addresses. BEA WebLogic Applicatio Itegratio Developmet Guide 8-5

154 8 Developig a Desig-Time GUI Table 8-1 Custom Validators for Word Object (Cotiued) Validator Date Descriptio Determies if the supplied value is a valid date usig a specified date/time format AbstractIputTagSupport ad Its Descedats com.bea.web.tag.abstractiputtagsupport The tag classes provided by the Web toolkit are resposible for: Geeratig the HTML for a form field ad pre-populatig its value with a default, if applicable. Displayig a localized error message ext to the form field if the supplied value is ivalid. Iitializig a com.bea.web.validatio.word object ad savig it i web applicatio scope so that the validatio object is accessible by the CotrollerServlet usig the form field s ame. Submit Tag Additioally, the ADK provides a submit tag, such as: <adk:submit ame= xyz_submit doactio= xyz /> This tag esures the doactio parameter is passed to the CotrollerServlet i the request. This results i the CotrollerServlet ivokig the xyz method o the registered RequestHadler. Form Processig Sequece This sectio discusses the sequece i which forms are processed. Figure 8-1 shows how forms are processed. 8-6 BEA WebLogic Applicatio Itegratio Developmet Guide

155 Itroductio to Desig-Time Form Processig Prerequisites Before forms ca be processed, the followig must occur: 1. Whe a JSP cotaiig a custom ADK iput tag is beig writte to the HTTP respose object, the tag esures that it iitializes a istace of com.bea.web.validatio.word ad places it ito the web applicatio scope, keyed by the iput field ame. This makes the validatio object available to the CotrollerServlet so that it ca perform coarse-graied validatio o a HTTP request prior to submittig the request to the RequestHadler. For example, <adk:it ame= age miiclusive= 1 maxiclusive= 120 required= true /> 2. The HTML for this tag will be geerated whe the JSP egie ivokes the dostarttag() method o a istace of com.bea.web.tag.itegertagsupport. The ItegerTagSupport istace will istatiate a ew istace of com.bea.web.validatio.itegerword ad add it to web applicatio scope uder the key age. Cosequetly, the CotrollerServlet ca retrieve the ItegerWord istace from its ServletCotext wheever it eeds to validate a value for age. The validatio will esure that ay value passed for age is greater tha or equal to 1 ad less tha or equal to Lastly, the HTML form must also submit a hidde field amed doactio. The value of this parameter is used by the CotrollerServlet to determie the method o the RequestHadler that ca process the form. Followig these prerequisites, the JSP form appears as show i Listig 8-1: Listig 8-1 Sample JSP Form <form method= POST actio= cotroller > Age: <adk:it ame= age miiclusive= 1 maxiclusive= 120 required= true /> <adk:submit ame= processage_submit doactio= processage /> </form> BEA WebLogic Applicatio Itegratio Developmet Guide 8-7

156 8 Developig a Desig-Time GUI Steps i the Sequece The sequece diagram show i Figure 8-1 illustrates the trasactios that occur durig form processig. Figure 8-1 UI Form Processig Sequece Diagram The sequece is as follows: 1. User submits the form with age=10, doactio=processage. 2. CotrollerServlet retrieves the age field from the HTTP request. 3. CotrollerServlet retrieves a com.bea.web.validatio.word object from its ServletCotext usig key age. The object is a istace of com.bea.web.validatio.itegerword. 8-8 BEA WebLogic Applicatio Itegratio Developmet Guide

157 Desig-Time Features 4. CotrollerServlet ivokes the validate() method o the Word istace ad passes 10 as a parameter. 5. The Word istace determies that the value 10 is greater tha or equal to 1 ad is less tha or equal to 120. The Word istace returs true to idicate that the value is valid. 6. The CotrollerServlet retrieves the RequestHadler from the sessio or creates it ad adds it to the sessio as hadler. 7. The CotrollerServlet uses the Java Reflectio API to locate ad ivoke the processage() method o the RequestHadler. A exceptio is geerated if the method does ot exist. The method sigature is: public ActioResult processage(httpservletrequest request) throws Exceptio 8. The RequestHadler processes the form iput ad returs a ActioResult object to idicate the outcome of the processig. The ActioResult cotais iformatio used by the CotrollerServlet to determie the ext page to display to the user. The ext page iformatio should be the ame of aother JSP or HTML page i your web applicatio; for example, thaks would display the thaks.jsp page to the user. 9. The the ActioResult is a success, the the CotrollerServlet redirects the HTTP respose to the display page for the web applicatio. I the ADK, the display page is typically display.jsp. 10. The display.jsp icludes the JSP idicated by the cotet parameter; for example, thaks.jsp, ad displays it to the user. Desig-Time Features Desig-time developmet has its ow features, differet from those associated with rutime adapter developmet. This sectio describes those features. BEA WebLogic Applicatio Itegratio Developmet Guide 8-9

158 8 Developig a Desig-Time GUI Java Server Pages A desig-time GUI is comprised of a set of 11 Java Server Pages. JSPs are simply HTML pages that call Java servlets, which ivoke some trasactio. To the user, the JSP looks just like ay other web page. The JSPs that comprise a desig-time GUI are: Table 8-2 Desig-Time GUI JSPs Fileame display.jsp logi.jsp cofco.jsp appvwadmi.jsp addevet.jsp addservc.jsp depappvw.jsp Descriptio The display page, also called the Adapter Home Page; this page cotais the HTML ecessary to create the look-ad-feel of the applicatio view. For istructios o usig this page, please refer to Step 5d: Create display.jsp. This page is supplied by the ADK. The Adapter Desig Time Logi page. The Cofirm Coectio page; this page provides a form for the user to specify coectio parameters for the EIS. The Applicatio View Admiistratio page; this page provides a summary of a udeployed applicatio view. The Add Evet page; this page allows the user to add a ew evet to the applicatio view. The Add Service page; this page allows the user to add a ew service to the applicatio view. The Deploy Applicatio View page; this page allows the user to specify deploymet properties BEA WebLogic Applicatio Itegratio Developmet Guide

159 Desig-Time Features Table 8-2 Desig-Time GUI JSPs (Cotiued) Fileame appvwsum.jsp Descriptio The Summary page; this page displays the followig iformatio about a applicatio view: Deployed State; that is, whether the applicatio view is deployed or udeployed Coectio Criteria Deploymet Iformatio (poolig cofiguratio, log level, ad security) List of Evets List of Services For a discussio o how to implemet these JSPs, please refer to Step 2: Determiig the Scree Flow. JSP Templates The desig-time framework provides a set of JSP templates for rapidly assemblig a web applicatio to defie, deploy, ad test a ew applicatio view for a adapter. A template is a HTML page that is dyamically geerated by a Java Servlet based o parameters provided i the HTTP request. Templates are used to miimize the umber of custom pages ad custom HTML eeded for a web applicatio. The templates supplied by the ADK provide three primary features for adapter developers. The ADK desig-time templates provide most of the HTML forms eeded to deploy a applicatio view. I most cases, you will oly have to supply three custom forms: l l l Oe to collect the EIS-specific coectio parameters. A secod to collects the EIS-specific iformatio eeded to add a evet. A third to collect the EIS-specific iformatio eeded to add a service. I additio, you ca supply a custom JSP for browsig a metadata catalog for a EIS. The templates also leverage the iteratioalizatio ad localizatio features of the Java platform. The cotet of every page i the web applicatio is stored i a BEA WebLogic Applicatio Itegratio Developmet Guide 8-11

160 8 Developig a Desig-Time GUI message budle. Cosequetly, the web iterface for a adapter ca be quickly iteratioalized. The templates cetralize look-ad-feel ito a sigle locatio. Refer to Developig a Desig-Time GUI for a complete list of JSP templates provided by the ADK. The ADK Tag Library The JSP tag library helps to develop user-friedly HTML forms ad abstracts complexity from the adapter page developers. Custom tags for form iput compoets allow page developers to seamlessly lik to the validatio mechaism. Custom tags are provided for the followig HTML iput tags: Table 8-3 ADK JSP Tags Tag adk:check box adk:cotet adk:date adk:double adk: adk:float adk:idetifier adk:it adk:label adk:password adk:submit Descriptio Determies if the checkbox form field should be checked whe a form is displayed; this tag does ot perform validatio. Provides access to a message i the message budle. Verifies the user s iput is a date value that meets a specific format. Verifies the user s iput is a double value. Verifies the user s iput is a vaadklid list of addresses (oe or more). Verifies the user s iput is a float value. Verifies the user s iput is a valid Java idetifier. Verifies the user s iput is a iteger value. Displays a label from the message budle. Verifies the user s iput i a text field agaist a Perl 5 regular expressio ad maskes the iput with a asterisk (*). Liks the form to the validatio mechaism BEA WebLogic Applicatio Itegratio Developmet Guide

161 Desig-Time Features Table 8-3 ADK JSP Tags (Cotiued) Tag adk:text adk:textarea adk:url Descriptio Verifies the user s iput agaist a Perl 5 regular expressio. Verifies the user s iput ito a text area matches a Perl 5 regular expressio. Verifies the user s iput is a valid URL. JSP Tag Attributes Table 8-4 JSP Tag Attributes You ca customize the JSP tags by applyig the attributes listed i Table 8-4: Tag adk:it, adk:float, adk:double Requires Attributes ame - field ame Optioal Attributes default - default value o page display maxlegth - maximum legth of value size - display size miiclusive - value supplied by user must be greater tha or equal to this value maxiclusive - value supplied by user must be less tha or equal to this value miexclusive - value supplied by user must be strictly greater tha this value maxexclusive - value supplied by user must be strictly less tha this value required - (default is false, ot required) attrs - additioal HTML attributes BEA WebLogic Applicatio Itegratio Developmet Guide 8-13

162 8 Developig a Desig-Time GUI Table 8-4 JSP Tag Attributes (Cotiued) Tag Requires Attributes Optioal Attributes adk:date ame - field ame default - default value o page display maxlegth - maximum legth of value size - display size required - (default is false, field is ot required) attrs - additioal HTML attributes leiet - should the date formatter be leiet i its parsig? default is false format - the expected format of the user s iput, default is MM/dd/yyyy adk: , adk:url, adk:idetifier adk:text, adk:password ame - field ame ame - field ame default - default value o page display maxlegth - maximum legth of value size - display size required - (default is false, field is ot required) attrs - additioal HTML attributes default - default value o page display maxlegth - maximum legth of value size - display size required - (default is false, field is ot required) attrs - additioal HTML attributes patter - a Perl 5 regular expressio adk:textarea ame - field ame default - default value o page display required - (default is false, field is ot required) attrs - additioal HTML attributes patter - a Perl 5 regular expressio rows - umber of rows to display colums - umber of colums to display Note: For more iformatio o tag usage, see adk.tld i: <WLAI_ROOT>\dev\adk\src\war\WEB-INF\taglibs 8-14 BEA WebLogic Applicatio Itegratio Developmet Guide

163 File Structure JavaScript Library The ADK provides JavaScript for opeig ad closig child widows. The Applicatio View The applicatio view represets a busiess-level iterface to the specific fuctioality i a applicatio. For more iformatio, see The Applicatio View i Itroductio to the ADK. File Structure The file structure ecessary to build a desig-tim GUI adapter is the same as that required for service adapters. See Step 2a: Set Up the File Structure. I additio to the structure described there, you should also be aware that: The desig-time iterface for each adapter is a J2EE web applicatio that is budled as a.war file. A web applicatio is a budle of.jsp,.html ad image files. The web applicatio descriptor is WEB-INF/web.xml. This descriptor istructs the J2EE web cotaier how to deploy ad iitialize the web applicatio. The Flow of Evets Figure 8-2 outlies the steps required to develop a desig-time GUI. Figure 8-2 Desig-Time GUI Developmet Flow of Evets BEA WebLogic Applicatio Itegratio Developmet Guide 8-15

164 8 Developig a Desig-Time GUI 8-16 BEA WebLogic Applicatio Itegratio Developmet Guide

165 Step 1: Developmet Cosideratios Step 1: Developmet Cosideratios These are the items you eed to cosider before commecig with desig-time GUI developmet: Determie the adapters to be supported. Will this GUI support evet adapters? Service adapters? Both? Determie browsig. The EIS must supply fuctios to access the evet/service catalog. If the EIS does ot supply these, the user ca t browse the catalogs. If the EIS does supply them, we recommed the followig desig priciple: a call from the desig-time UI to get metadata from the EIS is really o differet tha a call from a rutime compoet. Both execute fuctios o the back-ed EIS. Cosequetly, you eed to leverage your rutime architecture as much as possible to provide the desig-time metadata features. You should ivoke desig time specific fuctios that use a CCI Iteractio object. The sample adapter icluded with the ADK provides a example/framework of this approach. Note: For examples of typical browse sequeces, see How the DBMS Sample Adapter Works i The DBMS Sample Adapter or How the Sample Adapter Works i The Sample Adapter. Determie schema geeratio. How will the adapter geerate the request/respose schema for a service? Will it make a call to the EIS or use some other methodology? Geerally, the adapter eeds to call the EIS to get metadata about a fuctio or evet. The adapter the trasforms the EIS metadata ito XML schema format. To make this happe, you eed to ivoke the SOM API. Agai, the sample adapter provides istructios for implemetig the SOM API. For more iformatio o this API, see The ADK Tag Library. Determie the testig prerequisites. Will some sort of service testig be supported? If so, you eed to provide: l A class that trasforms the XML respose schema ito a HTML form. For a example, see: BEA WebLogic Applicatio Itegratio Developmet Guide 8-17

166 8 Developig a Desig-Time GUI l <WLAI_HOME>/dev/dbms/docs/api/com/bea/adapter/dbms/utils/ TestFormBuilder.html A JSP amed testform.jsp that ivokes the trasformatio ad displays the HTML form. To see a example of this file, go to <WLAI_HOME>/dev/dbms/war/. Step 2: Determiig the Scree Flow Next, you eed to determie the order i which the JSPs will appear whe the user displays the applicatio view. This sectio describes the basic, required scree flow for a successful applicatio view. Note that these are miimum requiremets, as you ca add more screes to the flow to meet your specific eeds. Scree 1: Loggig I The applicatio view is a secure system, therefore, the user will eed to log i before he or she ca implemet the view. The Applicatio View Maagemet Logi page thus must be the first page the user sees. To use this page, the user supplies a valid userame ad password. That iformatio is the validated to esure that the user is a member of the adapter group i the default WebLogic security realm. Note: The security for the Applicatio View Maagemet web applicatio is specified i the WEB-INF/web.xml file, which is shipped i the wlai.war file. Scree 2. Maagig Applicatio Views Oce the user successfully logs i, the Applicatio View Maagemet page appears. This page lists the folders that cotai the applicatio views, the status of these folders, ad ay actio take o them. From this page, the user ca either view existig applicatio views or add ew oes BEA WebLogic Applicatio Itegratio Developmet Guide

167 Step 2: Determiig the Scree Flow To view a existig applicatio view, the user clicks the appropriate folder ad drills dow to the desired applicatio view. The user the selects the applicatio view ad the Applicatio View Summary page appears (appvwsum.jsp; see Scree 9: Summarizig the Applicatio View ). To add a ew applicatio view, the user clicks Add Applicatio View, which will display the Defie New Applicatio View page. Scree 3: Defiig the New Applicatio View The Defie New Applicatio View page (defappvw.jsp) allows the user to defie a ew applicatio view i ay folder i which the cliet is located. To do this, the user eeds to provide a descriptio that associates the applicatio view with a adapter. This form provides text boxes for eterig the applicatio view ame ad descriptio ad a drop-dow list box displayig adapters with which the user ca associate the applicatio view. Oce the ew adapter is defied, the user selects OK ad the Cofigure Coectio page appears. Scree 4: Cofigurig the Coectio If the ew applicatio view is valid, the user will eed to cofigure the coectio. Therefore, oce the applicatio view is validated, the ext scree i the flow should be the Cofigure Coectio page (cofco.jsp). This page provides a form for the user to specify coectio parameters for the EIS. Sice coectio parameters are specific to every EIS, this page is differet across all adapters. Whe the user submits the coectio parameters, the adapter attempts to ope a ew coectio to the EIS usig the parameters. If successful, the user is forwarded to the ext page, Applicatio View Admiistratio. BEA WebLogic Applicatio Itegratio Developmet Guide 8-19

168 8 Developig a Desig-Time GUI Scree 5: Admiisterig the Applicatio View With a ew applicatio view created, the user will eed a way of admiisterig it. Therefore, the ext scree i the flow should be the Applicatio View Admiistratio page (appvwadmi.jsp). This page provides a summary of a udeployed applicatio view. Specifically, it shows the followig: Coectio criteria The coectio criteria sectio provides a lik that returs the user to the Cofigure Coectio page so that he or she ca chage coectio parameters. List of evets For each evet o the applicatio view, the user ca do the followig: l View the XML schema. l Remove the evet. Whe the user chooses to remove the evet, the system cofirms this before removig the evet. l Provide evet properties. List of services For each service o the applicatio view, the user ca do the followig: l View the request XML schema. l View the respose XML schema. l Remove the service. Whe the user chooses to remove the service, the system will cofirm that choice before removig the evet. l Provide service properties. I additio to providig a list of evets ad a list of services o the applicatio view, the page provides a lik to add a ew evet or service. Scree 6: Addig a Evet The user will obviously eed to add ew evets to a applicatio view. Therefore, the Applicatio View Admiistratio page cotais a lik to the Add Evet page (addevet.jsp). This page allows the user to add a ew evet to the applicatio view BEA WebLogic Applicatio Itegratio Developmet Guide

169 Step 2: Determiig the Scree Flow The followig rules apply to a ew evet: Every evet must have a uique ame. l l l The evet ame ca oly cotai a-z, A-Z, 0-9, ad uderscore (_) ad must begi with a letter. Spaces, dots, commas, ad so o are ot allowed. The legth of the ame caot exceed 256 characters. The evet ame must be uique to the applicatio view. If the user specifies a evet ame that is ot uique, the form will reload with a error message idicatig that the evet is already defied. Optioally, the user ca specify a descriptio for the evet. This descriptio caot exceed 2048 (2K) characters. I additio to ame ad descriptio, every evet has EIS specific parameters. The collectio of EIS-specific parameters defie a evet type for the adapter. Optioally, some adapters provide a mechaism for browsig the evet catalog for a EIS. After addig ad savig a ew evet, the user will be retured to the Applicatio View Admiistratio page. Scree 7: Addig a Service As with evets, the user will also eed to add ew services to a applicatio view. Therefore, the Applicatio View Admiistratio page cotais a lik to the Add Service page (addservc.jsp). This page allows the user to add a ew service to the applicatio view. The followig rules apply to a ew evet: Every service must have a uique ame. l The service ame ca oly cotai a-z, A-Z, 0-9, ad uderscore (_) ad must begi with a letter. Spaces, dots, commas, ad so o are ot allowed. l l The legth of the ame caot exceed 256 characters. The service ame must be uique to the applicatio view. If the user specifies a service ame that is ot uique, the form will reload with a error message idicatig that the service is already defied. BEA WebLogic Applicatio Itegratio Developmet Guide 8-21

170 8 Developig a Desig-Time GUI Optioally, the user ca specify a descriptio for the service. This descriptio caot exceed 2048 (2K) characters. I additio to ame ad descriptio, every service has EIS specific parameters. The collectio of EIS specific parameters defie a service type for the adapter. Optioally, some adapters provide a mechaism for browsig the service catalog for a EIS. After addig ad savig a ew service, the user will be retured to the Applicatio View Admiistratio page. Scree 8: Deployig a Applicatio View Oce the user adds at least oe service or evet, he or she ca deploy the applicatio view. Deployig a applicatio view makes it available to process evets ad services. If the user chooses to deploy the applicatio view, he or she will be forwarded to the Deploy Applicatio View page (depappvw.jsp). This scree allows the user to specify deploymet properties. The user ca specify: Coectio poolig parameters l Miimum pool size: must be greater tha or equal to 0 l Maximum pool size: must be greater tha or equal to oe. l Target fractio of maximum pool size: must be greater tha zero ad less tha oe. l Allow Pool to Shrik: is the coectio pool allowed to shrik? Loggig level: The user ca specify oe of four loggig levels l l l l Log all messages Log iformatioals, warigs, errors, ad audit messages Log warigs, errors, ad audit messages Log errors ad audit messages Security: The user ca access a form to apply security restrictios for the applicatio view by clickig o the lik that reads Restrict Access. This creates a child widow BEA WebLogic Applicatio Itegratio Developmet Guide

171 Step 2: Determiig the Scree Flow Cotrollig User Access The user ca grat or revoke a user s access privileges by specifyig a user or group ame i the form provided. Each applicatio view has two types of access: read ad write. Read access allows the user to execute services ad subscribe to evets. Write access allows the user to deploy/edit/udeploy the applicatio view. Deployig the Applicatio View The user deploys the applicatio view by clickig the deploy butto. He or she must decide whether or ot the applicatio view should be deployed persistetly. Persistet deploymet meas that the applicatio view will be redeployed wheever the applicatio server is restarted. Savig the Applicatio View The user ca save a udeployed applicatio view ad retur to it later via the Applicatio View Maagemet Cosole. This process assumes that all deployed applicatio views are saved i the repository. I other words, deployig a usaved applicatio view will automatically save it. Scree 9: Summarizig the Applicatio View Upo successful applicatio view deploymet, the user will be forwarded to the Applicatio View Summary page (appvwsum.jsp). This page provides the followig iformatio about a applicatio view: Deployed state: Deployed or Udeployed l If the applicatio view is deployed: The page will show a lik to udeploy the applicatio view. If the user chooses the Udeploy lik, a child widow will ask the user to cofirm his choice to udeploy the applicatio view. If the user cofirms, the applicatio view will be udeployed ad the summary page will be redisplayed. Udeployed applicatio views are still saved i the repository. This allows the user to edit or remove the applicatio view. BEA WebLogic Applicatio Itegratio Developmet Guide 8-23

172 8 Developig a Desig-Time GUI l If the adapter supports the testig of evets, the Summary page displays a test lik for each evet. Testig of evets is ot directly supported by the ADK. Also, if the adapter supports the testig of services, the summary page will display a test lik for each service. The ADK demostrates oe possible approach to testig services by providig the testservc.jsp ad testrslt.jsp files. You are free to use these pages to devise your ow service testig strategy. If the applicatio view is ot deployed: The page will show a Lik to Deploy the applicatio view. If the user chooses the Deploy lik, the applicatio view will be deployed ad the applicatio view summary page will reload. The page will show a lik to edit the applicatio view. If the user chooses the Edit lik, a child widow ask the user to cofirm his or her choice to edit the applicatio view. If the user cofirms the choice to edit, the Applicatio View Admiistratio page appears. The page will show a lik to remove the applicatio view. If the user chooses the Remove lik, a child widow will ask the user to cofirm his or her choice to remove the applicatio view from the ADK repository. If the user cofirms, the applicatio view will be deleted from the Applicatio Itegratio repository ad the user will be redirected to the adapter mai page. Coectio criteria Deploymet iformatio (poolig cofiguratio, log level, ad security) List of evets: For each evet, there will be a lik to view the schema ad, if supported, to test the evet. The user caot remove evets from this page; they must choose to edit first. List of services: For each service, the page will cotai a lik to view the request schema ad the respose schema, ad, if supported, to test the service. The user caot remove services from this page; they must udeploy ad edit first BEA WebLogic Applicatio Itegratio Developmet Guide

173 Step 3: Cofigurig the Developmet Eviromet Step 3: Cofigurig the Developmet Eviromet This step describes the processes you must complete to prepare your computer for desig-time GUI developmet. Step 3a: Create the Message Budle Next, you eed to create the message budle. Ay message destied for the ed-user should be placed i a message budle. This budle is simply a.properties text file that cotais key=value pairs that allow you to iteratioalize messages. Whe a locale ad atioal laguage are specified at rutime, the cotets of the message is iterpreted, based upo the key=value pair ad the message is preseted to the user i the correct laguage for his or her locale. For istructios o creatig a message budle, please refer to the JavaSoft tutorial o iteratioalizatio at: java.su.com/docs/books/tutorial/i18/idex.html Step 3b: Cofigure the Eviromet to Update JSPs Without Restartig the WebLogic 6.0 Server The desig-time UI is deployed as a J2EE web applicatio from a.war file. A.war file is simply a.jar file with a web applicatio descriptor i WEB-INF/web.xml i the.jar file. However, the.war file does ot allow the J2EE Web cotaier i WebLogic 6.0 to re-compile JSP s o the fly. Cosequetly, you ormally have to restart your WebLogic server just to chage a JSP file. Sice this goes agaist the spirit of JSP, the ADK suggests the followig workaroud to eable you to update JSPs without restartig WebLogic Server 6.0: BEA WebLogic Applicatio Itegratio Developmet Guide 8-25

174 8 Developig a Desig-Time GUI 1. Costruct a valid.war file for your adapter s desig time UI. For the sample adapter, this is accomplished by usig At. Listig 8-2 shows the target that produces the J2EE.war file: Listig 8-2 Sample Code Showig Target that Creates a.war File <target ame= war depeds= jar > <!-- Clea-up existig eviromet --> <delete file= ${LIB_DIR}/${WAR_FILE} /> <delete dir= ${SRC_DIR}/war/WEB-INF/lib /> <delete dir= ${SRC_DIR}/war/WEB-INF/classes /> <war warfile= ${LIB_DIR}/${WAR_FILE} webxml= ${SRC_DIR}/war/WEB-INF/web.xml > <fileset dir= ${PROJECT_DIR} icludes= versio_ifo.xml /> <!-- IMPORTANT! Exclude the WEB-INF/web.xml file from the WAR as it already gets icluded via the webxml attribute above --> <fileset dir= ${SRC_DIR}/war excludes= WEB-INF/web.xml /> <!-- IMPORTANT! Iclude the ADK desig time framework ito the adapter s desig time Web applicatio. --> <fileset dir= ${ROOT}/adk/src/war /> <!-- Iclude classes from the adapter that support the desig time UI --> <classes dir= ${SRC_DIR} icludes= sample/web/*.class /> <!-- Iclude all JARs required by the Web applicatio uder the WEB-INF/lib directory of the WAR file --> <lib dir= ${LIB_DIR} icludes= ${JAR_FILE} /> 8-26 BEA WebLogic Applicatio Itegratio Developmet Guide

175 Step 3: Cofigurig the Developmet Eviromet <lib dir= ${WLAI_LIB_DIR} icludes= adk.jar,adk-web.jar,bea.jar, logtoolkit.jar,webtoolkit.jar,wlai-commo.jar,wlai-ejb-cliet.j ar,xcci.jar,xmltoolkit.jar /> <lib dir= ${RESOURCE_DIR}/log4j icludes= log4j.jar /> <lib dir= ${RESOURCE_DIR}/OROMatcher-1.1.0a icludes= oromatcher.jar /> <lib dir= ${RESOURCE_DIR}/xml icludes= xerces_dp1.jar /> <lib dir= ${RESOURCE_DIR}/xml icludes= xala.jar /> </war> <!-- Ujar the WAR ito a temp directory; for developmet --> <ujar src= ${LIB_DIR}/${WAR_FILE} dest= ${LIB_DIR}/ BEA_WLS_SAMPLE_ADK_Web /> </target> This At target costructs a valid.war file for the desig time iterface i the <PROJECT_ROOT>/lib directory, where <PROJECT_ROOT> is the locatio uder the Applicatio Itegratio istallatio where the developer is costructig the adapter; for example: <BEA_HOME\<WLAI_HOME>\dev\sample for the sample adapter. I additio, this target performs a ujar operatio i the lib directory. This extracts the.war ito a temporary directory. This is the key to havig WebLogic recompile JSPs without restartig. 2. Next, load your web applicatio ito WebLogic 6.0 server ad cofigure the developmet eviromet. Do the followig: a. To load your web applicatio ito WebLogic 6.0 server, you ca use the WebLogic cosole, but we recommed that you edit the cofig.xml file for your domai; for example: <BEA_HOME>\wlserver6.0sp1\cofig\mydomai\cofig.xml. Note:If you choose to edit your cofig.xml file, you will eed to add a <applicatio> elemet uder the domai elemet: BEA WebLogic Applicatio Itegratio Developmet Guide 8-27

176 8 Developig a Desig-Time GUI b. Replace BEA_WLS_SAMPLE_ADK_Web with your adapter s logical ame. c. Replace <WLAI_HOME> with the locatio of your Applicatio Itegratio istallatio; replace <PROJECT_ROOT> with the directory ame of your adapter developmet tree, as show i Listig 8-3. Listig 8-3 Sample Code Showig Name of Adapter Developmet Tree <Applicatio Deployed="true" Name="BEA_WLS_SAMPLE_ADK_Web" Path="<WLAI_HOME>\dev\<PROJECT_ROOT>\lib"> <WebAppCompoet Name="BEA_WLS_SAMPLE_ADK_Web" ServletReloadCheckSecs="1" Targets="myserver" URI= "BEA_WLS_SAMPLE_ADK_Web"/> </Applicatio> Note: If you ru GeerateAdapterTemplate, the iformatio i Listig 8-3 will be automatically updated. You ca the ope <WLAI_HOME>/dev/ <CLONE>/src/overview.html ad copy ad paste it as your cofig.xml etry. The key is the URI attribute of the <WebAppCompoet> elemet. Notice that it poits to BEA_WLS_SAMPLE_ADK_Web ad ot BEA_WLS_SAMPLE_ADK_Web.war. This is the temporary directory that you created whe you created the.war file. It cotais your extracted.war file cotets. WebLogic server will watch this directory for JSP chages. 3. To chage a JSP, do ot chage it i the temporary directory; chage it from the src/war directory ad the rebuild the war target. Remember, whe the.war file is created, it is also extracted ito the directory WebLogic 6.0 is watchig. WebLogic 6.0 will pick up the chages to the specific JSP oly. The watch iterval used by WebLogic 6.0 is set by the pagechecksecods i WEB-INF/weblogic.xml. Listig 8-4 shows how this is doe: Listig 8-4 Sample Code Showig How to Set the Watch Iterval <jsp-descriptor> <jsp-param> 8-28 BEA WebLogic Applicatio Itegratio Developmet Guide

177 Step 3: Cofigurig the Developmet Eviromet <param-ame>compilecommad</param-ame> <param-value>/jdk130/bi/javac.exe</param-value> </jsp-param> <jsp-param> <param-ame>keepgeerated</param-ame> <param-value>true</param-value> </jsp-param> <jsp-param> <param-ame>pagechecksecods</param-ame> <param-value>1</param-value> </jsp-param> <jsp-param> <param-ame>verbose</param-ame> <param-value>true</param-value> </jsp-param> </jsp-descriptor> This approach also tests whether your.war file is beig costructed correctly. 4. Fially, you should precompile JSPs whe the server starts. This saves you from havig to load every page before kowig if they will compile correctly. To eable precompilatio you will eed to have weblogic.xml from the sample adapter ad the followig elemet i your WEB-INF/web.xml file. Listig 8-5 shows how this is doe: Listig 8-5 Sample Code Showig How to Eable Precompilatio of JSPs <cotext-param> <param-ame>weblogic.jsp.precompile</param-ame> <param-value>true</param-value> </cotext-param> BEA WebLogic Applicatio Itegratio Developmet Guide 8-29

178 8 Developig a Desig-Time GUI You ca also pre-compile your JSPs usig the WebLogic JSP compiler whe you build your.war target usig At. This is accomplished by performig the tasks outlied i Listig 8-6 ad described here: The first task creates the directory where WebLogic 6.0 looks for JSP servlet classes at rutime. There is oe caveat to usig this approach: you have to specify the target server ame. Cosequetly, it may ot suffice as a deploymet strategy. The secod task ivokes the JSP compiler jspc, provided i WebLogic 6.0. This task pre-compiles all the JSPs for your web applicatio ad places them i the ${LIB_DIR}/BEA_WLS_SAMPLE_ADK_Web/WEB-INF/_tmp_war_myserver_ myserver_bea_wls_sample_adk_web directory for your web applicatio. Cosequetly, this allows you to esure your JSPs will compile every time you build your adapter. Listig 8-6 Sample Code Showig a Alterate Way to Eable Precompilatio of JSPs <mkdir dir= ${LIB_DIR}/BEA_WLS_SAMPLE_ADK_Web/ WEB-INF/_tmp_war_myserver_myserver_BEA_WLS_SAMPLE_ADK_Web/jsp_ser vlet /> <!-- This precompiles the JSPs i the Web applicatio durig the build. However, this will oly prevet WebLogic from precompilig if the target server is myserver. If the user is usig ay other target server ame, the JSP pages will be re-precompiled whe the server starts --> <java classame= weblogic.jspc fork= yes > <arg lie= -d ${LIB_DIR}/BEA_WLS_SAMPLE_ADK_Web/WEB-INF/ _tmp_war_myserver_myserver_bea_wls_sample_adk_web -webapp ${LIB_DIR}/BEA_WLS_SAMPLE_ADK_Web -compileall -cotextpath BEA_WLS_SAMPLE_ADK_Web -deped -keepgeerated /> <classpath refid= CLASSPATH /> </java> 8-30 BEA WebLogic Applicatio Itegratio Developmet Guide

179 Step 4: Implemetig the Desig-Time GUI For more iformatio o precompilig JSPs, see: Step 4: Implemetig the Desig-Time GUI Implemetig the steps described i Itroductio to Desig-Time Form Processig for every form i a web applicatio is a tedious ad error proe developmet process. The desig-time framework simplifies this process whe you are usig a Model-View-Cotroller paradigm. To implemet the desig-time GUI, you eed to implemet the DesigTimeRequestHadler class. This class accepts user iput from a form ad performs a desig-time actio. To implemet this class, you must exted the AbstractDesigTimeRequestHadler provided with the ADK; see the Javadoc for this class for a detailed overview of the methods provided by this object. Exted AbstractDesigTimeRequestHadler The AbstractDesigTimeRequestHadler provides utility classes for deployig, editig, copyig, ad removig applicatio views o the Applicatio Itegratio server. It also provides access to a applicatio view descriptor. The applicatio view descriptor provides the coectio parameters, list of evets, list of services, log levels, ad pool settigs for a applicatio view. The parameters are show o the Applicatio View Summary page. At a high-level, the AbstractDesigTimeRequestHadler provides a implemetatio for all actios that are commo across adapters. Specifically, these actios are: Defie the applicatio view. Cofigure the coectio. BEA WebLogic Applicatio Itegratio Developmet Guide 8-31

180 8 Developig a Desig-Time GUI Note: The ADK provides the method to process coectio parameters to obtai a CCI coectio but does ot supply the cofco.jsp. See Step 5a: Create the cofco.jsp Form for istructios o creatig this form. Deploy the applicatio view. Provide applicatio view security. Edit the applicatio view. Udeploy the applicatio view. Methods to Iclude To esure these actios, you must supply the followig methods whe you create the cocrete implemetatio of AbstractDesigTimeRequestHadler: iitservicedescriptor(); This method adds a service to a applicatio view at desigtime (see Step 4b. Implemet iitservicedescriptor() ). iitevetdescriptor(); This method adds a evet to a applicatio view at desigtime (see Step 4c. Implemet iitevetdescriptor() ). You also eed to provide i every cocrete implemetatio of AbstractDesigTimeRequestHadler the followig two methods: protected Strig getadapterlogicalname(); This method returs the adapter logical ame ad is used to deploy a applicatio view uder a adapter logical ame. protected Class getmaagedcoectiofactoryclass(); This method returs the SPI MaagedCoectioFactory implemetatio class for the adapter. Step 4a. Supply the MaagedCoectioFactory Class To supply the MaagedCoectioFactory class, you eed to implemet the followig method: 8-32 BEA WebLogic Applicatio Itegratio Developmet Guide

181 Step 4: Implemetig the Desig-Time GUI protected Class getmaagedcoectiofactoryclass(); This method returs the SPI MaagedCoectioFactory implemetatio class for the adapter. This class is eeded by the AbstractMaagedCoectioFactory whe attemptig to get a coectio to the EIS. Step 4b. Implemet iitservicedescriptor() For service adapters, you eed to implemet iitservicedescriptor() so that the adapter user ca add services at desigtime. This method is implemeted as show i Listig 8-7: Listig 8-7 iitservicedescriptor() Implemetatio protected abstract void iitservicedescriptor(actioresult result, IServiceDescriptor sd, HttpServletRequest request) throws Exceptio This method is ivoked by the AbstractDesigTimeRequestHadler s addservc() implemetatio. It is resposible for iitializig the EIS-specific iformatio of the IServiceDescriptor parameter. The base class implemetatio of addservc() hadles the error hadlig, etc. The addservc() method is ivoked whe the user submits the addservc JSP. Step 4c. Implemet iitevetdescriptor() For evet adapters, you will eed to implemet iitevetdescriptor() so that the adapter user ca add evets at desigtime. This method is implemeted as show i Listig 8-8: BEA WebLogic Applicatio Itegratio Developmet Guide 8-33

182 8 Developig a Desig-Time GUI Listig 8-8 iitevetdescriptor() Implemetatio protected abstract void iitevetdescriptor(actioresult result, IEvetDescriptor ed, HttpServletRequest request) throws Exceptio; This method is ivoked by the AbstractDesigTimeRequestHadler s addevet() implemetatio. It is resposible for iitializig the EIS-specific iformatio of the IServiceDescriptor parameter. The base class implemetatio of addevet() hadles such cocepts as error hadlig. The addevet() method is ivoked whe the user submits the addevet JSP. You should t override addevet, as it cotais commo logic ad delegates EIS-specific logic to iitevetdescriptor(). Note: Whe addig properties to a service descriptor, the property ames must follow the bea ame stadard otherwise the service descriptor does ot update the IteractioSpec correctly. Step 5: Write the HTML Forms The fial step to implemetig a desig-time GUI is to write the various forms that comprise the iterface. See Java Server Pages for a list ad descriptio of the ecessary forms. See Step 2: Determiig the Scree Flow for the specific details of each form. The followig sectios describe how to actually code these forms ad iclude a sample of that code BEA WebLogic Applicatio Itegratio Developmet Guide

183 Step 5: Write the HTML Forms Step 5a: Create the cofco.jsp Form This page provides a HTML form for users to supply coectio parameters for the EIS. You are resposible for providig this page with your adapter s desig time web applicatio. This form posts to the CotrollerServlet with doactio=cofco. This implies that the RequestHadler for your desig time iterface must provide the followig method: public ActioResult cofco(httpservletrequest request) throws Exceptio The implemetatio of this method is resposible for usig the supplied coectio parameters to create a ew istace of the adapter s MaagedCoectioFactory. The MaagedCoectioFactory supplies the CCI CoectioFactory, which is used to obtai a coectio to the EIS. Cosequetly, the processig of the cofco form submissio verifies that the supplied parameters are sufficiet for obtaiig a valid coectio to the EIS. The cofco form for the sample adapter is show i Listig 8-9: Listig 8-9 Codig cofco.jsp <%@ taglib uri= /WEB-INF/taglibs/adk.tld prefix= adk %> <form method= POST actio= cotroller > <table> <tr> <td><adk:label ame= username required= true /></td> <td><adk:text ame= username maxlegth= 30 size= 8 /></td> </tr> <tr> <td><adk:label ame= password required= true /></td> <td><adk:password ame= password maxlegth= 30 size= 8 /></td> </tr> <tr> BEA WebLogic Applicatio Itegratio Developmet Guide 8-35

184 8 Developig a Desig-Time GUI <td colspa= 2 ><adk:submit ame= cofco_submit doactio= cofco /></td> </tr> </table> </form> The followig paragraphs describe the cotets of Listig 8-9. Icludig the ADK Tag Library The lie: <%@ taglib uri= /WEB-INF/taglibs/adk.tld prefix= adk %> istructs the JSP egie to iclude the ADK tag library. These tags are listed i Table 8-3. Postig the CotrollerServlet The lie: <form method= POST actio= cotroller > istructs the form to post to the CotrollerServlet. The CotrollerServlet is cofigured i the web.xml file for the web applicatio ad is resposible for delegatig HTTP requests to a method o a RequestHadler. You do ot eed to provide ay code to use the CotrollerServlet; however, you must supply the iitial parameters, described i Table 8-5: Table 8-5 CotrollerServlet Parameters Parameter MessageBudleBase Descriptio This property specifies the base ame for all message budles supplied with a adapter. The ADK always uses the adapter logical ame for its sample adapters. However, you are free to choose your ow amig covetio for message budles. Notice that this property is also established i the ra.xml BEA WebLogic Applicatio Itegratio Developmet Guide

185 Step 5: Write the HTML Forms Table 8-5 CotrollerServlet Parameters (Cotiued) Parameter DisplayPage LogCofigFile RootLogCotext RequestHadlerClass Descriptio This property specifies the ame of the JSP that cotrols scree flow ad look-ad-feel. I the sample adapter, this page is display.jsp. This property specifies the log4j cofiguratio file for the adapter. This property specifies the root log cotext. Log cotext helps categorize log messages accordig to modules i a program. The ADK uses the adapter logical ame for the root log cotext so that all messages from a specific adapter will be categorized accordigly. This property provides the fully qualified ame of the request hadler class for the adapter. I the sample adapter, this value is sample.web.desigtimerequesthadler. See below for details o implemetig a DesigTimeRequestHadler. Displayig the Label for the Form Field The lie: <adk:label ame= username required= true /> displays a label for a field o the form. The value that is displayed is retrieved from the message budle for the user. The required attribute idicates if the user must supply this parameter to be successful. Displayig the Text Field Size The lie: <adk:text ame= username maxlegth= 30 size= 8 /> sets a text field of size 8 with maximum legth (max legth) of 30. Displayig a Submit Butto o the Form The lie: BEA WebLogic Applicatio Itegratio Developmet Guide 8-37

186 8 Developig a Desig-Time GUI Implemetig cofco() <adk:submit ame= cofco_submit doactio= cofco /> displays a butto o the form that allow the adapter user to submit the iput. The label o the butto will be retrieved from the message budle usig the cofco_submit key. Whe the form data is submitted, the CotrollerServlet will locate the cofco method o the registered request hadler (see the RequestHadlerClass property) ad pass the request data to it. The AbstractDesigTimeRequestHadler provides a implemetatio of the cofco() method. This implemetatio leverages the Java Reflectio API to map coectio parameters supplied by the user to setter methods o the adapter s MaagedCoectioFactory istace. You oly eed to supply the cocrete class for your adapter s MaagedCoectioFactory by implemetig this method: public Class getmaagedcoectiofactoryclass() Step 5b: Create the addevet.jsp form This form allows the user to add a ew evet to a applicatio view. This form is EIS specific. The addevet.jsp form for the sample adapter is show i Listig 8-10: Listig 8-10 Sample Code Creatig the addevet.jsp Form <%@ taglib uri= /WEB-INF/taglibs/adk.tld prefix= adk %> <form method= POST actio= cotroller > <table> <tr> <td><adk:label ame= evetname required= true /></td> <td><adk:text ame= evetname maxlegth= 100 size= 50 /></td> </tr> <tr> 8-38 BEA WebLogic Applicatio Itegratio Developmet Guide

187 Step 5: Write the HTML Forms <td colspa= 2 ><adk:submit ame= addevet_submit doactio= addevet /></td> </tr> </table> </form> The followig paragraphs describe the cotets of addevet.jsp: Icludig the ADK Tag Library The lie: <%@ taglib uri= /WEB-INF/taglibs/adk.tld prefix= adk %> istructs the JSP egie to iclude the ADK tag library. These tags are described i Table 8-3. Postig the CotrollerServlet The lie: <form method= POST actio= cotroller > istructs the form to post to the CotrollerServlet. The CotrollerServlet is cofigured i the web.xml file for the web applicatio ad is resposible for delegatig HTTP requests to a method o a RequestHadler. You do ot eed to provide ay code to use the CotrollerServlet; however, you must supply the iitial parameters, as described i Table 8-5, CotrollerServlet Parameters. Displayig the Label for the Form Field The lie: <adk:label ame= evetname required= true /> displays a label for a field o the form. The value that is displayed is retrieved from the message budle for the user. The required attribute idicates if the user must supply this parameter to be successful. BEA WebLogic Applicatio Itegratio Developmet Guide 8-39

188 8 Developig a Desig-Time GUI Displayig the Text Field Size The lie: <adk:text ame= evetname maxlegth= 100 size= 50 /> sets a text field of size 50 with maximum legth (max legth) of 100. Displayig a Submit Butto o the Form The lie: Addig Additioal Fields <adk:submit ame= addevet_submit doactio= addevet /> displays a butto o the form that allow the adapter user to submit the iput. The label o the butto will be retrieved from the message budle usig the addevet_submit key. Whe the form data is submitted, the cotroller servlet will locate the addevet method o the registered request hadler (see the RequestHadlerClass property) ad pass the request data to it. You must also add ay additioal fields that the user requires for defiig a evet. See the DBMS or sample adapters for examples of forms with multiple fields. You ca fid these files i <WLAI_HOME>/dev/dbms/src/dbms/ or <WLAI_HOME>/dev/ /src/ /. Step 5c: Create the addservc.jsp form This form allows the user to add a ew service to a applicatio view. This form is EIS-specific. The addservc.jsp form for the sample adapter is show i Listig 8-11: Listig 8-11 Codig addservc.jsp <%@ taglib uri= /WEB-INF/taglibs/adk.tld prefix= adk %> <form method= POST actio= cotroller > <table> 8-40 BEA WebLogic Applicatio Itegratio Developmet Guide

189 Step 5: Write the HTML Forms <tr> <td><adk:label ame= servicename required= true /></td> <td><adk:text ame= servicename maxlegth= 100 size= 50 /></td> </tr> <tr> <td colspa= 2 ><adk:submit ame= addservc_submit doactio= addservc /></td> </tr> </table> </form> Icludig the ADK Tag Library The lie: <%@ taglib uri= /WEB-INF/taglibs/adk.tld prefix= adk %> istructs the JSP egie to iclude the ADK tag library. The ADK tag library supports the user-friedly form validatio provided by the ADK. The ADK tag library provides the tags described i Table 8-3. Postig the CotrollerServlet The lie: <form method= POST actio= cotroller > istructs the form to post to the CotrollerServlet. The CotrollerServlet is cofigured i the web.xml file for the web applicatio ad is resposible for delegatig HTTP requests to a method o a RequestHadler. You do ot eed to provide ay code to use the CotrollerServlet; however, you must supply the iitial parameters as described i Table 8-5, CotrollerServlet Parameters. BEA WebLogic Applicatio Itegratio Developmet Guide 8-41

190 8 Developig a Desig-Time GUI Displayig the Label for the Form Field The lie: <adk:label ame= servcname required= true /> displays a label for the form field. The value that is displayed is retrieved from the message budle for the user. The required attribute idicates if the user must supply this parameter to be successful. Displayig the Text Field Size The lie: <adk:text ame= evetname maxlegth= 100 size= 50 /> sets a text field of size 50 with maximum legth (max legth) of 100. Displayig a Submit Butto o the Form The lie: Addig Additioal Fields <adk:submit ame= addservc_submit doactio= addservc /> displays a butto o the form that allow the adapter user to submit the iput. The label o the butto will be retrieved from the message budle usig the addservc_submit key. Whe the form data is submitted, the CotrollerServlet will locate the addservc method o the registered request hadler (see the RequestHadlerClass property) ad pass the request data to it. You must also add ay additioal fields that the user requires for defiig a a service. See the DBMS or sample adapters for examples of forms with multiple fields. You ca fid these files i <WLAI_HOME>/dev/dbms/src/dbms/ or <WLAI_HOME>/dev/ /src/ / BEA WebLogic Applicatio Itegratio Developmet Guide

191 Step 5: Write the HTML Forms Step 5d: Create display.jsp This JSP is resposible for establishig the HTML template ad icludig cotet pages for your web applicatio. It icludes the page give by the doactio parameter supplied i the request. The purpose of this JSP is to cetralize the HTML that determies look-ad-feel ito a sigle JSP for your desig time framework.the display.jsp page provides the followig for the desig time web applicatio: Establishes the look-ad-feel template for all pages. Icludes other jsp pages based o the doactio HTTP request parameter. If the doactio HTTP request parameter is ot supplied, the display.jsp page icludes mai.jsp. You must have mai.jsp. Registers the error page for Java exceptios as error.jsp from the ADK. Sice display.jsp cotrols the look-ad-feel for all pages, please refer to Step 7. Implemetig the Look-ad-Feel for more iformatio o creatig it. Step 5e: Write the WEB-INF/web.xml Web Applicatio Deploymet Descriptor You will eed to create a WEB-INF/web.xml web applicatio deploymet descriptor for your adapter. Whe you cloe a adapter from the sample adapter by usig GeerateAdapterTemplate, a web.xml file for that adapter will be automatically geerated. The importat compoets of this file are described i Listig 8-12 through Listig 8-16: Listig 8-12 web.xml Servlet Compoets <servlet> <servlet-ame>cotroller</servlet-ame> <servlet-class>com.bea.web.cotrollerservlet</servlet-class> <iit-param> BEA WebLogic Applicatio Itegratio Developmet Guide 8-43

192 8 Developig a Desig-Time GUI <param-ame>messagebudlebase</param-ame> <param-value>bea_wls_sample_adk</param-value> <descriptio>the base ame for the message budles for this adapter. The CotrollerServlet uses this ame ad the user s locale iformatio to determie which message budle to use to display the HTML pages.</descriptio> </iit-param> <iit-param> <param-ame>displaypage</param-ame> <param-value>display.jsp</param-value> <descriptio>the ame of the JSP page that icludes cotet pages ad provides the look-ad-feel template. The CotrollerServlet redirects to this page to let it determie what to show the user.</descriptio> </iit-param> <iit-param> <param-ame>logcofigfile</param-ame> <param-value>bea_wls_sample_adk.xml</param-value> <descriptio>the ame of the sample adapter s LOG4J cofiguratio file.</descriptio> </iit-param> <iit-param> <param-ame>rootlogcotext</param-ame> <param-value>bea_wls_sample_adk</param-value> <descriptio>the root category for log messages for the sample adapter. All log messages created by the sample adapter will have a cotext startig with this value.</descriptio> </iit-param> 8-44 BEA WebLogic Applicatio Itegratio Developmet Guide

193 Step 5: Write the HTML Forms <iit-param> <param-ame>requesthadlerclass</param-ame> <param-value>sample.web.desigtimerequesthadler</param- value> <descriptio>class that hadles desig time requests</descriptio> </iit-param> <iit-param> <param-ame>debug</param-ame> <param-value>o</param-value> <descriptio>debug settig (o off, off is default)</descriptio> </iit-param> <load-o-startup>1</load-o-startup> </servlet> This compoet show i Listig 8-13 maps the CotrollerServlet to the ame cotroller. This actio is importat because the ADK JSP forms assume the CotrollerServlet is mapped to the logical ame cotroller. Listig 8-13 web.xml CotrollerServlet Mappig Compoet <servlet-mappig> <servlet-ame>cotroller</servlet-ame> <url-patter>cotroller</url-patter> </servlet-mappig> This compoet show i Listig 8-14 declares the ADK tag library: BEA WebLogic Applicatio Itegratio Developmet Guide 8-45

194 8 Developig a Desig-Time GUI Listig 8-14 web.xml ADK Tab Library Compoet <taglib> <taglib-uri>adk</taglib-uri> <taglib-locatio>/web-inf/taglibs/adk.tld</taglib-locatio> </taglib> This compoet show i Listig 8-15 declares the security costraits for the web applicatio. Curretly, the user must belog to the adapter group: Listig 8-15 web.xml Security Costrait Compoet <Security-costrait> <web-resource-collectio> <web-resource-ame>adaptersecurity</web-resource-ame> <url-patter>*.jsp</url-patter> </web-resource-collectio> <auth-costrait> <role-ame>adapter</role-ame> </auth-costrait> <user-data-costrait> <trasport-guaratee>none</trasport-guaratee> </user-data-costrait> </security-costrait> This compoet show i Listig 8-16 declares the logi cofiguratio: 8-46 BEA WebLogic Applicatio Itegratio Developmet Guide

195 Step 7. Implemetig the Look-ad-Feel Listig 8-16 web.xml Logi Cofiguratio Compoet <logi-cofig> <auth-method>form</auth-method> <realm-ame>default</realm-ame> <form-logi-cofig> <form-logi-page>/logi.jsp</form-logi-page> <form-error-page>/logi.jsp?error</form-error-page> </form-logi-cofig> </logi-cofig> <security-role> <role-ame>adapter</role-ame> </security-role> Step 7. Implemetig the Look-ad-Feel A importat programmig practice you should observe whe developig a desig-time GUI is to implemet a cosistet look-ad-feel across all pages i the applicatio view. The look-ad-feel is determied by display.jsp. This page is icluded with the ADK ad provides the followig for the desig time web applicatio: Establishes the look-ad-feel template for all pages Icludes other JSPs based o the cotet HTTP request parameter. If the cotet HTTP request parameter is ot supplied, display.jsp must iclude mai.jsp. Registers the error page for Java exceptios as error.jsp from the ADK. To implemet a look-ad-feel across a set of pages, do the followig: BEA WebLogic Applicatio Itegratio Developmet Guide 8-47

196 8 Developig a Desig-Time GUI 1. Use display.jsp from the sample adapter as a startig poit. See sample\src\war\web-inf\web.xml for a example. 2. Usig HTML, alter the look-ad-feel markup i this page to reflect your ow look-ad-feel or compay idetity stadards. 3. Somewhere i your HTML markup, be sure to iclude: <%pagecotext.iclude(sbpage.tostrig());%> This code is a custom JSP tag used to iclude other pages. This tag uses the JSP scriptlet sbpage.tostrig() to iclude a HTML or JSP ito the display page. sbpage.tostrig() evaluates to the value for the HTTP request parameter cotet at rutime BEA WebLogic Applicatio Itegratio Developmet Guide

197 APPENDIX A Adapter Setup Worksheet Use the worksheet begiig o the followig page to help you idetify ad collect critical iformatio about the adapter you are developig. The aswers to the questios posed o the worksheet will help you coceptualize the adapter you are buildig before you actually bega to code. They will help you defie such compoets as the adapter logical ame ad the Java package base ame ad help you determie the locales for which you eed to localize message budles. If you are usig the GeerateAdapterTemplate utility, the aswers you provide o this worksheet are essetial to its success. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide A-1

198 A Adapter Setup Worksheet Adapter Setup Worksheet Before you begi developig a adapter, aswer as may of the followig questios as you ca. Questios preceded by a asterisk (*) are required to use the GeerateAdapterTemplate utility. 1. *What is the ame of the EIS for which you are developig a adapter? 2. *What is the versio of the EIS? 3. *What is the type of EIS; for example, DBMS, ERP, etc.? 4. *Who is the vedor ame for this adapter? 5. *What is the versio umber for this adapter? 6. *What is the adapter logical ame? 7. Does the adapter eed to ivoke fuctioality withi the EIS? If so, the your adapter eeds to support services. 8. What mechaism/api is provided by the EIS to allow a exteral program to ivoke fuctioality provided by the EIS? 9. What iformatio is eeded to create a sessio/coectio to the EIS for this mechaism? 10. What iformatio is eeded to determie which fuctio(s) will be ivoked i the EIS for a give service? 11. Does the EIS allow you to query it for iput ad output requiremets for a give fuctio? If so, what iformatio is eeded to determie the iput requiremets for the service? 12. For all the iput requiremets, which oes are static across all requests? Your adapter should ecode static iformatio ito a IteractioSpec object. 13. For all the iput requiremets, which oes are dyamic per request? Your adapter should provide a XML schema that describes the iput parameters required by this service per request. A-2 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

199 Adapter Setup Worksheet 14. What iformatio is eeded to determie the output requiremets for the service? 15. Does the EIS provide a mechaism to browse a catalog of fuctios your adapter ca ivoke? If so, your adapter should support browsig of services. 16. Does the adapter eed to receive otificatios of chages that occur iside the EIS? If so, the your adapter eeds to support evets. 17. What mechaism/api is provided by the EIS to allow a exteral program to receive otificatio of evets i the EIS? The aswer of this questio will help determie if a pull or a push mechaism is developed. 18. Does the EIS provide a way to determie which evets your adapter ca support? 19. Does the EIS provide a way to query for metadata for a give evet? 20. What locales (laguage/coutry) does your adapter eed to support? BEA WebLogic Applicatio Itegratio Adapter Developmet Guide A-3

200 A Adapter Setup Worksheet A-4 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

201 APPENDIX B The DBMS Sample Adapter This sectio cotais iformatio o the followig subjects: Itroductio to the DBMS Sample Adapter How the DBMS Sample Adapter Works How the DBMS Sample Adapter Was Developed How the DBMS Adapter Desig-Time GUI was Developed Itroductio to the DBMS Sample Adapter The DBMS adapter is a J2EE-compliat adapter built with the BEA WebLogic Applicatio Itegratio Adapter Developmet Kit. It provides a cocrete example for adapter providers of how oe might use the ADK to costruct a adapter. A relatioal database was used as the EIS of a adapter because it allows adapter providers to focus o the adapter/adk specifics, rather tha become bogged-dow i uderstadig a particular proprietary EIS. The DBMS sample adapter gives you (developers ad busiess aalysts) a cocrete example of a adapter, icludig a JSP-based GUI, to help you uderstad the possibilities that are at your disposal usig the ADK to build adapters. If you are a busiess aalyst, you might ejoy ruig through the iterface to get a better uderstadig of a applicatio view, service, ad evet as show i How the DBMS Sample Adapter Works. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-1

202 B The DBMS Sample Adapter If you are a adapter developer, you will also wat to review How the DBMS Sample Adapter Was Developed ad How the DBMS Adapter Desig-Time GUI was Developed, the code, ad Javadoc to gai isight ito how you ca exted ad use the classes of the ADK to build a JCA-compliat adapter. The DBMS adapter satisfies the followig requiremets: Provides a GUI that allows ed-users to coect to a Cloudscape, Oracle, or SQLServer database. Uses the classes ad tools of the ADK. Allows users to create applicatio views with evets ad services. Allow users to test evets ad services. Provides a GUI that eables users to browse the catalogs, schemas, tables, ad colums of the uderlyig database from the GUI. Supports the creatio of services that perform selects, iserts, deletes, ad updates agaist the database (EIS). How the DBMS Sample Adapter Works This sectio provides you with a opportuity to see how the DBMS adapter works before you start developig oe of your ow. If you are a busiess aalyst, you might ejoy ruig through the iterface to get a feel for how the adapter works. The example i this sectio shows how to create a service that iserts a customer i the uderlyig database, ad the demostrates how a evet is geerated to otify others that this actio has take place. This sectio cotais iformatio o the followig subjects: Before You Begi Accessig the DBMS Sample Adapter A Tour of the DBMS Sample Adapter B-2 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

203 How the DBMS Sample Adapter Works Before You Begi Make sure the followig tasks have bee performed before you try to access the DBMS sample adapter: Istall the BEA WebLogic Applicatio Itegratio. For more iformatio, see the BEA WebLogic Applicatio Itegratio Istallatio ad Setup Guide. Set up the ADK At-Based Make Process. Esure that the DBMS sample adapter has bee deployed so that the desig-time GUI is accessible. For more iformatio, see the BEA WebLogic Applicatio Itegratio Istallatio ad Cofiguratio Guide. Accessig the DBMS Sample Adapter To access the DBMS adapter: 1. Ope a ew browser widow. 2. Ope the URL for your system s Applicatio View Maagemet Cosole. The Applicatio Itegratio Cosole - Logi page displays. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-3

204 B The DBMS Sample Adapter A Tour of the DBMS Sample Adapter This sectio provides you with a short tour through the DBMS Sample adapter. Before you begi, you eed to ope the DBMS adapter Logi page o your browser. For iformatio about accessig the DBMS adapter, see Accessig the DBMS Sample Adapter. B-4 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

205 How the DBMS Sample Adapter Works 1. To log o to the Applicatio View Maagemet Cosole, eter your WebLogic userame ad password, the click Logi. The Applicatio View Maagemet Cosole displays. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-5

206 B The DBMS Sample Adapter 2. Click Add Applicatio View. The Defie New Applicatio View page displays. Whe you create the applicatio view, you provide a descriptio that associates the applicatio view with the DBMS adapter. Note: For detailed iformatio about applicatio views, see Itroductio to Usig Applicatio Itegratio. For detailed iformatio about defiig applicatio views, see Defiig Applicatio Views i the BEA WebLogic Applicatio Itegratio User Guide.. 3. To defie a applicatio view: a. I the Applicatio View Name field, eter TestAppView. B-6 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

207 How the DBMS Sample Adapter Works Note: The ame should describe the set of fuctios performed by this applicatio. Each applicatio view ame must be uique to its adapter. Valid characters are aythig except., #, \, +, &,,,,, ad a space. b. I the Descriptio field, eter a brief descriptio of the applicatio view. c. From the Associated Adapters list, choose the DBMS adapter to use to create this applicatio view. d. Click OK. The Cofigure Coectio Parameters page displays.. 4. At the Cofigure Coectio Parameters page, you defie the etwork-related iformatio ecessary for the applicatio view to iteract with the target EIS. You eed to eter this iformatio oly oce per applicatio view: a. Eter your WebLogic User Name ad WebLogic Password. b. Make sure the XA Compliat Data Source? box is uchecked. c. I the Data Source Name (JNDI) field, eter WLAI_DataSource. d. I the Pig Table field, eter APP.EVENT. e. Click Cotiue. The Applicatio View Admiistratio page displays. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-7

208 B The DBMS Sample Adapter Note: The Admiistratio page summarizes the coectio criteria, ad oce evets ad services are defied, you ca view the schemas ad summaries ad also delete a evet or service from this page. 5. Now that you have created a applicatio view, you are ready to add a service to it. To add the service you must supply a ame for the service, provide a descriptio ad eter the SQL statemet. You ca use the browse lik to browse the DBMS adapter database schemas ad tables ad specify the database table CUSTOMER_TABLE. To add a service: a. I the Admiistratio page, click Add i the Services field. The Add Service page displays. B-8 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

209 How the DBMS Sample Adapter Works b. I the Uique Service Name field, eter IsertCustomer. c. I the Descriptio field, eter a descriptio of the service. d. Click Browse DBMS to view the table ad colum structure of the database. If you are writig a complex query, you may leave the Browse widow ope i order to cut ad paste table or colum ames ito your query. e. I the DBMS Schemas for Catalog page, click APP. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-9

210 B The DBMS Sample Adapter f. I the DBMS Table Types page, click TABLE. g. I the Tables list for APP page, click CUSTOMER_TABLE. The Browse widow ow displays the colum ames ad colum types. B-10 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

211 How the DBMS Sample Adapter Works h. Click Close to close to close the widow to retur to the Add Service Page. Note: This widow is icluded i the tour to itroduce you to the fuctioality, ad it is ot ecessary to select ay text for this exercise. i. I the Service Page, add the followig iformatio ito the SQL Statemet field: Isert ito APP.CUSTOMER_TABLE (FIRSTNAME, LASTNAME, DOB) VALUES ([FIRSTNAME VARCHAR], [LASTNAME VARCHAR], [DOB DATE]) j. Click Add. The Admiistratio page displays. Note: For additioal iformatio about addig services, see Addig Services to a Applicatio View i the BEA WebLogic Applicatio Itegratio User Guide. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-11

212 B The DBMS Sample Adapter 6. Add a evet to your applicatio view. I order to add a evet, you must provide a uique evet ame ad a descriptio. The you must specify the database table upo which a trigger should be added for the evet. You must also specify if it is a isert, update or delete evet. You ca use the Browse DBMS lik to browse the DBMS database schemas ad tables ad to specify the database table. The you ca automatically populate the field with the selected table ame. To add a evet: a. I the Admiistratio page, click Add i the Evet field. The Add Evet page displays. b. I the Uique Evet Name field, eter CustomerIserted. c. I the Descriptio field, eter a descriptio of the evet. d. Click the Browse DBMS lik to view the table ad colum structure of the database. B-12 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

213 How the DBMS Sample Adapter Works e. Select the CUSTOMER TABLE radio butto, ad click Fill table ame with selected table. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-13

214 B The DBMS Sample Adapter f. Select the Isert Evet radio butto. g. Whe fiished, click Add. The Applicatio View Admiistratio page displays. B-14 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

215 How the DBMS Sample Adapter Works 7. Prepare to deploy the applicatio view. The Applicatio View Admiistratio page provides you with a sigle locatio for cofirmig the cotet of your applicatio view before you save it or deploy it. I this page, you ca view the followig: l l l Cofirm or edit the descriptio of the applicatio view. Cofirm or recofigure Coectio Criteria for the applicatio view. Delete services ad evets. l Save the applicatio view so you ca retur to it later or deploy the applicatio view to the server. After verifyig the applicatio view parameters, click Cotiue. The Deploy Applicatio View to Server page displays. 8. Deploy the Applicatio View. I order to deploy the applicatio view, you must provide several parameters such as eablig asychroous service ivocatio, providig the evet router URL, ad chagig the coectio pool parameters, amog other parameters. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-15

216 B The DBMS Sample Adapter To deploy the applicatio view: a. Make sure the Eable Asychroous Service Ivocatio check box is checked. b. I the Evet Router URL field, eter c. For the Coectio Pool Parameters, accept the default values: Miimum Pool Size - 1 Maximum Pool Size - 10 Target Fractio of Maximum Pool Size Allow Pool to Shrik - checked d. I the Log Cofiguratio field, select Log warigs, errors, ad audit messages. e. Make sure the Deploy persistetly? box is checked. B-16 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

217 How the DBMS Sample Adapter Works f. Click the Restrict Access lik. The Applicatio View Security page displays. 9. Set permissios for the applicatio view. You ca grat or revoke read ad write access for a user or a group. To set permissios for the applicatio view: a. For Choose a Actio, select the Revoke radio butto. b. I the Specify a User or Group, eter Jdoe. c. For Permissio: select the Write (Deploy/Udeploy/Edit App View) radio butto. d. Click Doe. The Deploy Applicatio View Page displays. e. Click Deploy. 10. Oce the applicatio view is deployed, the summary page displays all relevat iformatio about the deployed applicatio view. Use the Summary page to view schemas, evet ad service summaries, test services ad evets ad udeploy the applicatio view. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-17

218 B The DBMS Sample Adapter 11. Test a evet. To esure that the applicatio view is workig correctly, you ca test the evets ad services i the applicatio view. You ca test a evet by ivokig a service or by maually creatig the evet. The user ca also specify how log the applicatio should wait to receive the evet. To test a evet usig a service: a. From the Summary page, click the Test lik for CustomerIserted. The Test Evet page displays. B-18 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

219 How the DBMS Sample Adapter Works b. I the Test Evet page, select the Service radio butto, ad select IsertCustomer i the Service meu. c. I the How log should we wait to receive the evet? field, eter d. Click Test. The Test Service page displays. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-19

220 B The DBMS Sample Adapter e. I the FIRSTNAME field, eter a first ame. f. I the LASTNAME field, eter a last ame. g. I the DOB field, eter a date of birth i the correct format. h. Click Test. The Test Result page displays to show the cotets of the XML documets represetig the evet you geerated ad the respose geerated by the applicatio view. B-20 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

221 How the DBMS Sample Adapter Was Developed How the DBMS Sample Adapter Was Developed This sectio describes each iterface used to develop the DBMS adapter. The ADK provides may of the ecessary implemetatios required by a Java Coector Architecture-compliat adapter; however, sice some iterfaces caot be fully implemeted util the EIS ad its eviromet are defied, the DBMS adapter was created to illustrate the detail-specific or cocrete implemetatio of the abstract classes provided i the ADK. The process of creatig the DBMS adapter is comprised of the followig steps: Developmet Referece Documetatio Step 1: Developmet Cosideratios Step 2: Implemetig the Server Provider Iterface Package Step 3: Implemetig the Commo Cliet Iterface Package Step 4: Implemetig the Evet Package Step 5: Deployig the Adapter Developmet Referece Documetatio You ca review the Javadoc ad code for the methods defied i the steps that follow i this sectio to see how the implemetatios provided by the ADK were leveraged. You ca fid the Javadoc for this implemetatio i: <WLAI_HOME>\dev\dbms\docs\api\idex.html You ca fid the code listig for this package i: <WLAI_HOME>\dev\dbms\src\com\bea\adapter\dbms\spi Note: <WLAI_HOME> is the drive or home directory where BEA WebLogic Applicatio Itegratio is istalled. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-21

222 B The DBMS Sample Adapter Step 1: Developmet Cosideratios The Adapter Setup Worksheet is available to help adapter developers idetify ad collect critical iformatio about a adapter they are developig before they begi codig. For the DBMS sample adapter, the worksheet questios are aswered as follows: Note: Questios preceded by a asterisk (*) are required to use the GeerateAdapterTemplate utility. 1. *What is the ame of the EIS for which you are developig a adapter? Cloudscape, SQLServer, Oracle databases. 2. *What is the versio of the EIS? Cloudscape, MSSQLServer 7.0 Oracle *What is the type of EIS; for example, DBMS, ERP, etc.? DBMS 4. *What is the vedor ame for this adapter? BEA 5. *What is the versio umber of this adapter? Noe - Sample Oly 6. *What is the adapter logical ame? BEA_WLS_DBMS_ADK 7. Does the adapter eed to ivoke fuctioality withi the EIS? Yes If so, the your adapter eeds to support services. Yes 8. What mechaism/api is provided by the EIS to allow a exteral program to ivoke fuctioality provided by the EIS? JDBC B-22 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

223 How the DBMS Sample Adapter Was Developed 9. What iformatio is eeded to create a sessio/coectio to the EIS for this mechaism? Database URL, driver class, user ame, password 10. What iformatio is eeded to determie which fuctio(s) will be ivoked i the EIS for a give service? Fuctio ame, executeupdate, executequery 11. Does the EIS allow you to query it for iput ad output requiremets for a give fuctio? Yes, you ca browse data structures. If so, what iformatio is eeded to determie the iput requiremets for the service? SQL 12. For all the iput requiremets, which oes are static across all requests? Your adapter should ecode static iformatio ito a IteractioSpec object. SQL 13. For all the iput requiremets, which oes are dyamic per request? Your adapter should provide a XML schema that describes the iput parameters required by this service per request. The iput requiremets would chage depedig o the SQL expressio for the service 14. What iformatio is eeded to determie the output requiremets for the service? /a 15. Does the EIS provide a mechaism to browse a catalog of fuctios your adapter ca ivoke? If so, your adapter should support browsig of services. Yes 16. Does the adapter eed to receive otificatios of chages that occur iside the EIS? If so, the your adapter eeds to support evets. Yes BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-23

224 B The DBMS Sample Adapter 17. What mechaism/api is provided by the EIS to allow a exteral program to receive otificatio of evets i the EIS? The aswer of this questio will help determie if a pull or a push mechaism is developed. Noe. The DBMS adapter was built o the BEA WebLogic Applicatio Itegratio evet geerator usig a pull mechaism. 18. Does the EIS provide a way to determie which evets your adapter ca support? Yes 19. Does the EIS provide a way to query for metadata for a give evet? Yes 20. What locales (laguage/coutry) does your adapter eed to support? Multiple Step 2: Implemetig the Server Provider Iterface Package Table 8-6 SPI Class Extesios To implemet the DBMS adapter Server Provider Iterface (SPI) ad meet the J2EE-compliat SPI requiremets, the classes i the ADK were exteded to create the followig cocrete classes: This cocrete class... MaagedCoectioFactoryImpl MaagedCoectioImpl CoectioMetaDataImpl LocalTrasactioImpl Exteds this ADK class... AbstractMaagedCoectioFactory AbstractMaagedCoectio AbstractCoectioMetaData AbstractLocalTrasactio These classes provide coectivity to a EIS ad establish a framework for evet listeig ad request trasmissio, establish trasactio demarcatio, ad allow maagemet of a selected EIS. B-24 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

225 How the DBMS Sample Adapter Was Developed MaagedCoectioFactoryImpl Basic Implemetatio The first step i implemetig a SPI for the DBMS adapter was to implemet the MaagedCoectioFactory iterface. A MaagedCoectioFactory supports coectio poolig by providig methods for matchig ad creatig a MaagedCoectio istace. The ADK provides com.bea.adapter.spi.abstractmaagedcoectio Factory, a implemetatio of the Java Coector Architecture iterface javax.resource.spi.maagedcoectiofactory. The DBMS adapter exteds this class i com.bea.adapter.dbms.spi.maagedcoectiofactoryimpl. Listig 8-17 shows the derivatio tree for MaagedCoectioFactoryImpl. Listig 8-17 com.bea.adapter.dbms.spi.maagedcoectiofactoryimpl javax.resource.spi.maagedcoectiofactory -->com.bea.adapter.spi.abstractmaagedcoectiofactory -->com.bea.adapter.dbms.spi.maagedcoectiofactoryimpl Developers Commets The MaagedCoectioFactory is the cetral class of the Java Coector Architecture s SPI package. The ADK s AbstractMaagedCoectioFactory provides much of the required implemetatio for the methods declared i Su s iterface. To exted the ADK s AbstractMaagedCoectioFactory for the DBMS adapter, the key createcoectiofactory() ad createmaagedcoectio() methods were implemeted. Overrides for equals(), hashcode(), checkstate() were also writte to provide specific behaviors for the databases supported by the DBMS adapter. There are private attributes about which the superclass has o kowledge. Whe creatig your adapters, you must provide setter/getter methods for these attributes. The abstract createcoectiofactory() method is implemeted to provide a EIS-specific CoectioFactory usig the iput parameters. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-25

226 B The DBMS Sample Adapter Additioally, createmaagedcoectio() is the mai factory method of the class. It checks to see if the adapter is cofigured properly before doig aythig else. It the implemets methods of the superclass to get a coectio ad a password credetial object. It the attempts to ope a physical database coectio; if this succeeds, it istatiates ad returs a MaagedCoectioImpl (the DBMS adapter implemetatio of MaagedCoectio), which is give the physical coectio. Note: The createmaagedcoectio() method uses our member m_bisxacompliatdatasource boolea to coditioally ope either a XA or a o-xa compliat datasource. The methods it ivokes to do this are private ad are iterestig to review. MaagedCoectioImpl Basic Implemetatio Other methods are getter/setter methods for member attributes. A MaagedCoectio istace represets a physical coectio to the uderlyig EIS i a maaged eviromet. MaagedCoectio objects are pooled by the applicatio server. For more iformatio, read about how the ADK implemets the AbstractMaagedCoectio istace i MaagedCoectio. The ADK provides com.bea.adapter.spi.abstractmaagedcoectio, a implemetatio of the J2EE iterface javax.resource.spi.maagedcoectio. The DBMS adapter exteds this class i com.bea.adapter.dbms. spi.maagedcoectioimpl. Listig 8-18 shows the derivatio tree for MaagedCoectioImpl. Listig 8-18 com.bea.adapter.dbms.spi.maagedcoectioimpl javax.resource.spi.maagedcoectio -->com.bea.adapter.spi.abstractmaagedcoectio -->com.bea.adapter.dbms.spi.maagedcoectioimpl B-26 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

227 How the DBMS Sample Adapter Was Developed Developers Commets CoectioMetaDataImpl This class is well documeted i the Javadoc commets sice the MaagedCoectio is a crucial part of the Java Coector Architecture SPI specificatio. You should focus o our implemetatio of the followig methods: Basic Implemetatio java.lag.object.getcoectio(javax.security.auth.subject subject, javax.resource.spi.coectiorequestifo coectiorequestifo) protected void destroyphysicalcoectio(java.lag.object objphysicalcoectio) protected void destroycoectiohadle(java.lag.object objhadle) boolea comparecredetials(javax.security.auth.subject subject, javax.resource.spi.coectiorequestifo ifo) The pig() method is used to check whether the physical database coectio (ot our cci.coectio) is still valid. If a exceptio occurs, pig() is very specific about checkig the type so that a coectio is ot eedlessly destroyed. Other methods are EIS specific or are simply required setter/getters. The MaagedCoectioMetaData iterface provides iformatio about the uderlyig EIS istace associated with a MaagedCoectio istace. A applicatio server uses this iformatio to get rutime iformatio about a coected EIS istace. For more iformatio, read about how the ADK implemets the AbstractCoectioMetaData istace i MaagedCoectio. The ADK provides com.bea.adapter.spi.abstractcoectiometadata, a implemetatio of the J2EE iterface javax.resource.spi.maagedcoectio MetaData. The DBMS adapter exteds this class i com.bea. adapter.dbms.spi.coectiometadataimpl. Listig 8-19 shows the derivatio tree for CoectioMetaDataImpl. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-27

228 B The DBMS Sample Adapter Listig 8-19 com.bea.adapter.dbms.spi.coectiometadataimpl javax.resource.spi.maagedcoectiometadata -->com.bea.adapter.spi.abstractcoectiometadata -->com.bea.adapter.dbms.spi.coectiometadataimpl Developers Commets The ADK s AbstractCoectioMetaData implemets the followig: LocalTrasactioImpl Basic Implemetatio javax.resource.cci.coectiometadata javax.resource.spi.maagedcoectiometadata This implemetatio of the CoectioMetaData class uses a DatabaseMetaData object. Sice the ADK's abstract implemetatio was used, you must provide EIS-specific kowledge whe implemetig the abstract methods i this class. The LocalTrasactio iterface provides support for trasactios that are maaged iteral to a EIS resource maager ad do ot require a exteral trasactio maager. For more iformatio, read about how the ADK implemets the AbstractLocalTrasactio istace i LocalTrasactio. The ADK provides com.bea.adapter.spi.abstractlocaltrasactio, a implemetatio of the J2EE iterface javax.resource.spi.localtrasactio. The DBMS adapter exteds this class i com.bea.adapter.dbms. spi.localtrasactioimpl. Listig 8-20 shows the derivatio tree for LocalTrasactioImpl. B-28 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

229 How the DBMS Sample Adapter Was Developed Listig 8-20 com.bea.adapter.dbms.spi.localtrasactioimpl javax.resource.spi.localtrasactio -->com.bea.adapter.spi.abstractlocaltrasactio -->com.bea.adapter.dbms.spi.localtrasactioimpl Developers Commets This class utilizes the ADK s abstract superclass which provides loggig ad evet otificatio. The superclass implemets both the CCI ad SPI LocalTrasactio iterfaces provided by Su. The DBMS adapter s cocrete class implemets the three abstract methods of the superclass: dobegitx() docommittx() dorollbacktx() Step 3: Implemetig the Commo Cliet Iterface Package Table 8-7 CCI Class Extesios To implemet the DBMS adapter Commo Cliet Iterface (CCI) ad meet the J2EE-compliat CCI requiremets, ADK classes to create the followig cocrete classes were exteded: This cocrete class... CoectioImpl IteractioImpl IteractioSpecImpl Exteds this ADK class... AbstractCoectio AbstractIteractio IteractioSpecImpl BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-29

230 B The DBMS Sample Adapter These classes provide coectivity to ad access back-ed systems. The cliet iterface specifies the format of the request ad respose records for a give iteractio with the EIS. Note: Although implemetig the Commo Cliet Iterface (CCI) is optioal i the Java Coector Architecture 1.0 specificatio, it is likely to be required i the future. For your referece, the DBMS adapter provides a complete implemetatio. CoectioImpl Basic Implemetatio A Coectio represets a applicatio-level hadle that is used by a cliet to access the uderlyig physical coectio. The actual physical coectio associated with a Coectio istace is represeted by a MaagedCoectio istace. For more iformatio, read about how the ADK implemets the AbstractCoectio istace i Coectio. The ADK provides com.bea.adapter.cci.abstractcoectio, a implemetatio of the J2EE iterface javax.resource.cci.coectio. The DBMS adapter i by implemetig com.bea.adapter.dbms.cci. CoectioImpl. Listig 8-21 shows the derivatio tree for CoectioImpl. Listig 8-21 com.bea.adapter.dbms.cci.coectioimpl javax.resource.cci.coectio -->com.bea.adapter.cci.abstractcoectio -->com.bea.adapter.dbms.cci.coectioimpl Developers Commets The CoectioImpl class is the DBMS adapter s cocrete implemetatio of the javax.resource.cci.coectio iterface. It exteds the ADK s AbstractCoectio class. The actual physical coectio associated with a coectio istace is represeted by a MaagedCoectio istace. B-30 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

231 How the DBMS Sample Adapter Was Developed IteractioImpl Basic Implemetatio A cliet gets a coectio istace by usig the getcoectio() method o a CoectioFactory istace. A coectio ca be associated with zero or more iteractio istaces. The simplicity of this cocrete class is a testamet to the power of extedig the ADK s base classes. The Iteractio eables a compoet to execute EIS fuctios. A iteractio istace is created from a coectio ad is required to maitai its associatio with the Coectio istace. For more iformatio, read about how the ADK implemets the AbstractIteractio istace i Iteractio. The ADK provides com.bea.adapter.cci.abstractiteractio, a implemetatio of the J2EE iterface javax.resource.cci.iteractio. The DBMS adapter exteds this class i com.bea.adapter.dbms.cci. IteractioImpl. Listig 8-22 shows the derivatio tree for IteractioImpl. Listig 8-22 com.bea.adapter.dbms.cci.iteractioimpl javax.resource.cci.iteractio -->com.bea.adapter.cci.abstractiteractio -->com.bea.adapter.dbms.cci.iteractioimpl Developers Commets This is the cocrete implemetatio of the ADK s Iteractio object. As expected, the methods are EIS-specific implemetatios of Java Coector Architecture/ADK required methods. Both versios of the Java Coector Architecture s javax.resource.cci.iteractioexecute()method (the cetral method of this class) were implemeted. The mai logic for the execute() method has the followig BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-31

232 B The DBMS Sample Adapter IteractioSpecImpl Basic Implemetatio sigature: public Record execute(iteractiospec ispec, Record iput). This method retur the actual output record from the iteractio, so it is the oe that is called more ofte. The secod implemetatio is provided as a coveiece method. This form of execute() has the followig sigature: public boolea execute(iteractiospec ispec, Record iput, Record output). The secod implemetatio s logic returs a boolea, which idicates oly the success or failure of the iteractio. A IteractioSpecImpl holds properties for drivig a iteractio with a EIS istace. A IteractioSpec is used by a iteractio to execute the specified fuctio o a uderlyig EIS. The CCI specificatio defies a set of stadard properties for a IteractioSpec, but a IteractioSpec implemetatio is ot required to support a stadard property if that property does ot apply to its uderlyig EIS. The IteractioSpec implemetatio class must provide getter ad setter methods for each of its supported properties. The getter ad setter methods covetio should be based o the Java Beas desig patter. For more iformatio, read about how the ADK implemets the IteractioSpecImpl istace i IteractioSpec. The ADK provides com.bea.adapter.cci.iteractiospecimpl, a implemetatio of the J2EE iterface javax.resource.cci.iteractiospec. The DBMS adapter exteds this class i com.bea.adapter.dbms. cci.iteractiospecimpl. Listig 8-23 shows the derivatio tree for IteractioSpecImpl. Listig 8-23 com.bea.adapter.dbms.cci.iteractiospecimpl javax.resource.cci.iteractiospec -->com.bea.adapter.cci.iteractiospecimpl -->com.bea.adapter.dbms.cci.iteractiospecimpl B-32 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

233 How the DBMS Sample Adapter Was Developed Developers Commets A implemetatio class for IteractioSpec iterface is required to implemet the java.io.serializable iterface. IteractioSpec exteds the ADK IteractioSpec i order to add setter/getter methods for the Strig attribute m_sql. The getter/setter methods should be based o the Java Beas desig patter as specified i the Java Coector Architecture 1.0 specificatio. Step 4: Implemetig the Evet Package This package cotais oly oe class: the DBMS adapter EvetGeeratorWorker. It does the work for the evet geerator for the DBMS adapter. DbmsEvetGeeratorWorker The EvetGeeratorWorker class implemets the followig iterfaces: com.bea.wlai.evet.ievetgeerator java.lag.ruable. Basic Implemetatio The DBMS adapter EvetGeeratorWorker exteds the ADK s AbstractPullEvetGeerator because a database caot push iformatio to the evet geerator; you therefore eed to pull or actually poll the database for chages about which you are iterested i beig otified. Listig 8-24 shows the derivatio tree for DbmsEvetGeeratorWorker. Listig 8-24 DbmsEvetGeeratorWorker com.bea.adapter.evet.abstractevetgeerator -->com.bea.adapter.evet.abstractpullevetgeerator -->com.bea.adapter.dbms.evet.dbmsevetgeeratorworker BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-33

234 B The DBMS Sample Adapter Developers Commets This cocrete implemetatio of the ADK s AbstractPullEvetGeerator implemets the abstract methods: protected abstract void postevets(ievetrouter router) throws Exceptio protected abstract void setupnewtypes(list listofnewtypes) protected abstract void removedeadtypes(list listofdeadtypes). It also overrides the followig methods: void doiit(map map) void docleaupoquit(). These methods are EIS specific ad are used to idetify a evet withi the cotext of the EIS while iteractig with the database to create ad remove evet defiitios ad evets. Additioally, these methods create ad remove the actual triggers o the database that are fired whe a evet occurs. The key method of the class is postevets(). It creates the IEvet objects of the data take from rows i the EVENT table of the database. This method takes a IEvetRouter as a argumet. After creatig a IEvet usig the IEvetDefiitio object s createdefaultevet() method, it populates the evet data, ad the evet is propagated to the router by callig router.postevet(evet). Oce the evet is set to the router, the method deletes the row of evet data from the database. The method setupnewtypes()creates ew evet defiitios, makig sure that the appropriate trigger is created for the database. For each evet defiitio, the method creates a trigger iformatio object that describes the catalog, schema, table, triggertype, ad trigger key that the evet defiitio represets. A map of trigger keys is kept so that triggers are ot redudatly added to the database. If the map does t cotai the ew key, the trigger text for the database is geerated. The method removedeadtypes() also creates a trigger iformatio object; however, it also checks if oe or more evet types match it. All evet defiitios that match this trigger are removed from the map, ad the the trigger is removed from the database. B-34 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

235 How the DBMS Sample Adapter Was Developed Step 5: Deployig the Adapter After implemetig the SPI, CCI ad evet iterfaces, the adapter is deployed. To deploy the adapter: Update the RA.XML File. Create the.rar File. Deploy the.rar File. Step 5a: Update the RA.XML File The DBMS adapter provides the ra.xml file i the adapter s.rar file (META-INF/ra.xml). Sice the DBMS adapter exteds the AbstactMaagedCoectioFactory class, the followig properties are provided i the ra.xml file: LogLevel LaguageCode CoutryCode MessageBudleBase LogCofigFile RootLogCotext AdditioalLogCotext However, the DBMS sample adapter requires these additioal declaratios: Table 8-8 RA.XML Properties Property UserName Password DataSourceName Descriptio The userame for DBMS adapter logi. The password for DBMS adapter logi. The ame of the JDBC coectio pool BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-35

236 B The DBMS Sample Adapter Table 8-8 RA.XML Properties Property XaCompliatAsBoolea PigTable Descriptio Idicates whether or ot the data source is XA compliat. Idetifies the table i the DBMS that ca be piged to verify the coectio. You ca view the complete ra.xml file for the DBMS adapter i: *WLAI_HOME\dev\dbms\src\rar\meta-if\ * WLAI_HOME is the drive or home directory where BEA WebLogic Applicatio Itegratio is istalled. Step 5b: Create the.rar File Class files, loggig cofiguratio, ad message budle(s) should be budled ito a file. This.jar file ad META-INF/ra.xml should the be budled ito.rar file. The ANT build.xml file demostrates how to properly costruct the.rar file. Step 5c: Deploy the.rar File The.rar file should be deployed ito the cotaier i the J2EE-compliat applicatio server. The deploymet procedure is differet o every J2EE-compliat server. How the DBMS Adapter Desig-Time GUI was Developed The desig-time GUI is the user iterface that allows the user to create applicatio views, add services ad evets ad deploy the adapter if it is hosted i the BEA WebLogic Applicatio Itegratio. This sectio discusses some specific desig time issues that were cosidered durig the developmet of the DBMS adapter. The process of creatig the DBMS adapter desig-time GUI is comprised of the followig steps: B-36 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

237 How the DBMS Adapter Desig-Time GUI was Developed Step 1: Developmet Cosideratios Step 2: Determie Necessary Java Server Pages Step 3: Create the Message Budle Step 4: Implemetig the Desig-Time GUI Step 5: Writig Java Server Pages Step 1: Developmet Cosideratios Some of the importat developmet cosideratios regardig the desig-time GUI for the DBMS adapter icluded: Determie the database(s) that were goig to be supported. Determie browsig depth. Determie the DBMS schema geeratio. Determie if the adapter should support testig of services ad evets. Step 2: Determie Necessary Java Server Pages The DBMS adapter uses the ADK s Java Server Pages (JSPs) for a desig-time GUI; however, additioal Java Server pages have bee added to provide adapter-specific fuctioality. A descriptio of the additioal JSPs follows: Fileame addevet.jsp addservice.jsp Descriptio The Add Evet page allows a user to add a ew evet to the applicatio view. The Add Service page allows the user to add a ew service to the applicatio view. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-37

238 B The DBMS Sample Adapter Fileame browse.jsp cofco.jsp display.jsp testform.jsp Descriptio The Browse page hadles the flow logic ad display for the Browse widow of the DBMS adapter. Although this fuctioality was developed specifically for this adapter, it illustrates a fairly commo iteractio betwee the desig-time iterface ad the uderlyig adapter. It uses the DesigTimeRequestHadler (hadler) of the DBMS adapter, which exteds the ADK s AbstractDesigTimeRequestHadler. The best way to uderstad the browse fuctioality of the DBMS adapter is to deploy the adapter ad use your web browser to access the desig-time framework. The Cofirm Coectio page provides a form for a user to specify coectio parameters for the EIS. The Display page is the mai displayer for other Java Server Pages i the adapter. It autheticates the request ad sets the basic look of each scree with a title ad descriptio. It icludes each JSP that is requested ad displays it ilie. The Testform page is icluded (<jsp:iclude page='testform.jsp'/>) i the ADK's testsrvc.jsp page. It accesses the IteractioSpec for this iteractio ad displays the SQL for the service o scree. It the creates a form for gatherig required user iput to test a service. It does this by gettig the RequestDocumetDefiitio from the hadler's ApplicatioView ad the passig it alog with the.jsp Writer to a utility class, com.bea.adapter.dbms.utils.testformbuilder, which actually creates the required form. Step 3: Create the Message Budle To support the iteratioalizatio of all text labels, messages ad exceptios, the DBMS adapter uses a message budle based o a text property file. The property file uses copied ame value pairs from the BEA_WLS_SAMPLE_ADK property file, ad ew etries were added for properties specific to the DBMS adapter. B-38 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

239 How the DBMS Adapter Desig-Time GUI was Developed The message budle for the DBMS adapter is cotaied i * wlaihome\dbms\src directory, which was istalled with the ADK. The wlaihome idicates the drive used durig istallatio. Please refer to BEA_WLS_DBMS_ADK.properties i the directory above. For additioal istructios o creatig a message budle, refer to the JavaSoft tutorial o iteratioalizatio at Step 4: Implemetig the Desig-Time GUI To implemet the desig-time GUI, you eed to create a DesigTimeRequestHadler class. This class accepts user iput from a form ad provides methods to perform a desig-time actio. For more iformatio o the DesigTimeRequestHadler, see Step 4: Implemetig the Desig-Time GUI i Developig a Desig-Time GUI. The DBMS adapter public class DesigTimeRequestHadler exteds AbstractDesigTimeRequestHadler, ad it provides the methods show i Table 8-9: Table 8-9 Methods for the DBMS Sample Adapter Desig-Time GUI Method browse(java.lag.strig dbtype, com.bea.coector.documetrecord iput) getadapterlogicalname() getmaagedcoectiofactoryclass() supportsservicetest() Descriptio Hadles the back-ed behavior for the Browse fuctioality of the addevet.jsp ad addservc.jsp. Returs the adapter's logical ame ad helps paret whe deployig applicatio views, etc. Returs the adapter's SPI MaagedCoectioFactory implemetatio class, used by paret to get a CCI coectio to the EIS. Idicates that this adapter desig time supports the testig of services. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-39

240 B The DBMS Sample Adapter Method iitservicedescriptor(actioresult result, IServiceDescriptor sd, HttpServletRequest request) iitevetdescriptor(actioresult result, IEvetDescriptor ed, HttpServletRequest request) GetDatabaseType() Descriptio Iitializes a service descriptor which ivolves creatig the request ad respose schemas for the service. A typical approach is to execute a Iteractio agaist the EIS to retrieve metadata ad trasform it ito a XML schema. Cosequetly, the CCI iterface provided by the adapter was used. This method is called from the addsrvc method of the AbstractDesigTimeRequestHadler. Iitializes a evet descriptor. The evet descriptor provides iformatio about a evet o a applicatio view. Subclasses will eed to supply a implemetatio of this method. If evets are ot supported, the the implemetatio should throw a UsupportedOperatioExceptio. This method will ot be called (by the AbstractDesigTimeRequestHadler) util the evet ame ad defiitio have bee validated ad it is cofirmed that the evet does ot already exist for the applicatio view. This method is used to determie the type of dbms beig used. At preset BEA WebLogic Applicatio Itegratio supports Oracle, Microsoft SQL Server, ad Cloudscape. Step 5: Writig Java Server Pages The followig issues are relevat for the DBMS adapter, ad you may ecouter them as you develop your ow adapter. Custom JSP Tags Save a Object s State Write the WEB-INF/web.xml Web Applicatio Deploymet Descriptor B-40 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

241 How the DBMS Adapter Desig-Time GUI was Developed Custom JSP Tags Save a Object s State The Java Server Pages are displayed withi the display.jsp; thus display.jsp is the first.jsp that eeds to be writte. The ADK provides a library of custom.jsp tags, which are used extesively throughout the Java server pages of the ADK ad DBMS adapter. They provide the ability to add validatio, to save field values whe the user clicks away, ad a umber of other features. You may also eed to save a object s state as you write the Java server pages. There are a umber of ways to save a object s state whe buildig your adapter usig the ADK. The AbstractDesigTimeRequestHadler maitais a ApplicatioViewDescriptor of the applicatio view beig edited. This is ofte the best place to save state. Calls to the hadler are fast ad efficiet. You ca also ask the AbstractDesigTimeRequestHadler for a Maager Bea, usig its coveiece methods: getapplicatioviewmaager(); getschemamaager(); ad getnamespacemaager(), to retrieve iformatio from the repository about a applicatio view. This is more time-cosumig but may be ecessary o occasio. Sice it is a Java Server Page, you ca also use the sessio object, although everythig put i the sessio must explicitly implemet the java.io.serializable iterface. Write the WEB-INF/web.xml Web Applicatio Deploymet Descriptor Write the WEB-INF/web.xml Web applicatio deploymet descriptor. I most cases, you should use the sample adapter's web.xml file as a startig poit ad modify the ecessary compoets to fit your eeds. For detailed iformatio, see the BEA WebLogic Server product documetatio at BEA WebLogic Applicatio Itegratio Adapter Developmet Guide B-41

242 B The DBMS Sample Adapter B-42 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

243 APPENDIX C The Sample Adapter This sectio cotais iformatio o the followig subjects: Itroductio to the Sample Adapter How the Sample Adapter Works How the Evet Adapter was Developed Creatig the Adapter Desig-Time GUI Itroductio to the Sample Adapter The adapter is a J2EE-compliat adapter built with BEA WebLogic Applicatio Itegratio Adapter Developmet Kit. The purpose of the adapter is to provide a way for ay applicatio to sed otice i case of system failure or process completio. This otificatio is directed usig , which could be cofigured to target multiple addresses or eve a pager. A sigle templated message could be created for umerous errors allowig the adapter to plug i replaceable parameters ad sed the otificatio. The adapter provides sample implemetatios of both a services ad evets. The evet implemetatio provides sample code for both push ad pull evet geerator paradigms. The service implemetatio eables the cliet to sed ad message BEA WebLogic Applicatio Itegratio Adapter Developmet Guide C-1

244 C The Sample Adapter with a miimum of iformatio. Service-specific data is iformatio required to sed a message, such as source address, target addresses, subject, ad the body of a message. The sample adapter gives you (developers ad busiess aalysts) a cocrete example of a adapter, icludig a JSP-based GUI, to help you uderstad the possibilities that are at your disposal usig the ADK to build adapters. If you are a busiess aalyst, you may ejoy ruig through the iterface to get a better uderstadig of a applicatio view, service, ad evet as show i How the Sample Adapter Works. If you are a adapter developer, you will also wat to review How the Evet Adapter was Developed ad Creatig the Adapter Desig-Time GUI, the code, ad javadoc to gai isight ito how you ca exted ad use the classes of the ADK to build a JCA-compliat adapter. How the Sample Adapter Works This sectio provides you with a opportuity to have a look at the adapter before you start developig a adapter of your ow. If you are a busiess aalyst, you may ejoy ruig through the iterface to get a feel for how the adapter works. The example i this sectio shows how to create a applicatio view for sedig or receivig s. This sectio cotais iformatio o the followig subjects: Before You Begi Accessig the Sample Adapter A Tour of the Sample Adapter Before You Begi Make sure the followig tasks have bee performed before you try to access the sample adapter: Istall the BEA WebLogic Applicatio Itegratio. For more iformatio, see the BEA WebLogic Applicatio Itegratio Istallatio ad Setup Guide. C-2 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

245 How the Sample Adapter Works Set up the ADK At-Based Make Process. For more iformatio, see Step 2c: Settig Up the Build Process. Esure that the sample adapter has bee deployed so that the desig-time GUI is accessible. For more iformatio, see the BEA WebLogic Applicatio Itegratio Istallatio ad Setup Guide. Accessig the Sample Adapter To access the Adapter: 1. Ope a ew browser widow. 2. Ope the URL for your system s Applicatio View Maagemet Cosole. The Applicatio Itegratio Cosole - Logi page displays. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide C-3

246 C The Sample Adapter A Tour of the Sample Adapter This sectio provides you with a short tour through the Sample adapter. Before you begi, you eed to have the adapter Logi page up o your browser. For iformatio about accessig the adapter, see Accessig the Sample Adapter. 1. To log o to the Applicatio View Maagemet Cosole, eter your WebLogic userame ad password, the click Logi. The Applicatio View Maagemet Cosole displays. C-4 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

247 How the Sample Adapter Works 2. Click Add Applicatio View. The Defie New Applicatio View page displays. Whe you create the applicatio view, you provide a descriptio that associates the applicatio view with the adapter. Note: For detailed iformatio about applicatio views, see Itroductio to Usig Applicatio Itegratio. For detailed iformatio about defiig applicatio views, see Defiig Applicatio Views i the BEA WebLogic Applicatio Itegratio User Guide. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide C-5

248 C The Sample Adapter. 3. To defie a applicatio view: a. I the Applicatio View Name field, eter TestAppView. Note: The ame should describe the set of fuctios performed by this applicatio. Each applicatio view ame must be uique to its adapter. Valid characters are aythig except., #, \, +, &,,,,, ad a space. b. I the Descriptio field, eter a brief descriptio of the applicatio view. c. From the Associated Adapters list, choose the adapter to use to create this applicatio view. d. Click OK. The Cofigure Coectio Parameters page displays.. C-6 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

249 How the Sample Adapter Works 4. At the Cofigure Coectio Parameters page, you defie the etwork-related iformatio ecessary for the applicatio view to iteract with the target EIS. You eed to eter this iformatio oly oce per applicatio view: a. Eter your User Name ad Password. b. Eter the service URL i the Coect Strig field. c. Click Cotiue. The Applicatio View Admiistratio page displays. Note: The Admiistratio page summarizes the coectio criteria, ad oce evets ad services are defied, you ca view the schemas ad summaries ad also delete a evet or service from this page. 5. Now that you have created a applicatio view, you are ready to add a service. To add a service: a. I the Admiistratio page, click Add i the Services field. The Add Service page displays. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide C-7

250 C The Sample Adapter b. I the servicename field, a meaigful ame for the service. c. I the servicedesc field, eter a user descriptio for the service. d. I the To field, eter a list of target addresses. e. I the From field, eter the source address. f. I the CC filed, eter a list of addresses to receive a copy. g. I the BCC field, eter a list of addresses to receive a blid copy, delimited by a semicolo. h. I the Subject Field, eter the subject of the . i. Select the Text radio butto to sed a plai text message. Select Template to defie replaceable parameters. Note: The body type ca be either text or template. A template ca cotai tags for replaceable parameters. C-8 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

251 How the Sample Adapter Works j. I the ope text field, eter the text of the message. Note: The body ca cotai replaceable parameters if the type is template, otherwise it will cotai a text message. k. Click Add Service. The Admiistratio page displayed. 6. Now that you have created a applicatio view, you are ready to add a evet to it. To add a evet: a. I the Admiistratio page, click Add i the Evet field. The Add Evet page displays. b. I the evetname field, eter a meaigful ame for the evet. c. I the evetdesc field, eter a descriptio of the evet. d. Select either the IMAP or POP3 radio butto. Whe cofigurig a evet you ca use either the POP3, or IMAP access protocols depedig o the type of evet geerator you wish to deploy. Use IMAP if you are tryig to deploy the Push evet geerator. Use POP3 to deploy the Pull evet geerator. Whe IMAP is selected you ca select a folder to liste to. POP3/Pull supports the use of a sigle folder, the INBOX folder. e. Scroll to select a folder to query for mail. f. Click Save AppView. The Appliatio View Admiistratio page displays. BEA WebLogic Applicatio Itegratio Adapter Developmet Guide C-9

252 C The Sample Adapter 7. Prepare to deploy the applicatio view. The Applicatio View Admiistratio page provides you with a sigle locatio for cofirmig the cotet of your applicatio view before you save it or deploy it. I this page, you ca view the followig: l l l l Cofirm or edit the descriptio of the applicatio view. Cofirm or recofigure Coectio Criteria for the applicatio view. Delete services ad evets. Save the applicatio view so you ca retur to it later or deploy the applicatio view to the server. After verifyig the applicatio view parameters, click Cotiue. The Deploy Applicatio View to Server page displays. C-10 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide

253 How the Sample Adapter Works 8. Deploy the Applicatio View. I order to deploy the applicatio view, you must provide several parameters such as eablig asychroous service ivocatio, providig the evet router URL, ad chagig the coectio pool parameters, amog other parameters. To deploy the applicatio view: a. Make sure the Eable Asychroous Service Ivocatio check box is checked. b. I the Evet Router URL field, eter c. For the Coectio Pool Parameters, accept the default values: Miimum Pool Size - 1 Maximum Pool Size - 10 Target Fractio of Maximum Pool Size Allow Pool to Shrik - checked BEA WebLogic Applicatio Itegratio Adapter Developmet Guide C-11

254 C The Sample Adapter d. I the Log Cofiguratio field, eter Log warigs, errors, ad audit messages. e. Make sure the Deploy persistetly? box is checked. f. Click Deploy. 9. Oce the applicatio view is deployed, the summary page displays all relevat iformatio about the deployed applicatio view. Use the Summary page to view schemas, evet ad service summaries, test services ad evets ad udeploy the applicatio view. C-12 BEA WebLogic Applicatio Itegratio Adapter Developmet Guide