BEA WebLogic Server. Programming WebLogic Enterprise JavaBeans

Transcription

1 BEA WebLogic Server Programmig WebLogic Eterprise JavaBeas WebLogic Server 6.0 Documet Date March 3, 2001

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

3 About This Documet xvii Audiece xviii e-docs Web Site xviii How to Prit the Documet xviii Related Iformatio xix Cotact Us! xix Documetatio Covetios xx EJB Features ad Chages i WebLogic Server 1-1 Implemetatio of Nofial Specificatio 1-1 EJB 2.0 Upgrade for WebLogic Server 1-2 EJB 2.0 Features 1-2 Supported Features 1-2 Features i Developmet 1-3 Major EJB Chages i This Release 1-3 Message-Drive Bea Support 1-4 Cotaier-Maaged Persistece 1-4 EJB QL 1-5 Applicatio Assembly Support i Deployig EJBs 1-5.jar,.ear, ad Directory Deploymet Uits 1-5 Usupported Deploymet Utilities 1-5 DDCoverter Upgrade Utility 1-6 WebLogic Server EJB Desig ad Developmet 2-1 Ivokig Deployed EJBs 2-1 Accessig EJBs from either Local or Remote Cliets 2-2 Restrictios o Accessig EJB Istaces 2-3 Storig EJB Refereces i Home Hadles 2-3 Usig Home Hadles Across a Firewall 2-3 EJB Desig Tips 2-4 Preserve Trasactio Resources 2-4 Allow the Datastore to Maage Trasactios 2-5 Usig Cotaier-Maaged Trasactios Istead of Bea-Maaged Trasactios 2-5 Never Demarcate Trasactios from Applicatio 2-5 Use Correct Modelig for Etity EJBs 2-6 Etity EJBs Should Be Coarse-Graied 2-6 Etity EJBs Should Cotai Busiess Logic 2-6 Optimize Etity EJB Data Access 2-6 Use ismodified() Where Appropriate 2-7 Usig Iheritace with EJBs 2-7 Usig Sessio Beas 2-8 Usig Message-Drive Beas 3-1

4 What Are Message-Drive Beas? 3-1 Differeces Betwee Message-Drive Beas ad Stadard JMS Cosumers 3-2 Differeces Betwee Message-Drive Beas ad Stateless Sessio EJBs 3-3 Cocurret Support for Message-Drive Beas 3-3 Ivokig a Message-Drive Bea 3-4 Developig Message-Drive Beas 3-4 Bea Class Requiremets 3-4 Creatig ad Removig Bea Istaces 3-5 Usig the Message-Drive Bea Cotext 3-6 Implemetig Busiess Logic with omessage() 3-6 Hadlig Exceptios 3-7 Trasactio Services for Message-Drive Beas 3-7 Message Receipts 3-8 Message Ackowledgmet 3-8 Deployig Message-Drive Beas i WebLogic Server 3-9 Deploymet Descriptors 3-9 Deploymet Elemets 3-9 The WebLogic Server EJB Cotaier 4-1 EJB Life Cycle i WebLogic Server 4-2 Stateless Sessio EJB Life Cycle 4-2 Iitializig EJB Istaces 4-2 Activatig ad Poolig EJBs 4-3 Stateful EJB Life Cycle 4-3 Iitializig ad Usig EJB Istaces 4-4 Passivatig Stateful EJBs 4-4 Removig Stateful Sessio EJB Istaces 4-5 Usig max-beas-i-free-pool 4-6 Stateful Sessio EJB Requiremets 4-7 Special Use of max-beas-i-free pool 4-7 Lockig Model for Etity EJBs 4-8 ejbload() ad ejbstore() Behavior for Etity EJBs 4-8 Usig db-is-shared to Limit Calls to ejbload() 4-9 Restrictios ad Warigs for db-is-shared 4-10 Usig is-modified-method-ame to Limit Calls to ejbstore() 4-10 Warig for is-modified-method-ame 4-11 Usig delay-updates-util-ed-of-tx to Chage ejbstore() Behavior 4-11 Settig the Etity EJBs to Read-Oly 4-12 Read-Write Cache Strategy 4-12 Read-Oly-Cache-Strategy 4-12 Restrictios for Read-Oly EJBs 4-12

5 Read-Mostly Patter 4-13 EJBs i WebLogic Server Clusters 4-14 Overview 4-14 Clustered EJBHome Objects 4-15 Clustered EJBObjects 4-15 Sessio EJBs i a Cluster 4-16 Stateless Sessio EJBs 4-16 Stateful Sessio EJBs 4-17 I-Memory Replicatio for Stateful Sessio EJBs 4-18 Requiremets ad Cofiguratio 4-18 Limitatios of I-Memory Replicatio 4-19 Etity EJBs i a Cluster 4-19 Read-Write Etity EJBs 4-19 No-Trasactioal Datastores 4-21 Trasactio Maagemet 4-21 Trasactio Maagemet Resposibilities 4-21 Usig javax.trasactio.usertrasactio 4-22 Restrictio for Cotaier-Maaged EJBs 4-23 Distributig Trasactios Across Multiple EJBs 4-23 Callig Multiple EJBs from a Sigle Trasactio Cotext 4-23 Ecapsulatig a Multi-Operatio Trasactio 4-24 Distributig Trasactios Across EJBs i a WebLogic Server Cluster 4-24 Trasactio Isolatio Level 4-25 Limitatios of TRANSACTION_SERIALIZABLE 4-25 Special Note for Oracle Databases 4-25 Resource Factories 4-26 Settig Up JDBC Datasource Factories 4-26 Settig up URL Coectio Factories 4-27 Persistece Services 4-28 Usig WebLogic Server RDBMS Persistece 4-29 Writig Fiders for RDBMS Persistece 4-29 Fider Sigature 4-30 fider-list Staza 4-30 fider-query Elemet 4-31 Usig WebLogic Query Laguage (WLQL) 4-31 Sytax 4-31 Operators 4-31 Operads 4-32 Examples of WLQL Expressios 4-33 Usig Java Expressios i WLQL 4-34

6 Example of Fider Method Sigatures 4-36 Restrictios 4-37 Lockig ad Cachig Services for Etity EJBs 4-38 Pessimistic Lockig Services 4-38 Database Lockig Services 4-38 Settig Up Database Lockig 4-39 Home Method Support for Etity EJBs 4-40 WebLogic Server Cotaier-Maaged Persistece Services 5-1 EJB 2.0 Persistece Features ad Chages 5-2 get ad set Method Restrictios 5-2 BLOB ad CLOB DBMS Colum Restrictios 5-2 EJB QL Requiremet for EJB 2.0 Beas 5-3 ismodified() Not Required for CMP Beas 5-3 Usig EJB QL 5-3 Basic EJB QL Sytax 5-4 EJB QL Strig Literals 5-4 EJB QL Operators 5-4 Fider Methods 5-4 Fider Parameter Placeholders 5-5 Select Methods 5-5 EJB QL Coditioal Expressios 5-5 EJB QL Examples 5-6 Migratig from (EJB 1.1) WLQL to (EJB 2.0) EJB QL 5-7 Usig WebLogic Query Laguage Extesio 5-8 ORDERBY 5-8 Cotaier-Maaged Relatioships 5-8 Oe-to-Oe Relatioships 5-9 Oe-to-May Relatioships 5-10 May-to-May Relatioships 5-10 Uidirectioal Relatioships 5-10 Bidirectioal Relatioships 5-10 Primary Keys 5-11 Foreig Keys 5-11 Groups 5-11 Specifyig Field Groups 5-12 Usig Groups 5-12 Supported Data Types 5-13 Deployig EJBs to WebLogic Server 6-1 Required Steps for Deployig EJBs 6-1 Settig Deploymet Properties 6-2

7 Geeratig EJB Cotaier Classes 6-4 Loadig EJB Classes ito WebLogic Server 6-5 Deployig EJBs at WebLogic Server Startup 6-5 Deployig EJBs i Differet Applicatios 6-6 Deployig EJBs i a Ruig WebLogic Server (Dyamic Deploymet) 6-6 EJB Deploymet Names 6-7 Viewig Deployed EJBs 6-7 Deployig New EJBs ito a Ruig Eviromet 6-8 Udeployig Deployed EJBs 6-8 Udeployig EJBs 6-9 Updatig Deployed EJBs 6-9 The Update Process 6-10 Updatig the EJB 6-10 Deployig EJBs i the EJB Cotaier 7-1 Roles ad Resposibilities 7-1 WebLogic Server Deploymet Files 7-2 Automatic Deploymet Directory 7-4 Deployig Compiled EJB.jar Files 7-4 Deployig Ucompiled EJB.jar Files 7-5 Deployig from a EJB.jar Directory 7-6 WebLogic Server EJB Utilities 8-1 ejbc 8-1 Sytax 8-2 Argumets 8-2 Optios 8-2 Examples 8-3 DDCoverter 8-4 Covertig EJBs for Use i WebLogic Server Covertig EJB CMP 1.1 Beas to EJB CMP 2.0 Beas 8-4 Covertig CMP Beas betwee WebLogic Server Versios 8-5 Sytax 8-5 Argumets 8-6 Optios 8-6 Examples 8-6 deploy 8-7 Sytax 8-7 Argumets 8-7 Optios 8-8 WebLogic Server 6.0 EJB Deploymet Properties 9-1 Maually Editig XML Deploymet Files 9-1

8 DOCTYPE Header Iformatio 9-2 Documet Type Defiitios (DTDs) for Validatio 9-3 weblogic-ejb-jar.xml Deploymet Descriptor File 9-4 Idex of weblogic-ejb-jar Deploymet Elemets 9-5 allow-cocurret-calls 9-8 Fuctio 9-8 Example 9-8 cocurrecy-strategy 9-9 Fuctio 9-9 Example 9-9 db-is-shared 9-10 Fuctio 9-10 Example 9-10 delay-updates-util-ed-of-tx 9-11 Fuctio 9-11 Example 9-11 descriptio 9-12 Fuctio 9-12 Example 9-12 destiatio-jdi-ame 9-13 Fuctio 9-13 Example 9-13 ejb-ame 9-14 Fuctio 9-14 Example 9-14 ejb-referece-descriptio 9-15 Fuctio 9-15 Example 9-15 ejb-ref-ame 9-16 Fuctio 9-16 Example 9-16 eable-call-by-referece 9-17 Fuctio 9-17 Example 9-17 etity-cache 9-18 Fuctio 9-18 Example 9-18 etity-clusterig 9-19 Fuctio 9-19 Example 9-19

9 etity-descriptor 9-20 Fuctio 9-20 Example 9-20 fiders-load-bea 9-21 Fuctio 9-21 Example 9-21 home-call-router-class-ame 9-22 Fuctio 9-22 Example 9-22 home-is-clusterable 9-23 Fuctio 9-23 Example 9-23 home-load-algorithm 9-24 Fuctio 9-24 Example 9-24 idle-timeout-secods 9-25 Fuctio 9-25 Example 9-25 iitial-beas-i-free-pool 9-26 Fuctio 9-26 Example 9-26 is-modified-method-ame 9-27 Fuctio 9-27 Example 9-27 isolatio-level 9-28 Fuctio 9-28 Example 9-29 jdi-ame 9-29 Fuctio 9-29 Example 9-29 lifecycle 9-30 Fuctio 9-30 Example 9-30 max-beas-i-cache 9-31 Fuctio 9-31 Example 9-31 max-beas-i-free-pool 9-32 Fuctio 9-32 Example 9-32 message-drive-descriptor 9-33

10 Fuctio 9-33 Example 9-33 method 9-34 Fuctio 9-34 Example 9-34 method-itf 9-35 Fuctio 9-35 Example 9-35 method-ame 9-36 Fuctio 9-36 Example 9-36 method-param 9-37 Fuctio 9-37 Example 9-37 method-params 9-38 Fuctio 9-38 Example 9-38 passivatio-strategy 9-39 Fuctio 9-39 Example 9-39 persistece 9-40 Fuctio 9-40 Example 9-40 persistece-type 9-41 Fuctio 9-41 Example 9-41 persistece-use 9-42 Fuctio 9-42 Example 9-42 persistet-store-dir 9-43 Fuctio 9-43 Example 9-43 pool 9-44 Fuctio 9-44 Example 9-44 pricipal-ame 9-45 Fuctio 9-45 Example 9-45 read-timeout-secods 9-46 Fuctio 9-46

11 Example 9-46 referece-descriptor 9-47 Fuctio 9-47 Example 9-47 replicatio-type 9-48 Fuctio 9-48 Example 9-48 res-ev-ref-ame 9-49 Fuctio 9-49 Example 9-49 res-ref-ame 9-50 Fuctio 9-50 Example 9-50 resource-ev-descriptio 9-51 Fuctio 9-51 Example 9-51 resource-descriptio 9-52 Fuctio 9-52 Example 9-52 role-ame 9-53 Fuctio 9-53 Example 9-53 ru-as-idetity-pricipal 9-54 Fuctio 9-54 Example 9-54 security-role-assigmet 9-55 Fuctio 9-55 Example 9-55 stateful-sessio-cache 9-56 Fuctio 9-56 Example 9-56 stateful-sessio-clusterig 9-57 Fuctio 9-57 Example 9-57 stateful-sessio-descriptor 9-58 Fuctio 9-58 Example 9-58 stateless-bea-call-router-class-ame 9-59 Fuctio 9-59 Example 9-59

12 stateless-bea-is-clusterable 9-60 Fuctio 9-60 Example 9-60 stateless-bea-load-algorithm 9-61 Fuctio 9-61 Example 9-61 stateless-bea-methods-are-idempotet 9-62 Fuctio 9-62 Example 9-62 stateless-clusterig 9-63 Fuctio 9-63 Example 9-63 stateless-sessio-descriptor 9-64 Fuctio 9-64 Example 9-64 trasactio-descriptor 9-65 Fuctio 9-65 Example 9-65 trasactio-isolatio 9-66 Fuctio 9-66 Example 9-66 tras-timeout-secods 9-67 Fuctio 9-67 Example 9-67 type-idetifier 9-68 Fuctio 9-68 Example 9-68 type-storage 9-69 Fuctio 9-69 Example 9-69 type-versio 9-70 Fuctio 9-70 Example 9-70 weblogic-cmp-rdbms-jar.xml Deploymet Descriptor File 9-71 Idex of weblogic-cmp-rdbms-jar.xml Deploymet Elemets 9-71 cmp-field 9-73 Fuctio 9-73 Example 9-73 cmr-field 9-74 Fuctio 9-74

13 Example 9-74 colum-map 9-75 Fuctio 9-75 Example 9-75 data-source-ame 9-76 Fuctio 9-76 Example 9-76 dbms-colum 9-77 Fuctio 9-77 Example 9-77 ejb-ame 9-78 Fuctio 9-78 Example 9-78 field-group 9-79 Fuctio 9-79 Example 9-79 field-map 9-80 Fuctio 9-80 Example 9-80 foreig-key-colum 9-81 Fuctio 9-81 Example 9-81 group-ame 9-82 Fuctio 9-82 Example 9-82 key-colum 9-83 Fuctio 9-83 Example 9-83 max-elemets 9-84 Fuctio 9-84 Example 9-84 method-ame 9-85 Fuctio 9-85 Example 9-85 method-param 9-86 Fuctio 9-86 Example 9-86 method-params 9-87 Fuctio 9-87 Example 9-87

14 query-method 9-88 Fuctio 9-88 Example 9-88 relatio-ame 9-89 Fuctio 9-89 Example 9-89 relatioship-role-ame 9-90 Fuctio 9-90 Example 9-90 table-ame 9-91 Fuctio 9-91 Example 9-91 weblogic-ql 9-92 Fuctio 9-92 Example 9-92 weblogic-query 9-93 Fuctio 9-93 Example 9-93 weblogic-relatioship-role 9-94 Fuctio 9-94 Example 9-94 WebLogic Server 5.1 EJB Deploymet Properties 10-1 Maually Editig XML Deploymet Files 10-1 Basic Covetios 10-2 DOCTYPE Header Iformatio 10-2 Documet Type Defiitios (DTDs) for Validatio 10-3 weblogic-ejb-jar.xml Deploymet Descriptor File 10-4 Cachig Properties 10-4 cachig-descriptor 10-5 Persistece Properties 10-7 persistece-descriptor 10-7 Clusterig Properties clusterig-descriptor Trasactio Properties trasactio-descriptor EJB Refereces referece-descriptor Isolatio Level Settigs trasactio-isolatio isolatio-level 10-15

15 method Security Role Assigmets security-role-assigmet eable-call-by-referece weblogic-cmp-rdbms-jar.xml Deploymet Descriptor File RDBMS Defiitio Elemets pool-ame schema-ame table-ame EJB Field-Mappig Elemets attribute-map object-lik bea-field dbms-colum Fider Elemets fider-list fider method-ame method-params method-param fider-query fider-expressio 10-22

16

17 About This Documet This documet describes how to develop ad deploy Eterprise JavaBeas (EJBs) o WebLogic Server. This documet is orgaized as follows: Chapter 1, EJB Features ad Chages i WebLogic Server, is a overview of EJB features supported i WebLogic Server. Chapter 2, WebLogic Server EJB Desig ad Developmet, is a overview of desig techiques developers ca use to create EJBs. Chapter 3, Usig Message-Drive Beas, explais how to develop ad deploy message-drive beas i the WebLogic Server cotaier. Chapter 4, The WebLogic Server EJB Cotaier, describes the services available to the EJB with the WebLogic Services cotaier. Chapter 5, WebLogic Server Cotaier-Maaged Persistece Services, describes the EJB 2.0 cotaier-maaged persistece services available for the WebLogic Server cotaier. Chapter 6, Deployig EJBs to WebLogic Server, describes the steps ecessary to deploy EJB to WebLogic Server. Chapter 7, Deployig EJBs i the EJB Cotaier, describes the process for deployig EJBs i the EJB cotaier. Chapter 8, WebLogic Server EJB Utilities, describes the utilities, shipped with WebLogic Server, that are used with EJBs. Chapter 9, WebLogic Server 6.0 EJB Deploymet Properties, describes the WebLogic-specific deploymet descriptors for the EJB 2.0 cotaier that are supplied i WebLogic Server 6.0. Programmig WebLogic Eterprise JavaBeas xvii

18 Chapter 10, WebLogic Server 5.1 EJB Deploymet Properties, describes the WebLogic-specific deploymet descriptors shipped with WebLogic Server 5.1. These properties are provided for referece purposes. Audiece This documet is iteded maily for applicatio developers who are iterested i developig Eterprise JavaBeas (EJBs) for use i dyamic Web-based applicatios. Readers are assumed to be familiar with EJB architecture, XML codig, ad Java programmig. e-docs Web Site BEA product documetatio is available o the BEA corporate Web site. From the BEA Home page, click o Product Documetatio. How to Prit the Documet You ca prit a copy of this documet from a Web browser, oe mai topic at a time, by usig the File Prit optio o your Web browser. A PDF versio of this documet is available o the WebLogic Server 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 WebLogic Server documetatio Home page, click Dowload Documetatio, ad select the documet you wat to prit. Adobe Acrobat Reader is available at o charge from the Adobe Web site at xviii Programmig WebLogic Eterprise JavaBeas

19 Related Iformatio Aditioal documetatio related to EJBs icludes: Java Remote Method Ivocatio (RMI) Extesible Markup Laguage (XML) Java Namig ad Directory Iterface (JNDI) Cotact Us! Your feedback o BEA documetatio is importat to us. Sed us at docsupport@bea.com if you have questios or commets. Your commets will be reviewed directly by the BEA professioals who create ad update the documetatio. I your message, please idicate the software ame ad versio you are usig, as well as the title ad documet date of your documetatio. If you have ay questios about this versio of BEA WebLogic Server, or if you have problems istallig ad ruig BEA WebLogic Server, 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 Programmig WebLogic Eterprise JavaBeas xix

20 Documetatio Covetios The followig documetatio covetios are used throughout this documet. Covetio Ctrl+Tab italics moospace text moospace italic text UPPERCASE TEXT Usage Keys you press simultaeously. Emphasis ad book titles. Code samples, commads ad their optios, Java classes, data types, directories, ad file ames ad their extesios. Moospace text also idicates text that you eter from the keyboard. Examples: import java.util.eumeratio; chmod u+w * cofig/examples/applicatios.java cofig.xml float Variables i code. Example: Strig CustomerName; Device ames, eviromet variables, ad logical operators. Examples: LPT1 BEA_HOME OR { } A set of choices i a sytax lie. [ ] Optioal items i a sytax lie. Example: java utils.multicasttest - ame -a address [-p portumber] [-t timeout] [-s sed] xx Programmig WebLogic Eterprise JavaBeas

21 Covetio Usage Separates mutually exclusive choices i a sytax lie. Example: java weblogic.deploy [list deploy udeploy update] password {applicatio} {source}... Idicates oe of the followig i a commad lie: A argumet ca be repeated several times i the commad lie. The statemet omits additioal optioal argumets. You ca eter additioal parameters, values, or other iformatio... Idicates the omissio of items from a code example or from a sytax lie. Programmig WebLogic Eterprise JavaBeas xxi

22 xxii Programmig WebLogic Eterprise JavaBeas

23 Implemetatio of Nofial Specificatio 1 EJB Features ad Chages i WebLogic Server WebLogic Server Versio 6.0 icludes a implemetatio of Su Microsystems Eterprise JavaBeas 1.1 ad 2.0 architecture. This architecture defies a stadard way of creatig server compoets that are part of distributed object-orieted applicatios. Eterprise JavaBeas are the stadard used to defie server-side compoets. The followig sectios provide a overview of the EJB features ad the chages itroduced i the WebLogic Server Versio 6.0 Eterprise JavaBeas implemetatio: Implemetatio of Nofial Specificatio EJB 2.0 Upgrade for WebLogic Server EJB 2.0 Features Major EJB Chages i This Release Implemetatio of Nofial Specificatio The Eterprise JavaBeas 2.0 implemetatio i WebLogic Server Versio 6.0 will be fully supported ad ca be used i productio. However, be advised that the Su Microsystems EJB 2.0 specificatio is ot yet fialized, ad the WebLogic Server implemetatio of the EJB 2.0 architecture is based o the most curret public draft of Programmig WebLogic Eterprise JavaBeas 1-1

24 1 EJB Features ad Chages i WebLogic Server this specificatio. Cosequetly oce the specificatio is fialized, there could be chages to the Eterprise JavaBeas 2.0 implemetatio i future versios of WebLogic Server. These chages may cause applicatio code developed for WebLogic Server Versio 6.0 to be icompatible with EJB 2.0 implemetatios supported i future releases. EJB 2.0 Upgrade for WebLogic Server Before you ca use the EJB 2.0 features with WebLogic Server Versio 6.0, you must dowload the EJB20.jar file ad the EJB 2.0 README file after you have istalled WebLogic Server Versio 6.0. The EJB 2.0.jar file is a upgrade to WebLogic Server Versio 6.0 that eables the EJB 2.0 features. To dowload the.jar file: 1. Select the product dowload optio from the BEA web site, bea.com. 2. Copy the zip file for the EJB 2.0 upgrade to your machie. This zip file cotais the EJB20.jar ad the EJB 2.0 README files. 3. Use the istructios i the EJB 2.0 README file to istall the JAR file. EJB 2.0 Features This sectio lists the EJB 2.0 features that are ew to WebLogic Server Versio 6.0 ad the EJB 2.0 features that are i developmet. Supported Features Support for the followig features is provided i WebLogic Server 6.0. Support for message-drive beas EJB 2.0 cotaier-maaged persistece services, icludig support for EJB-QL 1-2 Programmig WebLogic Eterprise JavaBeas

25 Major EJB Chages i This Release Support for etity EJB home methods EJB 2.0 XML deploymet properties I-memory replicatio for stateful sessio EJBs i a cluster Database lockig optio for etity EJBs Improved EJB Deploymet ad redeploymet capabilities ismodified() o loger required for EJB 2.0 CMP etity beas Compliace with EJB 1.1 specificatio Features i Developmet Because the cotaier is based o pre-release versios of the EJB 2.0 specificatio, certai EJB 2.0 features are ot yet available. Kow differeces betwee the cotaier ad the publicly available EJB 2.0 specificatio are ackowledged i this documet where applicable. The followig EJB 2.0 cotaier ad WebLogic Server features will ot be supported util a future release of the WebLogic Server EJB 2.0 cotaier: Support for the fial EJB 2.0 specificatio Depedet objects Ru-as-specified-idetity Major EJB Chages i This Release This release of WebLogic Server Versio 6.0 cotais major chages to the supported EJB features. The followig sectios describe some of those chages: Programmig WebLogic Eterprise JavaBeas 1-3

26 1 EJB Features ad Chages i WebLogic Server Message-Drive Bea Support EJBs are itegrated with the Java Message Service (JMS) to provide the ability for a message-drive bea to act as a stadard JMS message cosumer. The message-drive bea is a stateless compoet that is ivoked by the EJB cotaier as a result of receivig messages from a JMS Queue or Topic. The message-drive bea the performs busiess logic based o the message cotets. Usig the message-drive bea model allows EJB developers to work with a familiar framework ad set of tools ad also provides access to the additioal support provided by the cotaier. Message-drive beas have o home or remote iterface, ad therefore caot be directly accessed by iteral or exteral cliets. Cliets iteract with message-drive beas oly idirectly, by sedig a message to a JMS Queue or Topic. WebLogic Server automatically creates ad removes message-drive bea istaces as eeded to process icomig messages. Oly the WebLogic Server cotaier directly iteracts with a message-drive bea by creatig bea istaces ad passig JMS messages to those istaces as ecessary. The goal of the message-drive bea model is to assure that developig a EJB, that is asychroously ivoked to hadle the processig of icomig JMS messages, is as easy as developig the same fuctioality i ay other JMS MessageListeer. For more iformatio o message-drive beas, see Developig Message-Drive Beas o page 3-4. Cotaier-Maaged Persistece This release provides added support for cotaier-maaged relatioships amog etity beas. This cotaier-maaged persistece model is a improvemet over the limitatios of the field-based approach to cotaier-maaged persistece i earlier versios. With cotaier-maaged persistece, database access calls are ot writte i the etity bea. Istead, persistece is hadled by the EJB cotaier that is available at ru time. The persistet fields ad relatioships for which the cotaier must geerate data access calls are specified i the deploymet descriptors. Whe the etity bea is deployed, the cotaier is used to geerate the ecessary database access calls. For more iformatio o cotaier-maaged persistece, see EJB 2.0 Persistece Features ad Chages o page Programmig WebLogic Eterprise JavaBeas

27 Major EJB Chages i This Release EJB QL This release supports for Eterprise JavaBeas Query Laguage (EJB QL). EJB QL is a sytax for the defiitio of fider methods or queries for etity beas with cotaier-maaged persistece. This sytax allows the Persistece Maager to provide for the implemetatio of the fider methods. EJB QL defies fider methods so that they are portable across cotaiers ad persistece maagers. EJB QL is a declarative, SQL-like laguage that is meat to be compiled to the target laguage of the persistet datastore used by a Persistece Maager. For more iformatio o EJB QL, see Usig EJB QL o page 5-3. Applicatio Assembly Support i Deployig EJBs WebLogic Server simplifies the process of deployig multiple EJB deploymet uits to oe or more WebLogic Servers. Whe WebLogic Server is started, the EJBs are automatically assembled ad deployed to the appropriate WebLogic Server..jar,.ear, ad Directory Deploymet Uits You ca deploy a Eterprise Applicatio Archive (EAR) file or a Java Archive (JAR) file by either copyig the file to the cofig/examples/applicatios directory or by deployig the file from the WebLogic Admiistratio Cosole. The files ad subdirectories cotaied i the deploymet directory must observe the same restrictios as files ad subdirectories stored i a.jar file. Usupported Deploymet Utilities The followig EJB deploymet utilities o loger exist with WebLogic Server Versio 6.0: DDCreator EJB Deploymet Wizard WebLogic Server does ot provide a DDCreator utility to geerate ew ejb-jar.xml deploymet files. However, you ca use DDCoverter with a earlier WebLogic Server text deploymet descriptio to geerate a valid ejb-jar.xml file. Programmig WebLogic Eterprise JavaBeas 1-5

28 1 EJB Features ad Chages i WebLogic Server Note: If you are a EJB provider ad you eed to create a ew ejb-jar.xml file from scratch, see the JavaSoft EJB 1.1 or 2.0 specificatio for istructios. DDCoverter Upgrade Utility The ew DDCoverter utility provides a quick ad easy way to upgrade earlier WebLogic Server EJB deploymet descriptors, such as those i WebLogic Server 5.1, to WebLogic Server Versio 6.0. DDCoverter takes a existig WebLogic Server text descriptio file ad geerates the.xml ad weblogic-ejb-jar.xml files required for deployig to Versio 6.0. DDCoverter also automatically geerates a rdbms-jar.xml deploymet file for etity EJBs that use WebLogic RDBMS-based persistece services. See DDCoverter o page 8-4 for istructios o usig the DDCoverter utility. 1-6 Programmig WebLogic Eterprise JavaBeas

29 CHAPTER 2 WebLogic Server EJB Desig ad Developmet The followig sectios provide a collectio of desig tips ad debuggig poits to keep i mid whe buildig applicatios with Eterprise JavaBeas. A umber of these tips apply to remote object models, Remote Method Ivocatio (RMI) ad Commo Object Request Broker Architecture (CORBA), as much as they do to EJB. Ivokig Deployed EJBs EJB Desig Tips Ivokig Deployed EJBs WebLogic Server automatically creates implemetatios of a EJB s home ad remote iterfaces that ca fuctio remotely. This meas that all cliets whether they reside i the same server as the EJB, or o a remote computer ca access deployed EJBs i a similar fashio. With the EJB 1.1 ad 2.0 specificatio, all EJBs must specify their eviromet properties usig Java Namig ad Directory Iterface (JNDI). EJB cliets ca cofigure their JNDI ame spaces to iclude the home EJBs that reside aywhere o the etwork o multiple machies, applicatio servers, or cotaiers. Programmig WebLogic Eterprise JavaBeas 2-1

30 2 WebLogic Server EJB Desig ad Developmet However, i desigig eterprise applicatio systems, you must still cosider the effects of trasmittig data across a etwork betwee EJBs ad their cliets. Due to etwork overhead, it is still more efficiet to access beas from a local cliet a servletoraotherejb tha to do so from a remote cliet where data must be marshalled, trasmitted over the etwork, ad the umarshalled. Accessig EJBs from either Local or Remote Cliets... Oe differece betwee accessig EJBs from local cliets or from remote cliets is i obtaiig a IitialCotext for the bea. Remote cliets obtai a 6IitialCotext from the WebLogic Server IitialCotext factory. WebLogic Server local cliets geerally use a getiitialcotext method to perform this lookup, similar to the followig excerpt: Cotext ctx = getiitialcotext("t3://localhost:7001", "user1", "user1password");... static Cotext getiitialcotext(strig url, Strig user, Strig password) { } Properties h = ew Properties(); h.put(cotext.initial_context_factory, "weblogic.jdi.wliitialcotextfactory"); h.put(cotext.provider_url, url); h.put(cotext.security_principal, user); retur ew IitialCotext(h); Iteral cliets of a EJB, such as servlets, ca simply create a IitialCotext usig the default costructor, as show here: Cotext ctx = ew IitialCotext(); 2-2 Programmig WebLogic Eterprise JavaBeas

31 Ivokig Deployed EJBs Restrictios o Accessig EJB Istaces Although database cocurrecy is the default ad recommeded process for cocurrecy access, it is possible to use etity EJBs that ca be accessed by multiple cliets i a serial fashio. However, this process is available for use with legacy applicatios that deped o this exclusive optio. Usig this exclusive optio meas that if two cliets attempt to access the same etity EJB istace (a istace havig the same primary key), the secod cliet is blocked util the EJB is available. For more iformatio o the database cocurrecy optio, see Lockig Model for Etity EJBs o page 4-8. Simultaeous access to a stateful sessio EJB results i a RemoteExceptio, as required by the EJB 1.1 specificatio. However, you ca set the allow-cocurret-calls optio to specify that a stateful sessio bea istace will allow cocurret method calls. This access restrictio o stateful sessio EJBs applies whether the EJB cliet is remote or iteral to WebLogic Server. If multiple servlet classes access a sessio EJB, each servlet thread (rather tha each istace of the servlet class) must have its ow sessio EJB istace. To avoid cocurret access, a JSP/servelet ca use a stateful sessio bea i request scope. Storig EJB Refereces i Home Hadles Oce a cliet has obtaied the EJBHome object for a EJB istace, it ca create a referece to the home object by callig gethomehadle(). gethomehadle() returs a HomeHadle object, which ca be used to obtai the home iterface to the same EJB istace at a later time. A cliet ca pass the HomeHadle object as argumets to aother cliet, ad the receivig cliet ca use the hadle to obtai a referece to the same EJBHome object. Cliets ca also serialize the HomeHadle ad store it i a file for later use. Usig Home Hadles Across a Firewall By default, WebLogic Server stores its IP address i the HomeHadle object for EJBs. This ca cause problems with certai firewall systems. If you are uable to locate EJBHome objects usig home hadles passed across a firewall, use the followig steps: 1. Start WebLogic Server. Programmig WebLogic Eterprise JavaBeas 2-3

32 2 WebLogic Server EJB Desig ad Developmet 2. Start the WebLogic Server Admiistratio Cosole. 3. From the left-had pae, expad the Servers ode ad select a server. 4. I the right-had pae, select the Cofiguratio tab for that server ad the the Network tab. 5. Check the Reverse DNS Allowed box to eable reverse DNS lookups. Whe you eable reverse DNS lookups, WebLogic Server stores the DNS ame of the server, rather tha the IP address, i EJB home hadles. EJB Desig Tips The followig sectios describe desig tips for developig ad deployig EJBs o your system. Preserve Trasactio Resources Database trasactios are typically oe of the most valuable resources i a olie trasactio-processig system. Whe usig EJBs with WebLogic Server, trasactio resources are eve more valuable due to their relatioship with database coectios. WebLogic Server ca use a sigle coectio pool to service multiple, simultaeous database requests. The efficiecy of the coectio pool is largely determied by the umber ad legth of database trasactios that use the pool. For o-trasactioal database requests, WebLogic Server ca allocate ad deallocate a coectio very quickly, so that the same coectio ca be used by aother cliet. However, for trasactioal requests, a coectio becomes reserved by the cliet for the duratio of the trasactio. To optimize trasactio use o your system, always follow a iside-out approach to trasactio demarcatio. Trasactios should begi ad ed at the iside of the system (the database) where possible, ad move outside (toward the cliet applicatio) oly as ecessary. The followig sectios describe this rule i more detail. 2-4 Programmig WebLogic Eterprise JavaBeas

33 EJB Desig Tips Allow the Datastore to Maage Trasactios May RDBMS systems provide high-performace lockig systems for OLTP trasactios. With the help of Trasactio Processig (TP) moitors such as Tuxedo, RDBMS systems ca also maage complex decisio support queries across multiple datastores. If your uderlyig datastore has such capabilities, use them where possible. You should ever prevet the RDBMS from automatically delimitig trasactios. Usig Cotaier-Maaged Trasactios Istead of Bea-Maaged Trasactios Your system should rarely rely o bea-maaged trasactio demarcatio. Use WebLogic Server cotaier-maaged trasactio demarcatio uless you have a specific eed for bea-maaged trasactios. Possible scearios where you may eed bea-maaged trasactios are: You must defie multiple trasactios from withi a sigle method call. WebLogic Server demarcates trasactios o a per-method basis; if you require multiple trasactios i a sigle method call, you must use bea-maaged trasactios. Note: However, keep i mid that if your EJBs use multiple trasactios i a sigle method call, it is still better to break the trasactios out across multiple methods ad use cotaier-maaged trasactios with the revised bea. A sigle trasactio must spa multiple EJB method calls. For example, oe method begis a trasactio, ad aother method commits or rolls back the trasactio. I geeral, this practice should be avoided where possible sice it requires detailed iformatio about the workigs of the EJB object. If it is required, you must use bea-maaged trasactio coordiatio, ad you must coordiate cliet calls to the respective methods. Never Demarcate Trasactios from Applicatio I geeral, cliet applicatios are ot guarateed to stay active over log periods of time. If a cliet begis a trasactio ad the exits before committig, it wastes valuable trasactio ad coectio resources i WebLogic Server. Moreover, eve if the cliet does ot exit durig a trasactio, the duratio of the trasactio may be uacceptable if it relies o user activity to commit or roll back data. Always demarcate trasactios at the WebLogic Server or RDBMS level where possible. Programmig WebLogic Eterprise JavaBeas 2-5

34 2 WebLogic Server EJB Desig ad Developmet Use Correct Modelig for Etity EJBs Readig ad writig RDBMS data via a etity bea ca cosume valuable etwork resources. Network traffic may occur betwee a cliet ad WebLogic Server, as well as betwee WebLogic Server ad the uderlyig datastore. Use the followig suggestios to model etity EJB data correctly ad avoid uecessary etwork traffic. Etity EJBs Should Be Coarse-Graied You should ot attempt to model every object i your system as a etity EJB. I particular, small subsets of data cosistig of oly a few bytes should ever exist as etity EJBs, as the trade-off i etwork resources is uacceptable. For example, lie items i a ivoice or cells i a spreadsheet are too fie-graied ad should ot be accessed frequetly over a etwork. I cotrast, logical groupigs of a ivoice s etries, or a subset of cells i a spreadsheet may be modeled as a etity EJB, if additioal busiess logic is required for the data. Etity EJBs Should Cotai Busiess Logic Eve coarse-graied objects may be iappropriate for modelig as a etity EJB if the data requires o additioal busiess logic. For example, if the methods i your etity EJB work oly to set or retrieve data values, it is more appropriate to use JDBC calls i a RDBMS cliet or to use a sessio EJB for modelig. Etity EJBs should ecapsulate additioal busiess logic for the modeled data. For example, a bakig applicatio that uses differet busiess rules for Platium ad Gold customers might model all customer accouts as etity EJBs; the EJB methods ca the apply the appropriate busiess logic whe settig or retrievig data fields for a particular customer type. Optimize Etity EJB Data Access Etity EJBs ultimately model fields that exist i a data store. Optimize etity EJBs wherever possible to simplify ad miimize database access. I particular: Limit the complexity of jois agaist EJB data. Avoid log-ruig operatios that require disk access i the datastore. 2-6 Programmig WebLogic Eterprise JavaBeas

35 EJB Desig Tips Esure that EJB methods retur as much data as possible, so as to miimize roud-trips betwee the cliet ad the datastore. For example, if your EJB cliet must retrieve data fields, use bulk get/setattributes() methods to miimize etwork traffic. Use ismodified() Where Appropriate Use the ismodified() method i etity EJBs to elimiate uecessary database writes for read-oly operatios. However, this is o loger required for EJB 2.0 cotaier-maaged persistece (CMP) etity beas. See Usig is-modified-method-ame to Limit Calls to ejbstore() o page 4-10 for more iformatio. Usig Iheritace with EJBs Usig iheritace may be appropriate whe buildig groups of related beas that share commo code. However, be aware of several iheritace restrictios that apply to EJB implemetatios. For bea-maaged EJBs, the ejbcreate() method must retur a primary key. Ay class that iherits from the bea-maaged EJB class caot have a ejbcreate() method that returs a differet primary key class. This restrictio applies eve if the ew class is derived from the base EJB s primary key class. The restrictio also applies to the bea s ejbfid() methods. Additioal restrictios exist for EJBs where iheritig aother EJB implemetatio chages the iterface. For example, the followig table describes a situatio where a derived bea adds a ew method that is meat to be accessible remotely: Bea Method Iterface Method ABea afoo() ARemote afoo() BBea (exteds ABea) bfoo() BRemote bfoo() However if you use this example, you caot have the BHome iterface iherit from the AHome iterface, because AHome.create() ad BHome.create() retur differet remote iterfaces. Programmig WebLogic Eterprise JavaBeas 2-7

36 2 WebLogic Server EJB Desig ad Developmet You ca still use iheritace to have methods i the beas that are uique to a particular class, that iherit from a superclass or that are overridde i the subclass. See the example Eterprise JavaBea subclass Child example packages ad classes i the WebLogic Server distributio. Usig Sessio Beas Oe way to desig sessio beas is to use a model-view-cotroller desig. The view is the GUI form ad the model is the piece of code that supplies data to the scree. I a typical cliet-server system, the model lives o the same server as the view ad talks to the server. The model should reside o the server, i the form of a sessio bea. (This is aalogous to havig a servlet providig support for a HTML form, except that a model sessio bea does ot affect the fial presetatio.) With this desig there should be oe model sessio bea istace for each GUI form istace, which acts as the form s represetative o the server. For example, if you have a list of 100 etwork odes to display i a form, you might have a method called getnetworknodes() o the correspodig EJB which returs a array of values relevat to that list. This approach keeps the overall trasactio time short, ad requires miimal etwork badwidth. I cotrast, cosider a approach where the GUI form calls a etity EJB fider method that retrieves refereces to 100 separate etwork odes. For each of the refereces, the cliet must go back to the datastore to retrieve additioal data, which cosumes cosiderable etwork badwidth ad may yield uacceptable performace. 2-8 Programmig WebLogic Eterprise JavaBeas

37 CHAPTER 3 Usig Message-Drive Beas The followig sectios describe how to develop ad deploy message-drive beas i the EJB 2.0 for BEA WebLogic Server cotaier. Because message-drive beas utilize parts of the stadard JMS API, you should first become familiar with the WebLogic JMS messagig system before attemptig to implemet message-drive beas. See the Programmig WebLogic JMS documet for more iformatio. What Are Message-Drive Beas? Developig Message-Drive Beas Trasactio Services for Message-Drive Beas Deployig Message-Drive Beas i WebLogic Server What Are Message-Drive Beas? A message-drive bea is a special kid of EJB that acts as a message cosumer i the WebLogic JMS messagig system. As with stadard JMS message cosumers, message-drive beas receive messages from a JMS Queue or Topic, ad perform busiess logic based o the message cotets. EJB deployers create listeers to a Queue or Topic at deploymet time, ad WebLogic Server automatically creates ad removes message-drive bea istaces as eeded to process icomig messages. Programmig WebLogic Eterprise JavaBeas 3-1

38 3 Usig Message-Drive Beas Differeces Betwee Message-Drive Beas ad Stadard JMS Cosumers Because message-drive beas are implemeted as EJBs, they beefit from several key services that are ot available to stadard JMS cosumers. Most importatly, message-drive bea istaces are wholly maaged by the WebLogic Server EJB cotaier. Usig a sigle message-drive bea class, WebLogic Server creates multiple EJB istaces as ecessary to process large volumes of messages cocurretly. This stads i cotrast to a stadard JMS messagig system, where the developer must create a MessageListeer class that utilizes a server-wide sessio pool. The WebLogic Server cotaier provides other stadard EJB services to messagedrive beas, such as security services ad automatic trasactio maagemet. These services are described i more detail i Trasactio Maagemet o page 4-21 ad i Trasactio Services for Message-Drive Beas o page 3-7. Fially, message-drive beas beefit from the write-oce, deploy-aywhere quality of EJBs. Whereas a JMS MessageListeer is tied to specific sessio pools, Queues, or Topics, message-drive beas ca be developed idepedetly of available server resources. A message-drive bea s Queues ad Topics are assiged oly at deploymet time, utilizig resources available o the particular WebLogic Server istace. Note: Oe limitatio of message-drive beas compared to stadard JMS listeers is that a give message bea deploymet ca be associated with oly oe Queue or Topic, as described i Deployig Message-Drive Beas i WebLogic Server. If your applicatio requires a sigle JMS cosumer to service messages from multiple Queues or Topics, you must use a stadard JMS cosumer, or deploy multiple message-drive bea classes. 3-2 Programmig WebLogic Eterprise JavaBeas

39 What Are Message-Drive Beas? Differeces Betwee Message-Drive Beas ad Stateless Sessio EJBs I several ways, the dyamic creatio ad allocatio of message-drive bea istaces mimics the behavior of stateless sessio EJB istaces. However, message-drive beas are differet from stateless sessio EJBs (ad other types of EJBs) i several sigificat ways: Message-drive beas process multiple JMS messages asychroously, rather tha processig a serialized sequece of method calls. Message-drive beas have o home or remote iterface, ad therefore caot be directly accessed by iteral or exteral cliets. Cliets iteract with message-drive beas oly idirectly, by sedig a message to a JMS Queue or Topic. Note: Oly the WebLogic Server cotaier directly iteracts with a message-drive bea by creatig bea istaces ad passig JMS messages to those istaces as ecessary. WebLogic Server maitais the etire life cycle of a message-drive bea; istaces caot be created or removed as a result of cliet requests or other API calls. Cocurret Support for Message-Drive Beas Message-Drive Beas support cocurret processig for both topics ad queues. Previously, oly cocurret processig for Queues was supported. To esure cocurrecy, chage the weblogic-ejb-jar.xml deploymet descriptor max-beas-i-free-pool settig to >1. If this elemet is set to more tha oe, the cotaier will spaw as may threads as specified. For more iformatio o this elemet see, max-beas-i-free-pool o page Programmig WebLogic Eterprise JavaBeas 3-3

40 3 Usig Message-Drive Beas Ivokig a Message-Drive Bea Whe a JMS Queue or Topic receives a message, use WebLogic Server to call a associated message-drive bea as follows: 1. Obtai a ew bea istace. Obtai a ew bea istace from the coectio pool if oe already exists, or create a ew oe. See Creatig ad Removig Bea Istaces o page If the bea caot be located i the pool ad a ew oe must be created, call the bea s setmessagedrivecotext() to associate the istace with a cotaier cotext. The bea ca utilize elemets of this cotext as described i Usig the Message-Drive Bea Cotext o page Call the bea s omessage() method to perform busiess logic. See Implemetig Busiess Logic with omessage() o page 3-6. Note: These istaces ca be pooled. Developig Message-Drive Beas To create message-drive EJBs, you must follow certai covetios described i the JavaSoft EJB 2.0 specificatio, as well as observe several geeral practices that result i proper bea behavior. Bea Class Requiremets The EJB 2.0 specificatio provides detailed guidelies for defiig the methods i a message-drive bea class. The followig output shows the basic compoets of a message-drive bea class. Classes, methods, ad method declaratios i bold are required as part of the EJB 2.0 specificatio: public class MessageTraderBea implemets javax.ejb.messagedrivebea { public MessageTraderBea() {...}; 3-4 Programmig WebLogic Eterprise JavaBeas

41 Developig Message-Drive Beas // A EJB costructor is required, ad it must ot declared as // accept parameters. The costructor must ot be // fial or abstract. public void omessage(javax.jms.message MessageName) {...} parameter of // omessage() is required, ad must take a sigle // type javax.jms.message. The throws clause (if used) must ot ot be // iclude a applicatio exceptio. omessage() must // declared as fial or static. public void ejbremove() {...} parameters. applicatio // ejbremove() is required ad must ot accept // The throws clause (if used) must ot iclude a //exceptio. ejbremove() must ot be declared as fial or static. } fialize{}; // The EJB class caot defie a fialize() method Creatig ad Removig Bea Istaces The WebLogic Server cotaier calls the message-drive bea s ejbcreate() ad ejbremove() methods whe creatig or removig a istace of the bea class. As with other EJB types, the ejbcreate() method i the bea class should prepare ay resources that are required for the bea s operatio. The ejbremove() method should release those resources, so that they are freed before WebLogic Server removes the istace. Programmig WebLogic Eterprise JavaBeas 3-5

42 3 Usig Message-Drive Beas Message-drive beas should also perform some form of regular clea-up routie outside of the ejbremove() method, because the beas caot rely o ejbremove() beig called uder all circumstaces (for example, if the EJB throws a rutime exceptio). Usig the Message-Drive Bea Cotext WebLogic Server calls setmessagedrivecotext() to associate the message-drive bea istace with a cotaier cotext.this is ot a cliet cotext; the cliet cotext is ot passed alog with the JMS message. WebLogic Server provides the EJB with a cotaier cotext, whose properties ca be accessed from withi the istace by usig the followig methods from the MessageDriveCotext iterface: getcallerpricipal() iscallerirole() setrollbackoly() The EJB ca use this method oly if it utilizes cotaier-maaged trasactio demarcatio. getrollbackoly() The EJB ca use this method oly if it utilizes cotaier-maaged trasactio demarcatio. getusertrasactio() The EJB ca use this method oly if it utilizes bea-maaged trasactio demarcatio. Note: Although getejbhome() is also iherited as part of the MessageDriveCotext iterface, message-drive EJBs do ot have a home iterface. Callig getejbhome() from withi a message-drive EJB istace yields a IllegalStateExceptio. Implemetig Busiess Logic with omessage() Themessage-drive bea s omessage() method performs all of the busiess logic for the EJB. WebLogic Server calls omessage() whe the EJB s associated JMS Queue or Topic receives a message, passig the full JMS message object as a argumet. It is the message-drive EJB s resposibility to parse the message ad perform the ecessary busiess logic i omessage(). 3-6 Programmig WebLogic Eterprise JavaBeas

43 Trasactio Services for Message-Drive Beas Make sure that the busiess logic accouts for asychroous message processig. For example, it caot be assumed that the EJB receives messages i the order they were set by the cliet. Istace poolig withi the cotaier meas that messages are ot received or processed i a sequetial order, although idividual omessage() calls to a give message-drive bea istace are serialized. See javax.jms.messagelisteer.omessage() for more iformatio. Hadlig Exceptios Message-drive bea methods should ot throw a applicatio exceptio or a RemoteExceptio,eveioMessage(). If ay method throws such a exceptio, WebLogic Server immediately removes the EJB istace without callig ejbremove(). However, from the cliet perspective the EJB still exists, because future messages are forwarded to a ew istace that WebLogic Server creates. Trasactio Services for Message-Drive Beas As with other EJB types, message-drive beas ca demarcate trasactio boudaries either o their ow (usig bea-maaged trasactios), or by havig the WebLogic Server cotaier maage trasactios (cotaier-maaged trasactios). I either case, a message-drive bea does ot receive a trasactio cotext from the cliet that seds a message. WebLogic Server always calls a bea s omessage() method by usig the trasactio cotext specified i the bea s deploymet descriptor, as required by the EJB 2.0 specificatio. Because o cliet provides a trasactio cotext for calls to a message-drive bea, beas that use cotaier-maaged trasactios must be deployed usig the Required or NotSupported trasactio attribute i ejb-jar.xml. Trasactio attributes are defied i ejb-jar.xml as follows: <assembly-descriptor> <cotaier-trasactio> Programmig WebLogic Eterprise JavaBeas 3-7