Websphere 6.1.x is IBM's application server offering. The latest release is 6.1.0.13 which does not have EJB3 or JEE5 support. There is a recently released (Nov 07) EJB3 feature pack which provides some support for EJB3 and JPA. Currently there is no true JEE5 offering from IBM. This causes some issues with Seam integration with applications that use EJB3.
First we will go over some basic information about the Websphere environment that we used for these examples. After a good deal of research and work we were able to get EJB3 applications to function correctly. We will go over the details of those steps with the jee5 example. We will also deploy the the JPA example application.
Websphere is a commercial product and so we will not discuss the details of its installation other than to say follow the directions provided by your particular installation type and license. This section will detail the exact server versions used, installation tips, and some custom properties that are needed for all of the examples.
All of the examples and information in this chapter are based on the the latest version of Websphere at the time of this writing.
Websphere Application Server 6.1.0.13
Feature Pack for EJB 3.0 for Websphere Application Server V6.1 (3.0.6.1.0.13)
The EJB3 feature pack that we installed came with the 6.1.0.13 patch version of Websphere. Installing the feature pack does not ensure that your server will have the proper environment for EJB3 applications. Be sure that as part of the installation of the feature pack you follow the instructions to create a new server profile with the EJB3 feature pack enabled, or augment one of your existing ones. This can also be done after the installation by running the profile managment tool.
There are times that restarting the server will be required after deploying or changes the examples in this chapter. Its does not seem like every change requires a restart. If you get errors or exceptions after modifing a property or deploying an application try to restart the server.
There are a couple of Websphere custom properties that are required for Seam integration. These properties are not needed specifically for Seam, but work around some issues with Websphere. These are set following the instructions here : Setting web container custom properties
prependSlashToResource = "true" — This solves a fairly common issue with Websphere where applications are not using a leading "/" when attempting to access resources. If this is not set then a java.net.MalformedURLException will be thrown. With this property set you will still see warnings, but the resources will be retrieved as expected.
SRVE0238E: Resource paths must have a leading slash
com.ibm.ws.webcontainer.invokefilterscompatibility = "true" — This solves an issue with Websphere where it throws a FileNotFoundException when a web application attempts to access a file resource that does not actually exist on disk. This is a common practice in modern web applications where filters or servlets are used to process resource requests like these. This issue manifests itself as failures to retrieve JavaScript, CSS, images, etc... when requesting a web page.
PK33090; 6.1: A filter that serves a file does not pop-up an alert message
The jee5/booking example is based on the Hotel Booking example (which runs on JBoss AS). Out of the box it is designed to run on Glassfish, but with the steps below it can be deployed to Websphere. It is located in the $SEAM_DIST/examples/jee5/booking directory.
As stated before the EJB3 feature pack does not provide a full jee5 implementation. This means that there are some tricks to getting an application deployed and functioning.
Below are the configuration file changes that are need to the base example.
We need to change the way that we look up EJBs for Websphere. We need to remove the /local from the end of the jndi-pattern attribute. It should look like this:
<core:init
This is the first place that we notice an unexpected change because this is not full jee5 implementation.
Websphere does not support Servlet 2.5, it requires Servlet 2.4. For this change we need to adjust the top of the web.xml file to look like the following:
<?xml version="1.0" encoding="UTF-8"?> <web-app
Next we have to make some changes to the EJB references in the web.xml. These changes are what will allow Websphere to bind the EJB2 references in the web module to the the actual EJB3 beans in the EAR module. Replace all of the ejb-local-refs when the values below.
<!-- JEE5 EJB3 names --> > <ejb-local-ref> <ejb-ref-name>jboss-seam-jee5/BookingListAction</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.example.booking.BookingList</local> </ejb-local-ref> <ejb-local-ref> <ejb-ref-name>jboss-seam-jee5/RegisterAction</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.example.booking.Register</local> </ejb-local-ref> <ejb-local-ref> <ejb-ref-name>jboss-seam-jee5/ChangePasswordAction</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.example.booking.ChangePassword</local> </ejb-local-ref> <ejb-local-ref> <ejb-ref-name>jboss-seam-jee5/HotelBookingAction</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.example.booking.HotelBooking</local> </ejb-local-ref> <ejb-local-ref> <ejb-ref-name>jboss-seam-jee5/HotelSearchingAction</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.example.booking.HotelSAll of the examples and informaearching</local> </ejb-local-ref> <ejb-local-ref> <ejb-ref-name>jboss-seam-jee5/EjbSynchronizations</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.transaction.LocalEjbSynchronizations</local> </ejb-local-ref>
The important change is that there is an empty local-home element for each EJB. This tells Websphere to make the correct bindings between the web module and the EJB3 beans. The ejb-link element is simply not used.
For this example we will be using the default datasource that comes with Websphere. To do this change the jta-data-source element:
<jta-data-source>DefaultDatasource</jta-data-source>
Then we need to adjust some of the hibernate properties. First comment out the Glassfish properties. Next you need to add/change the properties:
<!--<property name="hibernate.transaction.flush_before_completion" value="true"/>--> <property name="hibernate.cache.provider_class" value="org.hibernate.cache.HashtableCacheProvider"/> <property name="hibernate.dialect" value="GlassfishDerbyDialect"/> <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.WebSphereExtendedJTATransactionLookup"/>
hibernate.transaction.manager_lookup_class — Standard Hibernate transaction manager property for Websphere 6.X
hibernate.transaction.flush_before_completion — This is commented out because we want the container to manage the transactions. Also if this is set to true an exception will be thrown by Websphere when the EJBContext is looked up.
com.ibm.wsspi.injectionengine.InjectionException: EJBContext may only be looked up by or injected into an EJB
hibernate.dialect — From WAS 6.1.0.9 on the embedded DB was switched to the same Derby DB in Glassfish.
You will need to get the GlassfishDerbyDialect.class and copy it into the /resources directory. The class exists in the JPA example and can be copied using the command below assuming you are in jee5/booking directory:
cp ../../jpa/resources-websphere61/WEB-INF/classes/GlassfishDerbyDialect.class ./resources
This class will be put into the jboss-seam-jee5.jar file using changes to the build.xml discussed later.
This file must also be copied from the JPA example because either the Derby DB or the dialect does not support changes to the ID column. The files are identical except for the column difference. Use the following command to make the copy
cp ../../jpa/resources-websphere61/import.sql ./resources
In order to get the changes we have made into our application we need to make some changes to the build.xml. There are also some additional jars that are required by our application in order to work with Websphere. This section will cover what changes are needed to the build.xml.
JSF libraries — Websphere 6.1 comes with their own version of JSF 1.1 (Seam requires JSF 1.2). So we must add these jars to our application.
jsf-api.jar
jsf-impl.jar
Since Websphere is not a fully compliant JEE5 implementation we need to add these EL libraries:
el-api.jar
el-ri.jar
jboss-seam.jar — for some reason when deploying the application through the Websphere administration console it can not find the jboss-seam.jar at the base of the EAR archive. This means that we need to add it to the /lib of the EAR.
Finally we remove the log4j.jar so that all of the log output from our application will be added to the Websphere log. Additional steps are required to fully configure log4j and those are outside of the scope of this document.
Add the following entry to the bottom of the build.xml file. This overrides the default fileset that is used to populate the jboss-seam-jee5.jar. The primary change is the addition of the GlassfishDerbyDialect.class:
<fileset id="jar.resources" dir="${resources.dir}"> <include name="import.sql" /> <include name="seam.properties" /> <include name="GlassfishDerbyDialect.class" /> <include name="META-INF/persistence.xml" /> <include name="META-INF/ejb-jar.xml" /> </fileset>
Next we need to add the library dependencies discussed above. For this add the following to bottom of the ear.lib.extras fileset entry:
<!--<include name="lib/log4j.jar" />--> <include name="lib/el-api.jar" /> <include name="examples/jpa/lib/el-ri.jar" /> <include name="lib/jsf-api.jar" /> <include name="lib/jsf-impl.jar" /> <include name="lib/jboss-seam.jar" /> </fileset>
Now all that is left is to execute the ant archive task and the built application will be in the jee5/booking/dist directory.
So now we have everything we need in place. All that is left is to deploy it - just a few steps more.
For this we will use Websphere's administration console. As before there are some tricks and tips that must be followed.
The steps below are for the Websphere version stated above, yours may be slightly different.
Log in to the administration console
Access the Enterprise Application menu option under the Applications top menu.
At the top of the Enterprise Application table select Install. Below are installation wizard pages and what needs to done on each:
Preparing for the application installation
Browse to the examples/jee5/booking/dist/jboss-seam-jee5.ear file using the file upload widget.
Select the Next button.
Select installation options
Select the Deploy enterprise beans check box. This is needed unless you used a Websphere tool to package the application.
Select the Next button.
Map modules to servers
No changes needed here as we only have one server. Select the Next button.
Map EJB references to beans This page will list all of the beans that we entered in the web.xml.
Make sure that Allow EJB reference targets to resolve automatically check box is selected. This will tell Websphere to bind our EJB3 beans to the EJB references in the web module.
Select the Next button.
Map virtual hosts for Web modules
No changes needed here. Select the Next button.
Summary
No changes needed here. Select the Finish button.
Installation
Now you will see it installing and deploying your application.
When if finishes select the Save link and you will be returned to the Enterprise Applications table.
Now that we have our application installed we need to make some adjustments to it before we can start it:
Starting from the Enterprise Applications table select the Seam Booking link.
Select the Manage Modules link.
Select the jboss-seam-jee5.war link.
Change the Class loader order combo box to Classes loaded with application class loader first.
Select Apply and then Save options.
Return the Seam Booking page.
On this page select the Class loading and update detection link.
Select the radio button for Classes loaded with application class loader first.
Even though we are not enabling class reload you must also enter a valid number in the Polling interval for updated files text area (zero works fine).
Select Apply and then Save options.
You should verify that the change you just made has been remembered. We have had problems with the last class loader change not taking effect - even after a restart. If the change did not take you will need to do it manually, following these directions:
Open the following file in a text editor of your choice:
$WebSphereInstall/$yourServerName/profiles/$yourProfileName/config/cells/ $yourCellName/applications/Seam Booking.ear/deployments/ Seam Booking/deployment.xml
Modify the following line so that PARENT_FIRST is now PARENT_LAST:
<classloader xmi:
Save the file and now when go to the Class loading and update detection page you should see Classes loaded with application class loader first selected.
To start the application return to the Enterprise Applications table and select our application in the list. Then choose the Start button at the top of the table.
You can now access the application at .
The default timeout period for a Websphere 6.1 Stateful EJB is 10 minutes. This means that you may see some EJB timeout exceptions after some idle time. It is possible to adjust the timeout of the Stateful EJBs on an individual basis, but that is beyond the scope of this document. See the Websphere documentation for details.
Thankfully getting the jpa example to work is much easier than the jee5 example. This is the Hotel Booking example implemented in Seam POJOs and using Hibernate JPA with JPA transactions. It does not require EJB3 support to run.61
This will create container specific distribution and exploded archive directories with the websphere61 label.
This is similar to the jee5 example at Section 28.2.3, “Deploying the application to Websphere”, but without so many steps.
From the Enterprise Applications table select the Install button.
Preparing for the application installation
Browse to the examples/jpa/dist-websphere61/jboss-seam-jpa.war file using the file upload widget.
In the Context root text box enter jboss-seam-jpa.
Select the Next button.
Select the Next button for the next three pages, no changes are needed.
Summary page
Review the settings if you wish and select the Finish button to install the application. When installation finished select the Save link and you will be returned to the Enterprise Applications table.
As with the jee5 example there are some class loader changes needed before we start the application. Follow the instructions at installation adjustments for jee5 example but exchange jboss-seam-jpa for Seam Booking.
Finally start the application by selecting it in the Enterprise Applications table and clicking the Start button.
You can now access the application at the.
The differences between the JPA examples that deploys to JBoss 4.2 and Websphere 6.1 are mostly expected; library and configuration file changes.
Configuration file changes
WEB-INF/web.xml — the only significant change is that Websphere 6.1 only support Servlet 2.4 so the top of this file was changed.
META-INF/persistence.xml — the main changes here are for the datasource JNDI path, switching to the Websphere 6.1 transaction manager look up.
Changes for dependent libraries
WEB-INF/lib — The Websphere version requires several library packages because they are not included as they are with JBoss AS. These are primarily for hibernate, JSF-RI support and their dependencies. Below are listed only the additional jars needed above and beyond the JBoss JPA example.
To use Hibernate as your JPA provider you need the following jars:
Seam requires JSF 1.2 and these are the jars needed for that. Websphere 6.1 ships with its own implementation of JSF 1.1.
Various third party jars that Websphere Websphere. As stated above in Section 28.2, “ The jee5/booking example ” there are some tricky changes needed to get an EJB3 application running. This section will take you through the exact steps.] websphere_example [echo] Accepted project name as: websphere_example [input] Do you want to use ICEFaces instead of RichFaces [n] (y, [n], ) [input] skipping input as property icefaces.home.new has already been set. [input] Select a RichFaces skin .websphere_example] [com.mydomain.websphere_example] org.jboss.seam.tutorial.websphere.action [input] Enter the Java package name for your entity beans [org.jboss.seam.tutorial.websphere.action] [org.jboss.seam.tutorial.websphere.action] org.jboss.seam.tutorial.websphere.model [input] Enter the Java package name for your test cases [org.jboss.seam.tutorial.websphere.action.test] [org.jboss.seam.tutorial.websphere.action.test] org.jboss.seam.tutorial.websphere: /rhdev/projects/jboss-seam/svn-seam_2_0/jboss-seam-2_0/seam-gen/build.properties [echo] Installing JDBC driver jar to JBoss server [copy] Copying 1 file to /home/jbalunas/jboss/jboss-4.2.2.GA/server/default/lib [echo] Type 'seam create-project' to create the new project BUILD SUCCESSFUL Total time: 3 minutes 5 seconds
Type ./seam new-project to create your project and cd /home/jbalunas/workspace/websphere_example to the newly created structure.
We now need to make some changes to the generated project.
Alter the jta-data-source to be DefaultDatasource. We are going to be using the integrated Websphere DB.
Add or change the properties below. These are described in detail at Section 28.WebSphereExtendedJTATransactionLookup"/>
Remove the JBoss AS specific method of exposing the EntityManagerFactory:
<property name="jboss.entity.manager.factory.jndi.name" value="java:/websphere_exampleEntityManagerFactory">
You'll need to alter persistence-prod.xml as well if you want to deploy to Websphere using the prod profile.
As with other examples we need to include this class for DB support. It can be copied from the jpa example into the websphere_example/resources directory.
cp $SEAM/examples/jpa/resources-websphere61/WEB-INF/classes/GlassfishDerbyDialect.class ./resources, we are using Websphere's default datasource)
Enable container managed transaction integration - add the <transaction:ejb-transaction /> component, and it's namespace declaration xmlns:transaction=""
Alter the jndi-pattern to java:comp/env/websphere_example/#{ejbName}
We do not need managed-persistence-context for this example and so can delete its entry.
<persistence:managed-persistence-context
Websphere does not support Servlet 2.5, it required Servlet 2.4. For this change we need to adjust the top of the web.xml file to look like the following:
<?xml version="1.0" encoding="UTF-8"?> <web-app
As with the jee5/booking example we need to add EJB references to the web.xml. These references require the empty local-home to flag them for Websphere to perform the proper binding.
<ejb-local-ref> <ejb-ref-name>websphere_example/AuthenticatorAction</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.tutorial.websphere.action.Authenticator</local> </ejb-local-ref> <ejb-local-ref> <ejb-ref-name>websphere are good to go.
This application has similar requirements as the jee5/booking example.
Change the default target to archive (we aren't going to cover automatic deployment to Websphere).
<project name="websphere_example" default="archive" basedir=".">
Websphere looks for the drools /security.drl file in the root of the war file instead of the root of the websphere ge Websphere dependencies. You will need to copy the el-ri.jar from the $SEAM/examples/jpa/lib directory.
<!-- jsf libs --> <include name="lib/jsf-api.jar" /> <include name="lib/jsf-impl.jar" /> <include name="lib/el-api.jar" /> <include name="lib/el-ri.jar"/>
Third party dependencies. You will need to copy the jboss-archive-browsing.jar from the $SEAM/examples/jpa/lib directory into the the projects /lib directory. You will also need to acquire the concurrent.jar and place it in the same directory. You can get this from any jboss distribution or just search for it.
<!--" />
jboss-seam.jar - this is needed in both the ear base and /lib directory.
<!-- seam jar --> <include name="lib/jboss-seam" /> <!-- seam jar --> <include name="lib/jboss-seam.jar" /> </fileset>
Build your application by calling ant in the base directory of your project (ex. /home/jbalunas/workspace/websphere_example ). The target of the build will be dist/websphere_example.ear .
To deploy the application follow the instructions here : Section 28.2.3, “Deploying the application to Websphere” but use references to this project websphere_example instead of jboss-seam-jee5.