J2EE Componenent Wizard Tutorial

Before I start, here is an addendum right at the beginning. Days after this tutorial was posted version 1.2 of J2EE Componenent Wizard appeared. The problems talked about (ejb-ref and ejb-local-ref elements wrongly created) at the end of this tutorial do not exist in version 1.2. I would recommend downloading version 1.2 and using that. There are minor differences in the GUI, but mainly things are much the same.

This tutorial will show you how to use version 1.1 of J2EE Component Wizard to develop a J2EE application using an Entity Bean with Container Managed Persistence. The level is very basic. I have added some comments that may be useful to somebody just starting out with J2EE programming. Many of you will no doubt not need them.

The bean you are going to write will accesses a PostgreSQL database and is controlled by a Stateless Session Bean. The database has one table called user_tbl with three columns:

usr_name_pk
pwd
email

usr_name_pk is the primary key. You may want to get into the habit of ending all primary keys with _pk and all foreign keys with _fk. It helps when us humans have to read code. All three columns are text columns. Do NOT use user as a name in PostgreSQL.

You can find J2EE Component Wizard here. Personally I've found J2EEWizard one of the easiest (if not the easiest) J2EE Integrated Development Environment to use. The development approach is from the outside inward - you first create the project, then the archives, then generic contents for your archives. This "generic contents" are components like ejbs, servlets, jsps etc. They are generic because they are only templates or skeletons at this stage. The last step is to customize your content. One can also customize each component as one creates it before creating another component.

In this example a Java Server Page accesses a servlet which accesses a java bean which accesses the Stateless Session Bean via its remote interfaces. The Stateless Session Bean in turn accesses the Entity EJB via its local interfaces. Responses from the database make their way back to the java bean where they are "presented" in html code which is "read" by the JSP after a response.sendRedirect(the JSP) is called.

The J2EE application is in an archive called UserManager.jar and the web-application in an archive called UserManager.war. Both of them are in an archive called usermanager.ear

Global Settings

Click Project --> Global Settings. A Project Settings dialog box will appear. The fields are really self explanatory. Note that all your projects will be rooted in one directory. Each project will of course have its own directory under your projects root directory. Here is what my Project Settings dialog box looks like:

Every project will use these settings unless overridden with project specific settings. We'll come to that.

Creating your Project

After finishing your set-up, click File --> New which will bring up the following dialog box in which you specify the name of your new project:

Write in the name of your new project as indicated in the image and click the New Project button.

J2EE Wizard's GUI will now look like the following image. Note the directory folders under the project name on the left side.

Project Settings

If we want to change any of the global settings for this project, now is the time to do it. Highlight the Project Name at the top left corner and the global settings will appear as your project settings. Change what you want to change. You will see that I changed the server cofiguration from all to default and the datasource JNDI name from java:/DefaultDS to java:/usermanager.database.

Creating the skeleton

Archive Creation

The .ear archive that contains all other archives and the necessary xml descriptors specifying how these enclosed archives relate to the project as a whole. ear is an abbreviation for Enterprise ARchive.
The .jar archive that holds all enterprise java beans (EJBs), helper classes, data object classes, data access object classes and any other classes as well as .xml descriptor files specifying how some of the classes in this jar archive relate to the project (the application) and to each other and to the container or application server - JBoss in our case.
The .war archive which holds all the files that make up a web application. That includes JSPs, servlets, java beans (not ejbs), helper classes, image files, sound files and possibly other files as well as the xml descriptors specifying how the contents of this war file relates to the web server (Jetty or Tomcat inside JBoss) and to the project.

It is only necessary to create the war and jar archives. The ear archive will be created just before the application (project in our case) is deployed to JBoss.

To keep things conceptually neat we'll first create both the jar and war archives. Click Project --> New Archive --> EJB Archive.
The following dialog box will come up:

Fill in the fields as indicated. Your package prefix will depend on what you filled into the relevant window in the Project Settings dialog box. Note that I changed the package prefix to be in all lower case letters. Note the .jar at the end to indicate that all classes in this package are in the jar archive. This is a bit obsessive compulsive, but it keeps things neat and clear. Now click OK. You have created the empty shell of your jar archive.

Now let's create the shell of our war archive.
Click Project --> New Archive --> Web Archive.
The following dialog box will come up:

Much the same applies here as to the jar archive. You will see that a clear pattern of doing things is emerging.

Now we are finished with our archives. Let's add content to them.

Adding Components to our Archives

We will start with our jar archive.

Select the EJB Archives heading on the left near the top by clicking on it. Then click Project --> New EJB --> Entity Bean. The following dialog box will appear:

Note the UserManager.jar in the drop-down box. This is where we want this entity bean to reside. After filling in the Name field as indicated and clicking on the Display Name field, the contents of the Display Name and Class fields will change as indicated in the image above. Make sure that everything is as in the image above. Click OK. You have now created the template of a CMP EJB called UserEntityEJB.java So far it contains only generic code that is part of every CMP EJB. We will later use this template to create a unique EJB.

Let's create the session bean.

Select Project --> New EJB --> Session Bean. Fill in the resulting dialog so it looks like below:

Note the UserManager.jar in the drop down list which is the container that is going to contain both the Entity and Session Beans. Click OK.

You will now notice the UserSessionEJB on the left side in the J2EE Wizard GUI.

We are now finished adding components to the .jar archive. Let's start with the .war archive.

Highlight Web Archives on the left side and then select (from the menu bar)Project --> New Web Component --> Java Server Page. Fill in as indicated below:

Click OK.

Note the drop down list and make sure this JSP is created in the right archive, that is to say UserManager.war

Similarly, let us create an errorpage. This is what the relevant dialog looks like:

Now let's create the skeleton for the servlet.

Select Project --> New Web Component --> Servlet. Fill in as indicated below:

Make sure from the drop down list that you are adding all components to the right archive.

To create the bean is not quite so straightforward. It is best to do it by hand and add it to your directory tree. Here is the code for the bean. You can copy and paste it.

This is where it belongs in your directory tree:

You will not have the build directory at this stage (it will come) and you will have to create the bean directory by hand.

We have now created the skeletons of six components in two archives:

An entity bean
A session bean

A JSP
An error page
A servlet
A java bean

This is what your J2EE Wizard GUI should look like at this stage:

Fleshing it out

We now have the complete skeleton of our application. Let's flesh it out.

The Entity Bean

Select the UserEntityEJB on the left side of the GUI. We now have to build up our EJB stepwise. The entity bean has an intimate relationship with persistent fields in our database tables. Therefore, defining persistent fields in the entity bean is a good place to start. Select the CMP (Container Managed Persistence) Properties tab. This is where we define the persistent fields of our bean. Click on the Add button to define a persistence field and fill in these fields as indicated in the image below:

As this EJB is an uncomplicated EJB, we won't use most of the tabs. We have just created member variables, let's create methods. Select the Methods tab. Click the Add Value-Object Methods button. The J2EEWizard GUI will now look like this:

Do check the code of every method to make sure your persistent fields (usr_name_pk, pwd and email) are not referred to as attribute_name. If you find that remove the value object methods, go to the CMP tab and click and save every peristent field. Then re-generate the value object methods.

A few words about value objects: they are classes with all the persistent fields as member variables. They have getter and setter methods like you are familiar with. In addition, they also have a

public boolean Equals(Object obj)

method to compare other objects to this object and a

public int hashCode()

method which returns the hashcode for this value object. They have a postfix Data. For example, our value object will be called UserEntityData. Instead of passing usr_name_pk, pwd and email as strings we now pass a single UserEntityData object. The same is of course true for return values. As a value object is totally dependent on your declared persistent fields you must create value object methods only after you are finished with your persistent fields. In addtion, every time you make any changes to your persistent fields you must delete your old value object methods and create new ones. You will have noticed the information dialog that said all the above, only in many less words.

Now right click the highlighted UserEntityEJB label on the left side of the J2EE Wizard GUI. Select Show generated Sourcecode. Note the Ctrl-F7 keyboard short-cut which you can use to perform this function. You will have noticed a Generate Sourcecode menu item. It is not necessary to Generate Sourcecode before invoking Show Generated Sourcecode. Your ejbCreate method will be there in all its glory. Note that UserEntityEJB contains no member field variables corresponding to our peristent data - that is to say no Strings usr_name_pk, pwd and email. In fact, it contains no member field variables at all. The only indication that we have these persistent fields are the abstract getter and setter methods using the names of these fields. This is a feature of CMP EJB's. It will be the same in any CMP EJB which you create. The container (JBoss in this case) will synchronize with your DBMS and get and set values in the columns of the database table represented by this bean. The container also implements the abstract getter and setter methods. Note that at any one time your bean will represent only one row in your table. But your bean can represent any row in your table and even create new rows, which is exactly what ejbCreate() does - that is to say create one new row.

You will see that, according to the method signature, ejbCreate() returns a UserEntityPK. UserEntityPK is a primary key class created by J2EE Component Wizard. In reality a primary key can be one of the Java API classes or primitives, like a String or an int, if the primary key is composed of just one component. However, if the primary key is a compound key it has to be wrapped in one class of your own creation. With J2EE Wizard you will not have to worry about that as the J2EE Wizard creates a primary key class for every primary key, whether it consists of only one component or is a compound key. ejbCreate() returns null. Do not overly concern yourself with the return type in the signature. Forget it, for now.

Now select the Find-/Select Methods tab. Click on Add Find-Method. After changing the name to ejbFindAll your J2EE Wizard GUI will look something like this:

This method returns everything in the table. A java.util.Collection of objects implementing the UserEntityLocal interface is returned. Note the Local in the Return-Type-Mapping field. The View-Type is of course local as opposed to remote. We will use remote in the session bean.

Right click the UserEntityEJB and select Generate Sourcecode from the context menu like you did a minute or two ago. Then right click UserEntityEJB again and select Show generated Sourcecode. You will note that no business code (as opposed to comments) to implement this method is created in UserEntityEJB. All you will find are the XDoclet @ejb.finder tag and the related information needed to implement this finder method. This you will find as comments and not part of the business code of the class at all. This is how it looks:

/*
 *
 * @ejb.finder      signature="java.util.Collection findAll()"
 *                  query="SELECT OBJECT(U) FROM UserEntity AS U"
 *                  result-type-mapping="Local"
 *                  view-type="local"
 *                  description=""
 *                  transaction-type="Required"
 *                  unchecked="true"
 */

If you use the EJBDoclet task of XDoclet (like J2EEwizard does) to write interfaces and deployment descriptors, all finder methods are blue-printed (the plan that will give rise to the actual finder method) this way. Only if you specify Select Methods will any business code appear in your EJBEntity bean. To use a select method from outside the EJB Entity bean you will of course have to write an interface method which will also give rise to business code in your EJB Entity bean. But that is another story.

This is all you have to do to implement the four methods we need for the Entity Bean. Easy, isn't it?

Our bean is not going to reference other beans. Neither is it going to use environment entries or use resource environment references. You also specified the datasource to be used in the Project Properties right in the beginning. You can at any stage look at the source code for UserEntityEJB as we progress. Look at the Xdoclet tags generated by adding a data source. The documentation in XDoclet will tell you exactly what every tag means.

Next we must establish the context our bean will operate in. Click the Deployment tab and fill in all fields as indicated below and check the check boxes as indicated. The JNDI name specified here can be used to access this bean. However, if one has declared an <ejb-local-ref> (for a local home interface object) or an <ejb-ref> (for a home interface object) element in a bean's (say Session Bean A) deployment descriptor, one can use the names specified here, and not the JNDI name, to access this bean from, in this case, Session Bean A. To prevent one from making a mistake with either the JNDI or COMP names they are declared as static finals in the localHome interface of the entity bean and the local interface of the session bean in this tutorial. But always go withe the name in the <ejb-local-ref> or <ejb-ref> elements if they exist.

The Schema Name is used exactly like a table name. One uses a table name in SQL, likewise one uses a schema name in EJB QL. Therefore, a schema name is much the same as a table name. Remember, even though J2EE often works with a database it is in essence Java programming. The schema and the table it represents can have the same name or, like in this example, different names. I used a different name because using anything but lower case in PostgreSQL is a hassle calling for quote characters (inverted commas).

Look at the other tabs. Under the Transaction tab Transaction should be Required for all mehtods. You may have to click on something else but the UserManagerEntityEJB on the left side and then back on UserManagerEJB again for all the methods to show up in the GUI. You should be able to leave all other values as generated by J2EE Component Wizard. That's it for the Entity Bean. Save all your work and let's move on to the Session Bean.

The Session Bean

We are going to have four methods:

A method for adding a user
A method for removing a user
A method to find a user by name
A method to find all users

Both our Session and Entity Beans live in the same archive and will use the same Java Virtual Machine. Therefore our Session Bean may use the local interfaces of our Entity Bean to call methods on our Entity Bean. This saves overhead. Our session bean on the other hand may be called from a machine on the other side of the world. Whatever calls the session bean will have to use remote and home interfaces to call the session bean. In our example they will of course all live happily on the same machine in the same ear archive.

We know that our Session Bean is going to be heavily involved in communicating with our Entity Bean. Let us make sure it will be able to do so before we do anything else. Select the EJB References tab and fill in the fields as below:

Now think back on when I talked about JNDI and COMP names and told you that a static reference to one of these may prevent problems but may also cause problems. Look at the EJB reference name used here: java:comp/env/ejb/UserEntity. If you now migrate to where your UserEntityLocalHome is and open that up you will discover the following code:

public static final String COMP_NAME="java:comp/env/ejb/UserEntityLocal";

Similar, but not quite the same. Using a static reference to the COMP_NAME here will not work. If you make your EJB reference name exactly the same as your COMP_NAME a static reference to the relevant COMP_NAME will work.

The reference is an ejb local reference. It will be specified in an <ejb-local-ref> element in the ejb-jar.xml deployment descriptor. The view type we have defined for UserEntityEJB is local. Take note of the java:comp/env/ejb/UserEntity name. We will use it in a moment to access interface objects of the entity bean.

Select the Additional Declarations tab and then under that the Import Statements tab. At the end of the list of import statements you should see the following:

import au.com.databaseapplications.usermanager.jar.interfaces.UserEntityPK;
import au.com.databaseapplications.usermanager.jar.interfaces.UserEntityData;
import au.com.databaseapplications.usermanager.jar.interfaces.UserEntityLocalHome;
import au.com.databaseapplications.usermanager.jar.interfaces.UserEntityLocal;

Your prefixes may be different. If it is not there, add it.

Still under the Additional Declarations tab, but this time under Instance Variable sub-tab, enter the following if it is not already there:

private SessionContext sessionContext;

Now to make sure a reference to the LocalHome interface of our Entity Bean will always be readily available. So, still under the Additional Declarations tab, buth this time under the Private Helper Methods sub-tab, enter the following:

 private au.com.databaseapplications.jar.interfaces.UserEntityLocalHome getLocalHome(){	
    try{
    	Context initial = new InitialContext();
    	Object objref = initial.lookup("java:comp/env/ejb/UserEntity"); 
    	UserEntityLocalHome userHome = (UserEntityLocalHome)objref;
		return userHome;
    }
    catch (NamingException ex) {
        throw new EJBException("Exception in 
	   trying to get an Entity LocalHome object\n" + ex.getMessage());
    }

  }

This is where we make use of the name in Sourcecode of the entity bean. Remember when we specified it a few minutes ago? Recall that it is different from the COMP_NAME, but only slightly so. This slight difference is what makes those who have not noticed it use a static reference to the COMP_NAME. The Session Bean should now be able to get a handle on the Entity Bean. Let's use this handle and implement some methods which can be called on the Entity Bean. Select the Methods tab and fill in the one method as shown. You will have to click the Add button.

This method, like all business methods in this session bean, returns a string (with <br> tags) ready for display in the browser. Click the Add button.

Note that this method takes three parameters, all of them Strings. These three Strings are then wrapped in a value object which is passed as a single parameter. The email parameter is not seen in the image - the text field is too small.

Again click the Add button. The findAll method looks like this:

 public String findAll() throws javax.ejb.FinderException
  {
    String result ="";
    int no = 0;
    try{
	   UserEntityLocalHome userHome = getLocalHome();
         java.util.Collection col = userHome.findAll();
         java.util.Iterator iter = col.iterator();
         while(iter.hasNext()){
			UserEntityLocal usr = (UserEntityLocal)iter.next();
			result += "User No " + ++no + "<br>Name: "
			+ usr.getUsr_name_pk() + "<br>Password: " + usr.getPwd() +
			"<br>E-mail Address: " + usr.getEmail() + " <br>";
        }
		return result;
    }     
    catch (javax.ejb.FinderException ex) {
        result = ex.toString();
        return result;
    }
    catch(Exception e){
      return (e.getCause()).toString(); 
    }    
  }

Note that by calling the findAll method on the EntityBean a collection of EntityLocal objects is returned. We now iterate through this collection and get all data from each EntityLocal object. We build up a String that is ready for display in the browser.

The next method is removeUser(String user) and looks like this:

 public String removeUser(String user) throws javax.ejb.RemoveException
  {
    try{
	  UserEntityPK key = new UserEntityPK(user);
	  UserEntityLocalHome userHome = getLocalHome();
	  userHome.remove(key);
	  return "This user was removed";
    }
    catch(javax.ejb.RemoveException e){
      return (e.getCause()).toString(); 
    }
  }

I am sure you will mangage to do this on your own. It is just like the other methods.

The last method in our session bean has to do with finding a user by user name. It looks like this:

public String findUser(String user) throws javax.ejb.FinderException
  {   
    String result = "";
      try{
		UserEntityPK key = new UserEntityPK(user);
		UserEntityLocalHome userHome = getLocalHome();
		UserEntityLocal usr = userHome.findByPrimaryKey(key);
		String name = usr.getUsr_name_pk();
		String password = usr.getPwd();
		String email = usr.getEmail();
		result = "User Details:<br> Name: " + name + "<br> Password: " + password + 
		   "<br> E-mail Address: " + email;
		return result;
      }
	  catch(javax.ejb.ObjectNotFoundException onfe){
	   return "This user does not exist.  Start by checking your spelling.  
		Case is important";	
	  }
      catch (javax.ejb.FinderException ex) {
        result = ex.toString();
		return result;
      }
	catch(Exception e){
   	   result = (e.getCause()).toString();
	   return result; 
     }
  }

We now have all four methods defined. This is what your GUI should look like:

Now click the Deployment tab and make sure your fields are filled in and checkboxes ticked as shown below.

This is what you should see when you select the Transaction tab:

Note that we did not define a ejbCreate method for the Session bean. It was defined for the Entity Bean when we created value object methods. Define an ejbCreate method for both your Session Bean. These are not defined by default. Leave the body empty.

The JSP file

Here is the code for the JSP file:

<%@ page errorPage="errorpage.jsp" %>
<jsp:useBean id="messengerBean" scope="session" 
   class="au.com.databaseapplications.usermanager.war.bean.UserManagerBean" /> 

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>User Management CMP EJB</title>
  </head>
 <!-- The form for entering the data -->
  <body bgcolor="#ffffcc" text="brown">
    <center><h2>User Management CMP EJB with JSP</h2></center>
    <p><center><b>This is a Java Server Page, trying to call a 
      Container Managed EntityBean.</b></center></p>
    <form action="messengerServlet" method="post"> 
    <table align="center">
	<tr>
	    <td><input type="text" name="user_name" size="15"></td>
	    <td><input type="text" name="password" size="15"></td>
	    <td><input type="text" name="email" size="20"></td>
	</tr>
	<tr>
	    <td align="center">User Name</td>
	    <td align="center">Password</td>
	    <td align="center">E-mail Address</td>
	</tr>
	<tr>
	    <td colspan="3"><center><input type="submit" name="command" 
	      value="Add"></center></td>
	</tr>
    </table>
    <br>
    <br>
	<center><input type="submit" name="command" value="Remove User"></center>
    <br>
    <br>
	<center><input type="submit" name="command" value="Get by Name"></center>
    <br>
    <br>
	<center><input type="submit" name="command" value="Get All"></center>
    </form>

	<center><h3>    <%= messengerBean.getResult() %> </h3></center>
	<% messengerBean.setResult(""); %>
  </body>
</html>

Note that this JSP is almost pure html. That is the way one wants it. The rationale is that web developers with limited or no Java skills can work on the appearance of the web page while a coder can implement functionality.

As an aside, why is the folliwng line in the above JSP? Look right at the end:

<% messengerBean.setResult(""); %>

Expand Java Server Pages and select UserManagerJsp. Then select the File Content tab and copy the above to the relevant window. Change what needs to be changed. Save. Now select the Mapping tab, click Add and map your index page to /indexpage.

This is what the Java Server Page is going to look like:

All the results will be displayed below the Get All button.

Here is the code for the error page:

<html>
	<body bgcolor="#ff0000" text="yellow">
	<%@ page isErrorPage="true" %>
		<center><h1>Error Page</h1></center>
	<!-- use the implicit exception object, which holds a -->
	<!-- reference to the thrown exception -->
		<center><h2>An exception has been thrown.  These are the details</h2>
		   </center><br>
		<%= exception.getMessage() %>
	</body>
</html>

I am sure you will know what to do. Remember to select the Mapping tab, click Add and map your error page to /errorpage.

We are done with the Java Server Pages.

The Servlet

The servlet is going to use the bean. Therefore the first thing to do is make sure the bean is imported into the servlet. Select UserManagerServlet on the left and then click the Additional Declarations tab and under that the Import Statements sub-tab. Now add:

import au.com.databaseapplications.usermanager.war.bean.UserManagerBean;

Matheus da Silva Souza from Brazil pointed it out that one should also import javax.servlet.http.HttpSession. That is perfectly right, of course. Thanks Matheus. So, import that as well.

Still under the Additional Declarations tab click the Instance Variable sub-tab. Add the following:

private UserManagerBean bean;

Now to declare and implement some methods. Let's start with a private helper method. Click the Private Helper Method sub-tab. Below is the code for this method. It does redirection and we will call it many times.

 private void redirect(HttpServletResponse response){
	try{
  	  response.sendRedirect("indexpage");
	}
	catch(java.io.IOException ioe){
  	  bean.setResult(ioe.getMessage());
	} 
  }

Now the init method. It has but little code. Here it is:

 public void init(ServletConfig config) throws ServletException{
   super.init(config);
  }

Click the Methods tab. You will notice all servlet implemented methods in a drop-down list. Select init and complete this method. Then select doPost. Here is its body:

{
	String command = "";
	//We are going to enter data or get data out and display it.
	try{
  	   command = request.getParameter("command");
	   if(command != null && !command.equals("")){
		HttpSession session = request.getSession();
		bean = (UserManagerBean)session.getAttribute("messengerBean");	
		if(command.equals("Add")){
		   String name = request.getParameter("user_name");
		   String pwd = request.getParameter("password");
		   String email = request.getParameter("email");
		   if(name == null || name.equals("") || pwd == null || pwd.equals("") 
			|| email == null || email.equals("")){
			bean.setResult( "Fill in all fields");
			redirect(response);					
			return;
		   }
		   bean.createUser(name, pwd, email);
		   redirect(response);		 
		}
		else if(command.equals("Remove User")){
		  String name = request.getParameter("user_name");
		  if(name == null || name.equals("")){
			bean.setResult( "Fill in the name of the user you want to remove");
			redirect(response);
			return;
		  }
		  bean.removeUser(name);
		  redirect(response);
		  return;				
		}
		else if(command.equals("Get by Name")){
		  String name = request.getParameter("user_name");
		  if(name == null || name.equals("")){
			bean.setResult( "Fill in the name of the user you want to get 
			   details for");
			redirect(response);					
			return;
		  }
		  bean.findUser(name);
		  redirect(response);
		  return;			
		}
		else if(command.equals("Get All")){
		  bean.findAll();
		  redirect(response);
		  return;				
		}	  
	  }
	}
	catch(java.lang.NullPointerException npe){
	  bean.setResult( "In the Servlet: A Null Pointer Exception -  " + npe.toString());
	  redirect(response);	  
	}
	
	catch(Exception e){	
	  bean.setResult( "In the Servlet<br>" +  e.getMessage());
	  redirect(response);
	  return;
	}
}

You may be disappointed that we are finished with the servlet. As you can see, all it does is take output from the form in the JSP, analyze that, and then send the appopriate message to the bean. Here is the last thing to do for the servlet, map it to /messengerServlet.

The java bean

The java bean needs to communicate with the session bean. To facilitate that J2EEWizard creates a utility class called (in this case) au.com.databaseapplications.usermanager.war.service.ServiceLocator. It can do much more than we want at this stage. We are only interested in it getting us a reference to the home interface of the session bean - to be correct I should really say an object implementing the home interface of the session bean. ServiceLocator does this using a method called doLookup. This method returns an object, therefore this object needs to be casted to a UserSessionHome interface implementing object.

You already have the code for the UserManagerBean. If you look at that you will notice that two interfaces of the session bean are imported. The session bean lives in the jar archive and the UserManagerBean in the war archive. To ensure that the contents of the jar archive is available to classes in the war archive do the following:
Expand the WEB Archives node and select the User Manager node under that. Now select the EJB References tab. Fill the boxes in so they look like below:

This is much the same as you did for the Entity Bean to make it available to the Session Bean. The view type here is remote. The EJB Reference Name we specified here in this case is exactly the same as the COMP_NAME. You will notice that this class sends messages from the servlet to the session bean, then gets a string response back from the session bean and initialises a global variable of its own with this result. The java server page "reads" this global variable and displays it as an html page. Look at the code of UserManagerBean and see how a reference to objects implementing the interfaces of the session bean are obtained.

The datasource

I used PostgreSQL. All one has to do is create a database in it. It is as simple as typing in: createdb WizTut on the command line. No need to create any tables at all. The server will create them when the application is deployed.

There is a difference in how datasources are specified between JBoss-3.0.x and the JBoss I now have, 3.2.x. If you have JBoss-3.0.x you can use J2EEWizard to create datasource. Select Project --> New JBoss Service --> JDBC Database Connection. It is easy. I used it when I had JBoss-3.0.4

However, if you have JBoss-3.2.x, find an xml file describing your DBMS to JBoss. There are about twenty in $JBOSS_HOME/docs/examples/jca. Copy the relevant one to $JBOSS_DEPLOY_DIRECTORY, which is $JBOSS_HOME/server/default/deploy in my case.

The file is called postges-ds.xml for PostgreSQL and has the following inside it:

<datasources>
  <local-tx-datasource>
    <jndi-name>PostgresDS</jndi-name>
    <connection-url>jdbc:postgresql://[servername]:[port]/[database name]</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <user-name>x</user-name>
    <password>y</password>
  </local-tx-datasource>
</datasources>

I changed it to look like this:

 <local-tx-datasource>
  <jndi-name>usermanager.database</jndi-name>
    <connection-url>jdbc:postgresql://10.0.1.4:5432/WizTut</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <user-name>john</user-name>
    <password>k1ngk0ng</password>
  </local-tx-datasource>

The next edition of J2EEWizard, which is 1.2, will be able to create datasources for JBoss-3.2.x Watch the J2EEGuru website.

Save all your work. You may want to quickly check all your methods and persistent fields. On my machine definitely declared and implemented methods may revert back to the original default name on occasion. This has now happened to me on two computers. I have had a faulty jboss.xml descriptor generated twice. The fault was the same in both cases. I'd be interested to know if this also happens to other people. See what follows.

Now go to Project --> Generate System Files . From here go to Project --> Generate Sourcecode and last of all you should theoretically go to Project --> Build All. Personally I recommend opening a term window (DOS window for Windows users) at this point and migrate to the UserManager directory. build.xml should be in this directory. Now call ant xdoclet-generate. Then inspect your jboss.xml and ejb-jar.xml deployment descriptors. Look at the pictures below. If the faulty entry in jboss.xml has been generated, comment it out like shown below. If no <local-ref> element has been generated in ejb-jar.xml, put it in as shown.

The jboss.xml descriptor

The ejb-jar.xml descriptor

Now you can call ant deploy-jboss which will compile all .java files, build the .jar, .war and .ear archives and deploy the .ear to JBoss. If JBoss is running at this stage you can watch the output. Be sure your database server is running as well. If everything went well open your browser and go to: http://localhost:8080/UserManager/indexpage The page should come up - well, with a bit of luck. Then enter data and play around.

Well, this is the end. The plan is to use this as the base for a tutorial about security in JBoss. Please e-mail me and tell me if this helped and if it should be changed in any way.