Monday, March 29, 2010

Walkthrough: Integrating GWT with JBoss 5.1.0 & EJB3

This tutorial describes steps to easily create a JavaEE enterprise application, using the following components:

  • Google Web Toolkit (version 1.7 or 2.0)
  • Eclipse Ganymede or Galileo, Java EE version
  • GWT Eclipse Plugin
  • JBoss AS 5.1.0.GA
  • JBoss Tools plugin
Hint: Anything that is a user action will be in green.

Getting Started


If you haven’t already done so, you need to download all of those components. See ‘links’ at the end of this document for help. This tutorial requires the JavaEE version of Eclipse.

  • Unpack the JBoss distribution to wherever you would like.
  • Unpack/Install Eclipse, and start it up
  • Install the GWT Plugin for Eclipse, using the link provided for instructions
  • Install the JBoss Tools plugin for Eclipse, using the link provided.
Once you have all those components downloaded and installed, create a new empty workspace in Eclipse, and close the welcome screen.

1. Create the Server Environment


In eclipse, Open Window/Preferences and select Server/Runtime Environments
Click Add.


Select JBoss Community/JBoss 5.1 Runtime, and click Next.
(You won’t see this option unless you have installed the JBoss Tools Eclipse Plugin.)



Click Browse to configure the JBoss Home Directory. (This is wherever you unpacked it in Getting Started)
Select a server configuration; ‘default’ is fine for now.

Click Finish
Click OK to close the preferences.

2. Create an Enterprise Application Project


Select File/New/Enterprise Application Project
Enter the project name (I chose ‘tutorial_ear’ for this example.)



Click Finish

This just created an Enterprise Application aRchive Project, which will be used to jar up all the other components for easy deployment.

3. Create an EJB Project



Select File/New/EJB Project
Enter the project name (I chose tut_ejb here)
Check the Add project to an EAR setting



Click Next
Click Next again
At this point, you can choose if you want to have an EJB Client Jar or not. I left this checked, just 'cuz it's the default.

4. Create an EJB


Right click the EJB project, and select New/Session Bean(EJB3.x)
Set the Java Package and the Class name.
For this tutorial, we will only create a local interface.



Click Finish

In the ejbClient project, open the corresponding bean interface (SampleBeanLocal), and add a method. In this case, I added a method called getEJBHello(String name).



Save the file.

Go to the implementation (SampleBean.java), and implement the method:



Save the file.

5. Create the GWT Project

Click on the Google New Web Application Project icon in the toolbar
Set the project name, the package, and then configure the SDK.
Uncheck Use Google App Engine, as we’re using JBoss instead.



Click Finish.
At this point, your workspace configuration should look like this.



If you did not select the ejbClient project, then of course that project will not be here.

5.1 Modify the GWT project

Some things need to be done to the GWT project right off, before doing anything else.

5.1.1 Add Facets to the project

Open the Navigator view (Window/Show View/Navigator), open the gwt project, and double-click the .project file to open it.
Find the natures list, and add the following three items to it:

<nature>org.eclipse.wst.common.modulecore.ModuleCoreNature</nature>
<nature>org.eclipse.wst.common.project.facet.core.nature</nature>
<nature>org.eclipse.wst.jsdt.core.jsNature</nature>


(The result is it should look like this:)


Close the .project file
Close the gwt project, by right-clicking it, and selecting Close Project.
Reopen it, by right-clicking and select Open Project.
(This will cause eclipse to accept the new natures.)

5.1.2 Configure Project Facets

Right click the project, and select Properties.
Select Project Facets.
Enable Java
Enable Dynamic Web Module



BEFORE DOING ANYTHING ELSE, Click on Further configuration available...
Click Next to get to the Web Module configuration
Change the Content directory value to “war” so it aligns with the GWT generated project.



Click OK to close the Further Configuration
Click OK to close the project facets

Note: If you click OK before changing the Content directory, eclipse will irreversibly set the content directory; you cannot click "further configuration" and change it later. (Although, you can edit its .project file!)

5.1.3 Update the web.xml

In order for EJB injection to work, we need to update the web.xml web-app version from 2.3 to 2.5.
Find the gwt app’s web.xml, and open it.
Replace the header (including the web-app node), with the folllowing:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">


Save it.
If you plan on using JNDI lookups, and not injection, then you can skip this step. For example, if you need to use Stateful beans, then you probably don’t want to use injection. (See dev tips at the end.)

5.2 Add the GWT project to the EAR

Right click the EAR project, and select Properties.
Select Java EE Module Dependecies, and check the GWT project.



Click OK

6. Call the EJB!

Open the GreetingServiceImpl class using the greatest Eclipse tool of all time: Open Type.
Click the Open Type toolbar button, or type Shift-Ctrl-T. (I like this shortcut so much, I am thinking of mapping it to the spacebar!)
Inject the EJB. In this case, my bean interface is called SampleBeanLocal.
So, to inject it, I add the code:

@EJB
SampleBeanLocal sampleBean;




At this point, the project needs to have it’s build path updated...
Hover over the red squigglies on SampleBeanLocal, and select Fix Project Setup.
That should take care of that.

Modify the GWT server code to use the EJB:



7. Compile the GWT application

Click the GWT Compiler icon, and compile your app.
Refresh the ‘war’ folder on your GWT application, so eclipse will see the changes. You can do this by right-clicking the project, and selecting refresh.

We’re almost done!!!

8. Configure the JBoss Server

Click on the Servers tab near the bottom. If you don’t see it, you can select Window/Show View/Servers.
Right click in the servers view, and select New/Server
Select JBoss AS 5.1



Click Finish
This depends on Step 1, Configuring the JBoss Runtime Environment. If you did not complete that step, then you can click on Configure runtime environments here, to set things up now.

Right click the new server, and select Add and Remove.



Add the EAR to the Configured side, and click Finished

9. Start the server!

Right-click the server, and select either Start or Debug. Debug will let you set breakpoints in your server-side code.

After a while, in the console, you should hopefully see that your apps have deployed:

12:34:26,195 INFO [EJBContainer] STARTED EJB: org.example.tutorial.ejb.SampleBean ejbName: SampleBean

12:34:26,215 INFO [JndiSessionRegistrarBase] Binding the following Entries in Global JNDI:

tutorial_ear/SampleBean/local - EJB3.x Default Local Business Interface
tutorial_ear/SampleBean/local-org.example.tutorial.ejb.SampleBeanLocal - EJB3.x Local Business Interface

12:34:26,292 INFO [TomcatDeployment] deploy, ctxPath=/tut_gwtapp

12:34:26,119 INFO [JBossASKernel] Added bean(jboss.j2ee:ear=tutorial_ear.ear,jar=tut_ejb.jar,name=SampleBean,service=EJB3) to KernelDeployment of: tut_ejb.jar

12:34:26,122 INFO [EJB3EndpointDeployer] Deploy AbstractBeanMetaData@1a98d7b{name=jboss.j2ee:ear=tutorial_ear.ear,jar=tut_ejb.jar,name=SampleBean,service=EJB3_endpoint bean=org.jboss.ejb3.endpoint.deployers.impl.EndpointImpl properties=[container] constructor=null autowireCandidate=true}

12:34:26,194 INFO [SessionSpecContainer] Starting


Once it is started, you can open your browser and go to:
http://localhost:8080/tut_gwtapp
and you should see your GWT application come up!




(Note there is a missing space after the Hello. Ooops. That's a bug in the SessionBean.)


10. Source code


You can download the source files from Here. Note that I deleted the gwt-user.jar from the tut_gwtapp to reduce the size. Namely, that is file tut_gwtapp/war/WEB-INF/lib/gwt-user.jar. It is part of the standard GWT distibution.


11. Conclusion

Using these awesome, powerful tools, you can integrate these components easily, to quicky build enterprise applications.

  • Why would I want to use EJBs?
EJB3 comes with some very powerful features! I will let you know as soon as I think of any. Okay, here’s one: Many existing EA code bases are already using EJBs as their primary way of doing business logic, and they are well understood by Java architects.

Something to watch out for, however, is that a Stateful EJB session bean may not be what you think it is. You might consider using @EJB to inject a stateful bean into your servlet code. This will likely lead to problems, however, as this bean is in no way tied to the web session, and so every call to your servlet will get a new bean.
Instead, when you need a stateful bean, you will need to look up the bean as per normal, and then cache it somewhere, eg., in the http session.

One downside to using Session Beans from your code is that you can't call them directly from the client code. You must make normal GWT RPC calls, and in the server code, make the call to the EJB... Haven’t figured out a way around that yet, and I don't think there is one.

12. Dev Cycle Tips

  • GWT compilation
The GWT compiler writes to the war folder. After compiling, you need to refresh that folder, so that Eclipse knows about the changes, and will redeploy the resources.

  • JBoss Startup time
It takes a long time to start and stop JBoss. So, don’t do that!
Start the server once.
If you are running in debug mode, you typically only need to refresh your war directory, and your changes will be deployed immediately, for client code.
For server code changes, you typically only need to save the file, and it will be deployed immediately, while in debug mode.
If your server changes do require a restart, don’t restart JBoss, but rather, undeploy and then redeploy the EAR. This is lots faster.

  • Export
Once you are happy with your EAR project, you can export it using File/Export...

13. Links