C:\JBoss
admin
bin
client
conf
db
deploy
lib
log
tmpThis is it as far as installation of JBoss is concerned. Now to start JBoss with default configuration go to JBoss/bin directory and run the following command at the DOS prompt :
C:\JBoss\bin>run
run.bat is a batch file which starts the JBoss Server. Once JBoss Server starts, you should see huge lines of text appearing on your command prompt screen. These lines show that JBoss Server is starting. Once JBoss startup is complete you should see a message like following on your screen :
[Default] JBoss 2.4.3 Started in 0m:11s
Well done, you just installed and ran JBoss successfully on your system for the first time. To stop JBoss, simply press Ctrl + C on the command prompt and JBoss will stop, again after displaying huge lines of text.
ii. Installing, Configuring and Running Tomcat Server :
First download latest stable release of Tomcat Server from Tomcat web site. Current latest stable release is 4.0.1. If you are on Windows platform then you have the luxury of downloading Tomcat in an executable ( .exe ) format. So from the different types of Tomcat files available for download, select following :
jakarta-tomcat-4.0.1.exe
Once download is complete, double click this file to start the process of Tomcat installation. Installation is quite straight forward. During setup if you are running Windows NT/2K/XP, you'll be asked if you want to install it as a service, select 'yes' if you know what as a service is and how to start and stop it. Basically allowing the Tomcat to be installed a service means that you will be able to auto-start Tomcat when Windows starts and secondly Tomcat will run in the background and you won't have to keep one command prompt window open while it is running. Both of these features are great if you are using Tomcat on production machines. During development I will suggest that you don't install Tomcat as a service.
It will also ask you where you want it to be installed. Give it any location you want or simply allow it to be installed on the default location of C:\Program Files\Apache Tomcat 4.0.
Before starting Tomcat, let's first configure it a bit on the next page.
Configuring and Running Tomcat :
Create a new folder under the main C:\ drive and name it "Projects". Now create a new sub-folder in the C:\Projects folder and name it "TomcatJBoss". The directory structure should look like following :
C:\Projects
TomcatJBossNow open conf/Server.xml file from within the Tomcat directory where you have installed it. By default this location will be :
C:\Program Files\Apache Tomcat 4.0\conf\server.xml
Some where in the middle where you can see multiple <Context> tags, add following lines between other <Context> tags :
<!-- Tomcat JBoss Context -->
<Context path="/jboss" docBase="C:\Projects\TomcatJBoss\" debug="0"
reloadable="true" />Now save Server.xml file. Go to Start -> Programs -> Apache Tomcat 4.0 -> Start Tomcat, to start Tomcat Server. If everything has been setup correctly, you should see following message on your command prompt.
Starting service Tomcat-Standalone Apache Tomcat/4.0.1
iii. Developing your first Session EJB :
As we learned in "An Introduction to Enterprise JavaBeans" article, Session EJBs are responsible for maintaining logic in our J2EE applications. What we did not say in that article was that Session beans are also the simplest EJBs to develop. So that's why our first EJB will be a Session bean.
As you will see in a moment, every EJB class file has two accompanying interfaces and one XML file. The two interfaces are Remote and Home interfaces. Remote interface is what the client gets to work with, in other words Remote interface should contain the methods you want to expose to your clients. Home interface is actually EJB builder and should contain methods used to create Remote interfaces for your EJB. By default Home interface must contain at least one create() method. The actual implementation of these interfaces, our Session EJB class file remains hidden from the clients. The XML file we talked about is named as "ejb-jar.xml" and is used to configure the EJBs during deployment. So in essence our EJB, which we are going to create ( we will call it FirstEJB from now onwards ) consists of following files :
com
stardeveloper
ejb
session
First.java
FirstHome.java
FirstEJB.java
META-INF
ejb-jar.xmlFirst.java will be the Remote interface we talked about. FirstHome.java is our Home interface and FirstEJB.java is the actual EJB class file. The ejb-jar.xml deployment descriptor file goes in the META-INF folder.
Create a new folder under the C:\Projects folder we had created earlier, and name it as "EJB". Now create new sub-folder under C:\Projects\EJB folder and name it as "FirstEJB". Create a new folder "src" for Java source files in the "FirstEJB' folder. The directory structure should look like following :
C:\Projects
TomcatJBoss
EJB
FirstEJB
srcNow create directory structure according to the package com.stardeveloper.ejb.session in the "src" folder. If you know how package structure is built, it shouldn't be a problem. Anyhow, the final directory structure should like following :
C:\Projects
TomcatJBoss
EJB
FirstEJB
src
com
stardeveloper
ejb
sessionNow create a new First.java source file in com/stardeveloper/ejb/session folder. Copy and paste following code in it:/* First.java */ package com.stardeveloper.ejb.session; import javax.ejb.EJBObject; import java.rmi.RemoteException; public interface First extends EJBObject { public String getTime() throws RemoteException; }Hit the 'save' button to save First.java source file.
Explanation :
First line is the package statement which tells that First interface belongs in the com.stardeveloper.ejb.session package :package com.stardeveloper.ejb.session;Next two lines are import statements for importing required classes.
import javax.ejb.EJBObject; import java.rmi.RemoteException;Then comes interface declaration line which tells that this is an interface with name "First" which extends an existing interface javax.ejb.EJBObject.
Note: Every Remote interface *must* always extend EJBObject interface. It is a requirement, not an option.public interface First extends EJBObject {Now as I said on the last page, we have to declare methods in Remote interface which we want to be called by the client ( which the client can access and call ). For simplicity, we will only declare a single method, getTime(); which will return a String object containing current time.
public String getTime() throws RemoteException;Notice that there are no {} parenthesis with this method as it has been declared in an interace. Remote interface method's must also throw RemoteException because EJBs are distributed components and during the call to an EJB, due to some network problem, exceptional events can arise, so all Remote interface method's must declare that they can throw RemoteException in Remote interfaces.
FirstHome.java :
Let's now create the Home interface for our FirstEJB. Home interface is used to create and get access to Remote interfaces. Create a new FirstHome.java source file in com/stardeveloper/ejb/session package. Copy and paste the following code in it :/* FirstHome.java */ package com.stardeveloper.ejb.session; import javax.ejb.EJBHome; import javax.ejb.CreateException; import java.rmi.RemoteException; public interface FirstHome extends EJBHome { public First create() throws CreateException, RemoteException; }Hit the 'save' button to save FirstHome.java source file.
Explanation :
First few lines are package and import statements. Next we declare our FirstHome interface which extends javax.ejb.EJBHome interface.Note: All Home interfaces *must* extend EJBHome interface.public interface FirstHome extends EJBHome {We continue exploring FirstHome.java on the next page.
FirstHome.java :
Then we declare a single create() method which returns an instance of First Remote interface. Notice that all methods in Home interfaces as well must also declare that they can throw RemoteException. One other exception that they *must* declare that they can throw is CreateException.public First create() throws CreateException, RemoteException;We are done with creating Remote and Home interfaces for our FirstEJB. These two are the only things which our client will see, the client will remain absolutely blind as far as the actual implementation class, FirstEJB is concerned.
FirstEJB.java :
FirstEJB is going to be our main EJB class. Create a new FirstEJB.java source file in com/stardeveloper/ejb/session folder. Copy and paste following text in it :/* FirstEJB.java */ package com.stardeveloper.ejb.session; import javax.ejb.SessionBean; import javax.ejb.EJBException; import javax.ejb.SessionContext; import java.rmi.RemoteException; import java.util.Date; public class FirstEJB implements SessionBean { public String getTime() { return "Time is : " + new Date().toString(); } public void ejbCreate() {} public void ejbPassivate() {} public void ejbActivate() {} public void ejbRemove() {} public void setSessionContext(SessionContext context) {} }Hit the 'save' button to save FirstEJB.java source file.
Explanation :
First few lines are package and import statements. Next we declare our FirstEJB class and make it implement javax.ejb.SessionBean interface.Note: All Session bean implementation classes *must* implement SessionBean interface.public class FirstEJB implements SessionBeanOur first method is getTime() which had declared in our First Remote interface. We implement that method here in our FirstEJB class. It simply returns get date and time as you can see below :
public String getTime() { return "Time is : " + new Date().toString(); }Then come 5 callback methods which are part of SessionBean interface and since we are implementing SessionBean interface, we have to provide empty implementations of these methods. Later in other articles when will build some really useful Session beans, we will then see some use of these callback methods there, for now we don't need them.
ejb-jar.xml :
Let's now create the EJB deployment descriptor file for our FirstEJB Session bean. Create a new ejb-jar.xml file in the FirstEJB/META-INF folder. Copy and paste following text in it :<?xml version="1.0"?> <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd"> <ejb-jar> <description></description> <enterprise-beans> <session> <display-name>FirstEJB</display-name> <ejb-name>First</ejb-name> <home>com.stardeveloper.ejb.session.FirstHome</home> <remote>com.stardeveloper.ejb.session.First</remote> <ejb-class>com.stardeveloper.ejb.session.FirstEJB</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> </session> </enterprise-beans> <assembly-descriptor> <container-transaction> <method> <ejb-name>First</ejb-name> <method-name>*</method-name> </method> <trans-attribute>Supports</trans-attribute> </container-transaction> <security-role> <description>Users</description> <role-name>users</role-name> </security-role> </assembly-descriptor> </ejb-jar>ejb-jar.xml :
One or more EJBs are packaged inside a JAR ( .jar ) file. There should be only one ejb-jar.xml file in an EJB JAR file. So ejb-jar.xml contains deployment description for one or more than one EJBs. Now as we learned in an earlier article, there are 3 types of EJBs so ejb-jar.xml should be able to contain deployment description for all 3 types of EJBs.Our ejb-jar.xml file for FirstEJB contains deployment description for the only EJB we have developed; FirstEJB. Since it is a Session bean, it's deployment description is contained inside <session></session> tags.
<ejb-jar> <description></description> <enterprise-beans> <session></session> </enterprise-beans> </ejb-jar>Now let's discuss different deployment descriptor tags inside the <session></session> tag. First is the <ejb-name> tag. The value of this tag should be name of EJB i.e. any name you think should point to your Session EJB. In our case it's value is "First". Then come <home>, <remote> and <ejb-class> tags which contain complete path to Home, Remote and EJB implementation classes. Then comes <session-type> tag whose value is either "Stateless" or "Stateful". In our case it is "Stateless" because our Session bean is stateless. For more info on Stateless and Stateful Session beans, please read "An Introduction to Enterprise JavaBeans" article. Last tag is <transaction-type>, whose value can be either "Container" or "Bean". We will learn more about transactions in another article, for now it is sufficient to say that the transactions for our FirstEJB will be managed by the container.
<ejb-jar> <description></description> <enterprise-beans> <session> <display-name>FirstEJB</display-name> <ejb-name>First</ejb-name> <home>com.stardeveloper.ejb.session.FirstHome</home> <remote>com.stardeveloper.ejb.session.First</remote> <ejb-class>com.stardeveloper.ejb.session.FirstEJB</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> </session> </enterprise-beans> </ejb-jar>Then there is a <container-transaction> tag which tells that all methods of FirstEJB "support" transactions. We will learn more about these tags and ejb-jar.xml as we continue to learn more about transactions and security in EJB environment in other articles. For now let's move forward.
Compiling the EJB Java source files :
Our directory and file structure till now looks something like following :C:\Projects TomcatJBoss EJB FirstEJB src com stardeveloper ejb session First.java FirstHome.java FirstEJB.java META-INF ejb-jar.xmlYou can compile all the Java source file by using a command like following on the command prompt :
C:\Projects\EJB\FirstEJB\src\com\stardeveloper\ejb\session> javac -verbose -classpath %CLASSPATH%;C:\JBoss\client\jboss-j2ee.jar -d C:\Projects\EJB\FirstEJB *.javaNote: The point to remember is to make sure jboss-j2ee.jar ( which contains J2EE package classes ) in the CLASSPATH, or you will get errors when trying to compile these classes.If you have installed JBoss Server in a separate directory then substitute the path to jboss-j2ee.jar with the one present on your system. The point is to put jboss-j2ee.jar in the CLASSPATH for the javac, so that all EJB source files compile successfully.
On the next page we will learn how to package these .class files and .xml file into an easy to deploy JAR file.
Packaging EJB source files into a JAR file :
Till now our directory and file structure should look something like following :C:\Projects TomcatJBoss EJB FirstEJB com stardeveloper ejb session First.class FirstHome.class FirstEJB.class META-INF ejb-jar.xml src com stardeveloper ejb session First.java FirstHome.java FirstEJB.javaNow to package the class files and XML descriptor file together, run the following command at the command prompt :
C:\Projects\EJB\FirstEJB>jar cvfM FirstEJB.jar com META-INFRunning this command should produce an EJB JAR file with the name of FirstEJB.jar in the FirstEJB folder. But there is one thing still left to be done.
Adding JBoss specific configuration file :
Till now our FirstEJB.jar file contains generic EJB files and deployment description. To run it on JBoss we will have to add one other file into the META-INF folder of this JAR file, called jboss.xml. This file contains the JNDI mapping of FirstEJB.So create a new jboss.xml file in the FirstEJB/META-INF folder where ejb-jar.xml file is present. Copy and paste the following text in it :
<?xml version='1.0' encoding='UTF-8' ?> <!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS//EN" "http://www.jboss.org/j2ee/dtd/jboss.dtd"> <jboss> <enterprise-beans> <session> <ejb-name>First</ejb-name> <jndi-name>ejb/First</jndi-name> </session> </enterprise-beans> </jboss>To add this new jboss.xml file into our existing FirstEJB.jar file, run the following command at the DOS prompt :
C:\Projects\EJB\FirstEJB>jar uvfM FirstEJB.jar META-INFNow our FirstEJB.jar is ready to be deployed to the JBoss Server.
iv. Deploying FirstEJB.jar on JBoss Server :
Deploying EJBs on JBoss is as easy as copying the FirstEJB.jar file and pasting it into the C:\JBoss\deploy folder. If JBoss is running, you should see text messages appearing on the console that this EJB is being deployed and finally deployed and started. As simple as that.v. Creating the client JSP page :
Create new WEB-INF folder in C:\Projects\TomcatJBoss folder. Now create a new web.xml file and copy/paste following text in it :<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2.3.dtd"> <web-app> </web-app>As you can see, this web.xml is almost empty and is not doing anything useful. We still created it because Tomcat will throw an error if you try to access this /jboss context that we had created earlier without creating a /WEB-INF/web.xml file.
firstEJB.jsp JSP Client page :
Create a new JSP page in the C:\Projects\TomcatJBoss folder and save it as "firstEJB.jsp". Now copy and paste the following code in it :<%@ page import="javax.naming.InitialContext, javax.naming.Context, java.util.Properties, com.stardeveloper.ejb.session.First, com.stardeveloper.ejb.session.FirstHome"%> <% long t1 = System.currentTimeMillis(); Properties props = new Properties(); props.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory"); props.put(Context.PROVIDER_URL, "localhost:1099"); Context ctx = new InitialContext(props); FirstHome home = (FirstHome)ctx.lookup("ejb/First"); First bean = home.create(); String time = bean.getTime(); bean.remove(); ctx.close(); long t2 = System.currentTimeMillis(); %> <html> <head> <style>p { font-family:Verdana;font-size:12px; }</style> </head> <body> <p>Message received from bean = "<%= time %>".<br>Time taken : <%= (t2 - t1) %> ms.</p> </body> </html>Hit the 'save' button to save the firstEJB.jsp JSP page.
Explanation :
As you can see the code to connect to an *external* JNDI/EJB Server is extremely simple. First we create a Properties object and put certain values for Context.INITIAL_CONTEXT_FACTORY and Context.PROVIDER_URL properties. The value for Context.INITIAL_CONTEXT_FACTORY is the interface provided by JBoss and the value for Context.PROVIDER_URL is the location:port number where JBoss is running. Both of these properties are required to connect to an *external* JNDI Server.Properties props = new Properties(); props.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory"); props.put(Context.PROVIDER_URL, "localhost:1099");We then get hold of that external JNDI Context object by creating a new InitialContext() object, it's argument being the Properties object we had created earlier.
Context ctx = new InitialContext(props);Next we use that external JNDI Context handle to lookup our FirstEJB running on JBoss. Notice that the argument to Context.lookup("ejb/First") is the same value we had put in the jboss.xml file to bind our FirstEJB to this name in the JNDI context. We use that same value again to look for it. Once our lookup is successful, we cast it to our FirstHome Home interface.
FirstHome home = (FirstHome)ctx.lookup("ejb/First");We then use create method of our FirstHome Home interface to get an instance of the Remote interface; First. We will now use the methods of our EJB's remote interface ( First ).
First bean = home.create();We then call the getTime() method we had created in our EJB to get the current time from JBoss Server and save it in a temporary String object.
String time = bean.getTime();Once we are done with our Session EJB, we use the remove method to tell the JBoss Server that we no longer need this bean instance. Next we also close the external JNDI Context.
bean.remove(); ctx.close();We then display this retrieved value from getTime() method on the user screen.
vi. Running the JSP page :
Before trying to run firstJSP.jsp page, we have to do one other thing. Copy following files from C:\JBoss\client folder and paste them in the C:\Projects\TomcatJBoss\WEB-INF\lib folder. It is a must, without it firstEJB.jsp page will not run.connector.jar deploy.jar jaas.jar jboss-client.jar jboss-j2ee.jar jbossmq-client.jar jbosssx-client.jar jndi.jar jnp-client.jarYou will also copy the FirstEJB.jar file from C:\Projects\EJB\FirstEJB folder to the C:\Projects\TomcatJBoss\WEB-INF\lib folder. Without it the Tomcat will not be able to compile firstEJB.jsp JSP page.
We are now ready to run our firstEJB.jsp page. Mover over to the last page of this tutorial, the next page.
Running firstEJB.jsp JSP page :
Now start JBoss Server if it is not already running. Also start Tomcat Server. If it is already running, then stop it and restart it again. Open your browser and access following page :http://localhost:8080/jboss/firstEJB.jspPlease substitute port number "8080" above with the port number where your Tomcat Server is running. By default it is "8080". If you have done everything as was described in this article, then you should see a result like following :
Fig - firstEJB.jsp Client ViewNote: Since we are not running Tomcat/JBoss combination on Stardeveloper, I could not provide an online demo for this tutorial. But one thing I can tell you is that this is all very easy and there is no reason why you should not be able to run it on your own system.
Summary :
In this tutorial we were able to learn what comprises an Enterprise JavaBean and how to develop and deploy an EJB. We created an EJB, deployed it on JBoss Server and called it from a JSP page running on Tomcat Server in a separate process.We also learned how to install and configure JBoss and Tomcat Servers. JBoss/Tomcat is a pretty popular combination now a days as quite a few sites are using it. If you don't like Tomcat, don't worry there is another very good Web container which supports latest JSP 1.2 and Servlets 2.3 specifications; Resin. Resin is an extremely fast server and having personal experience with it, I can say that Orion and Resin are two of the fastest Servers around. So if you want to substitute Resin with Tomcat for this tutorial ( or in your production web site ), you can easily do so. And as I have tested, you won't have to change a single line of code or change any configuration settings in the EJB and JSP pages that we have made.
Since it would have been your first EJB, I wanted to take as much time ( without wasting it of course ;) ) as possible to describe things in detail. I hope if you followed everything, you should be able to run it successfully on your system. Just in case if it didn't work out for you, try doing it again and pay attention to every step so that you don't leave anything.
discuss this topic to forum
