Tutorial for building J2EE Applications using JBOSS and ECLIPSE

Table of Contents

Tutorial. | Preface
 | About the Authors
 | Acknowledgments
 | Disclaimer
 | Introduction
 | Prerequisites for this tutorial
 | Tools required for this tutorial
 | Case Study Overview
Chapter 1. | Configuration of ECLIPSE using JBOSS and LOMBOZ
 | Install Eclipse
 | Install JBOSS
 | Creating Database Schema
 | Install Lomboz
 | Lomboz Configuration
 | Configure JBOSS to run from within Eclipse
 | Test your configuration
Chapter 2. | Overview Of J2EE Technology and Concepts
 | J2EE Components
 | J2EE Clients
 | Web Components
 | Business Components
 | Enterprise Information System Tier
 | J2EE Containers
 | Packaging
 | J2EE Platform Roles
 | Distributed Architecture in J2EE
 | Java Naming Directory Interface (JNDI) Architecture
Chapter 3. | Creating a Stateless Session Bean
 | Tasks
 | Create J2EE Project
 | Create StoreAccess Stateless Bean
 | Setup DAO
 | Create StoreAccess's DAO Interface
 | Add Business Method
 | Implement DAO Interface
 | Add Callback Method
 | Deploy StoreAccess Bean
 | Create your Test Client
 | Test your Client
Chapter 4. | Creating a Stateful Session Bean ( Coming Soon ....)
 | Tasks
 | Create StoreAccessState Stateful Bean
 | Create StoreAccessSate's DAO Interface
 | Add Business Method
 | Add Callback Method
 | Implement DAO Interface
 | Deploy StoreAccessState Bean
 | Create your Test Client
 | Test your Client
Chapter 5. | Creating a BMP Entity Bean
 | Tasks
 | Create Customer BMP Entity Bean
 | Create Customer's DAO Interface
 | Add Finder Methods
 | Add Business Methods
 | Implement Customer's DAO Interface :
 | Deploy Customer Bean
 | Add Create Method in StoreAccess
 | Add Business Method in StoreAccess
 | Create your Test Client
 | Test your Client
 | Exercise
Chapter 6. | Creating a CMP Entity Bean
 | Tasks
 | Create Item CMP Entity Bean
 | Implement ejbCreate Method
 | Add Finder Methods
 | Add Business Methods
 | Add Callback Methods
 | Deploy Item Bean
 | Add Business Method in StoreAccess
 | Create your Test Client
 | Test your Client
 | Exercise
Chapter 7. | Creating a Message Driven Bean
 | Tasks
 | Create RequestItems MDB Bean
 | Create Immutable Value Object RequestItem
 | Implement onMessage Method
 | Deploy RequestItems Bean
 | Create Test Client
 | Test your Client
 | Exercise
Chapter 8. | Creating Web Clients
 | Create AccessController Servlet
 | Implement init method
 | Implement methods doGet and doPost
 | Deploy AccessController Servlet
 | Test your Servlet
 | Create JSP Page
 | Add Html and JSP Tags
 | Deploy Module OnlineStore
 | Test your JSP Page
Feedback | Feedback

Preface.

This tutorial is about building Java 2 Platform, Enterprise Edition (J2EE) components using Eclipse as an Integrated Development Environment (IDE) and JBOSS as the Application Server. Tutorial covers step-by-step development of J2EE components, starting from setting up Eclipse, JBOSS and Lomboz. Lomboz uses Xdoclet (Attribute Oriented Programming) for rapid development of J2EE components. Importantly, all of the tools used in this tutorial can be downloaded free of charge, so there should be nothing stopping you!

Eclipse provides an excellent IDE, with features like refactoring and debugging. JBOSS is integrated within Eclipse using JBOSS plug-in. Lomboz is another plug-in used for building J2EE components, which provides wizards for bean creation, method creation, deployment of bean, test client creation etc. JBOSS is an integrated application server with convenient built-in components such as the Hypersonic Database and Jetty as the Web Engine. This bundling of all the key components of a J2EE environment assists beginners in learning how to develop J2EE applications. Having gained some skills and confidence, beginners can move on to tools provided by other vendors.

One of the problems J2EE developers face is that of synchronizing their code with J2EE's deployment descriptors. As development of components progresses, developers have to keep updating deployment descriptors, a generally tedious activity which can lead to other mistakes, instead of this devoting time to the business logic of the application. Xdoclet generates these interfaces and helper classes along with deployment descriptors, by parsing source files. These files are generated from templates that use the information provided in the source code and its JavaDoc tags. XDoclet allows developers to concentrate on only one Java source file per component, that is, concentrate on the business logic of the application, and the rest is done by Xdoclet.

For so many years developers have been looking for some sort of a tool which speeds up this process of development and deployment, and Xdoclet is certainly a step in that direction. Hopefully you'll find that Xdoclet makes development and deployment rapid and easy. So explore the power of Xdoclet, Eclipse and JBOSS!

About the Authors.

Glen McCallum.

Glen joined TUSC in 1990. He has extensive experience in software development for the telecommunications industry, including C, C++, Perl and Java. Outside of TUSC, Glen continues to fiddle with such technologies as he thinks are “cool”. This includes TCP/IP networking, security, cryptography, VPNs, digital video capture, Bluetooth, PDAs and J2EE, all on Linux. His wife and two young sons complete a “pure Linux” household.

Vishal Sharma.

Vishal was born in 1976 in India. He studied mechanical engineering, graduating in 1998. After working in that field for 6 months, he came to Australia and obtained a Master's degree in Computer Science. Since graduating from RMIT Melbourne in 2001 he first worked as a software engineer in Mcom Solutions developing communication protocols. Vishal joined TUSC in 2002 and has enjoyed a varied diet of different projects since then. Most recently he has been involved in building multi-tiered Web applications for the telecommunications industry, with a particular focus on J2EE technology.

Acknowledgments.

We'd like to thank some particular TUSC people: Rod Bower, Telecommunications Business Unit Manager, Sebastian Bellofiore, Delivery Manager and Marcia Abbott, Business Improvement Manager for their support and help in this initiative, and of course our colleagues for their collaboration; Simon Shields, Andrew Hendry and Ray Walford.

Vishal wishes to thank Glen McCallum for his guidance, inspiration and invaluable support in bringing this to you all.

Disclaimer.

TUSC MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OR SUITABILITY FOR A PARTICULAR PURPOSE.

TUSC shall not be liable for errors contained herein or for incidental consequential damages in connection with the supply of, performance of, or use of this material.

This document contains proprietary information which is protected by copyright.

All rights are reserved. No parts of this document may be photocopied, reproduced or translated to another language without the prior written permission of TUSC.

© Copyright 2003 TUSC Computer Systems Pty. Ltd.

Introduction.

Prerequisites for this tutorial.

Before you start this tutorial, you should ideally have a working knowledge of Java technology, XML, J2EE technology and some exposure to SQL, JDBC concepts, and Xdoclet (Attribute Oriented Programming). Even if you are new to a lot of this then don't panic – just expect to do a bit more learning along the way!

All the examples covered in this tutorial were developed on RedHat Linux 8.0, Sun Microsystem's JDK (j2sdk1.4.1_02), using Eclipse 2.1 as the IDE, and Lomboz 2.1_02 plugin for Eclipse. JBOSS-3.2.1 is being used as an application server to deploy applications. Jetty is used as the web server and Hypersonic SQL as the database, both of which are integrated in the JBOSS application server.

Tools required for this tutorial.

You will need a current version of Java Development Kit (JDK) or Java Runtime Environment (JRE) - at least JDK 1.3 onwards. Eclipse 2.1 is required as an Integrated Development Environment (IDE) along with the Eclipse plug-in Lomboz 2.1_02 for J2EE applications development and JBOSS integration.

JBOSS-3.2.1 is being used as an application server to deploy applications, together with its embedded Jetty web server and Hypersonic SQL database as noted above.

Case Study Overview.

For this tutorial we are using a case study similar to Inventory, rather than using any complex scenario or going into strict database design, as our aim is to learn how to design and develop various J2EE components using this new revolutionary approach of Attribute Oriented Programming with the help of these tools.

We have a database schema called 'MyStore' which is composed of five tables.

Table Supplier records details of those suppliers (many) who sell different materials to MyStore as request is sent to these suppliers from MyStore manager as need arises.

Table Manager records details of managers who run MyStore, currently there is only one manager.

Table Customer records details of those customers (many) who have bought some items at least once.

Table Items maintains an inventory of available/non-available items (many).

Table StoreAccess records the authentication details of all customers, suppliers and manager for on-line access of MyStore.

The MyStore Database is shown in the figure below.

To access data from the database and do business operations, we will create various J2EE components including Session, Entity and Message-driven Enterprise Java Bean components along with Web clients using Servlets and JSP pages.

Figure below presents an overview of the MyStore application's architecture.

Note : In the case of Web clients, a request is sent by Servlets/JSP (Java Server Pages) to beans using RMI (Remote Method Invocation). Stateless, Stateful and Bean Managed Persistence (BMP) Entity Beans access data from the database using Data Access Objects (DAO), which are wrappers for Java Database Connectivity (JDBC) code, while Container Managed Persistence (CMP) Entity Beans don't require a DAO, as the container manages communication between the Beans and the database, which is a very powerful feature. Finally, in the case of Java clients requests are made via Java middleware technology (RMI, CORBA, Java Messaging) to Entity Beans.

All beans together with their public behaviors/methods which will be implemented during the course of this tutorial are shown below. StoreAccessBean is a Session facade bean, which exposes its interface to the Presentation Tier, while encapsulating the complex business interactions with Customer, Manager, Item and Suppler Entity beans.

MyStore customers, suppliers and manager login into the system using the StoreAccess stateless session bean. Once authenticated, they request information about MyStore's inventory, manager details, customer details and supplier details using the various interfaces available in the StoreAccess bean, which invokes methods on the remaining beans, from where the information is requested. RequestItems and DeliverItems are Message Driven Beans which listen for messages from a JMS producer and transfer messages to appropriate beans.

Now lets start this tutorial, with setting up the environment in chapter 1.

Last updated: September11, 2003, Version 1.0

TUSC

Reliable, On-Time Delivery.

Copyright 2003 TUSC Pty. Ltd.


Chapter1 - Configuration of ECLIPSE to use JBOSS and LOMBOZ

TUSC

Search

Netcool Training

Tutorial for building J2EE Applications using JBOSS and ECLIPSE

Chapter 1

Configuration of ECLIPSE to use JBOSS and LOMBOZ

Install Eclipse.

First of all we have to set up Eclipse Integrated Development Environment (IDE) with JBOSS as our application server.

So go to this page: http://www.eclipse.org/downloads/index.php and download the binary for the Eclipse editor. You can download the appropriate binary for your platform. This tutorial was developed using Linux (Red Hat 8.0) as the operating system.

Example : eclipse-SDK-2.1-linux-gtk.zip, eclipse-SDK-2.1-win32.zip

Note : Eclipse does not include a Java runtime environment (JRE). You will need at least a 1.3 level Java runtime or Java development kit (JDK) installed on your machine in order to run Eclipse.

Now unzip this file into your home directory.

[vishal@localhost eclipse]$ unzip eclipse-SDK-2.1-linux-gtk.zip
Archive: eclipse-SDK-2.1-linux-gtk.zip
Archive: eclipse-SDK-2.1-linux-gtk.zip
inflating: eclipse/plugins/org.eclipse.core.boot_2.1.0/boot.jar
inflating: eclipse/plugins/org.eclipse.core.boot_2.1.0/splash.bmp
inflating: eclipse/plugins/org.eclipse.core.boot_2.1.0/boot.xml
inflating: eclipse/plugins/org.eclipse.core.boot_2.1.0/plugin.properties
-----------------------------------------------------------------------------
----------------------------------------------------------------------------
-------------------------------------------------------------------------
inflating: eclipse/install.ini
inflating: eclipse/startup.jar
inflating: eclipse/readme/readme_eclipse.html

Once you have unzipped this file you will have a directory called 'eclipse' in your home directory.
Go into that directory and run the script file called 'eclipse'.

[vishal@localhost eclipse]$ cd eclipse
[vishal@localhost eclipse]$ ls
cpl-v10.html features install.ini plugins startup.jar
eclipse icon.xpm notice.html readme workspace
[vishal@localhost eclipse]$ ./eclipse

This will run the Eclipse IDE on your workstation. Let's get familiar with this environment.

Install JBOSS.

Now Eclipse is installed and is running on your workstation, let's install JBOSS.

You can download JBOSS ready to run. Because JBOSS comes with a simple embedded Database (Hypersonic) and a web server (JBossWEB or Tomcat) you can use it out of the box without any initial configuration. Downloads can be accessed from either the JBOSS Project Page on SourceForge where you will always find up to date downloads (http://sourceforge.net/projects/jboss), or from the JBOSS Home Page where you will find useful information about JBoss, the official, free forums, project information etc., and also the download page http://www.jboss.org/downloads.jsp. For this tutorial we are using JBOSS-3.2.1 with the built-in 'Jetty' JBOSSWeb HTTP sever.

Example : jboss-3.2.1.zip (includes JBossWeb HTTP server and JSP/Servlet engine, EJB, CMP2.0, JCA, IIOP, Clustering, JTS, JMX.)

Note : JBOSS does not include a Java runtime environment (JRE).

First login as user 'root' and then unzip this file in a suitable place where you have enough space. I have unzipped it under an /opt/jboss/ directory.

It will create a directory named jboss-3.2.1 under /opt/jboss/.

Before you run JBOSS, in order to check your installation of JBOSS, make sure have you have following environment variables set.

JBOSS_HOME: /opt/jboss/jboss-3.2.1
JAVA_HOME: /usr/java/j2sdk1.4.1_02
CLASSPATH: /usr/java/j2sdk1.4.1_02/lib/tools.jar

Now go into directory jboss-3.2.1 and you will have all these directories.

[root@localhost jboss-3.2.1]# ls
bin client docs lib server

Go into the bin directory and you will find a script named run.sh.

Run this script from the command line. Hopefully it will start, and you will see this message.

15:12:59,876 INFO [Server] JBoss (MX MicroKernel) [3.2.1 (build: CVSTag=JBoss_3_2_1 date=200305041533)] Started in 59s:676ms.

Note: This means that JBOSS is installed and running successfully. Now, it's time to configure it from within the eclipse IDE.

In order to test JBOSS is running correctly, go to your web browser and access this url 'http://localhost:8080/jmx-console/index.jsp'.

Note: This page is referred as the 'JMX Management Console'.

If you can access this screen from your browser, JBOSS is running successfully.

Note that on this page under the sub-heading of 'jboss' there is a link 'service=Hypersonic'. Go to that link; that will bring up an 'MBean View' page. On this page there is an MBean operation called 'startDatabaseManager'; go there and press the 'Invoke' button. This will bring up the console for the embedded Hypersonic database, from where you can access schemas and do other database management operations.

Creating the Database Schema.

As mentioned in the case study, the schema for our Store's Inventory is composed of five relations. We will load this schema in the Hypersonic embedded database.

In order to that, we will use the following script files.

a) myStoreSchema.script – to create the database schema.

b) myStoreSchema.data – to populate the tables with data.

c) myStoreSchemaDrop.script – to drop/delete all tables used in this tutorial.

Downloads :

myStoreSchema.script

myStoreSchema.data

myStoreSchemaDrop.script

First of all copy these 3 files into the $JBOSS_HOME/server/default/data/hypersonic/ directory. In this example it is /opt/jboss/jboss-3.2.1/server/default/data/hypersonic/

Now access the HSQL Database Manager using the JMX-Management Console shown above.

Note: Please drop/delete any tables already present in the database with same name beforehand, or naturally errors will be raised when you will run these scripts.

On the top level menu of HSQL Database Manager File > Open Script.. > select myStoreSchema.script.

After clicking Open > press Execute SQL Statement and the following screen will appear as shown in the figure below.

Go to View > Refresh Tree. If you can see five new tables created then your schema is ready, and it's time to populate them with data.

Go to File > Open Script.. > select myStoreSchema.data > Open.. > Execute SQL Statement.

Now your data is loaded in the database, in order to verify just execute any query and see the results of that as shown in figure below.

Make sure you 'commit' (Options->commit) to save your schema in the database.

Note : Shutdown Jboss server as we will run it later from inside eclipse.

Install Lomboz.

In order to run JBOSS from within Eclipse you need a plug-in, and for this tutorial we are using Lomboz which is available from http://sourceforge.net/projects/lomboz or from http://www.objectlearn.com/index.jsp.

Note : We are using lomboz.21_02.zip for this tutorial.

Now unzip this file in a temporary directory; you will have a directory named plugins. Go to the directory plugins/com.objectlearn.jdt.j2ee/servers. This directory contains configuration files for various servers. For this tutorial we supply a configuration file for jboss3.2.1 available under downloads.

Note : If there are multiple configuration files the plugin will presently default to the first configuration file within the (eclipse/plugins/com.objectlearn.jdt.j2ee/servers/ ) directory in alphabetical order, so rename all the configuration files to a '.bak'
extension. This is just to avoid slip-ups whilst we're learning.

Now, copy the supplied jboss321all.server file into the servers directory.

cd plugins/
[vishal@localhost plugins]$ ls
com.objectlearn.jdt.j2ee
[vishal@localhost com.objectlearn.jdt.j2ee]$ cd servers
[vishal@localhost servers$ ls
jboss244.server.bak jboss303Tomcat4112.server.bak jboss300all.server.bak jboss321all.server
tomcat403.server.bak weblogic70.server
jboss300.server.bak tomcat410.server x.log

Here's a snippet from the file 'jboss321all.server' used for configuration. For this tutorial we will use this file, which you can download under Downloads.

Downloads :

jboss321all.server

You can change the various settings in this file according to your environment (e.g. the port number).

Once you have saved this file under the com.objectlearn.jdt.j2ee/servers directory, move the com.objectlearn.jdt.j2ee directory under $HOME/eclipse/plugins/ directory, where $HOME is your home directory.

[vishal@localhost temp/plugins] mv com.objectlearn.jdt.j2ee /home/vishal/eclipse/plugins/.

Now, we will configure Lomboz using this jboss321all.server file.

Note : Now you can now delete the temporary directory.

Lomboz Configuration.

Now run your Eclipse IDE to configure Lomboz ($HOME/eclipse/eclipse ).

Go to Window on top level menu > Open Perspective > Java as shown in fig below.

As we want to customize Java perspective for this tutorial:

Go to Window again at top level menu > Customize Perspective > Other.

Select Lomboz Actions sub node.

Click OK. Now you will have an icon under your top level menu like this.

Click on this icon will have a Lomboz J2EE View window in your workbench.

Now, Lomboz J2EE view is available.

Go to Window > Customize Perspective.

Select File > New sub node. Select all nodes starting with Lomboz.

Select Window > Show view. Select Console, Lomboz J2EE View and others as shown below in figure.

Now click ok. You will have all those options available from File > New > and Lomboz menu will appear, or by right clicking in the Package Explorer a pop up menu will appear.

Configure JBOSS to run from within Eclipse.

First of all we have to configure the Java Development settings, because Lomboz requires different directories for source and binaries.

Go to Window > Preferences > Java > New Project.

Enter src and bin for the names of these folders, which are the defaults. Please do not modify these names as they are required by some of the Lomboz tasks.

Also, make sure JRE library is set to 'JRE_LIB' variable.

Go to Window on top level menu > Preferences.

Go to the Lomboz node under the Preferences window. Make sure JDK Tools.jar is set to $JAVA_HOME/lib/tools.jar

Go to the server definitions sub node under Lomboz node. Select JBOSS 3.2.ALL under Server types and the rest of the options will be filled after loading the server configuration file which we made for this tutorial.

Now, under Server Definitions, go to 'Classpath' and make sure all the paths are correct. If there is a wrong setting for a path, it will show red crosses with jar icons in Server libraries / Client libraries sub section.

You can add or remove libraries from here. Make sure you 'Apply' the changes after altering the various options.

And now verify your 'Classpath Variables'.

Go to Window > Preferences > Java > Classpath Variables

If you get all these Classpath variables right according to your environment.

Test your configuration.

To test your configuration, create a J2EE Project as a test.

Go to File at top level menu > New > Lomboz J2EE Project.

Enter 'Test' as project name and press Next.

Check your settings here; if you have 'Test/src' on build path and 'Test/bin' under default output folders then it's ok.

Now click on Libraries tab on the Project Creation Wizard.

Because of a bug in Eclipse 2.1 this library is configured wrongly.

So select this library and Remove it.

Now, add a new library > Add Library.. > Select JRE System library > Next .

Select Default library and press Finish.

New library is configured.

Note: You have to repeat this step whenever you are creating a new J2EE Project, as there is a bug in eclipse 2.1.

Now press Next.

Go to Web Module > Add.. > Enter Module Name 'OnlineBank' > Ok.

Go to Ejb Modules tab > Add.. > Enter Module Name 'MyBank' > Ok.

Go to Targeted Server > Add.. > 'JBOSS 3.2.1 ALL' .

Note: 'JBOSS 3.2.1 ALL' is not the file name, but the name assigned to server in the 'jboss321all.server' file used for configuration showed above. Snippet from file below.

<serverDefinition
name="JBOSS 3.2.1 ALL"
ejbModules="true"

Press Finish.

Now you will have all these directories and libraries under Test Project in the Package Explorer.

Under Project Test 'src' is the directory where all packages for EJB components and Servlets will be developed, that is your java source files.

The 'MyBank' directory is your EJB Module and will have 7 files at start shown in fig below.

The 'OnlineBank' directory is your Web Module and will have 7 files shown in fig below. Your JSP pages will come under this directory for this module.

Note: If you are interested in Ant (from the Jakarta Project) then note that both modules have an Ant 'build.xml' file which is used to build the application.

Now go to top level menu option Window > Show View > Lomboz J2EE View.

Lomboz J2EE view will have Test Project , which has two modules 'MyBank' and 'OnlineBank' using JBOSS 3.2.1 as their default server.

Now it's time to create an EJB,

Go to File > New > Lomboz EJB creation wizard.

Note: You can access this wizard by right clicking in on project Test in Package Explorer. Go to New > Lomboz EJB creation wizard as explained in the beginning.

Add package name 'au.com.tusc'; you can choose another name if you want. Add 'MySession' in Name. Select Stateless Session EJB option.

This will create a file 'MySessionBean.java' under the 'au.com.tusc' package as shown in figure below.

Note: It will generate the bean name, jndi-name and type of bean in the file. Also the name of the file is appended with word 'Bean' as you gave the name of the bean as 'MySession' only. So be careful with naming conventions, as you only need to specify the bean name in the wizard. Don't append the word Bean to the name as the wizard will do that for you.

Now we will add a business method via the wizard.

Go to file 'MySessionBean.java' under 'Package Explorer' and expand that, right click on 'MySessionBean' node as shown in the figure below, select New > Lomboz EJB Method wizard.

In the method signature put 'public String learnJ2EE(String messg)', select method type as 'Business Method' and

Interface Type as 'Remote Interface'.

This will generate the required signature for your business method in your bean class.

Now add this line in this method "Me too! ";

Code Snippet from Bean file

 /**
  * @ejb.interface-method
  * tview-type="remote"
  *
  **/
     public  String learnJ2EE  (String messg)  {
         return "Me too! ";
     }

Save the file. Now we will generate the rest of the files (Home and Remote interfaces along with helper classes, using Xdoclet) required to deploy this bean.

First add this Bean to the module.

Go to Package Explorer > Test > MySessionBean.java > MySessionBean, right click on that; a menu will pop up. Go to Lomboz J2EE on this pop-up menu, and select 'Add EJB to module'.

Go to Package Explorer > Test > MyBank (which is a directory), right click on that; a menu will pop up. Go to Lomboz J2EE, which is at the bottom of this pop up menu. Select Generate EJB classes. This will generate the required interfaces, helper classes and files related to deployment; that is, deployment descriptors.

It will create a new directory named ejbsrc, which will have a package named au.com.tusc, and under that, remote and home interfaces, along with necessary helper classes, will be generated.

Note: You will not edit any files generated by Xdoclet under 'ejbsrc' directory at any time while doing this tutorial. Because every time you use option Generate EJB Classes, it generates the necessary interfaces and helper classes as mentioned above. These files are generated by Xdoclet, after parsing your bean class, which is created by Lomboz bean creation wizard. Xdoclet looks at the various declared tags and methods in the bean class and then generates files accordingly. As a result, you just add business methods and their implementations in the bean class, and the rest is left to Xdoclet. Hence at any time in the development, you won't need to (and shouldn't!) edit any generated files. It will become clearer as we progress in this tutorial.

Also under MyBank > META-INF directory now there are 15 files, which includes ejb-jar.xml and jboss.xml and ejb-generate.xml. Initially there were only 6 files as noted earlier. These extra files are needed for deployment of the bean.

Now let us deploy this bean without going into any further details of deployment.

Go to Lomboz J2EE view in your workspace, expand Test > expand MyBank.

You will have au.com.tusc.MySessionBean added to your MyBank EJB module.

Right click on JBOSS 3.2.1 ALL icon as shown in fig below.

A menu will pop up; select option Debug Server. It will start the server with Debug mode and after successful start it will show this message in the console under your workspace as shown in the figure below.

Go to Lombo J2EE View > expand Test > select MyBank and right click on that; a menu will pop up; select option Deploy.

Once the bean is deployed, a message will come in your 'Console' confirming that, as shown in the figure below.

Now we will create a client to access this bean deployed on JBOSS (application sever).

Go to Package Explorer > Test > src, right click on that, a menu will pop up > select EJB Test client.

Enter Package name 'test' and Client name as 'Client'.

Select EjbHome as 'MySessionHome' and Ejb Interface as 'MySession' > Finish as shown in the figure below.

Now the client is generated, it's time to call business methods on the deployed bean.

We need some code to invoke the method on the bean..

Go to Client.java and write these lines under the 'testBean()' method.

String request = "I'm tired of 'Hello, world' examples..";

System.out.println("Request from client : " + request);

System.out.println("Message from server : " + myBean.learnJ2EE(request) );

Code Snippet from Client.java.

     public void testBean() {
         try {
               au.com.tusc.MySession myBean = getHome().create();
               //--------------------------------------
                //This is the place you make your calls.
                //System.out.println(myBean.callYourMethod());
               String request = "I'm tired of 'Hello, world' examples..";
               System.out.println("Request from client : " + request);
               System.out.println("Message from server : " + myBean.learnJ2EE(request) );

          } catch (RemoteException e) {
                 e.printStackTrace();
          } catch (CreateException e) {
                 e.printStackTrace();
          } catch (NamingException e) {
                 e.printStackTrace();
          }
     }

Now first select Client node under Package Explorer. Go to top level menu and select this icon as shown below.

On this icon go to > Run as > Java Application.

Your Client is going to make a request, the results of which will be displayed in the console under your workspace, as shown below.

Note: Ignore these exceptions regarding org.apache.log4j.Property as it requires 'log4j.properties' on the clients path. We will cover this later on as this doesn't affect the functioning of the bean.

You have successfully created a bean and invoked an operation on it. Now, let's have a brief overview of J2EE concepts in the next chapter, before we start implementing the case study.

TUSC


Chapter2 - Overview Of J2EE Technology and Concepts

Netcool Training

Chapter 2.

Overview Of J2EE Technology and Concepts

The Java 2 Enterprise Edition (J2EE) is a multitiered architecture for implementing enterprise-class applications and web based applications. This technology supports a variety of application types from large scale web applications to small client server applications. The main aim of J2EE technology is to create a simple development model for enterprise applications using component based application model. In this model such components use services provided by the container, which would otherwise typically need to be incorporated in application code. Note this may not be ideal in all scenarios: for example, a small scale application might be a better fit for a light-weight Java technology solution (e.g. Servlets, JSPs, etc.).

J2EE Components :

J2EE applications are made up of different components. A J2EE component is a self-contained functional software unit that is assembled into a J2EE application with its helper classes and files and that communicates with other components in the application. The J2EE specification defines the following J2EE components:

Application clients and applets are components that run on the client.

Java Servlet and JavaServer Pages technology components are Web components that run on the web server.

Enterprise JavaBeans components (enterprise beans) are business components that run on the application server.

All these J2EE components are assembled into a J2EE application, verified to be well formed and in compliance with the J2EE specification, and deployed to production, where they are run and managed by the J2EE application server.

In addition to these primary components, it includes standard services and supporting technologies which are :

Java Database Connectivity (JDBC) technology provides access to relational database systems.

Java Transaction API (JTA) or Java Transaction Service (JTS) provides transaction support for J2EE components.

Java Messaging Service (JMS) for asynchronous communication between J2EE components.

Java Naming and Directory Interface (JNDI) provides naming and directory access.

Note : All J2EE components are written in the Java programming language

J2EE Clients :

There are normally two types of J2EE client: a Web client and an Application client as shown above in figure.

A Web client consists of two parts, dynamic Web pages containing various types of markup language (HTML, XML and others), which are generated by Web components running in the Web tier, and a Web browser, which draws the pages received from the server. Another category of web clients are sometimes called as thin client. Thin clients usually do not do things like query databases, execute complex business rules, or connect to any legacy applications. When we use a thin client, heavyweight operations like these are handled by enterprise beans executing on the J2EE server where they can leverage the security, speed, services, and reliability of J2EE server-side technologies.

A Web page received from the Web tier can include an embedded applet. An applet is a small client application written in the Java programming language that executes in the Java virtual machine installed in the Web browser. However, client systems will need the Java Plug-in and possibly a security policy file in order to execute applets successfully in the Web browser. Web components are often a preferred API for creating a Web client program because no plug-ins or security policy files are needed on the client systems. Moreover this allows cleaner and more modular application design because they provide a means to separate application logic from Web page design.

An Application client runs on a client machine and provides a way for users to handle tasks that require a richer user interface than can be provided by a markup language. It normally has a graphical user interface (GUI) created using the Swing or Abstract Window Toolkit (AWT) APIs. Application clients directly access enterprise beans running in the business tier. But if there is need for a web client it can open an HTTP connection to establish communication with a servlet running in the Web tier.

Note: If required, a command line interface can be used.

Web Components :

J2EE Web components can be either servlets or JSP pages. Servlets are Java programming language classes that dynamically process requests and construct responses. JSP pages are text-based documents that execute as servlets but allow a more natural approach to creating static content. HTML pages and applets are bundled with Web components during application assembly, but are not considered Web components by the J2EE specification. Similarly, server-side utility classes can also be bundled with Web components like HTML pages, but are not considered Web components by the J2EE specification. Shown below in figure is Web components communication.

The Web tier might include a JavaBeans component to manage the user input and send that input to enterprise beans running in the business tier for processing as shown above in the figure..

Business Components :

Business code, which is logic that solves or meets the needs of a particular business domain such as banking, retail, or finance, is handled by enterprise beans running in the business tier.

The figure above shows communication with business components, where an enterprise bean receives data from client programs, processes it (if necessary), and sends it to the enterprise information system tier for storage. An enterprise bean also retrieves data from storage, processes it (if necessary), and sends it back to the client program.

There are three kinds of enterprise beans: session beans (stateless and stateful), entity beans (bean managed and container managed), and message-driven beans. A session bean represents a transient conversation with a client. When the client finishes executing, the session bean and its data are gone. In contrast, an entity bean represents persistent data stored in one row of a database relation/table. If the client terminates or if the server shuts down, the underlying services ensure that the entity bean data is saved. A message-driven bean combines features of a session bean and a Java Message Service (JMS) message listener, allowing a business component to receive JMS messages asynchronously.

Note : Java Beans are not considered J2EE components by the J2EE specification as JavaBeans are different from Enterprise Beans. JavaBeans component architecture can be used in both server and client tiers to manage the communication between an application client or applet and components running on the J2EE server or between server components and a database, whereas Enterprise JavaBeans components are only used in the business tier as a part of the server tier. JavaBeans have instance variables and has an accessor and mutator methods to access properties of bean or say, accessing the data in the instance variables which simplifies the design and implementation of JavaBeans components.

Enterprise Information System Tier :

The enterprise information system tier handles enterprise information system software and includes enterprise infrastructure systems such as enterprise resource planning (ERP), mainframe transaction processing, database systems, and other legacy information systems. J2EE application components might need access to enterprise information systems for database connectivity.

J2EE Containers :

J2EE containers provide access to the underlying services of the J2EE Server environment via containers for different types of components. Traditionally, application developers have to write code for handling transaction, state management, multithreading, resource pooling etc. Now the J2EE container provides these services allowing you to concentrate on solving business problems.

Containers are the interface between a component and the low-level platform-specific functionality that supports the component. For example, before a Web, enterprise bean, or application client component can be executed, it must be assembled into a J2EE application and deployed into its container.

The assembly process involves specifying container settings for each component in the J2EE application and for the J2EE application itself. Container settings customize the underlying support provided by the J2EE server, which includes services such as Java Naming and Directory Interface, security, transaction management etc.

The J2EE server provides Enterprise JavaBeans (EJB) and Web containers. EJB container manages the execution of enterprise beans for J2EE applications, whereas Web container manages the execution of JSP page and servlet components for J2EE applications. Other than these two containers there are an Application client container and Applet container, which are not part of J2EE server as these reside on the client's machine as shown below.

An Application client container manages the execution of application client components whereas an Applet container manages the execution of applets. These are typically the JRE (Java Runtime Environment) and a Java-enabled Web browser respectively.

Packaging :

In order to deploy a J2EE application, after developing different components, it is packaged into special archive files that contain the relevant class files and XML deployment descriptors. These XML deployment descriptors contain information specific to each bundled component and are a mechanism for configuring application behavior at assembly or deployment time. These are bundled into different archive types for different component types.

Web components are archived in Web Archive (.war) file which contains servlets, JSP and static components such as HTML and image files. The .war file contains classes and files used in web tier along with a Web component deployment descriptor.

Business components are archived in Java Archive (.jar) file which contains an EJB deployment descriptor, remote, and object interface files along with helper files required by EJB component.

Client side class files and deployment descriptors are archived in Java Archive (.jar) file which make up the client application.

J2EE application is bundled in an Enterprise Archive (.ear) file which contains the whole application along with deployment descriptor that provides information about the application and its assembled components.

J2EE Platform Roles :

Building the different components of a J2EE application involves various roles in the development, deployment and management of an enterprise application.

The application component provider develops the reusable components of J2EE application, which can be Web components, enterprise beans, applets, or application clients for use in J2EE applications.

The application assembler takes all building blocks from the application component provider and combines them into J2EE applications.

The deployer is responsible for the installation/deployment of components in a J2EE environment or J2EE server.

The system administrator is responsible for configuration and administration of computing systems in an enterprise.

The tool provider is a vendor used to develop, package and deploy J2EE applications.

Note : All these above mentioned roles can be assigned to a person or an organization.

Distributed Architecture in J2EE :

All the J2EE applications implement a distributed architecture. In this an object is associated with a name, where names are provided by naming service, by advertising to various components and resolving client references to these service components as shown in figure below.

As a result of that, object references are obtained, by looking up for an object by its advertised name, once found, reference is obtained, and then carry out the necessary operations on that object using the host's services. A remote object advertises its availability with the name service using a logical name and the name service translates the name to the physical location of the object in the J2EE environment. Once the client request obtains a reference to a remote component, it can send requests to the remote component. The runtime system system handles the distributed communication between the remote objects, which includes serialization and deserialization of parameters.

Note : Various naming services used in distributed systems are RMI (for Java-only implementations), CORBA naming services, LDAP, DNS, NIS. The JBOSS application server uses RMI as its naming service.

Serialization and Deserialization are the same as marshalling and unmarshalling for those familiar with RPC terminology.

Java Naming Directory Interface (JNDI) Architecture :

J2EE uses the JNDI API to generically access naming and directory services using Java technology. The JNDI API resides between application and a naming service and makes the underlying naming service implementation transparent to application components.

A client can look up references to EJB components and other resources in a naming service as mentioned above. The client code remains unchanged, regardless of what naming service is used or what technology it is based on, as this doesn't make any difference to clients locating remote objects via the JNDI API.


Chapter3 - Creating a Stateless Session Bean

Netcool Training

Chapter 3.

Creating a Stateless Session Bean

This chapter covers how to create a stateless session EJB component. This bean will be responsible for authenticating the user by communicating with the database using Data Access Object (DAO) which encapsulates Java Database Connectivity (JDBC) code. A DAO has all attributes (fields) and behavior (methods) corresponding to the bean it is being used for.

All customers, supplier and manager of MyStore have been assigned a unique username and userid to access services of MyStore, but in order to access these services all these entities have to first login into the system (MyStore). The method for authentication is named loginUser, which takes two String parameters, username and password and returns the userID if authentication is successful.

Note : This method loginUser is a business method, normally business methods carry out operations or processing on values EJB components. From clients perspective, clients can see only business methods and invoke them on bean.

Tasks :

  1. Create a J2EE project named MyStore.

  2. Create a Stateless Session Bean named StoreAccess.

  3. Add a business method in bean named loginUser with the following signature

    public String loginUser (String username, String password)

  4. Create a DAO named StoreAccessDAOImpl under package au.com.tusc.dao. Generate the DAO interface.

  5. Implement the method named loginUser, generated in DAO interface, in StoreAccessDAOImpl. Method signature is

    public String loginUser (String username, String password)

  6. Add callback methods and implement them.

  7. Deploy StoreAccess bean.

  8. Create your test client named SessionClient under package au.com.tusc.client.

  9. Run your client and test the bean.

Create J2EE Project :

Now, lets start to write our first component of this tutorial.

Go to File > New > LombozJ2EE Project, project creation wizard will pop up.

Insert Project Name MyStore > Next .

Under Java Settings Check source, should be MyStore/src , libraries pointing to $JAVA_HOME > Go Next as shown in fig below.

Note: This step is shown in chapter1, as there is a bug in eclipse 2.1, so its important that you check your library settings are right.

Under Create J2EE Module, select Web Modules tab > Add.., enter Module name as OnlineStore > OK as shown in figure below.

Under Create J2EE Module, select EJB Modules tab > Add.., enter Module name as MyStoreMgr > OK .

Under Create J2EE Module, select Targeted Servers tab > Select JBOSS 3.2.1 ALL > Add.. > Finish.

Create Stateless Bean :

Go To Package Explorer > Expand Mystore (project) node > select src, right click and menu will pop up.

On pop up menu > New > Lomboz EJB Creation Wizard.

Enter package name au.com.tusc.session, bean name StoreAccess and select bean type as stateless > Finish.

This will create a package named au.com.tusc.session under src and StoreAccessBean under that package as shown in the figure below.

As we can see from the figure below it has created a class level tag @ejb.bean, which has assigned the bean type, name and its JNDI name which will be generated in Home interface. This tag will also generate deployment descriptors in ejb-jar.xml and jboss.xml file as well once you generate your EJB classes, which is covered later on in this chapter.

Note: It will generate the bean name, jndi-name and type of bean in the file. Also, the name of file is appended with word 'Bean' as you gave the name of the bean as StoreAccess only. Again, be careful with naming conventions, specifying the bean name only in the wizard without adding the word 'Bean' to the name as the wizard appends that for you.

Expand MyStoreMgr/META-INF node under Package Explorer. You will find there are seven files which are generated by Lomboz using Xdoclet as shown in the figure below.

Now we are going to generate all the interfaces including Home, Remote, DAO and other helper classes. We will explain why later on, but for the time being just follow the steps.

But before we get too excited, there are a few concepts to cover here.

Go to MyStoreMgr/META-INF > select and open ejbGenerate.xml.

Note: Lomboz uses this file to generate required interfaces and helper classes, so in the event that you have special needs then you will have to customize this file. See ejbdoclet under the Xdoclet documentation.

'ejbGenerate.xml' file is generated only once when you create your EJB module. So any changes made in this file will be reflected even if you modify your bean class and generate your classes again and again.

As we can see from the code snippet of file shown in figure at right, there are following tags defined.

<dataobject/> is defined for generating data Objects for holding values of EJB component's persistent fields, which correspond to columns in the associated table in the database.

Note: <dataobject/> has been deprecated in favour of Value Object which is more powerful in terms of relationships (1-1, 1-n and n-m).

<utilobject/> Creates method for generating GUID and for accessing Remote and Local Home objects.

<remoteinterface/> Generates remote interfaces for EJBs.

<localinterface/> Generates local interfaces for EJBs.

<homeinterface /> Generates remote home interfaces for EJBs.

<localhomeinterface/>Generates local home interfaces for EJBs.

<entitypk/>Generates primary key classes for entity EJBs.

<entitybmp/>Creates entity bean classes for BMP entity EJBs.

<entitycmp/>

<session/> Generates session bean class.

Note : There is no tag for generating a DAO.

So, we have to include this <dao/> tag.

For details, please refer ejbdoclet under Xdoclet documentation.

As we can see from the code snippet from this file the following tags are defined.

<jboss/> is a JBOSS specific tag required for JBOSS. You have to specify datasource, datasourcemapping and preferredrelationmapping. As it differs for different databases, so you may have to specify values appropriate to your environment. If these tags are commented out in JBOSS they default to the correct values for the built-in Hypersonic SQL database, but for the moment we'll set them anyway.

The other two files which are of importance to us are ejb-jar.xml and jboss.xml. The file ejb-jar.xml has all the deployment descriptors for beans and jboss.xml has the JBOSS specific deployment descriptors required by JBOSS.

Note : ejb-jar.xml file is generated every time you generate interface and helper classes for your bean. For the first time, it is empty, and jboss.xml will be generated every time when you will generate your classes for your bean.

Setup DAO :

Now, let's customize ejbGenerate.xml for setting up a DAO.

We have included a <dao> tag specifying the destination directory for the generated DAO interface and what pattern to be used.

Note : For details, please refer ejbdoclet under Xdoclet documentation.

We have included the datasource, datasoucremapping and preferredrelationmapping as shown in code snippet of ejbGenerate.xml file on right.

datasource="java:/DefaultDS" is a local JNDI name for data source to be used.

datsourcemapping="Hypersonic SQL" maps data object/value objects and their types to columns and data types associated with these columns.

preferredrelationmapping="foreign-key" defines type of database to be used.

Note : For more details, please refer JBOSS documentation.

Since we are using the Hypersonic database, these parameters are appropriate to that. These parameters relate to the configuration file standardjbosscmp-jdbc.xml which controls the CMP-to-JDBC mappings for JBOSS. This resides in $JBOSS_HOME/server/conf/ , e.g. /opt/jboss/jboss-3.2.1/server/default/conf/.

Code snippet from standardjbosscmp-jdbc.xml is shown in figure at right.

Note : The way Xdoclet works is bit different from some conventional styles of programming, as the Xdoclet tags will generate these (home and remote) interfaces along with necessary helper classes, which then will used in Bean and DAO Implementation class. However, until these are generated, we cannot write any business methods in Bean and JDBC wrappers in the DAO Implementation class. If this seems confusing then just follow the steps, and hopefully it will become more clear.

Create DAO Interface :

Since we are going to use a DAO to access the database for this Stateless Bean, we have to create a DAOImpl class which will implement that generated DAO interface.

Go to src > add package named au.com.tusc.dao > Add a class StoreAcessDAOImpl in that package.

Now go to your Bean class and declare this tag at the class level (that is at the top) as shown below to generate the DAO interface.

   @ejb.dao class="au.com.tusc.session.StoreAccessDAO"
    impl-class="au.com.tusc.dao.StoreAccessDAOImpl"

Expand StoreAccessBean node under Package Explorer. Right click and a pop up menu will appear.

On that menu go to Lomboz J2EE > Add EJB to module. Select EJB '[MyStoreMgr]' > OK.

Expand MyStoreMgr node under MyStore Project in Package Explorer. Right click and a menu will pop up.

Go to Lomboz J2EE > Generate EJB Classes as shown in the figure below.

EJB interfaces and helper classes are generated under ejbsrc/au.com.tusc.session directory as shown in the figure at the right.

Seven files are generated.

StoreAccess is the remote object interface.

StoreAccessLocal is the local object interface.

StoreAccessSession extends our bean class named StoreAccesBean.

StoreAccessHome is the remote home interface.

StoreAccessLocalHome is the local home interface.

StoreAccessUtil is a helper class which has methods for accessing Home and LocalHome interface along with generating GUID.

StoreAccesDAO is the DAO interface which we will use to implement our StoreAccessDAOImpl under au.com.tusc.dao.

StoreAccessDAO is generated by this tag declared in StoreAccesBean shown below. If you don't declare this tag in that file it won't generate this interface.

 @ejb.dao class=au.com.tusc.session.StoreAccessDAO
 impl-class=au.com.tusc.dao.StoreAccessDAOImpl

Other files of interest which are generated are ejb-jar.xml and jboss.xml under MyStoreMgr/META-INF.

As shown in the figure on the right, a few descriptors are generated in the ejb-jar.xml file.

These descriptors are generated by the following tag declared in the StoreAccesBean file.

@ejb.bean name ="StoreAccess"
jndi-name="StoreAccessBean"
type="Stateless"

This tag is added by Lomboz's bean creation wizard.

This tag also generates the following descriptors in jboss.xml as shown in the code snippet below.

So now we know which tags are responsible for generating classes, interfaces and descriptors.

Add Business Method :

Next step is to add a business method in the bean.

Go to StoreAccesBean > Right click > Select New on pop up menu > Select Lomboz Ejb Method Wizard.

Add a business method with the following signature: public String loginUser (String username, String password).

Select Method Type as Business and Interface as Remote as shown in the figure below..

This wizard generates a loginUser method in our bean class, with the method level tag '@ejb.interface' shown below.

This tag is responsible for generating this method in the Remote Interface (in this case it is StoreAccess which will be created once you generate your classes). This tag is covered later on in this chapter.

Now, This business method needs to invoke a method on the DAO, which will communicate with the database.

Therefore we add another tag on this method, so that a method with this signature is generated in DAO interface which we can implement in the DAOImpl class. Then this business method can invoke the method in DAOImpl class to get the desired result.

@dao.call name="loginUser"

So add this tag at the method level as shown in the figure at right.

Now generate your EJB classes again as shown in the steps we went through earlier.

Note: OK, OK! For reference these are the steps you have to follow.

Expand 'MyStoreMgr' node under 'MyStore' Project in Package Explorer.

Right click and a pop up menu will appear.

Go to Lomboz J2EE > Generate EJB Classes.

After generating the classes, we look at first the generated DAO interface and then the generated Session Class.

In StoreAcessDAO two methods are generated.

1. init() by default.

2. loginUser(), generated by tag shown below.

@dao.call name="loginUser"

Note: Please do not edit any class generated by Xdoclect.

In StoreAcessSession two methods of our interest are

1. getDAO() creates instance of DAOImpl calss.

2. loginUser(), calls loginUser method in DAOImpl class, which we have to implement.

Code snippet from 'StoreAccessSession'.

Implement DAO Interface :

Now, we will implement methods in the StoreAccessDAOImpl class.

First import the following packages.

javax.naming.InitialContext;

javax.sql.DataSource;

java.sql.Connection;

java.sql.PreparedStatement;

java.sql.ResultSet;

java.sql.SQLException;

Change your class declaration so that StoreAccessDAOImpl implements StoreAccessDAO.

Add a field to store the JDBC resource factory reference.

private DataSource jdbcFactory;

In init() method, locate the reference "jdbc/DefaultDS" using the JNDI API, and store the reference in variable jdbcFactory.

Lookup string is "java:comp/env/jdbc/DefaultDS".

Code Snippet is shown in the figure on the right.

Now add the required code in loginUser().

In method loginUser(), first get the connection to the database using the jdbcFactory.

Create a SQL statement which searches for userid in the table StoreAccess where userid and password is provided for each user.

Return userid if successful, else raise SQLException.

Code snippet is shown in the figure on the right.

Go back to your loginUser method in StoreAccessBean class.

In StoreAcessBean class under the loginUser method just add some debug statements, as shown below in this code snippet.

Note : We don't have to call the loginUser method in StoreAccessDAOImpl, as it being invoked by the loginUser method in StoreAccessSession class which inherits StoreAccessBean class, that is the StoreAccessSession class has overridden this method.

Code snippet from StoreAccessSession shown below.

Add Callback Methods :

Now, add callback methods to complete this bean as shown below.

  1. setSessionContext.

  2. UnsetSessionContext.

Note : These callback methods are invoked by the EJB container.

Add a field to store sessionContext.

protected SessionContext ctx;

Add method setSessionContext with sessionContext as parameter and assign that to the sessionContext variable as shown below in the code snippet.

Similarly add method unsetSessionContext, assign context variable to null as shown above.

Note : StoreAccessSession class inherits the StoreAccessBean abstract class and implements SessionBean, which will override all methods of interface SessionBean. So after finishing the methods in the bean class, generate your EJB classes again. SessionContext methods will be overridden as shown in figure below. Code snippet from StoreAccessSession shown below.

Now let's look at the generated Home and Remote interfaces.

In the case of the Remote interface all business methods declared in the bean are also generated with the same signature. This is due to the class level tag declared in the StoreAccess Bean as discussed above after adding business methods. Code snippet for tag is shown below.

So, loginUser is generated in a Remote Interface called StoreAccess as shown below because of this tag.

In the case of the Home Interface only one method is created named 'create', which is generated by default because of the <homeinterface/> tag in ejbGenerate.xml as shown below.

Also, other then that, it has JNDI_NAME and COMP_NAME (which is the fully qualified name for bean) is also generated, these are generated because of this tag declared at class level in 'StoreAccessBean' class shown below in figure.

Note : For further options associated with these tags please refer to the 'ejbdoclet' documentation in Xdoclet.

Now, all the aspects are pretty much covered, and our bean's functionality is complete. Now for the deployment descriptors..

Deploy Bean :

In order to deploy our bean we have to declare a few tags in the StoreAccessBean class as shown below in the code snippet.

Add the tag shown below in at the class level (at the top).

@ejb.resource-ref res-ref-name="jdbc/DefaultDS"
res-type="javax.sql.Datasource"
res-auth="Container"

This tag will generate deployment descriptors in ejb-jar.xml, as the bean has to know which datasource you are going to connect to, what is its type, etc. This will generate these descriptors as shown in code snippet below.

Add the tag shown below in StoreAccessBean at the class level (at the top).

@jboss.resource-ref res-ref-name="jdbc/DefaultDS" jndi-name="java:/DefaultDS"

This tag will generate deployment descriptors in jboss.xml, as the application server has to know with what jndi-name datasource it has been registered with. This will generate these descriptors as shown in the code snippet below.

Now, everything is complete, and it's time to deploy the bean.

First, regenerate your EJB classes as shown in the steps above for the final time.

Note : We have regenerated the classes again and again, in order to explain every step and its result. Once you are familiar with these steps you will need much fewer of these iterations. Either way, it doesn't matter, as your implementation always remains untouched by this process.

Go to Lomboz J2EE View > expand node MyStore > expand MyStoreMgr > select 'Jboss 3.2.1 ALL' .

Right click > select Debug Sever on the pop up menu as shown in figure below.

Go to MyStoreMgr node in LombozJ2EE view > right click > select Deploy on the pop up menu as shown in the figure below.

And now wait for your deployment result.

If everything goes fine, you will have this message under your console as shown in the figure below.

So, now our bean is deployed successfully, let's create our test client, which will invoke the loginUser method on 'StoreAccessBean'.

Create your Test Client :

Go to Project MytStore node > select src node > right click.

Select New on pop up menu > select Lomboz EJB Test Client Wizard as shown in the figure below.

Select package name au.com.tusc.client, name as SessionClient and select Ejb Home as au.com.tusc.session.StoreAccessHome and Ejb Interface as au.com.tusc.session.StoreAccess as shown in the figure below.

This will generate the required methods for you in your SessionClient class and you have to just invoke the loginUser method on the bean as shown below.

Now the last step is to write code in your client.

So add these lines under the testBean method as shown in figure below.

System.out.println("Request from client : ");
System.out.println("Reply from Server: Your userid is " +
myBean.loginUser("ANDY","PASSWD"));

Test your Client :

Now, in order to test your client, Select SessionClient node > Go at top level menu and select the icon with the 'Running Man'.

On that select 'Run as' > select 'Java Application', as shown below.

Now under your console, if you get your reply for 'ANDY' as 'U2', then your call is successful as shown below.

Note : So our Stateless Session Bean is deployed and tested successfully and from now onwards you should be comfortable using Lomboz. In future we will not go into the detail of the steps for using Lomboz and will concentrate more on other aspects of beans.


Chapter5 - Creating a BMP Entity Bean

Netcool Training

Chapter 5.

Creating a BMP Entity Bean

This chapter describes how to create a Bean Managed Persistence (BMP) EJB component. We will create two BMP beans, Customer and Manager, as shown below. The Customer bean will be responsible for storing the details of customers of MyStore. The Manager bean stores details of the manager of MyStore. Both beans communicate with their respective tables in the database using Data Access Objects (DAOs) named CustomerDAO and ManagerDAO respectively.

All customers have been assigned a unique customerID for housekeeping purposes in MyStore in addition to their username for accessing the services of MyStore. Similarly the Manager of MyStore has been assigned a unique ManagerID.

Note : It is the usual practice to access business methods of BMP beans via a session bean, which encapsulates business logic and acts as an interface to further EJB components. In this case Customer and Manager are accessible via by StoreAccess.

This approach comes from a pattern called a Session Facade, whereby enterprise beans encapsulate business logic and business data and expose their interfaces. The session bean acts as a facade to encapsulate the complexity of interactions with the lower-level beans. The session facade is responsible for managing business objects and provides a uniform business service abstraction to presentation layer clients, thereby hiding the business object implementation in the lower-level beans.

This tutorial uses that pattern for business tier implementation.

Tasks :

  1. Create a BMP bean named Customer under package au.com.tusc.bmp.

  2. Create a DAO class named CustomerDAOImpl under package au.com.tusc.dao.

  3. Add all attributes/properties to the CustomerBean, with getter and setter methods for each of the attributes.

  4. Add a finder method named ejbFindByPrimaryKey with the signature

    public CustomerPK ejbFindByPrimaryKey (CustomerPK pk) throws FinderException

  5. Add a finder method named ejbFindByUserID with the signature

    public CustomerPK ejbFindByUserID (String userID) throws FinderException

  6. Add a business method named getCustomerData with the signature

    public CustomerData getCustomerData()

  7. Implement required methods in the CustomerDAOImpl class.

  8. Deploy the Customer Bean.

  9. Add a create method to the StoreAccess Bean.

    public void ejbCreate() throws javax.ejb.CreateException

  10. Add a business method to the StoreAccess Bean.

    public CustomerData getCustomerData(String userID)

  11. Create a test client named SessionBMPClient under package au.com.tusc.client.

  12. Run your client and test the bean.

Create the Customer BMP Entity Bean :

Go To Package Explorer > Expand Mystore (project) node > select src, right click and a menu will pop up.

On the pop up menu > New > Lomboz EJB Creation Wizard.

Enter package name au.com.tusc.bmp, bean name Customer and select bean type as Bean Manged Entity > Finish.

This will create a package named au.com.tusc.bmp under src and CustomerBean under that package as shown below.

Note: It will generate the bean name, jndi-name and type of bean in file. Also, the word 'Bean' is appended to the name of the file.

As we can see from the figure above it has created a class level tag @ejb.bean, which has assigned the bean type, its name and its JNDI name which will be generated in the Home interface. This tag will also generate deployment descriptors in ejb-jar.xml and jboss.xml file once you generate your EJB classes.

Now we are going to generate all the interfaces including Home, Remote, DAO and other helper classes. We don't need to specify any tags in ejbGenerate.xml as we have already set up that for the MyStoreMgr EJB module in chapter 3.

Go to node CustomerBean under au.com.tusc.bmp > LombozJ2EE > Add EJB to Module > Select MyStoreMgr > Ok.

Go to MyStoreMgr node > LombozJ2EE > Generate EJB classes.

Note: All these steps are covered in previous chapters (chapter 3 and 1) so please refer to those sections if you need further details.

Now let's see what files are generated by Xdoclet.

As shown below there are two new files named CustomerData and CustomerPK in addition to what we had for our session beans. We also have a CustomerBMP which extends our CustomerBean class. The remaining files should be familiar from our work with session beans.

As discussed in chapter 3 regading the various ejbDoclet tags used in ejbGenerate.xml, to generate these classes, CustomerData and CutomerPk are generated by following tags as shown below in this snippet from ejbGenerate.xml:

The relevant tags are <dataobject/> and <entitypk/>.

Note: There is no CustomerDAO class, as we haven't generated that file by specifying the dao tag in the CustomerBean class.

Create Customer's DAO Interface :

Since we are going to use a DAO to access database for this bean, we have to create a DAOImpl class to provide an implementation for the generated DAO interface.

Go to src > package au.com.tusc.dao > Add a class CustomerDAOImpl in that package.

Now go to your bean class and declare this tag at class level (ie. at the top) as shown below to generate the DAO interface.

   @ejb.dao class="au.com.tusc.bmp.CustomerDAO"
    impl-class="au.com.tusc.dao.CustomerDAOImpl"

Regenerate your classes and check that your DAO interface is generated.

Note : For reference the steps are as follows:

Expand MyStoreMgr node under MyStore Project in Package Explorer.

Right click and a pop up menu will appear.

Go to Lomboz J2EE > Generate EJB Classes as shown on the right.

As shown below, our DAO interface is generated.

If we look at the generated DAO class as shown below, it has four more methods than StoreAccess (which was a Stateless Session Bean) did when we first generated it (ie. prior to adding the method level @dao:call tag).

Note : It's worth mentioning here that BMP Entity beans don't need the @dao:call tag for generating DAO interface methods.

All these methods are generated by the tag described earlier for DAO interface generation, also shown below.

Also, let's look at the descriptors generated up until this step, in ejb-jar.xml under MyStoreMgr/META-INF.

These descriptors are generated by the following tag in CustomerBean.

@ejb.bean name="Customer"
jndi-name="CustomerBean"
type="BMP"

This tag generates descriptors in jboss.xml as well, which will be covered later on.

The next step is to add attributes/properties to our Customer Bean, which will be accessible to clients through the remote interface using getter and setter methods. These attributes are mapped to corresponding columns in the relevant table in the database.

In order to add these properties/attributes , define all attributes (as private to encapsulate) and their corresponding accessors/mutators (getter and setter methods). Each accessor (getter) method will have two tags or three in the case of a primary key. The mutator (setter) method will have only one tag declared on it.

Add these tags for attributes/properties (in Bean terms) as shown below.

/**

    * Returns the customerID
    * @return the customerID
    *
    * @ejb.persistence
    * @ejb.pk-field
    * @ejb.interface-method
    */
    public  java.lang.String getCustomerID() {
         return customerID ;
    }

    /**
     * Sets the customerID
     * @param java.lang.String the new customerID value
     *
     * @ejb.interface-method
     */
    public void setCustomerID (java.lang.String customerID)
         this.customerID = customerID;

}

Code snippet from CustomerBean is shown in figure at right.

Now, analyzing these tags,

  1. @ejb.persistence specifies this as a persistent attribute. All accessor and mutator methods will be overridden in generated BMP class, in this case it is CustomerBMP, and all mutator methods will have a dirty flag in them, as persistence is controlled by ejbLoad() and ejbStore().

  2. @ejb.pk-field specifies that this attribute is mapped to a primary key in database and and is assigned as a primary key in the PrimaryKey class, in this case the CustomerPK class.

  3. @ejb.interface generates these methods in the Remote interface.

Now, in the case of mutator methods (that is 'setCustomerID') the only tag required is @ejb.interface-method for generating this method in the remote interface.

Similarly, add methods and their tags for rest of the persistent fields. There will be no @ejb.pk-field tag as customerID is the primary key.

Note : In the case of a composite primary key you have to specify @ejb.pk-field tags on the other attributes/properties which make up the composite key.

Similarly, Add tags and methods for rest of the persistent fields, which in this case are, firstName, lastName, Address, phone and shareholderStatus as shown in this code snippet from CustomerBean.

Generate EJB classes and examine what methods are generated in the various classes, particularly in CustomerBMP and CustomerData.

Add Finder Methods :

Now let's add a finder method to our bean class.

Add a method with this signature:

public CustomerPK ejbFindByPrimaryKey (CustomerPK pk) throws FinderException

Put some debug statements in it and return null as shown below.

Now when we generate our EJB classes this method will be overridden in CustomerBMP. Also this method will call a corresponding method from CustomerDAO interface as shown below in this code snippet from CustomerBMP.

This will also create methods in the Home interface and DAO interfaces as shown below.

Add another finder method to CustomerBean, with the signature

public CustomerPK ejbFindByUserID (String userID) throws FinderException

Put some debug statements in it and return null as shown below.

Note : As stated in the EJB spec 12.8.1 all finder methods should return the Primary Key.

Again, regenerate your EJB classes, and there will be methods created in the CustomerHome interface, CustomerBMP and CustomerDAO, similar to those that were created for ejbFindByPrimaryKey.

A code snippet from the CustomerDAO class, after generating the EJB classes.

Add Business Methods :

Now, add a business method with the signature

public CustomerData getCustomerData() with Interface type as local.

Note : The steps to add a business method are covered in previous chapters (1 and 3), so please refer to them. Also, we have chosen the interface type to be local because these methods will be invoked in the same Java Virtual Machine. In this case they will be invoked by the stateless bean StoreAccess.

This will provide the details of an individual customer. Add some debug statements and return an instance of CustomerData as shown below in this code snippet from CustomerBean.

Make sure you generate your EJB classes again before you start implementing Customer's DAO interface.

Implement Customer's DAO Interface :

Now let's implement our methods in CustomerDAOImpl class.

CustomerDOAImp class under package au.com.tusc.dao implements methods generated in CustomerDAO class under package au.com.tusc.bmp.

First import the following packages.

javax.naming.InitialContext;
javax.sql.DataSource;
java.sql.Connection;
java.sql.PreparedStatement;
java.sql.ResultSet;
java.sql.SQLException;

Change your class declaration so that CustomerDAOImpl implements CustomerDAO.

Add a field to store the JDBC resource factory reference.

private DataSource jdbcFactory;

In the init() method, locate the reference jdbc/DefaultDS using the JNDI API, and store the reference in variable jdbcFactory.

The lookup string is "java:comp/env/jdbc/DefaultDS".

Code snippet is shown below.

In method load(), first get the connection to the database using field jdbcFactory. Create a SQL statement which searches for a record corresponding to customerid in table Customer, where customerid is the primary key. Code snippet is shown below.

In method store(), first get the connection to database using field jdbcFactory. Create an SQL statement which updates a record corresponding to customerid in table Customer, where customerid is the primary key. Code snippet is shown below.

In method ejbFindByUserID(), first get the connection to database using field jdbcFactory. Create an SQL statement which searches for the customerid corresponding to a given userid in table Customer, where customerid is primary key. Code snippet is shown below.

In method ejbfindByPrimaryKeystore(), first get the connection to database using field jdbcFactory. Create an SQL statement which searches for customerid in table Customer, where customerid is the primary key. Return the primary key. Code snippet is shown below.

Also, you should implement methods remove and create. We're leaving those as an exercise for you (you've probably got the idea by now!), or you can leave them as stubs as shown below.

Now our CustomerDAOImpl class is finished. Generate your EJB classes again.

After generating your EJB classes, let's look at the Home Local Interface and the Remote Local interface.

In the Remote Local Interface (which is CustomerLocal in this case), there is one business method exposed, and the rest are all the methods to access the attributes/properties of the bean (as we also declared these methods as interface methods in CustomerBean), as shown below. These methods are generated by @ejb.interface-method tag.

In the Home Local Interface, which is CustomerLocalHome in this case, there are two finder methods as shown below. It has also generated JNDI_NAME and the bean's fully qualified name, COMP_NAME.

These names are generated by the following tag declared in CustomerBean as shown below.

Note : We are not currently interested in the Customer interface (which is a Remote interface) and CustomerHome (which is a Remote Home interface), because we are accessing bean methods in the same Java Virtual Machine, so we need only Local interfaces.

Note : In CustomerBean we haven't implemented any methods for the setting and unsetting of context, because it is generated by Xdoclet in the CustomerBMP class, as shown below.

Now Customer Bean and its DAO implementation is complete and we can deploy this bean.

Deploy Customer Bean :

In order to deploy this bean we have to add a few deployment descriptors to it. We will add the two tags shown below.

First add the tag shown below at class level in CustomerBean.

@ejb.resource-ref res-ref-name="jdbc/DefaultDS"
res-type="javax.sql.Datasource"
res-auth="Container"

This tag will generate deployment descriptors in ejb-jar.xml, as the bean has to know which datasource you are going to connect to, and what is its ts type, etc. This will generate these descriptors as shown below.

Add this second tag required for the JBOSS application server.

@jboss.resource-ref res-ref-name="jdbc/DefaultDS"
 jndi-name="java:/DefaultDS"

This tag will generate deployment descriptors in jboss.xml, as the application server has to know with what jndi-name the datasource has been registered with. This will generate these descriptors as shown below.

Now everything is complete, and it's time to deploy the bean. So, regenerate your EJB classes.

Note : As noted in earlier chapters we are regenerating classes over and over to properly illustrate each step and its result. Once you are proficient you will be able to forgo most of this.

Go to Lomboz J2EE View > expand node MyStore > expand MyStoreMgr > select 'Jboss 3.2.1 ALL' .

Right click > select 'Debug Sever' on pop up menu.

Note : This is to start your server, if you are already running your server then skip these steps and go to the next one.

Go to MyStoreMgr node in LombozJ2EE view > right click > select 'Deploy' on pop up menu as shown in figure below.

Note : All these techniques have been shown in previous chapters (1 and 3) so please refer to them.

The messages in the console will show whether your bean has been successfully deployed or not.

Now our Customer Bean is complete, and in order to create a client to invoke operations on this bean we have make some modifications to our StoreAccess Bean.

Note : As shown in the diagram at the beginning of this chapter that client will invoke operations on Customer Bean through Store AccesBean, as it is a good practice to access Entity Beans in this manner. As a result we need a Local view of Customer Bean rather than Remote, because both are in the same Java Virtual Machine.

Add Create Method in StoreAccess :

In StoreAccess Bean add an ejbCreate method, which will create a BMP Entity Bean (in this case a Customer Bean) with the following signature

public void ejbCreate () throws  javax.ejb.CreateException

Now, add a field to store the reference obtained by locating Customer in JNDI.

private CustomerLocalHome customerLocalHome;

In ejbCreate method store the reference in the customerLocalHome variable by invoking the getLocalHome static method in CustomerUtil class as shown in the code snippet below from StoreAccess Bean.

Add Business Method in StoreAccess :

Add another business method in StoreAccess Bean which will invoke the corresponding business method on Customer Bean.

Now, add a business method with this signature public CustomerData getCustomerData(String userID) with Interface type as Remote. As customers will log on to MyStore with username, once they are authenticated they will be identified by userid and they can retrieve their account details from MyStore using this userid.

Note : Steps to create business methods are covered in previous chapters.

Now invoke one of the finder methods of Customer on the reference variable we have created in the ejbCreate method.

CustomerLocal myCustomer  =   customerLocalHome.findByUserID(userID)

Now invoke the business method on Customer using the myCustomer reference variable.

CustomerData cd = myCustomer.getCustomerData()

Code snippet of this business method is shown below.

All methods in StoreAccess Bean have now been added for the accessing the Customer's business method. All that remains are the deployment descriptors required for linking/referencing the StoreAccess and Customer beans. We will add the two tags shown below.

First add this tag at class level in StoreAccess Bean.

@ejb.ejb-ref ejb-name="Customer"
 view-type="local"
 ref-name="CustomerLocal"

This tag will generate deployment descriptors in ejb-jar.xml, as StoreAccessBean has to know which bean it's referring to, and what is its view-type and ref-name. This will generate these descriptors as shown below.

Note : View type is local as both are in the same Java Virtual Machine, otherwise it would be Remote. Note that ref-name is generated as CustomerLocalHome rather than CustomerHome. Both are generated but we are using Local in this case.

Now add the second tag shown below at class level in StoreAccess Bean.

@jboss.ejb-ref-jndi ref-name="CustomerLocal"
jndi-name="CustomerLocal"

This tag will generate deployment descriptors in jboss.xml, as the application server has to know what jndi-name Customer Bean has been registered with. This will generate these descriptors as shown below.

Note : Ref-name and jndi-name are used for bean as local (in same JVM).

Note : As we can see from the code snippet above, the deployment descriptor generated by tag @jboss is wrong, because for local referencing of Customer tag <ejb-ref> should be <ejb-local-ref>. There seems to be a bug in this tag, so we will correct this manually by changing the tag in the jboss.xml file as shown below.

Caution here: Make sure that you do this change manually after you finish regenerating your EJB classes, because every time you regenerate your classes, 'jboss.xml' will initially have the wrong descriptors generated by this tag.

Now our changes to StoreAccess Bean are complete, so deploy your bean again now from the Lomboz J2EE View. The steps to do that are shown above and in previous chapters. Messages will appear in the console showing the status of deployment.

Once your bean is deployed successfully, create a test client which will invoke the loginUser method on StoreAccessBean and getCustomerData on CustomerBean.

Create your Test Client :

Go to Project MytStore node > select src node abd expand it > select au.com.tusc.client package > right click.

Select New on pop up menu > select Lomboz EJB Test Client Wizard.

Note : These steps are covered in previous chapters.

Select package name au.com.tusc.client, name as SessionBMPClient and select Ejb Home as au.com.tusc.session.StoreAccessHome and Ejb Interface as au.com.tusc.session.StoreAccess as shown in figure below.

This will generate required methods for you in your SessionBMPClient class and you simply invoke the loginUser and getCustomerData methods as shown.

Now to add some code to your client.

Add these lines under the testBean method as shown below.

System.out.println("Request from client : ");
String userID = myBean.loginUser("ANDY","PASSWD");
System.out.println("Reply from Server: Your userid is " + userID );
CustomerData cd = myBean.getCustomerData(userID);
System.out.println ("Andy your details with MyStore are " + cd );

Test your Client :

Now, in order to test your client, Select SessionBMPClient node > Go at top level menu and select the 'Man running' icon.

On that select 'Run as' > select Java Application, as shown below.

Now under your console, if your reply for 'ANDY' is 'U2', and his details for CustomerID are 'C2' as well, then your call is successful (see below).

Exercise :

Here is an exercise for you. To progress further, implement Manager as a BMP Entity bean similar to Customer, with the same behaviours. The detailed tasks are given below.

  1. Create a BMP Bean named Manager under package au.com.tusc.bmp.

  2. Create a DAO class named ManagerDAOImpl under package au.com.tusc.dao.

  3. Add all attribute/properties in ManagerBean, add accessor and mutator methods for each attribute.

  4. Add a find method named ejbFindByPrimaryKey with signature

    public ManagerPK ejbFindByPrimaryKey (MangerPK pk) throws FinderException.

  5. Add a find method named ejbFindByUserID with signature

    public MangerPK ejbFindByUserID (String userID) throws FinderException

  6. Add a business method named getManagerData with signature

    public ManagerData getManagerData()

  7. Implement methods in ManagerDAOImpl class. Lookup string required for JNDI API is "java:comp/env/jdbc/DefaultDS".

  8. Deploy Manager Bean.

  9. Add a field in StoreAccess Bean to store reference after lookup in JNDI for Manager

    private ManagerLocalHome managerLocalHome;

  10. In ejbCreate method of StoreAccess Bean store reference in managerLocalHome variable by invoking getLocalHome static method in ManagerUtil.

  11. Add a business method in StoreAccess Bean.

    public MangerData getManagerData(String userID)

  12. Add the following tags for deployment at class level for linking/referencing Manager.

    1. @ejb.ejb-ref ejb-name="Manager"
     view-type="local"
     ref-name="ManagerLocal"

2.  @jboss.ejb-ref-jndi ref-name="ManagerLocal"
      jndi-name="ManagerLocal"

  13. Test your Manager Bean by running your Test Client created for Customer named SessionBMPClient.

Note : Don't forget to fix the generated descriptors in jboss.xml as mentioned above in relation to Customer Bean.

Note : All these steps are the same as those for Customer. Implement this Bean which will be used in subsequent chapters.

In case you're unable to do that, we have provided ManagerBean, ManagerDAOImpl, modified StoreAccessBean and modified SessionBMPClient classes. You can download these files from downloads below.

Downloads :

ManagerBean

ManagerDAOImpl

StoreAccessBean

SessionBMPClient


Chapter6 - Creating a CMP Entity Bean

Netcool Training

Chapter 6.

Creating a CMP Entity Bean

This chapter covers how to create a Container Managed Persistence (CMP) EJB component. We will create two CMP beans, Item and Supplier as shown below. The Item bean will be responsible for storing the details of items, such as their availabability and their prices, for MyStore. The Supplier Bean stores details of Suppliers to MyStore. Both beans interact with corresponding tables in the database. In CMP this interaction is controlled by the container, in this case the JBOSS CMP container.

All Items have been assigned a unique itemId for housekeeping purposes within MyStore, and all suppliers have been assigned a unique supplierID in addition to their username which is what they use in accessing the services of MyStore.

Note : It is normal practice to access the business methods of CMP beans via a Session bean, that encapsulates the business logic and acts as an interface to the lower-level EJB components. In this case Supplier and Items are accessed via StoreAccess.

Tasks :

  1. Create a CMP bean named Items under package au.com.tusc.cmp.

  2. Implement the ejbCreate method, with the values of all attributes being passed as arguments and then assigned to the attributes using mutator (setter) methods.

  3. Add a finder method named findBySupplierID with the following query and signature:

    query "SELECT OBJECT(b) FROM MyStoreItem as b where b.supplierID = ?1"

    method "java.util.Collection findBySupplierID(java.lang.String supplierID)"

  4. Add a finder method named findByOutOfStock with the following query and signature:

    query "SELECT OBJECT(c) FROM MyStoreItem as c where c.quantity = 0"

    method "java.util.Collection findByOutOfStock()"

  5. Add a business method to get item details with the signature:

    public ItemData getItemData()

  6. Add another business method to register delivery of items with the signature:

    public void fillStock(java.lang.Integer quantity)

  7. Add callback methods, required for getting/setting bean context for bean with signatures:

    public void setEntityContext(EntityContext ctx)

    public void unsetEntityContext()

  8. Deploy the Item Bean.

  9. Add a field to the StoreAccess bean to store the Item reference (obtained from JNDI lookup):

    private ItemLocalHome itemLocalHome

  10. In the ejbCreate method of the StoreAccess bean store this reference in the itemLocalHome variable by invoking the getLocalHome static method in ItemUtil.

  11. Add a business method to StoreAccess Bean with the signature:

    public ItemData getItemData(String itemID)

  12. Add another business method to StoreAccess Bean with the signature:

    public java.util.ArrayList getOutOfStockItems()

  13. Add another business method to StoreAccess Bean with the signature:

    public java.util.ArrayList getItemBySupplier(String supplierID)

  14. Create a test client named SessionCMPClient under package au.com.tusc.client.

  15. Run your client and test the bean.

Create Items CMP Entity Bean :

Go To Package Explorer > Expand Mystore (project) node > select src, right click and a menu will pop up.

On the pop up menu > New > Lomboz EJB Creation Wizard.

Enter the package name au.com.tusc.cmp, the bean name Item and select the bean type as Container Manged Entity as shown below.

Go to Next and a new screen will pop up as shown below.

Enter MyStoreItem as the Schema Name.

Enter Item as the Table name.

Under Persistent Fields first enter itemID as the Field, with a Field Type of java.lang.String, ITEMID as its Database column, and VARCHAR for its SQL Type.

Press Add .. > It will add this field in Fields section, select this new field > Press Make Primary Key.

Similarly, add all the rest of the fields of the items table as shown below.

Add .. Field: supplierID, Field Type: java.lang.String, Database Column: SUPPLIERID, SQL Type: VARCHAR.

Add .. Field: description, Field Type: java.lang.String, Database Column: DESCRIPTION, SQL Type: VARCHAR.

Add .. Field: quantity, Field Type: java.lang.Integer, Database Column: QUANTITY, SQL Type: INTEGER.

Add .. Field: price, Field Type: java.lang.Float, Database Column: PRICE, SQL Type: DECIMAL.

After adding all these fields, press Finish.

This will create a package named au.com.tusc.cmp under src, and ItemBean will be be created within that package as shown below.

Note: In comparison with our earlier BMP Entity Beans (Customer & Manager), more tags have been generated at class level. Note also that CMP doesn't require a Data Access Object (DAO) interface, as communication between database and bean is controlled by the container.

Let's first the generate EJB classes and then we will examine these tags.

Go to node ItemBean under au.com.tusc.cmp > LombozJ2EE > Add EJB to Module > Select MyStoreMgr > Ok.

Go to MyStoreMgr node > LombozJ2EE > Generate EJB classes.

Note: All these steps are covered in previous chapters (chapters 3 and 1) in detail, so please refer to these if you have any queries.

Now, let's see what files have been generated by Xdoclet.

As shown below, the files generated are nearly the same as for BMP, except there are no Primary Key or DAO classes, and there is now ItemCMP which extends the ItemBean class. The remainder are the same as for BMP entity beans.

Now, let's examine these new tags, some of which have been covered in previous chapters.

  1. @ejb.bean tag provides information about the EJB. It is the one compulsory tag for all EJBs.

  2. @ejb.persistence tag is being used at two levels, at class level and method level. At class level it provides information about the persistence of a CMP entity bean, that is which database table this bean is going to interact with, which will provide that persistence. At method level it provides information about the mapping of the bean's persistent attributes to columns in that database table.

  3. @ejb.finder tag defines a finder method for the home interface. This requires the EJB QL query to fetch the data and a signature for the method. This tag can be used for multiple finder methods.

  4. @ejb.persistence-field method level tag is being deprecated in favour of @ejb.persistence tag, it provided information about persistent fields.

  5. @ejb.pk-field tag defines the primary key.

The code snippet below shows how persistent attributes are declared in a CMP Entity Bean.

Note: All persistent attributes are declared with abstract accessor and mutator methods in ItemBean. Note also that in the case of a composite primary key you have to specify the @ejb.pk-field tag on all other attributes/properties which combine to form the overall key as well.

Implement ejbCreate Method :

The ejbCreate method is created by method is created by the Lomboz Bean wizard, but we still have to add some code to complete it. Modify the signature of ejbCreate, passing all the attributes as parameters and then setting all these attributes using their associated mutator methods, as shown below.

Errata note :- There is an error in the figure shown below. The Integer attribute 'qunatity' should be called 'quantity'.

Note : The other interesting aspect of ejbCreate here is its return type, as its return type has to be same as the primary key type (e.g. it has to of type String, Integer, Float, or whatever). In this case it is String - the type of itemID, and when implemented it should return null.(Refer to the EJB Spec 10.5.1).

Add Finder Method :

Note: An entity bean's home interface defines one or more finder methods, to find an entity object or collection of entity objects. The name of each finder method starts with the prefix 'find', such as findPrice or findQuantity in our case. Every finder method except findByPrimaryKey(key) must be associated with a query element in the deployment descriptor. The entity bean provider declares the EJB QL finder query and associates it with the finder method in the deployment descriptor. A finder method is normally characterized by an EJB QL query string specified via the query element. Refer to the EJB Spec 10.5.6. This is covered in the Exercise section of this chapter.

Now let's add a finder method to our bean class to find items supplied by a particular supplier.

In order to add this finder method we have to declare a class level tag as discussed above, that is @ejb.finder.

So, add this tag:

@ejb.finder
query="SELECT OBJECT(a) FROM MyStoreItem a where a.supplierID = ?1"
signature="java.util.Collection findBySupplierID(java.lang.String supplierID)"

Note : In EJB QL, instead of the name of the table, the schema name is used (in this case it is MyStoreItem, rather then specifying Item as you would for an SQL query). Similarly the column names that would be used in SQL are replaced by their corresponding attributes as declared in the bean.

Generate your EJB classes to see what this tag and the previous finder tag have created in the Home Interface as shown below in this code snippet from the ItemLocalHome interface.

It has four methods, including the two finder methods generated by the finder tags declared at class level. The other two, create and findByPrimaryKey are created by Xdoclet(because of the <entitycmp/> tag in ejbGenerate.xml).

Add another finder method to find out-of-stock items in MyStore.

Add the following tag.

@ejb.finder
query="SELECT OBJECT(c) FROM MyStoreItem c where c.quantity = 0"
signature="java.util.Collection findByOutOfStock()"

Code snippet from ItemLocalHome after generating EJB classes for these finder methods.

Now, generate your EJB classes and analyze the relevant classes. All the finder methods are complete. Let's add some business methods now.

Add Business Methods :

Now, add a business method with this signature:

public ItemData getItemData()

.. with Interface type as local.

Note : The steps to add a business method are covered in previous chapters (1 and 3), so please refer to them. Also we have chosen the Interface type as local because these methods will be invoked within the same Java Virtual Machine.

This will provide description of individual items in MyStore. Add some debug statements and return an instance of ItemData as shown below in this code snippet from the Item bean.

Add another business method with the following signature:

public void fillStock (Integer quantity)

.. with Interface type as local. This will increment the items available to MyStore after the delivery of further items. Add some debug statements and following lines to complete the method.

Integer qty   = new Integer(  (quantity.intValue() + getQuantity().intValue()) ) ;
setQuantity ( qty );

Code snippet of fillStock in ItemBean shown below.

Add Callback Method

Unlike BMP (where they were generated) we have to add callback methods which will be overridden in the ItemCMP class.

First import the following package: javax.ejb.EntityContext

Add a field to store the entity context.

protected EntityContext eContext;

Add a method setEntityContext with entityContext as its parameter and assign that to your entityContext variable.

Similarly add a method unsetEntityContext, which sets the entityContext variable to null.

Code snippet for both methods is shown below.

Now all business and finder methods are complete, so it's time to generate EJB classes.

Let's examine the generated ItemCMP class, which is of most interest .

Unlike our BMP bean all persistent attribute behavior is being overridden by abstract methods. This is because the EJB container is responsible for maintaining their persistence.

All the callback methods we have implemented are being overridden as shown below.

Note : There are no ejbFinder methods in this class as with BMP beans, as all this is controlled by the container. Also as pointed out before, there is no PrimaryKey class generated and there is no need for a DAO class, as this too is controlled by the container.

Now, before we deploy our bean, we will just have a look at ejb-jar.xml and jboss.xml to see what descriptors are generated.

Note : We don't have to write any descriptors for the data sources as we did with Session and BMP beans, as the EJB container is responsible for that.

As shown in the code snippet above from the ejb-jar.xml file, all abstract methods are generated as persistent fields under the tag <cmp-field> because of the tag @persistence-field declared at each accessor method. Also the primary key class descriptor is generated under the <primary-key-class> tag and the primary key field is generated under the <primarykey-field> because of the tag @field-pk declared for the relevant attribute(s).

Descriptors for finder methods are generated along with the query defined to fetch the data as shown below. These finder tags are generated by the @ejb.finder tag declared at class level.

And in the jboss.xml file, the following descriptors are generated due to the tag @ejb.bean declared at class level, as shown below.

Note : @ejb.bean tag has been covered in previous chapters.

Item Bean functionality is complete in and ready for deployment.

Deploy Item Bean :

Go to Lomboz J2EE View > expand node MyStore > expand MyStoreMgr > select Jboss 3.2.1 ALL.

Right click > select Debug Sever on the pop up menu.

Note : This is to start your server, if you are already running your server then skip these steps and go to the next one.

Go to MyStoreMgr node in LombozJ2EE view > right click > select Deploy on the pop up menu as shown below.

Note : All these steps have been detailed in previous chapters (1 and 3), so, please refer to them.

Messages in the console will indicate whether deployment of your bean has been successful or not.

Now, lets modify StoreAccessBean to invoke methods on ItemBean.

Add a field to store our Item reference (obtained from JNDI lookup).

private ItemLocalHome itemLocalHome;

In the ejbCreate method store this reference in the itemLocalHome variable by invoking the getLocalHome static method in the ItemUtil class as shown in this code snippet below from StoreAccess Bean.

Add a Business Method to StoreAccess :

Add another business method to the StoreAccess Bean which will invoke this business method on our Item Bean.

Now, add a business method with this signature:

public ItemData getItemData(String itemID)

.. with Interface type as Remote. As managers will log on to MyStore with username, once authenticated they will be identified by their userid. They can then retrieve their account details from MyStore using that userid. A Manager can invoke methods on the Item Bean to examine the inventory of MyStore.

Note : Steps to create business methods are covered in previous chapters.

Now invoke one of Item's finder methods via the reference variable we have created in the ejbCreate method.

ItemLocal item  =   itemLocalHome.findByPrimaryKey(itemID)

Now invoke the business method of Customer on this reference.

ItemData myItem = item.getItemData()

Code snippet for this business method is shown below.

Add another business method to StoreAccess Bean.

Add a business method with this signature:

public java.util.ArrayList getOutOfStockItems()

.. with Interface type as Remote. This will return the items which are out of stock in MyStore.

Create two variables of type Collection and ArrayList respectively, as the finder method for Items returns a Collection and this method will return an ArrayList, after populating items which are out of stock from the returned Collection.

Collection items = null;
ArrayListItemsOutOfStock = null;

Now invoke one of the finder methods of Item on the reference variable we have created in the ejbCreate method.

items = itemLocalHome.findByOutOfStock()

Now iterate through the collection of out of stock items and add to the ArrayList.

ItemLocal myItemLocal  = (ItemLocal) iterate.next();
itemsOutOfStock.add(myItemLocal.getItemData());

Code snippet for this business method is shown below.

Add another business method to StoreAccess Bean.

Add a business method with this signature:

public java.util.ArrayList getItemBySupplier(String supplierID)

.. with Interface type as Remote. This will return the items which are provided to MyStore by a given supplier.

Create two variables of type Collection and ArrayList respectively as the finder method for Items returns a Collection and this method will return ArrayList, after populating items which are supplied by a particular supplier from the returned Collection.

Collection suppliedItems = null;
ArrayList itemsBySupplier = null;

Now invoke one of the finder methods of Item on the reference variable we have created in the ejbCreate method.

suppliedItems = itemLocalHome.findBySupplierID(supplierID)

Now iterate through the collection of items for this supplier and add to the ArrayList.

ItemLocal myItemsLocal  = (ItemLocal) iterate.next();
itemsBySupplier.add(myItemsLocal.getItemData());
Code snippet for this business method is shown below.

Now all the methods in StoreAccess Bean for accessing Item's business methods have been added. The only remaining bit is the deployment descriptors required for linking/referencing of StoreAccess and Item Bean. So we will the add two tags shown below.

First add the tag shown below at class level in StoreAccess Bean.

@ejb.ejb-ref ejb-name="Item"
view-type="local"
ref-name="ItemLocal"

This tag will generate deployment descriptors in 'ejb-jar.xml', as StoreAccessBean has to know which bean it is referring to, what is its view-type and ref-name. This will generate these descriptors as shown below.

Note : View type is local as both are in the same Java Virtual Machine, otherwise it would be Remote. Secondly ref-name is generated as ItemLocalHome, as we are using that rather than ItemHome (which was also generated, but is used in the Remote case).

Now add a second tag (shown below) at class level in StoreAccess Bean.

@jboss.ejb-ref-jndi ref-name="ItemLocal"
jndi-name="ItemLocal"

This tag will generate deployment descriptors in 'jboss.xml', as the application server has to know what jndi-name the Item bean has been registered with. This will generate these descriptors as shown below.

Note : Ref-name and jndi-name are used for bean as local (in same JVM).

Note : We can see in the code snippet above the deployment descriptors generated by tag @jboss. For the view type 'local' it generates incorrect deployment descriptors, as discussed in the previous chapter. So every time we use this tag we have to change the <ejb-ref> to <ejb-local-ref> before deployment. Caution here, that you do this change manually when you finally finish regenerating your EJB classes, because every time you regenerate your classes, 'jboss.xml' will be overwritten.

Now our Item Bean is complete after these changes, so deploy your bean again now, from the Lomboz J2EE View, as per the steps shown above and in previous chapters. Messages will appear in the console showing the status of deployment.

Once the bean is deployed successfully, create a test client which will invoke the loginUser method on StoreAccess Bean , getCustomerData on Customer Bean, getManagerData on Manager Bean and getOutOfStockItems on Item Beam.

Create your Test Client :

Go to Project MytStore node > select src node and expand it > select au.com.tusc.client package > right click.

Select New on the pop up menu > select Lomboz EJB Test Client Wizard.

Select package name au.com.tusc.client, name as SessionCMPClient and select Ejb Home as au.com.tusc.session.StoreAccessHome and Ejb Interface as au.com.tusc.session.StoreAccess.

This will generate required methods for you in your SessionCMPClient class and you only have to invoke loginUser, getCustomerData, getManagerData (Manager Bean was developed as part of an exercise in the previous chapter) and getOutOfStockItems as shown below.

Now, the last step is to write the code for your client.

In order to access out of stock items we need an Iterator and an ArrayList for items. So, declare two variables of these respective types, and import the packages for these types (which are java.util.ArrayList and java.util.Iterator).

Iterator itemsIterator = null;
ArrayList items = null;

And now add these lines of code to invoke the methods mentioned above.

System.out.println("Request from client : ");
String userID = myBean.loginUser("ANDY","PASSWD");
System.out.println("Reply from Server: Your userid is " + userID );
CustomerData cd = myBean.getCustomerData(userID);
System.out.println ("Andy your details with MyStore are " + cd );
String mgrID =   myBean.loginUser("RUSTY","PASSWD");
System.out.println("Reply from Server: Your mgrid is " + mgrID );
ManagerData md = myBean.getManagerData(mgrID);
System.out.println ("Rusty your details with MyStore are  " + md );
System.out.println("Manager Request : List items out of stock ");

items = myBean.getOutOfStockItems();
itemsIterator = items.iterator();
System.out.println("List Of Out Of stock Items ");

while ( itemsIterator.hasNext() ) {
   ItemData itemData= ( ItemData ) itemsIterator.next();
   System.out.println ("Item Data " + itemData );
}

Test your Client :

Now, in order to test your client, Select SessionCMPClient node > Go at top level menu and select the icon with the 'Running Man'.

On that select 'Run as' > select Java Application, as shown below.

Now on your console, if you get a reply saying two items out of stock which are 'CALCULATOR' and 'CLOCK', then your call is successful as shown below.

Exercise :

Now, here is an exercise for you. In order to proceed further, implement Supplier as a CMP Entity Bean. The tasks are given below:

  1. Create a CMP Bean named Supplier under package au.com.tusc.cmp.

  2. Implement the ejbCreate method, with all attributes passed as arguments and then assigned to attributes using mutator methods.

  3. Add a find method named findUserID with query and signature:

    query "SELECT OBJECT(b) FROM MyStoreSupplier as b where b.userID = ?1"

    method au.com.tusc.cmp.SupplierLocal findUserID(java.lang.String userID)

    Note : The method signature is find<cmp attribute> instead of findByPrimaryKey, because finder methods for non-key CMP attributes use this convention. Accordingly the return type for finder methods will be either Collection or <entity type>, as specified in the EJB specification, sections 10.5.6 and 10.5.2 respectively.

  4. Add a business method to get supplier details with signature:

    public SupplierData getSupplierData()

  5. Add a business method to get request items from various suppliers with signature:

    public void requestItem(String itemID, Integer quantity)

  6. Add callback methods, required for setting/unsetting bean context with signatures:

    public void setEntityContext(EntityContext ctx)

    public void unsetEntityContext()

  7. Deploy the Supplier Bean.

  8. Add a field to StoreAcess Bean to store its reference:

    private SupplierLocalHome supplierLocalHome

  9. In the ejbCreate method of StoreAccess Bean store a reference in supplierLocalHome variable by invoking the getLocalHome static method in supplierUtil.

  12. Add a business method to StoreAccess Bean with signature:

    public ItemData getItemData(String itemID)

  13. Add the following tags for deployment at class level for linking/referencing Supplier.

    1. @ejb.ejb-ref ejb-name="Supplier"
    view-type="local"
    ref-name="SupplierLocal"

2. @jboss.ejb-ref-jndi ref-name="SupplierLocal"
    jndi-name="SupplierLocal"

  14. Test your Supplier Bean by running your Test Client created for Item named SessionCMPClient.

Note : All these steps are same as were done for Item. Implement this Bean which will be used in subsequent chapters.

In case you have difficulty, we have provided a SupplierBean class, modified StoreAccessBean class and SesiomCMPClient class. You can download these files under downloads below.

Downloads :

SupplierBean

StoreAccessBean

SessionCMPClient


Chapter7 - Creating a Message Driven Bean

Netcool Training

Chapter 7.

Creating a Message Driven Bean

This chapter covers how to create a Message Driven Bean (MDB) EJB component. We will create two MDB beans, DeliverItems and RequestItems as shown below. The DeliverItems bean will replenish the stocks of various items within MyStore, and the RequestItems bean will send requests to various suppliers to deliver items which are out of stock. The MyStore manager will issue/send this request.

Note : Both message-driven beans access the StoreAccess bean through its remote interface, even though the StoreAcessBean is in the same JVM. This is because we have implemented StoreAccessBean as a Remote Bean, so it only exposes its remote interface. However, in accessing the Manager and Item beans, which are also used by these message-driven beans we can use their local interfaces as they are in the same JVM, and we have exposed their local interfaces.

Tasks :

  1. Create a MD bean named RequestItems under package au.com.tusc.mdb.

  2. Create an Immutable Value Object named RequestItem under package au.com.tusc.mdb. Add attributes and implement their accessor and mutator methods. The attributes are:

    private String username

    private String passwd

    private String itemID

    private int quantity

  3. Implement the onMessage method.

  4. Deploy the RequestItems Bean.

  5. Create your test client named RequestMDBClient under package au.com.tusc.mdb.

  6. Add a method named testMDBBean with the following signature and implement it.

    public void testMDBBean

  7. Run your client and test the bean.

Create RequestItems MDB Bean :

Go To Package Explorer > Expand Mystore (project) node > select src, right click and a menu will pop up.

On the pop up menu > New > Lomboz EJB Creation Wizard.

Enter package name au.com.tusc.mdb, bean name RequestItems and select bean type as Message Drive Bean (Queue) as shown below.

Press Finish.

This will create a package named au.com.tusc.mdb under src and RequestItemsBean within that package as shown below.

Note : Message-driven beans listen for messages from a JMS Producer, which gets information from a producer (perhaps another bean) and transfers it to the relevant Consumer bean. Since it is only responsible for processing such messages, it doesn't need any helper classes such as Remote and RemoteHome interfaces, Util classes, DAO class, etc. like our previous types of beans. The only helper classes we have to create are immutable value objects, which will be responsible for holding the information extracted from messages and then transferred to the bean(s).

Let's examine what methods and tags are generated by the EJB creation wizard..

It creates one @ejb.bean tag which assigns the name, transaction type, destination type and some other properties as shown below.

Unlike our previous beans it has a setMessageContext method for setting the context.

It has ejbCreate and ejbRemove methods like the other types of beans, as shown below.

It has a new method named onMessage which is the one of significance to us, where all the business logic will be written (as shown below).

Once a message is received from the JMS producer as a Message object, its data is extracted and filled into the immutable value object and then transferred to the relevant bean. This is covered later on in this chapter.

Now, before we add any functionality, create a class or immutable value object for extracting information from the message.

Create Immutable Value Object RequestItem :

Go to src > under package au.com.tusc.mdb > New >Class.

The java class wizard will pop up > Add class name as RequestItem, Superclass as java.lang.Object and Interfaces as Serializable as as shown below in figure.

This will generate a RequestItem class under au.com.tusc.mdb as shown below.

Add the following attributes to the RequestItem class as shown below.

private String username;
private String passwd;
private String itemID;
private int quantity;

Add accessor and mutator method for these attributes.

Select all attributes > Right click> Select source > Generate Getter and Setter as shown below.

Add a constructor for the class which has parameters with the same type as the attributes and assigns them to the attributes as shown below.

The RequestItem constructor is complete. Now to implement the onMessage method in the RequestItem Bean.

Implement onMessage Method :

This method is responsible for extracting the information from the message and transferring it to the relevant bean.

The MyStore Manager will check for items which are out of stock and generate a request to suppliers specifying the itemID and quantity required.

First import the packages java.util.ArrayList and java.util.Iterator .

Add the following variables to store references.

ArrayList outOfStockItems = null;
Iterator itemsIterator = null;
private StoreAccessHome storeAccess = null;
private SupplierLocalHome suppLocalHome = null;
private ItemLocalHome itemLocalHome = null;

Extract the data from the message into the immutable value object as shown below.

RequestItem ri =  (RequestItem) ((ObjectMessage) message).getObject();

Add the lines of code shown below, so that the manager can login.

StoreAccess access = StoreAccessUtil.getHome().create();
String mgrAccessID = access.loginUser(ri.getUsername(),ri.getPasswd());

Get items with zero quantity (no stock), by invoking getOutOfStockItems() on the StoreAccess Bean (which returns a Collection).

outOfStockItems = access.getOutOfStockItems();

Now, iterating over each item, get the supplierId associated with it by invoking the finder methods on the Supplier Bean, finally sending the required message to that supplier by invoking the business method requestItem() on the Supplier Bean.

itemsIterator = outOfStockItems.iterator();

while ( itemsIterator.hasNext() ) {
    ItemData itemData= ( ItemData ) itemsIterator.next();
    String suppID = itemData.getSupplierID();
    SupplierLocal supplier = this.suppLocalHome.findByPrimaryKey(suppID);
    Integer quantity = new Integer (ri.getQuantity());
    String itemID = ri.getItemID();
    supplier.requestItem( itemID, quantity);
}

Code snippet of onMessage is shown below.

Now our bean is complete, and all that remains are the deployment descriptors for the bean.

Deploy RequestItems Bean :

In order to deploy this bean we have to add fa ew deployment descriptors. As shown below, five tags have been added.

First add the tag shown below at class level in the RequestItems Bean, to obtain a reference to StoreAccessBean, so that methods can be invoked on that bean.

@ejb.ejb-ref
ejb-name="StoreAccess"
view-type="remote"
ref-name="StoreAccess"

This tag will generate deployment descriptors in ejb-jar.xml when you generate your ejb classes, as this message bean has to authenticate, before transferring information to the relevant bean. This will generate these descriptors as shown below.

Add another tag as shown below, to obtain a reference to the Supplier Bean from this bean.

@ejb.ejb-ref
ejb-name="Supplier"
view-type="local"
ref-name="SupplierLocal"

This tag will generate also generate descriptors in ejb-jar.xml when you generate your ejb classes, as this message bean transfers information to the Supplier bean. The following descriptors are generated as shown below.

Note : Another descriptor which has been generated is <ejb-name>, which is generated by the tag @ejb.bean that was added by the EJB creation wizard.

This tag generates the following descriptors in ejb-jar.xml:

Add another tag as shown below. This tag is JBOSS-specific, and is used to register a message-driven bean with a jndi-name, using the format "queue/name".

@jboss.destination-jndi-name                                                                                                                     name="queue/MdbQueue"

This will generate the following deployment descriptors in jboss.xml:

Note : For further documentation on MDB development with JBOSS, please refer to the JBOSS documentation.

Add another tag as shown below, required by JBOSS, for finding the Supplier bean using its JNDI NAME.

@jboss.ejb-ref-jndi ref-name="SupplierLocal"
 jndi-name="SupplierLocal"

Note : As discussed in chapter5, this tag generates incorrect descriptors within jboss.xml. For view-type="local" it generates an <ejb-ref> tag rather than an <ejb-local-ref> tag.

Correct the following tags:

Find these tags in jboss.xml and change them to <ejb-local-ref> as shown below.

Now add this last tag as shown below for our StoreAccess Bean, to reference the StoreAccess bean using its JNDI NAME .

@jboss.ejb-ref-jndi ref-name="StoreAccess"
jndi-name="StoreAccessBean"

This tag will generate the following descriptors in jboss.xml:

Now our RequestItems Bean is complete, so now add your bean and generate your EJB classes.

Go to the RequestItemsBean node under au.com.tusc.mdb > right click > select Lomboz J2EE... > Add EJB to Module > Ok.

Go to the MyStoreMgr node in Package Explorer > right click > select Lomboz J2EE... > Generate EJB classes.

Note : Since you have generated your classes you have to again fix the incorrectly-generated deployment descriptors in jboss.xml, under <message-driven> and <session>.

Now, let's deploy our bean. Go to Lomboz J2EE View, start your server if it is not running, and deploy your bean.

Messages will appear in console showing deployment status.

Note : Steps for deploying beans have been detailed in previous chapters.

Once the bean is deployed successfully, create your test client.

Create Test Client :

Now, to create a test client in this case, the Test Client Wizard can't help us, because it requires a Home interface and EJB interface to be selected, whereas for Message Driven Beans there is no Home interface and EJB interface required (as discussed above).

So, write a class and the necessary methods to invoke operations on the RequestItems Bean.

Add a class named RequestMDBClient under the package au.com.tusc.mdb.

Add a method named getContext with the following signature:

private InitialContext getContext() throws NamingException

Add the following lines of code to get the instance of IntialContext as shown below.

Add a method named testMDBBean with the following signature.

public void testMDBBean()

Now implement this method, in which the following steps are needed:

  1. Add a Data Object which is to be sent as the message.

  2. Create the Initial context reference.

  3. Create the Connection factory reference.

  4. Use this context to perform the lookup, where the lookup string is "queue/MdbQueue".

  5. Create the QueueConnection.

  6. Create the QueueSender.

  7. Create the QueueSession for the bean.

  8. Create the Object Message and pass the Data Object in message.

  9. Send the message.

  10. Finally, commit the session, and then close both the session and the connection. A code snippet of the testMDBean method is shown below.

Now your test client is complete, so let's test the client.

Test your Client :

To test your client, Select RequestMDBClient node > Go to the top level menu and select the 'Running Man' icon.

On that select 'Run as' > select Java Application.

Note : The steps to run test clients have been detailed in previous chapters.

Now, under your console, you should get the following messages:

This message on the console doesn't tell us whether the message has been delivered to relevant beans or not. In order to verify that, go to the database using JMX Management Console View > Hypersonic > Invoke Database Manager and then run a query on table 'supplier' to see if a message has been added for the supplier.

Note: Details on accessing this Database Manager are provided in chapter 1.

Since a supplier named Sebastian has received our message, our message has been transferred successfully.

Exercise :

Now, to progress further, please complete the following exercise. Implement DeliverItems as an MD bean. Detailed tasks are given below.

  1. Create an MD Bean named DeliverItems under the package au.com.tusc.mdb.

  2. Create an Immutable Value Object named DeliverItem under the package au.com.tusc.mdb. Add some attributes and implement their accessor and mutator methods. The attributes are:

    private String username

    private String passwd

    private String itemID

    private int quantity

  3. Implement the onMessage method in your DeliverItems Bean.

    Add these two variables to store references.

    private StoreAccessHome storeAccess = null;
private ItemLocalHome itemLocalHome = null;

    Extract the data from the message into your immutable value object as shown below.

    DelieverItem di =  (DeliverItem) ((ObjectMessage) message).getObject();

    Get the references for the StoreAccess and Item beans.

    StoreAccess access = StoreAccessUtil.getHome().create();
itemLocalHome = ItemUtil.getLocalHome();

    Invoke the loginUser method for supplier to get the Supplier's userid(accessID) and then find the Supplier's ID by invoking the getSupplierData method.

    String suppAcessID = access.loginUser(di.getUsername(), di.getPasswd());
SupplierData sd = access.getSupplierData(suppAccessID);
String suppID = sd.getSupplierID();

    If suppID is not equal to null, then invoke the finder method on the Item bean to get the details of the item to be delivered, by extracting itemID from message.

    ItemLocal item = this.itemLocalHome.findByPrimaryKey(di.getItemID());

    Get the supplier ID associated with the item found, so we can fill up the stock.

    String itemSuppID = item.getSupplierID();

    Compare itemSuppID and ItemID, if these are the same then fill the stock for that item by invoking the fillStock method in Item bean.

    if ( suppID.equals(itemSuppID)) {
    System.out.println ("Delivering items in store now... :");
    Integer quantity = new Integer (di.getQuantity());
    item.fillStock(quantity);
    System.out.println ("Stock of iten after dleivery is :" + item.getItemData());
}

  4. Add the following tags for deployment at the class level for linking/referencing Supplier.

    1. @ejb.ejb-ref
    ejb-name="StoreAccess"
    view-type="remote"
    ref-name="StoreAccess"

2. @ejb.ejb-ref
    ejb-name="Item"
    view-type="local"
    ref-name="ItemLocal"

3. @jboss.ejb-ref-jndi ref-name="ItemLocal"
    jndi-name="ItemLocal"

4. @jboss.ejb-ref-jndi ref-name="StoreAccess"
    jndi-name="StoreAccessBean"

 5. @jboss.destination-jndi-name
     name="queue/DelMdbQueue"

  5. Deploy your DeliverItems Bean.

  6. Create a test client named DeliverMDBClient under the package au.com.tusc.mdb.

  7. Add a method named testMDBBean with the following signature.

    public void testMDBBean

  8. Implement testMDBBean, for this a few steps have to be carried out.

    Add a Data Object which is to be sent as the message.

    Create Initial context.

    Create Connection factory.

    Using this context perform the JNDI lookup, where the lookup string is "queue/DelMdbQueue".

    Create QueueConnection.

    Create QueueSender.

    Create QueueSession for the bean.

    Create Object Message and pass the Data Object in the message.

    Send the message.

    Finally, commit the session and close both the session and the connection.

  5. Run your client and test the bean.

Note : All these steps are same as for the RequestItems Bean. This bean will be used in subsequent chapters.

In the event you run into some difficulty, we have provided the DeliverItemsBean, DeliverItem and DeliverMDBClient classes. You can download these files under downloads.

Downloads :

DeliverItemsBean

DeliverItem

DeliverMDBClient


Chapter8 - Creating Web Clients

Netcool Training

Chapter 8.

Creating Web Clients

This chapter describes how to create web clients in the Client Tier/Presentation Tier to access or otherwise communicate with the Business Tier. Servlets and JSP pages are the two examples of web clients which will be created. In a typical Model View Controller Pattern, the Servlet acts as the Controller whilst JSP pages act as the View (the Model being the data, of course).

Tasks :

  1. Create a Servlet named AccessController under the package au.com.tusc.servlet.

  2. Add a business method to StoreAccess Bean named getAllItems() with the following signature

    public java.util.ArrayList getAllItems()

  3. Implement the init method.

  4. Implement doGet and doPost methods.

  5. Add a method processRequest with the following signature

    protected void processRequest (HttpServletRequest request,HttpServletResponseresponse)

    throwsServletException, IOException

  6. Implement the processRequest method.

  7. Deploy the AccessController Servlet.

  8. Test the AccessContoller Servlet.

  9. Create a JSP Page named showItems.

  10. Modify the method processRequest in Servlet AccessController.

  11. Add HTML and JSP tags to display a list of all items in MyStore.

  12. Deploy the module OnlineStore.

  13. Test the showItems.jsp page.

Create AccessController Servlet :

Go To Package Explorer > Expand Mystore (project) node > select src, right click and a menu will pop up.

On the pop up menu > New > Lomboz Servlet Wizard as shown below.

Enter the package name au.com.tusc.servlet, with servlet name AccessController and select four methods to be implemented in the servlet as shown.

Press Next. A new screen will appear as shown below. Add Web Module (Browse.. web module and it will show list of web modules in this project), in this case it is OnlineStore, so select that. Enter the Servlet name as access, and Mapping URL as ' /access/* '.

Press Finish.

This will create a package named au.com.tusc.servlet under src and AccessController within that package as shown below.

As can be seen from the figure above the four methods we selected in the wizard are created, and only their implementation is required.

Apart from this, some descriptors are generated in web.xml, under Web-Module OnlineStore/WEB-INF as shown below:

These tags are generated by the Servlet Creation Wizard, where <url-pattern> tag specifies the path name by which the servlet will to be accessed. In this case it will be http://localhost:8080/OnlineStore/access. (N.B. - It's not necessary to have the same <servlet-name> and <url-pattern>.)

Web.xml contains all the deployment descriptors required for deployment of servlets.

Lomboz creates two pages when you create your web module, index.jsp and error.jsp.

Before we go further and start getting our hands dirty with servlets, let's have a look at what directories and files are generated by Lomboz under Web Modules, in this case OnlineStore, as shown below.

Files of interest include web.xml, where all the deployment descriptors will be placed (as discussed above), and targets.xml, which contains information about the server in which it will be deployed (in this case JBOSS). See the code snippet below from targets.xml.

Add Business Method :

Before we start implementing our servlet, add one more business method to StoreAccess Bean called getAllItems() with the following signature:

public java.util.ArrayList getAllItems()

This method will return all the items in MyStore by invoking the finder method in ItemsLocalHome named findAll, as shown below (code snippet from StoreAccess bean):

Now let's start implementing the generated methods in the servlet.

Implement init method :

This method is responsible for initializing servlets, so it is invoked when the servlet is first created and is not called again for each user request.

We will cache the references for our StoreAccess Bean in this method, as all the client interfaces available are exposed in StoreAccess.

So, first create a context. Then get a reference to a StoreAccess object by looking up the StoreAccess bean via the JNDI API.

Add a variable storeAccessHome of type StoreAccessHome to store the reference obtained by narrowing the object.

Create helper methods for getting Context, Home and assigning the reference to storeAccessHome as shown below.

Note : We have to narrow this object because we are accessing a remote interface. If it was a local interface, we wouldn't need to narrow the object.

Implement methods doGet and doPost :

In order to implement these two methods we will create a helper method to provide the functionality for both of them. The request is delegated to this method where all processing of information takes place. Once this business logic processing is complete it dispatches the request to the appropriate view for display, ie. JSP pages.

Note : This approach is based on the Front Controller pattern, where the controller acts as a central point of contact for handling requests, delegating business processing, and coordinating with dispatcher components, whilst dispatchers are responsible for view management and navigation. This pattern suggests centralizing the handling of all requests in this way, but also allows for different handler methods to be used in processing different request types.

Add a method named procesRequest with the following signature:

protected void processRequest (HttpServletRequest request, HttpServletResponse response)
                                 throws ServletException, IOException

Delegate request from doGet and doPost method to this method as shown below.

Now implement the processRequest() method.

This method is structured such that it will check for the parameter useraction within the request object. If the useraction parameter is empty then it will build a url for the login screen and generate a login screen page. If useraction has some value then it examines it. If it finds the request is to display items then it builds the url for that and generates a page displaying all the items. Finally, for errors a page is generated to display the error.

Add following attributes shown below, for building different urls.

Create a session object and get value from useraction parameter of request object as shown below in code snippet.

If useraction is empty, as it will be initially, then build the url for the login screen, and generate the login screen by invoking the method displayLoginScreen. Code snippet for displayLoginScreen is shown below.

This method calls displayLoginDataFields to generate the data fields for form submission as shown below.

Once this form is submitted, it checks to see whether validation is successful by invoking the method loginUser, which invokes the loginUser method in the StoreAccess Bean as shown below.

Once that is finished, as shown above in the processRequest method code snippet, it builds url's for displaying items and error. Code snippet for the method displayAllItems is shown below.

Code snippet for displayLoginErrorScreen shown below.

All these helper method are being used by the processRequest method, which is acting as a Controller and dispatches the request to the appropriate view, such as the login screen or display items screen.

Now our servlet is complete, as implementation of the rest of the methods is left as an exercise.

Deploy AccessController Servlet :

In order to deploy your servlet, go to LombozJ2EE view.

Select web module OnlineStore > right click > select Deploy module as shown below , make sure the server is running.

Deployment status appears on the console as shown below. If deployment is successful then test your servlet.

Test your Servlet :

Go to your browser and access the servlet using following URL, 'http://localhost:8080/OnlineStore/access'

where 'access' is the url mapping that was assigned while creating the servlet using the Servlet Creation Wizard, and OnlineStore is the web module,where this servlet resides.

The login screen will be displayed. Enter username as 'ANDY' and password as 'PASSWD'. The next screen will be list of items in MyStore as shown below.

We have successfully created a servlet, now let's access this catalogue via a JSP page.

Create JSP Page :

Go To Package Explorer > Expand Web Module node (OnlineStore) > right click and a menu will pop up.

On the pop up menu > New > Select Lomboz JSP Wizard as shown below.

Add file name showItems.jsp as shown below.

Press Next > Menu, the form Set JSP details will appear > Select Add.. under Beans section as shown below.

The menu for Select Beans will appear > Add ID as itemData, Scope as session and Class as ItemData.

Press Ok. Now selected JSP details can be seen after selecting various options as shown below.

Press Finish. A new file named showItems.jsp will be created under the web module OnlineStore as shown below.

Modify Method processRequest in Servlet AccessController :

Now, in order to display all items of MyStore from a JSP page, we have to modify the proccessRequest method in servlet AccessController.

Modify String ITEMS_SCREEN to "/showItems.jsp" as shown below.

Comment out the call to method displayAllItems in processRequest.

Add a Session attribute named itemsList with values of listItems.

Add a Request Dispatcher and pass buildUrl as an argument, which has the url for the showItems.jsp page.

Forward to that request dispatcher to draw the JSP page.

Code snippet of the modified processRequest method is shown below.

Add Html and JSP Tags :

First import the following packages: au.com.tusc.cmp.*, java.util.ArrayList and java.util.Iterator.

Now add the necessary HTML and JSP tags to access items of MyStore.

Get itemsList from our session attribute set in servlet AccessController.

Set itemData as a page attribute via pageContext.

Now display the attributes of itemData using JSP property access tags. Code snippet for the showItems page is shown below.

Note : This JSP Page is a view in the Front Controller Pattern discussed above.

Now the JSP page is done.

Go to OnlineStore (web module) node > right click > select Lomboz J2EE.. on pop up menu > Check All JSP Syntax.

See if there are any errors.

Go to OnlineStore node > right click > select Lomboz J2EE.. on pop up menu > Add WEB-INF/lib JARs to the Classpath as shown below.

Deploy Module OnlineStore :

In order to deploy, go to LombozJ2EE view.

Select web module OnlineStore > right click > select Deploy module, make sure the server is running.

Deployment status will be visible on the console. If deployment is successful then test your JSP page.

Test your JSP Page :

Go to your browser and access the servlet using the following web address, 'http://localhost:8080/OnlineStore/access'

where 'access' is the url mapping that was assigned whilst creating the servlet in the Servlet Creation Wizard, and OnlineStore is the web module where the servlet AccessController resides.

The login screen will be displayed. Enter username as 'ANDY' and password as 'PASSWD'. The next screen will be the list of items in MyStore as shown below.

You have successfully created a JSP page using all the J2EE components, and they have been created and deployed successfully. Congratulations!


Exported Projects

 Exported Projects:

Tutorial for building J2EE Applications using JBOSS and ECLIPSE


TUSC -

TUSC Reliable, On-Time Delivery.
Search

News & Events

Welcome

TUSC is an independent software services company specialising in infrastructure management solutions for enterprises with mission-critical networks. We have achieved an outstanding reputation for the reliable, on-time delivery of projects we undertake.

Our service and solution offerings for business and operational support systems, network management, event correlation and VPN’s.
         Stylised photograph of a phone keypad
More information about Telcommunications Solutions

Our service and solution offerings for SCADA, workforce management and distribution management.
         Photograph of a gas ring
More information about Utilities Solutions
dotted line
Netcool Training Employment

Latest News

TUSC Acquires EMS
TUSC has acquired Enterprise Management Solutions Pty Ltd (EMS), one of Australia's leading HP OpenV...
More Info: TUSC Acquires EMS
New On-Line J2EE Tutorial
TUSC has launched an on-line J2EE tutorial, as a part of its added-value customer service, which exp...
More Info: New On-Line J2EE Tutorial
TUSC Improves Alarm Management & Service Assurance at Telstra
TUSC is working on three major projects for Telstra designed to improve alarm management and to deli...
More Info: TUSC Improves Alarm Management & Service Assurance at Telstra
Latest Events

TUSC's Netcool Training
OMNIbus 3.6 User (UNIX)
Melbourne
6 October, 2003
More Info: OMNIbus 3.6 User (UNIX)
TUSC's Netcool Training
OMNIbus 3.6 Admin & Configuration
Melbourne
7 October, 2003 to
10 October, 2003
More Info: OMNIbus 3.6 Admin & Configuration
Sign-up for our Newsletter

Your name:
Your email:
Copyright 2002 TUSC Pty. Ltd. Terms of Use & Privacy Statement. Site design by Reactive


TUSC - Feedback

TUSC Reliable, On-Time Delivery.
Search

News & Events

Your name:
Your email:
Comments:
Back to top

Graphic montage of a light bulb, swirl, phone keypad and gas ring

Sign-up for our Newsletter

Your name:
Your email:
Copyright 2002 TUSC Pty. Ltd. Terms of Use & Privacy Statement. Site design by Reactive


TUSC - Telco Solutions - Netcool

TUSC Reliable, On-Time Delivery.
Search

News & Events

Telco's Solutions Netcool Training

Arrow Overview
Arrow Course Registration
Arrow Course Schedule
Arrow Course Descriptions

Overview

TUSC is the only Certified Netcool Training Partner in the Asia Pacific region and the leading certified systems integration partner in Australia. TUSC’s team of qualified Netcool Certified Consultants and Netcool Certified trainers has extensive hands-on experience with the Netcool suite of products gained with some of the regions leading telecommunications companies.

TUSC operates training facilities in the Asia-Pacific region with prime sites established in Melbourne, Sydney, Auckland and Singapore. TUSC can also provide courses on customer premises on request.
Course Registration

For all courses listed as "open" in the availability listings, you can apply for the course online. Please note that this does not guarantee you a spot in the course. You may also apply for courses designated as "wait-listed". You will be notified by a TUSC representative regarding the status of your application.

Please note that TUSC requires full payment prior to course commencement. In the event that full payment has not been received prior to the start date of the course, we regret to inform you that you will not be allowed to attend the course as planned.

Should you fail to attend or provide less than 10 working days notice of a cancellation or postponement of your booking, we regret that no refund can be made. TUSC reserves the right to cancel a class and is not responsible for airline or hotel penalties incurred because of a cancelled class.

Course registration normally closes 21 days prior to course start dates.

Course Schedule

Melbourne

Netcool Impact Certified Consultant (NCCI)
22 September 2003 - 24 September 2003
Cost: US$1800.00
Prerequisite: Impact 2.4 & Pass for the NCCO Programme
Registration closes Monday 1 September, 2003
Closed
OMNIbus 3.6 User (UNIX)
6 October 2003 - 6 October 2003
US$600.00
Prerequisite: Students should understand UNIX to a user level and have a basic understanding of network management.
Registration closes 15 September, 2003
Open
Register
OMNIbus 3.6 Admin & Configuration
7 October 2003 - 10 October 2003
US$2400.00
Prerequisite: OMNIbus 3.5 User
Registration closes 16th September, 2003
Open
Register
Impact 2.3
13 October 2003 - 17 October 2003
US$3000.00
Prerequisite: OMNIbus 3.5 User/Admin & Configuration
Registration closes 22nd September, 2003
Open
Register
Webtop 1.2
22 October 2003 - 23 October 2003
US$1200.00
Pre-requisite: Students must have a system administrator level understanding of UNIX/Unix Editor and knowledge of Network Management.
Registration Closes: 15 October, 2003
Open
Register
Reporter 1.4 Installation
1 December 2003 - 1 December 2003
US$600.00
Prerequisite: OMNIbus 3.5 User/Admin & Configuration
Registration closes 10th November, 2003
Open
Register
Reporter 1.4 Designer & Admin
2 December 2003 - 3 December 2003
US$1200.00
Prerequisite: OMNIbus 3.5 User/Admin & Configuration
Registration closes 11th November, 2003
Open
Register
Netcool/OMNIbus Certified Consultant - NCCO
8 December 2003 - 9 December 2003
US$1200.00
Pre-requisite: Prior attendance on the Netcool/OMNIbus course is mandatory.
Completion of the online Netcool/OMNIbus Pretest, details of which are sent with Booking Acknowledgement
Registration closes: 10 November, 2003
Open
Register

Sydney

OMNIbus 3.6 User (UNIX)
10 November 2003 - 10 November 2003
US$600.00
Prerequisite: Students should understand UNIX to a user level and have a basic understanding of network management.
Registration closes 13th October, 2003
Open
Register
OMNIbus 3.6 Admin & Configuration
11 November 2003 - 14 November 2003
US$2400.00
Prerequisite: OMNIbus 3.5 User
Registration closes 14th October, 2003
Open
Register
Netcool/Precision 3.3
17 November 2003 - 21 November 2003
US$3000.00
Pre-requisite: Students must have a "system administrator" level of understanding of UNIX/Unix Editor including knowledge of network management.
Registrations close: 10 November, 2003
Open
Register
Course Descriptions
Click here to view detailed course descriptions

Back to top

Stylised photograph of a phone keypad

“I recently attended a Netcool training course conducted by TUSC and was very satisfied with the whole experience. The material presented was relevant, well organised and professionally delivered. I would recommend TUSC to anyone needing top quality Netcool training.”

Simon Burson, Network Engineer, Datacraft.

Telstra Case study

Sign-up for our Newsletter

Your name:
Your email:
Copyright 2002 TUSC Pty. Ltd. Terms of Use & Privacy Statement. Site design by Reactive