From seam-commits at lists.jboss.org Mon Jan 28 17:08:23 2008 Content-Type: multipart/mixed; boundary="===============4506458556876075803==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r7270 - branches/Seam_2_0/doc/reference/en/modules. Date: Mon, 28 Jan 2008 17:08:23 -0500 Message-ID: --===============4506458556876075803== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: jbalunas(a)redhat.com Date: 2008-01-28 17:08:22 -0500 (Mon, 28 Jan 2008) New Revision: 7270 Added: branches/Seam_2_0/doc/reference/en/modules/websphere.xml Log: initial implementation of websphere chapter Added: branches/Seam_2_0/doc/reference/en/modules/websphere.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- branches/Seam_2_0/doc/reference/en/modules/websphere.xml = (rev 0) +++ branches/Seam_2_0/doc/reference/en/modules/websphere.xml 2008-01-28 22:= 08:22 UTC (rev 7270) @@ -0,0 +1,946 @@ + + Seam on IBM's Websphere + = + 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 0= 7) + EJB3 feature pack which provides some support for + EJB3 and JPA. Currently there + is no true JEE5 offering from IBM. This causes so= me + 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 re= search + 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 al= so deploy + the the JPA example application. + = +
+ Websphere environment and deployment information + = + Websphere is a commercial product and so we will not discuss t= he + details of its installation other than to say follow the directio= ns + 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. + = +
+ Installation versions and tips + All of the examples and information in this chapter are bas= ed on + the the latest version of Websphere at the time of this writin= g. + + + + Websphere Application Server 6.1.0.13 + + + + Feature Pack for EJB 3.0 for Websphere Application Se= rver + 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 n= ot + ensure that your server will have the proper environment for E= JB3 + 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. +
+ = +
+ Required custom properties + There are a couple of Websphere custom properties that are = required + for Seam integration. These properties are not needed specifi= cally + for seam, but work around some issues with Websphere. These are + set following the instructions here : + Setting web container custom properties + = + + + prependSlashToResource =3D "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 expecte= d. + + Detailed can be found at: + + SRVE0238E: Resource paths must have a leading + slash + + + + com.ibm.ws.webcontainer.invokefilterscompatibil= ity + =3D "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 mod= ern web + applications where filters or servlets are used to proce= ss + resource requests like these. This issue manifests itsel= f as + failures to retrieve JavaScript, CSS, images, etc... when + requesting a web page. + Detailed can be found at: + + PK33090; 6.1: A filter that serves a file does not po= p-up an + alert message + + +
+
+ = +
+ The <literal>jee5/booking</literal> example + = + The jee5/booking example is based on the H= otel + Booking example (which runs on JBoss AS). Out of the box it is de= signed = + 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. + = +
+ Configuration file changes + = + Below are the configuration file changes that are need to t= he base + example. + = + + + + resources/WEB-INF/components.xml + + + 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: + = + = + + ]]> + + + + resources/WEB-INF/web.xml + + + This is the first place that we notice an unexpect= ed + change because this is not full jee5 + implementation. + 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: + = + = + + + ]]> + Next you have to make some changes to the EJB refe= rences + 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. + = + = + + = + jboss-seam-jee5/AuthenticatorAction = = + Session = + + org.jboss.seam.example.booking.Authenticator = + = + = + = + jboss-seam-jee5/BookingListAction = + Session = + + org.jboss.seam.example.booking.BookingList = + = + = + = + jboss-seam-jee5/RegisterAction = + Session = + + org.jboss.seam.example.booking.Register = + = + = + = + jboss-seam-jee5/ChangePasswordAction = = + Session = + = + org.jboss.seam.example.booking.ChangePassword = + = + = + = + jboss-seam-jee5/HotelBookingAction = + Session = + + org.jboss.seam.example.booking.HotelBooking = + = + = + = + jboss-seam-jee5/HotelSearchingAction = = + Session = + = + org.jboss.seam.example.booking.HotelSAll of the examples and in= formaearching = + = + = + + jboss-seam-jee5/EjbSynchronizations = + Session + + org.jboss.seam.transaction.LocalEjbSynchronizations + ]]> + The important changes are that there is an empty + local-home element for each EJB. + This is the signal to Websphere so that it will make = the + correct bindings behind the scenes between the web mo= dule + and the EJB3 beans. The ejb-link + element is simply not used. + + + + + resources/META-INF/persistence.xml + + + For this example we will be using the default + datasource that comes with Websphere. To do this chan= ge the + jta-data-source element like below= . + DefaultDatasource + ]]> + Then we need to adjust some of the hibernate + properties. First comment out the Glassfish propertie= s. + Next you need to add/change the properties below. + = + = + --> + + + + ]]> + + + + + hibernate.transaction.manager_looku= p_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. Al= so + if this is set to true an + exception will be thrown by Websphere when t= he + EJBContext is looked up. + = + = + + + + hibernate.dialect + — From WAS 6.1.0.9 on the embedded DB = was + switched to the same Derby DB in + Glassfish. + + + + + + + resources/GlassfishDerbyDialect.class + + + You will need to get the + GlassfishDerbyDialect.class and + copy it into the /resources + directory. The class exists in the JPA example and ca= n be + copied using the command below assuming you are in + jee5/booking directory: + = + = + + This class will be put into the + jboss-seam-jee5.jar file using + changes to the build.xml discussed later. + + + + resources/import.sql + + + This file must also be copied from the JPA example + because either the Derby DB or the dialect does not s= upport + changes to the ID column. The files + are identical except for the column difference. Use t= he + following command to make the copy + = + = + + + + + + = +
+ = +
+ Building the <literal>jee5/booking</literal> + example + = + In order to get the changes we have made into our applicati= on 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. + = +
+ New libraries dependencies + + + + 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 expression language libraries as well: + + + el-api.jar + + + + el-ri.jar + + + + + + jboss-seam.jar — for + some reason when deploying the application through + the Websphere administration console it can not fi= nd + 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. + + + Then finally by removing the + log4j.jar all of the log output + from our application will be added to the Websphere + logging. Addition steps are required to fully + configure log4j and those are outside of the scope= of + this document. + + + = +
+ = +
+ Updating the <literal>build.xml</literal> file + = + 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. + = + = + + + + + + + ]]> + + = + Next we need to add the library dependencies discussed a= bove. + For this add the following to bottom of the + ear.lib.extras fileset entry. + = + = + --> + + + + + +]]> + + = + Now all that is left is to execute the ant + archive task and your application files should be= in + the jee5/booking/dist directory. + +
+ = +
+ = +
+ Deploying the application to Websphere + = + So now we have everything we need in place. All that is lef= t is to + deploy it - just a few steps more ;) + For that 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 t= he + 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 a= nd + 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 say + 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 rel= oad + 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 stuck. We 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 te= xt + editor of your choice: + = + = + + + + + Modify the following line so th= at + PARENT_FIRST + is now + PARENT_LAST: + = + = + ]]> + + + + Save the file and now when go t= o 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 + http://localhost:9080/seam-jee5/ + . + + = + + A note about Websphere Stateful bean timeouts + The default timeout period for a Websphere 6.1 Statef= ul + EJB is 10 minutes. This means that you may see some EJB= timeout + exceptions after some idle time. It is possible to adju= st the + timeout of the Stateful EJBs on an individual basis, but = + that is beyond the scope of this document. See the Webs= phere + documentation for details. + + + +
+ = +
+ = +
+ The <literal>jpa</literal> booking example + 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 Hiberna= te JPA + with JPA transactions. It does not require EJB3 support to + run. + = + The example already has a breakout of configurations and build + scripts for many of the common containers including Websphere. + = + First thing we are going to do is build and deploy that exampl= e. Then + we'll go over some key changes that we needed. + = +
+ Building the <literal>jpa</literal> example + Building it only requires running the correct ant comma= nd: + ant websphere61 + This will create container specific distribution and explod= ed + archive directories with the websphere61= label. +
+
+ Deploying the <literal>jpa</literal> example + This is similar to the jee5 example a= t = + , but without so m= any steps. + + + + From the Enterprise Applications t= able + select the Install button. + + + Preparing for the application + installation + + + Browse to the = + examples/jpa/dist-websphere61/jb= oss-seam-jpa.war + file using the file upload widget. + + + + In the Context root= text box + enter jboss-seam-jpa. + + + + Select the Next but= ton. + + + + + + Select the Next button for t= he next + three pages, no changes are needed. + + + + Summary page + + + Review the settings if you wish and se= lect + the Finish button to i= nstall + the application. When installation finis= hed select the + Save link and you will be retur= ned to the = + Enterprise Applications table. + + + + + + + + + As with the jee5 example there are= some + class loader changes needed before we start the applicat= ion. + Follow the instructions at + but exchange jboss-seam-jpa for Seam Booking. + + + + Finally start the application by selecting it in the = + Enterprise Applications table and cli= cking + the Start button. + + + + You can now access the application at the = + http://localhost:9080/jboss-seam-jpa/index.html= . + + + +
+ = +
+ Whats different for Websphere 6.1 + The differences between the JPA examples that deploys to JB= oss + 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 chang= ed. + + + + + META-INF/persistence.xml + — the main changes here are for the + datasource JNDI path, switching to the Websphere + 6.1 transaction manager look up class, and + changing the hibernate dialect to be + GlassfishDerbyDialect + . + + + + WEB-INF/classes/GlassfishDerbyDialect.= class + — this class is needed for the + hibernate dialect change to + GlassfishDerbyDialect + + + + import.sql — + either for the dialect or Derby DB the + ID column can not be + populated by this file and was removed. + + + + + + Changes for dependent libraries + WEB-INF/lib — The Websphere + version requires several library packages because they a= re + not included as they are with JBoss AS. These are primar= ily 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 n= eed + the following jars: + + + + hibernate.jar + + + + + hibernate-annotations.jar + + + + + hibernate-commons-annotations= .jar + + + + + hibernate-entitymanager.jar + + + + + hibernate-validator.jar + + + + + commons-collections.jar + + + + + jboss-archive-browsing.jar + + + + + + Seam requires JSF 1.2 and these are the jars= needed + for that. Websphere 6.1 ships with its own impl= ementation + of JSF 1.1. + + + + jsf-api.jar + + + + + jsf-impl.jar + + + + el-ri.jar + + + + el-api.jar + + + + + + Various third party jars that Websphere need= s: + + + antlr.jar + + + + cglib.jar + + + + asm.jar + + + + dom4j.jar + + + + + javassist.jar + + + + + + + + = +
+ = + = +
+ = + --===============4506458556876075803==--