EJB Development Using Borland JBuilder 6 and Borland Enterprise Server 5

Transcription

1 EJB Development Using Borland JBuilder 6 and Borland Enterprise Server 5 A step-by-step tutorial Original paper by Todd Spurling Updated and enhanced by Hartwig Gunzer, Sales Engineer, Borland Audience Evaluators or developers new to EJB using JBuilder 6 and Borland Enterprise Server 5 can use this step-by-step guide to get up and running with session beans, entity beans as well as message-driven beans, transactions, and clustering. Contents Introduction 2 Installation 2 Configuration 2 Part I Session beans 4 Part II Entity beans 8 Part III Transactions 11 Part IV Message-driven beans 15 Part V Clustering 18

2 Introduction Borland JBuilder 6 is the leading environment for developing EJB (Enterprise JavaBeans ) components and applications. Step by step, this paper takes the developer through using JBuilder 6 wizards and features to creating and deploying session beans, entity beans that participate in container-managed transactions as well as message-driven beans. The paper finishes with a brief demonstration of one clustering feature of Borland Enterprise Server 5. This paper provides a useful overview of the power and ease-of-use of the Borland business platform The teller example described herein is an abridged version of the bank transfer example supplied in the Borland Enterprise Server examples. This example has been cut down to reduce the number of steps involved in creating a first-time EJB application. Consult the actual bank transfer example for a more complete set of code. Installation To accurately execute the steps in this paper, you will need JBuilder 6 Enterprise, Borland Enterprise Server 5, Borland InterBase 6, and InterClient 2. All the software used is included in JBuilder 6 Enterprise, but if you feel confident, you can use your own database and JDBC driver instead of InterBase and InterClient. The steps in this tutorial are written against a Windows NT install. For other operating systems, substitute drive letters for directories as appropriate. Install JBuilder 6. This paper assumes the install directory will be c:\jbuilder6 (the default suggestion). Install Borland Enterprise Server 5. This guide assumes the install directory will be F:\Borland\Bes. This is not the default. The default osagent port is For the entity bean, you will need access to a database. In this paper, we use InterBase 6 and the type III JDBC driver: InterClient 2. Install InterBase c:\program Files\Borland\InterBase (default) Install InterClient The default is c:\program Files\Borland\InterClient In this paper, we use the following installation directory: f:\interclient Configuration Before we start, we need to enable Borland Enterprise Server integration inside JBuilder. JBuilder 6 makes this easy: all we need to do is provide JBuilder the location of Borland Enterprise Server. Start JBuilder. Choose Tools Enterprise Setup On the Application Servers tab, on Borland Enterprise Server 5, enter the install directory of Borland Enterprise Server. Evaluation versions of these Borland products are available for download from To obtain evaluation products on CD-ROM, contact the Borland office in your region. JBuilder 6 Enterprise Borland Enterprise Server 5 InterBase 6 and InterClient 2 2

3 To finish the setup, click OK and restart JBuilder to make the changes effective. Next, set up the JDBC configuration for InterBase. Select the Database Drivers tab and click Add, opening a library definition dialog. Click New to add the definition for the InterBase and JDBC driver. After restarting JBuilder, you will see that it provides us with a library definition. You will also see that it has enabled the integration with Borland VisiBroker and configured the project properties for J2EE development with Borland Enterprise Server. Now that we finished the configuration, we continue with developing some beans. In Part I of this paper, we create a JBuilder project, write a stateless session bean called TellerBean with a method to return a fictitious number that is the teller s number, and build a test client to access the bean. In Part II, we add the entity bean. In Part III, we add to the TellerBean another method to perform a transaction across two entity beans. Later, in Part V: Clustering, we use this method to determine to which teller each client is load-balanced. Part IV shows the development of a message-driven bean and a client that produces messages that will be delegated to the bean. When the New Library Wizard opens, provide the name, InterBase in this case, and add the JDBC driver to the library path. You can specify the location of this library definition; in this case it is located in the User Home. Click OK. The definition is added to the list. Click OK to add this definition to the database driver list. 3

4 Part I: Session beans Session bean development First, create the project: Choose File New Project Set the project name and directory to quickstart. Set the Root path to C:/project. Set the group s Path: field to create a JAR file called quickstart in this project s directory. Click OK. A menu pops up asking us what type of EJB we want to create. We chose the session bean: Click Finish. Now we will create an EJB Module. This new node in the project pane encapsulates the settings belonging to (a group of) Enterprise JavaBeans. When you invoke a build or make command, the EJB Module will cause JBuilder to automatically create or update a deployable JAR file containing our EJBs. Choose File New Enterprise tab EJB Module If you are wondering what happened to the EJB groups from previous JBuilder versions, they are now called EJB Modules. Set the class name to Teller and click Classes and packages. 4

5 Now we can check the classes JBuilder will generate for us. A dialog pops up where we enter the following method signature: Click OK. You will now see three classes added to the project. TellerHome and Teller are interfaces for the EJB container to implement. TellerBean is our bean to which we will add a method (our business logic). If you do a right-click on the pane displaying the contents of our bean, we can add another method: By using the interfaces drop-down list, we specify that we want the method to be declared in the remote interface of our bean. Now switch to the file ( e.g., by right-clicking on our bean pane and choosing View Bean Source ). Find the skeleton for the method we just created and complete it: public int gettellerno() { return 1; We have now finished writing the Java code of our EJB. Our next step is to complete and verify the deployment descriptor, an important part of EJB. It separates deployment settings from the development code so that partitioning and tuning of the application may take place without requiring changes to source code. The deployment descriptor already exists in our project: the EJB Module wizard generated it. When we used the wizard, it generated the Java code for the bean and added a matching entry into the deployment descriptor. Let s take a look at the deployment descriptor, for which we will use the integrated deployment descriptor editor. 5

6 Double-click quickstart module to view it. In the structure pane (below), expand TellerBean and click Container Transactions. JBuilder 6 already has added a transaction attribute, Required, for all methods of all interfaces. Click OK. In this case the Required transaction attribute will apply to all methods and interfaces of the bean. To verify that the settings in the deployment descriptor have no errors, click the Verify button In the constructor of the created class, you will see a try block containing the instantiation of a Naming Context, a lookup of JNDI for Teller, and a narrow of the returned object reference to the type TellerHome. That means, each time we look for an EJB, we obtain a reference to its home interface. We never talk directly to the bean. This is part of the EJB container s responsibilities. The message field should show 0 errors and 0 warnings. Save All your work and Make. We have completed the server side of our application, and now we will write a Java client to call gettellerno on our bean. In the main method, add the following lines of code to create the reference to the bean s home interface and call the remote method: client.create(); client.gettellerno(); Use a JBuilder 6 wizard to write a test client for our EJB: File New Enterprise tab EJB Test Client. The method will generate logging messages, so we will see the output result in the message view when we run the client. Save All your work and Make. Set the class to Client. Check all options but the one for the header comments. We have now completed the development of the stateless session bean and a test client. 6

7 Deployment For this example, we take the role of the deployer and deploy the bean to the Borland Enterprise Server 5. Make sure the Borland Enterprise Server is up and running. Select Tools EJB Deployment. Select the generated JAR file. JBuilder has already found the EJB Server. You can see the deployed bean in the Borland Enterprise Server Console as well. Run the client by right-clicking Client.java and choosing Run. Click OK. The JAR file will be deployed. You should get the following results: In the message tab for the client, you should see the following output of a successful invocation: -- Initializing bean access. -- Succeeded initializing bean access. -- Execution time: 3655 ms. -- Calling create() -- Succeeded: create() -- Execution time: 40 ms.. -- Calling GetTellerNo() -- Succeeded: GetTellerNo() -- Execution time: 321 ms. -- Return value from GetTellerNo(): 1 Look at the message tab of container to see the periodic printing of statistics showing the states of EJBs. 7

8 Part II: Entity beans Choose Database Create Database Entity bean development In this part, we will create a Container Managed Persistence Entity Bean that represents account data in a database. We will create some accounts from a client. Later, in Part III, the session bean we developed earlier will be modified to access two instances of this entity bean and perform a transfer of funds between accounts. An entity bean is an object representation of persistent data, which in our case is in a relational database. We will start with a predefined data dictionary (an existing table definition in a database) and use a JBuilder 6 wizard to create a CMP entity bean from this. At application runtime, the EJB container will implement the SQL for all data transfers between the database and bean. First, we create an InterBase database: Run InterBase Server. Run Programs InterBase InterClient InterServer. Run InterBase IBConsole. Login to the InterBase server. Select Server Login Provide an alias for the database Accounts. Set the file name as c:\project\quickstart\accounts.gdb Click OK. Select Tools Interactive SQL. Now create a table by entering the following data in the SQL: create table account ( name VARCHAR(20) NOT NULL, balance INTEGER NOT NULL, PRIMARY KEY (name) ); Execute the query by pressing the thunderbolt button. Exit Interactive SQL. 8

9 Entity bean development We will use a wizard in JBuilder to generate the code of our entity bean and add the bean to our existing project. First, select Tools Database Pilot to open the Database Pilot. We next add a database URL to JBuilder by selecting File New to open the new URL dialog box. Log in to the database using the interclient driver, the URL of ACCOUNTS.GDB, the username SYSDBA, and the password masterkey (or use Choose Existing Connection... as a shortcut to fill in the first two). Select the driver and navigate to the database we just created. Click OK to finish. Make sure that the check box for All schemas is checked. We set the name of the datasource to IB_Accounts Click OK. If you look at the navigator pane, you will notice that JBuilder has added a new node containing our account table. Close Database Pilot, saving changes when asked. The bean First of all, we need to import the schema from which we will create an entity bean Select EJB Module quickstart in the project pane and right-click the mouse button somewhere in the EJB designer pane Select Import Schema From... and Database A dialog pops up where we specify all the necessary information to connect to a database using JDBC Now we add a new entity bean to our EJB Module. Select the Module in the project pane and do a right-click once more in the EJB designer. Select New Entity Bean Map the entity bean to our account table by selecting the table from the combo box. 9

10 Save All your work and Make. We have finished writing the entity bean. In fact, the wizard has added an entry to the deployment descriptor as well as a data source entry. Look at the various files JBuilder generated to see the code for the entity bean. Next, a client will be written to access the entity bean, creating four instances, and thus creating four rows in the account table in the database. Now we have to map the table s columns to fields of our entity bean. To map the column representing the primary key, we rename the field that has been generated by JBuilder. It is called untitledfield1. We set the following properties: Use the EJB Test Client Wizard again, but this time create a test client against the AccountEntity EJB. Use the default class name AccountEntityTestClient1 and generate a main function. Add the following lines: client.create("john", 150); client.create("paul", 150); client.create("george", 150); client.create("ringo", 150); Save All your work and Make. Now we add a new field that will map to the second column of our table: Deployment To create the four accounts, we will run the client once against the container. This time,we will be running the container within JBuilder. Ensure Smart Agent, InterBase, and InterServer are running. Run the container in JBuilder by selecting the EJB Module with the right mouse button and clicking Run. Wait for the container to initialize. Run the AccountTestClient1 by right-clicking and choosing Run. Use the Database Pilot to see the four accounts we have created. 10

11 Part III: Transactions So far, we have used JBuilder for bean development and for testing. In this section, we will assume the roles of Application Assembler and Deployer by assembling the components of our application into one JAR file, deploying the file to Borland Enterprise Server, and configuring transaction attributes. Architecture Our Bank Application will require some new methods added to it so that we can perform a funds transfer from one account to another within the context of a transaction. In the application, the client will make a remote invocation on a new method, called transfer, on our session bean to transfer money between accounts. The client will pass in the following parameters: the name of the source account, the name of the destination account, and the amount to transfer. Using our entity bean, the session bean will look up the accounts and perform the transfer (a withdrawal and a deposit) within a transaction. public void deposit(int amount) { balance += amount; public void withdraw(int amount) { if(balance < amount) entitycontext.setrollbackonly(); else balance -= amount; Notice that the withdraw method forces a rollback of the transaction if there are insufficient funds in the account. Rebuild the stubs for the AccountHome interface Right-click AccountHome.java and choose Rebuild. Save All your work and Make. The entity bean will have two new methods to assist the transfer. Add two new methods and the following code to AccountEntityBean.java (refer to the first chapter about how to add new methods to an EJB) 11 The entity bean is now ready for deployment. But first, the Teller session bean will be modified to include the transfer method that withdraws from one account and deposits to another. Add a new method called transfer to the Teller EJB. It takes three parameters String accountfrom String accountto int amount

12 public void transfer(string accountfrom, String accountto, int amount) throws RemoteException { try { //get naming context Context ctx = new InitialContext(); For the sake of easy coding of JNDI access, add the following code to the imports section of TellerBean.java: import javax.naming.*; import javax.rmi.portableremoteobject; //look up jndi name //a logical name to look up in DD String homename = "java:comp/env/ejb/accountdept"; Object ref = ctx.lookup(homename); Let s look at the business logic for the transfer method. The client will call this method, specifying the source and destination accounts, as well as the amount. The method will use JNDI to look up a logical name that maps to the AccountHome interface in the deployment descriptor. The method also looks up the from and to accounts using the findbyprimarykey methods on the AccountHome interface. At this point, we have two logical instances of the entity bean in the container. We then call withdraw on the from account and deposit on the to account. Add the following code for the transfer method. //cast to Home interface AccountHome accounthome = (AccountHome) PortableRemoteObject.narrow(ref, AccountHome.class); // find accounts Account acc_from = accounthome.findbyprimarykey(accountfrom); Account acc_to = accounthome.findbyprimarykey(accountto); // transfer acc_from.withdraw(amount); acc_to.deposit(amount); catch(exception ex) { ex.printstacktrace(); throw new RemoteException(ex.getMessage()); Rebuild the stubs for the TellerHome interface. Right-click TellerHome.java and choose Rebuild. Save All your work and Make. The session bean is now finished. 12

13 We will now finish the deployment descriptor, assemble, and deploy the beans. To view the deployment descriptor, doubleclick the TellerBean in the project pane Change the transaction attribute to Requires New. Remember that the code in the transfer method looks up a logical name to find the AccountHome interface. This is called an EJB Reference. The mapping of that logical name to a real interface is determined in the deployment descriptor so that partitioning can take place at a later date without source code changes. So we must map the logical name java:comp/env/ejb/accountdept to our account bean. In the structure pane, expand the AccountEntity bean branch. Click Container Transactions. View the transaction attribute as Required. Select the EJB References tab. Click Add. Set the name as ejb/accountdept and click OK. Check the islink checkbox. Choose Account from the Link combo box. To verify that the settings in the deployment descriptor have no errors, right-click the EJB module and select Verify. The message field should show 0 errors and 0 warnings. Save All your work and Make. By manipulating transaction attributes, we can instruct the container to execute certain methods as a single unit of work (a transaction). Doing this in the deployment descriptor eliminates the need for writing specific Java code to manage transactions. In our example, we tell the container to execute the transfer method in a new transaction. The methods withdraw and deposit of the entity bean will use the transaction context created for the transfer method. In the role of the Assembler, we have decided that all the beans in the project make up the application because all of the beans are registered with the EJB Module QuickstartModule. The act of packaging the components as a single distributable (JAR) file was executed by JBuilder on the latest Make. You can view the contents of the JAR file by expanding the QuickstartModule node, and then double-clicking QuickstartModule.jar. In the structure pane, expand the TellerBean branch. Click Container Transactions. 13

14 Deployment We will assume the role of the deployer once more and push the JAR file to the application server. Make sure the container is no longer running in JBuilder. Make sure InterBase and InterServer are still running. Shut down the Smart Agent. Borland Enterprise Server will start the Smart Agent itself. Run Borland Enterprise Server. In JBuilder, run Tools EJB Deployment. Refer to the steps that were applied when we were deploying the session bean. In the role of deployer, we have one additional responsibility for this deployment: we need to add the InterClient JAR file to the classpath of the container we have deployed to. Start the Borland Enterprise Server Console. Select Tasks Deployment Deploy J2EE Module to a partition. The server-side components are deployed and ready. We now need to create a simple client in JBuilder to look up the teller and call transfer: File New Enterprise tab EJB Test Client. Choose to create a test client for the TellerBean Enterprise JavaBean. Name the class TransferClient. This time, add the following code to the usual spot in the end of the try block to contact the teller and perform a transfer. Make sure you use $100 as the amount. client.create(); client.transfer("john", "Paul", 100); Run the client by right-clicking TransferClient.java and choosing Run. Wait for the process to finish. When the transaction completes, viewing the accounts in the Database Pilot shows that $100 has been transferred from John s account to Paul s account. The dialog that opens up is the same that was used during the deployment of the EJBs in JBuilder. This time we use it to deploy a JDBC driver. Click Add and specify the location of the interclient.jar. Click OK. Run the client again without making any changes to the code. This time, when the withdraw method is executed within the transfer transaction, there are insufficient funds in John s account, so the transaction is set for rollback only. Subsequently, at the end of the transaction (the end of the transfer method), the transaction service cannot commit the transaction, so the change in balances is not committed to the database. The balances are set to the persisted values of the last transaction: John: $50, Paul: $

15 Part IV: Message-driven beans The EJB 2.0 specification introduces a new kind of EJB: message-driven beans. In contrast to the other kinds of EJB, this one supports asynchronous calls to the bean. Thus, the application doesn t have to wait for the return of the method call to the EJB prior to continuing its execution. Examples are clients or online shopping applications. JBuilder 6 Enterprise includes SonicMQ as a JMS provider. In the following example, we will create a message-driven bean that processes text messages and object messages. Thus, it acts as the message consumer. A client to the bean will take the role of the message-producer. In this example, we will start from scratch. Create a new project. Here we call it MDB. Create a new EJB Module. Let s name it MDBModule Specify it to be EJB 2.0 compliant and click OK. From the pop menu chose New Message-Driven Bean. Specify the following details. For the sake of simplicity, most of them are default values. Switch to the source code of our bean, that is, the file MDB1Bean.java, and locate the method onmessage(... ). This is the central method of the bean. It deals with incoming messages. We want to handle two kinds of messages: TextMessages and ObjectMessages. Add the following source code: 15

16 public void onmessage(message msg) { try { // consume text message if( msg instanceof TextMessage ) { System.out.println( new Date( ) + ": MDB received a text message" ); System.out.println( "Message: " + ( ( TextMessage) msg ).gettext() ); // consume object message if( msg instanceof ObjectMessage ) { System.out.println( new Date() + ": MDB received an object message"); ObjectMessage objmsg = ( ObjectMessage ) msg; Vector orderitems = ( Vector ) objmsg.getobject(); Enumeration orderitemsenum = orderitems.elements(); System.out.println( "Elements:" ); while( orderitemsenum.hasmoreelements() ) { System.out.println( ( String ) orderitemsenum.nextelement() ); catch( Exception e ) { System.out.println( "Exception: " + e ); In case of a text message, we just print the contents, that is, the text of the message. If we receive an object message, we expect the message to encapsulate a vector of strings. These strings represent order items. We print the items on screen. Now create a new class and call it Client. The client consists of the following source code: package mdb; //imports for the JMS import javax.naming.context; import javax.naming.initialcontext; import javax.jms.queue; import javax.jms.queueconnection; import javax.jms.queueconnectionfactory; import javax.jms.queuesender; import javax.jms.queuesession; import javax.jms.session; import javax.jms.textmessage; import javax.jms.objectmessage; // imports for the client import java.util.vector; public class Client { // constants for the queue factory and the // queue private static final String QUEUE_CONNECTION_FACTORY = "serial://jms/qcf"; private static final String QUEUE = "serial://jms/q"; // the main method public static void main(string[] args) throws Exception { // look up the queue factory Context ctx = new InitialContext(); QueueConnectionFactory qconnfact = (QueueConnectionFactory) ctx.lookup(queue_connection_factory); //create a connection from the factory QueueConnection qconn = qconnfact.createqueueconnection(); The source code continues on the next page. 16

17 //create a session from the connection QueueSession qsess = qconn.createqueuesession(false, Session.AUTO_ACKNOWLEDGE); // look up the queue Queue q = (Queue) ctx.lookup(queue); // create a sender to the queue from the // session QueueSender qsend = qsess.createsender(q); // create and send a text message from // the session TextMessage txtmsg = qsess.createtextmessage( "Hello MDB, this is a message from the client..."); System.out.println("Sending a text message to queue SampleQ1."); qsend.send(txtmsg); // create and send an object message from // the session. The object message // encapsulates a vector of strings Vector orderitems = new Vector(); orderitems.addelement( "JBuilder 6 Enterprise"); orderitems.addelement( "Borland Enterprise Server"); ObjectMessage objmsg = qsess.createobjectmessage(); objmsg.setobject( orderitems ); System.out.println("Sending an object message to queue SampleQ1."); qsend.send(objmsg); // close the connection qconn.close(); System.out.println("Done."); Rebuild the project. Start SonicMQ Broker by choosing Tools SonicMQ Broker. Also start Smart Agent by choosing Tools VisiBroker Smart Agent. Now you are ready to start the EJB container. The quickest way to do that is to right-click its EJB Module or the JAR file the module contains and select Run from the context menu. The EJB container starts up and runs your bean. Start the client by selecting Run from its context menu. You will see two tabs appear in the message pane: one for the container, the other for the client. You should see the following output in the appropriate tabs: Client: Sending a text message to queue SampleQ1. Sending an object message to queue SampleQ1. Done. Container: Sun Dec 16 13:34:10 CET 2001: MDB received a text message Message: Hello MDB, this is a message from the client... Sun Dec 16 13:34:11 CET 2001: MDB received an object message Elements: JBuilder 6 Enterprise Borland Enterprise Server 17

18 Part V: Clustering In this section, we demonstrate one of the cluster features of Borland Enterprise Server, JNDI name clustering. This clustering facilitates load balancing across containers. Open the Borland Enterprise Server Console. Select the standard partition with the right mouse button. Select Clone in the context menu. Borland Enterprise Server is built upon VisiBroker and inherits the load-balancing and fault-tolerant features of the ORB. The VisiBroker 4 Naming Service implements JNDI. It can be enabled for clustering and supports automatic load balancing of clients across replicated beans in multiple containers. In short, the same JNDI home name for a bean can be used in multiple container deployments of that bean. The Naming Service holds a reference to each container implementing the home interface registered with that home name. However, the Naming Service exposes the name only once to the client. When a client looks up the name in JNDI, the Naming Service hands out a reference to the next container, thus performing simple round-robin load balancing. In our example, we will build a homogeneous cluster: We will run two containers in Borland Enterprise Server 5 and deploy the bank application to each one. The TellerBean in the second container will be recompiled to return the number 2 as its teller number, so we can see the client load balancing taking place. First, we clone our standard partition in Borland Enterprise Server. Specify a name for the new partition. We call it simply clone. A clone of the standard partition with all its deployed modules will be created. To distinguish which container the client is connected to, we edit the teller number of our TellerBean before deploying the application to the second container. In JBuilder: Edit the TellerBean s gettellerno( ) to return 2. Save All your work and Make. 18

19 Use Tools EJB Deployment to deploy the JAR file to the partition clone. Run the Part I Client several times by right-clicking Client.java and choosing run repeatedly. Consecutive executions of the client will return different teller numbers. -- Return value from gettellerno(): Return value from gettellerno(): 1. The next picture shows the Module in the two partitions Conclusion We hope this paper has provided a useful overview of the power and ease-of-use of the Borland e-business platform. For more information, please visit the Web sites below, or contact your Borland sales representative. JBuilder 6 Enterprise Borland Enterprise Server 5 InterBase 6 & InterClient Enterprise Way Scotts Valley, CA Made in Borland Copyright 2002 Borland Software Corporation. All rights reserved. All Borland brand and product names are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the U.S. and other countries. All other marks are the property of their respective owners