So you need to deploy to WebSphere, and you really want to take advantage of all the benefits of Seam including EJB3 - but your not sure where to begin?
You're in luck!!
This article along with the Seam Reference Guide WebSphere Integration Chapter should tell you everything you need to know. I'm going to get into some of the troubleshooting and debugging that went into that investigation and explain some of the parts that took a lot of time to figure out. I don't want to repeat the reference guide chapter word-for-word so I'll refer you to it at some points.
What You Need
WebSphere 6.1.X does not support EJB3/JPA out of the box, so you need to download the EJB3 feature pack listed above. WebSphere is a commercial product so you will either have to have a IBM account or download the trial version. Basic installation of WebSphere can also be a little tricky - so don't forget to augment the server profile you plan on using with the EJB3 features.
A really good network connection would also be helpful when downloading WebSphere and the feature pack. WebSphere itself is almost 500MB, and the feature pack is an amazing 750MB. That's 1.25GB of application server downloads- not sure where it all went exactly.
Special WebSphere setting
There are 2 special properties that need to be set for WebSphere to work well with any modern web application (especially JSF/AJAX apps). They are both custom web container properties (how to change).
These were both amazingly difficult to find, and the errors that are displayed do not make it obvious as to what the problem is.
prependSlashToResource = "true"
If you start to see a lot of exceptions like java.net.MalformedURLException: SRVE0238E: this property is probably not set. What was more annoying about this issue is that you need to track down the correct WebSphere error file in order to see the full exception. IBM is saying that they are spec compliant and every path must start with a /, that may be, but I've never had this problem anywhere else.
Even after you add this property you will still see a lot of warning Resource paths should have a leading slash but the resource will be returned as expected.
com.ibm.ws.webcontainer.invokefilterscompatibility = "true"
In most modern web applications resources like javascript, css, etc... are often served to the browser via dynamic requests. Most of these requests go through servlet filters for processing. With out this custom property you will see 404 FileNotFoundException for each resource retrieved this way. The tricky part was finding that out in the first place - because the symptom of this issue is seen as problems with css or javascript. So it looks like a RichFaces or JSF component incompatibility. Use something like firebug to look at each server request and you'll see what the real problem is.
The JEE5 booking example
So now that WebSphere settings are configured we can move on to actually getting our application working. All of the paths below assume that you in the examples/jee5/booking directory under your seam distribution.
Configuration file changes
Except for the web.xml file all the other configuration file changes are pretty basic.
resources/WEB-INF/web.xml
What needed to be done to this file was difficult to track down. The documentation for the EJB3 feature pack was hard to navigate and at some points contradicted itself. What it comes down to is that WebSphere EJB3 feature pack is not a full JEE5 implementation. One of the side effects of that is WebSphere does not support Servlet 2.5. So how are we going to reference EJB 3.0 beans? Good question - the answer is a little mucking around with the <ejb-local-ref> tags.
First things first though you need to adjust the top of the file to use Servlet 2.4. See the reference guide for details.
Now for the <ejb-local-ref> tags (here is just one of them). Notice that the <local-home> element is empty. This is the special sauce that tells WebSphere to make the correct bindings between the web module and the EJB3 beans. Without this it looks like everything is configured correctly and binding names in the logs appear to be correct, but your application won't be able to retrieve the beans.
<ejb-local-ref>
<ejb-ref-name>jboss-seam-jee5/AuthenticatorAction</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home></local-home>
<local>org.jboss.seam.example.booking.Authenticator</local>
</ejb-local-ref>
resources/META-INF/persistence.xml
See the reference guide for the full details, here is just some of the notable changes.
If your application is idle for about 10 minutes (WebSphere's default SFSB timeout) you may see a lot of exceptions like the one below:
com.ibm.wsspi.injectionengine.InjectionException:
EJBContext may only be looked up by or injected into an EJB
This is another limitation of the EJB3 Feature pack. Only EJBs support injection of the EJBContext. This means that when Seam/Hibernate attempt to handle clean-up of the transaction this exception is thrown. The solution is to tell hibernate not to flush transactions before completion. This can be done by either removing the property below or by setting it to false {th default is false
).
<property name="hibernate.transaction.flush_before_completion" value="false"/>
resources/import.sql
The default import.sql file needs to be overwritten with the one from the Seam JPA example. Either the Derby DB or the dialect does not support changes to the ID column. If you see errors related to the ID column it is probably this issue.
Other file changes
See the reference guide for the full details on changes needed for these files.
- resources/WEB-INF/components.xml
- resources/GlassfishDerbyDialect.class
Library changes
Manipulating required libraries is a pretty standard task when deploying applications from one application server to another. As with other parts of this document the details are in the reference guide (specific jars, modifications to the build.xml file, etc...).
- WebSphere 6.1 comes with their own version of JSF 1.1 (Seam requires JSF 1.2).
- During deployment through the administration console jar files in the root of EAR are not visible and may cause ClassCastExceptions.
- GlassfishDerbyDialect.class needs to be injected into the jboss-seam-jee5.jar because there is no place to put unarchived classes in the EAR.
Deploying the application
I like to sum up the deployment steps with this phrase:
Cool administration consoles are great as long as they are easy to understand and do what they say they will
The IBM administration console is very slick and looks good. It can do a lot of things, but when it came to deploying the EJB3 application it got a little confusing.
EAR file libraries
As mentioned above jar files at the base of the ear do not always seem to be available through the deployment mechanism of the console. This mean that we actually had two copied of jboss-seam.jar jar file. One at the EAR root, and one in the /lib directory.
Deployment options
Probably because the EJB3 feature pack is relatively new many of the deployment options were not well explained. This meant a lot of trial and error (along with a good dose of forum and support browsing). The results seem easy Deploy enterprise beans
check box must be selected (only if the EAR was not packaged by a WebSphere tool), and Allow EJB reference targets to resolve automatically
is required to have the EJB3 bindings work correctly with the modified web.xml from above.
Classloader setting not working
The Reference Guide talks about changes that are needed to the classloader settings of the application. This is to be expected, but when one of the options on the admin console does not seem to take effect no matter how you modify it, or how many times you restart it gets frustrating. Eventually I was able to find the file that the console was attempting to change, and I was able to change it manually (described in the guide). The path to the file was a little crazy and without really digging into the logs and directory structure you would not be able to get past this issue.
$WebSphereInstall/$yourServerName/profiles/$yourProfileName/config/cells/$yourCellName/applications/Seam Booking.ear/deployments/Seam Booking/deployment.xml
Classloader Viewer
One great feature of the console is the ClassLoader Viewer. In order to get this to work for a server profile you need to activate it in the profile settings. This allows you to view the classloader hierarchy and inspect classpaths, loaded classes, and what jars the classes came from. You can also search the whole tree with wild cards. This was very valuable when investigating various ClassCastExceptions and incompatible class errors.
Wrap-up
Seam applications deploy to WebSphere just fine, but the server is a little hard to manage and use without being a WebSphere expert. A few glaring things popped out as unexpected, but configuration and library file tweaking will almost certainly be a part of application deployments no matter what the platform.
For more examples and information on Seam integration with WebSphere and other application servers check out the Seam Getting Started Guide or the Seam Reference Guide
