From seam-commits at lists.jboss.org Thu Jan 29 10:53:12 2009 Content-Type: multipart/mixed; boundary="===============8624837525922830636==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r9987 - trunk/doc/Seam_Reference_Guide/en-US. Date: Thu, 29 Jan 2009 10:53:12 -0500 Message-ID: --===============8624837525922830636== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: manaRH Date: 2009-01-29 10:53:12 -0500 (Thu, 29 Jan 2009) New Revision: 9987 Modified: trunk/doc/Seam_Reference_Guide/en-US/Websphere.xml Log: JBSEAM-3570 Modified: trunk/doc/Seam_Reference_Guide/en-US/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 --- trunk/doc/Seam_Reference_Guide/en-US/Websphere.xml 2009-01-29 15:52:44 = UTC (rev 9986) +++ trunk/doc/Seam_Reference_Guide/en-US/Websphere.xml 2009-01-29 15:53:12 = UTC (rev 9987) @@ -1,24 +1,18 @@ - Seam on IBM's Websphere + Seam on IBM's Websphere AS = - Websphere 6.1.x is IBM's application server offering. The latest - release is 6.1.0.19 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. + Websphere AS V7 is IBM's application server offering. This releas= e is + fully Java EE 5 certified. = - 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 + First we will go over some basic information about the Websphere = AS + environment that we used for these examples. We will + go over the details of those steps with the JEE5 booking example. We= will also deploy the JPA example application. =
- Websphere environment and deployment information + Websphere AS environment and deployment information = - Websphere is a commercial product and so we will not discuss t= he + Websphere AS is a commercial product and so we will not discus= s the 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, @@ -26,93 +20,22 @@ examples. =
- Installation versions and tips + Installation versions All of the examples and information in this chapter are bas= ed on - the version 6.1 of Websphere at the time of this writing. + the version V7 of Websphere AS at the time of this writing. - Websphere Application Server 6.1 + url=3D"http://www.ibm.com/developerworks/downloads= /ws/was"> + Websphere Application Server V7 = = - - - Feature Pack for EJB 3.0 for Websphere Application Se= rver - V6.1 (6.1.0.13) - - - - Fix Pack for Websphere Application Server - V6.1 (6.1.0.19) - = = - 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 management tool. - It is highly recommended to patch Websphere by - latest fix pack, at the time of this writing it is 6.1.0.19 - - A note about restarting the server - There are times that restarting the server will be required= after - deploying or changes the examples in this chapter. Its does no= t seem - like every change requires a restart. If you get errors or exc= eptions - after modifying a property or deploying an application try to = restart - the server. + After installing Websphere AS, create server profile with P= rofile Management Tool, if you + didn't create profile in installation process. + =
- = -
- 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 - - -
+ =
=
@@ -125,11 +48,6 @@ $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 = @@ -143,7 +61,7 @@ We need to change the way that we look up EJBs for - Websphere. We need to remove the + WAS. We need to remove the /local from the end of the jndi-pattern attribute. It should look like this: @@ -154,98 +72,94 @@ ]]> + = - resources/WEB-INF/web.xml + + resources/META-INF/ejb-jar.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 requires Servlet - 2.4. For this change we need to adjust the = top of - the web.xml file to look like the - following: + We need to replace the /local string from ejb-ref-name. = + See at the following final code: = + + + + + RegisterAction + + jboss-seam-jee5/AuthenticatorAction + Session + org.jboss.seam.example.booking.Authenticator + + + ]]> = - - - ]]> - Next, we have to make some changes to the EJB refe= rences + + + = + + resources/WEB-INF/web.xml + + = + 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 + what will allow WAS to bind automatically the EJB3 re= ferences in the web module to the the actual EJB3 beans in the EAR - module. Replace all of the + module. Replace all of the /local strings in 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.HotelSearching = - = - = - jboss-seam-jee5/EjbSynchronizations = + 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.HotelSearching + + + + jboss-seam-jee5/EjbSynchronizations + Session org.jboss.seam.transaction.LocalEjbSynchronizations ]]> = - The important change is that there is an empty - local-home element for each EJB. - This tells Websphere to make the correct bindings bet= ween = - the web module and the EJB3 beans. The = - ejb-link element is simply not use= d. = - Note also that EjbSynchronizations is a built-in Seam EJB and not part of the Hotel Booking ex= ample. This means that if your application's components.xml= = - specifies transaction:ejb-transaction - , then you must include: + specifies transaction:ejb-transaction, + then you must include: myapp/EjbSynchronizations @@ -263,7 +177,7 @@ For this example we will be using the default - datasource that comes with Websphere. To do this chan= ge the + datasource that comes with WAS. To do this change the jta-data-source element: DefaultDatasource @@ -287,7 +201,7 @@ hibernate.transaction.manager_looku= p_class — Standard Hibernate transaction - manager property for Websphere 6.X + manager property for WAS 6.X and 7 @@ -295,7 +209,7 @@ — 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 + exception will be thrown by WAS when the EJBContext is looked up. = = @@ -305,31 +219,30 @@ hibernate.dialect — From WAS 6.1.0.9 on the embedded DB = was - switched to the same Derby DB in - Glassfish. + switched to the same Derby DB as is in + Glassfish v2. - resources/GlassfishDerbyDialect.class + src/GlassfishDerbyDialect.java 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 + GlassfishDerbyDialect.java and + copy it into the /src + directory. The java class exists in the JPA example s= ource directory and can be copied using the command below assuming you are in jee5/booking directory: = = +cp ../../jpa/src/GlassfishDerbyDialect.java + ./src]]> This class will be put into the - jboss-seam-jee5.jar file using - changes to the build.xml discussed later. + jboss-seam-jee5.jar file. @@ -344,7 +257,7 @@ = = +cp ../../jpa/resources-websphere7/import.sql ./resources]]> @@ -359,60 +272,16 @@ 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 + application in order to work with WAS. This section will cover what changes are needed to the build.xml. =
- New libraries dependencies - - - - JSF libraries — Websphere 6.1 comes with - its 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 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. - - - Finally we remove the log4j.jar = + Library dependency changes + We remove the log4j.jar = so that all of the log output from our application= will = - be added to the Websphere log. Additional steps ar= e = + be added to the WAS log. Additional steps are = required to fully configure log4j and those are ou= tside of the scope of this document. - - - =
=
@@ -421,9 +290,8 @@ 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: + jboss-seam-jee5.jar. = + : = = @@ -431,43 +299,10 @@ - ]]> = - = - 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: - - = - = - --> - - - - - -]]> - = - We also need to add richfaces-api.jar, jsf-impl.jar and = - el-ri.jar into WEB-INF/lib of the war file. Add the followi= ng - fileset after ear.lib.extras fileset. = - = - - - = - ]]> - - A note about copying JSF and EL jars - There is a class loading issue with WebSphere, which causes th= e jars - from ear lib directory to not be available when the web module is = - initialized. - - = Now all that is left is to execute the ant archive task and the built application will be in the jee5/booking/dist directory. @@ -484,25 +319,26 @@ 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. + The steps below are for the WAS version stated above. = + The ports are default values, if you changed them substitute your= values. Log in to the administration console = = - + = + or = + - Access the Enterprise - Application menu option under the - Applications top menu. + Access the Websphere enterprise + applications menu option under the + Applications --> Application Type = left side menu. - At the top of the Enterprise - Application table select + At the top of the Enterprise + Applications table select Install. Below are installation wizard pages and what needs to done on each: @@ -521,6 +357,16 @@ Next button. + + Select the + Fast Path + button. + + + Select the + Next + button. + = = @@ -529,9 +375,10 @@ Select the Deploy - enterprise beans - check box. This is needed unless you - used a Websphere tool to package the + enterprise beans and = + Allow EJB reference target= s to resolve automatically + check boxes. This is needed unless = you + used a Websphere AS tool to package= the application. @@ -539,6 +386,8 @@ Next button. + = + = @@ -554,38 +403,6 @@ - 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 @@ -604,7 +421,7 @@ application. - When if finishes select the + When it finishes select the Save link and you will be returned to the Enterprise @@ -617,7 +434,7 @@ Now that we have our application installed we need= to - make some adjustments to it before we can start it: + make some adjustments to it before we can start it: Starting from the Enterprise @@ -631,22 +448,21 @@ Select the - jboss-seam-jee5.war + jboss-seam-jee5-booking.war link. Change the Class loader order combo box to = Classes loaded with application - class loader first. + class loader first (parent last).<= /para> Select Apply and then Save options. - Return the Seam - Booking page. + Return to the Seam Booking page. On this page select the Class @@ -657,59 +473,12 @@ 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 been remembered. We have had proble= ms 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 @@ -720,11 +489,11 @@ You can now access the application at - http://localhost:9080/seam-jee5/ + http://localhost:9080/seam-jee5-booking/inde= x.html . = - + =
= @@ -744,8 +513,7 @@ 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. + with JPA transactions. It does not use EJB3. = The example already has a breakout of configurations and build scripts for many of the common containers including Websphere. @@ -756,9 +524,9 @@
Building the <literal>jpa</literal> example Building it only requires running the correct ant comma= nd: - ant websphere61 + ant websphere7 This will create container specific distribution and explod= ed - archive directories with the websphere61= label. + archive directories with the websphere7 = label.
Deploying the <literal>jpa</literal> example @@ -776,19 +544,20 @@ Browse to the = - examples/jpa/dist-websphere61/jb= oss-seam-jpa.war + examples/jpa/dist-websphere7/jbo= ss-seam-jpa.war file using the file upload widget. - In the Context root= text box - enter jboss-seam-jpa. - + Select the + Fast Path + button. - Select the Next but= ton. - - + Select the + Next + button. + = @@ -797,6 +566,20 @@ + Map context roots for Web modules + = + + In the Context root text b= ox + enter jboss-seam-jpa. + + + + Select the Next button. + + = + + + Summary page @@ -809,6 +592,7 @@ + = @@ -816,7 +600,7 @@ 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. + but exchange jboss-seam-jpa_war for <= literal>Seam Booking. @@ -834,34 +618,40 @@
=
- Whats different for Websphere 6.1 + What's different for Websphere AS V7 The differences between the JPA examples that deploys to JB= oss - 4.2 and Websphere 6.1 are mostly expected; library and + 4.2 and Websphere AS V7 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 + transaction manager look up class, and changing the hibernate dialect to be GlassfishDerbyDialect . - WEB-INF/classes/GlassfishDerbyDialect.= class + WEB-INF/components.xml + — the change here is jndi-patter= n + without /local string. + + + + META-INF/ejb-jar.xml + — the same change in ejb-ref-nam= e, + where is replace /local string in = + jboss-seam-jee5/AuthenticatorAction. + + + + src/GlassfishDerbyDialect.java — this class is needed for the hibernate dialect change to GlassfishDerbyDialect @@ -873,15 +663,14 @@ 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 + The Websphere version requires several library packag= es because they are not included as they are with JBoss AS. These are primar= ily for - hibernate, JSF-RI support and their dependencies. Below= are = + hibernate and their dependencies. Below are = listed only the additional jars needed above and beyond = the JBoss = JPA example. @@ -927,31 +716,6 @@ - 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: @@ -993,7 +757,7 @@ =
Deploying an application created using - <literal>seam-gen</literal> on Websphere 6.1.0.13 + seam-gen on Websphere V7 = seam-gen is a very useful tool for develope= rs to quickly get an application up and running, and provides a foun= dation @@ -1145,18 +909,18 @@ - resources/GlassfishDerbyDialect.class + src/GlassfishDerbyDialect.java - As with other examples we need to include this cla= ss for + As with other examples we need to include this jav= a class for DB support. It can be copied from the jpa example into the - websphere_example/resources + websphere_example/src directory. = +cp $SEAM/examples/jpa/src/GlassfishDerbyDialect.java + ./src]]> @@ -1218,41 +982,24 @@ resources/WEB-INF/web.xml - - 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: - = - - - ]]> - = + = 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 + references require replacing /local string in = + ejb-ref-name to flag them for Websphere to perform the proper binding. = = - = - websphere_example/AuthenticatorAction = = - Session = - - org.jboss.seam.tutorial.websphere.action.Authenticator = - + + websphere_example/AuthenticatorAction + Session + org.jboss.seam.tutorial.websphere.action.Authenticator + = = websphere_example/EjbSynchronizations = Session - org.jboss.seam.transaction.LocalEjbSynchronizations ]]> @@ -1262,23 +1009,23 @@
Creating the <literal>AuthenticatorAction</literal> EJB - We want to take the existing Authenticator + We want to take the existing Authenticator Seam POJO component and create an EJB3 out of it. - + Change the generated Authenticator class - Rename the class to + Rename the class to AuthenticatorAction - Add the @Stateless + Add the @Stateless annotation to the new AuthenticatorAction class. - Create an interface called + Create an interface called Authenticator which AuthenticatorAction implements (EJB3 requires session beans to have a @@ -1345,62 +1092,6 @@ ]]> - We need to ge the - GlassfishDerbyDialect.class into - our application jar. To do that find the - jar task and modify the top of it so = that - it looks like this: - - = - = - - - - - - - - -...]]> - - - Next we need to get the - jboss-seam.jar into the base of the - EAR file. For deployment Websphere - requires this jar to be in both the /lib - directory and at the base of the EAR.= You - must add the following to the archive - task: - = - = - - -]]> - So that the whole archive task loo= ks - like: - = - = - - - - - - - - - - - - - -]]> - - Now we need to get extra jars into the = build.xml. Look for the = <fileset dir=3D"${basedir}"> se= ction = @@ -1417,9 +1108,7 @@ - - - + @@ -1451,17 +1140,6 @@ ]]> - JSF dependencies. You will need to copy the = - el-ri.jar from the = - $SEAM/examples/jpa/lib directory.<= /para> - - - - - ]]> - - Third party dependencies. @@ -1477,8 +1155,7 @@ jboss-seam.jar - this is nee= ded in - both the ear base and = - /lib + the ear base directory. @@ -1505,13 +1182,7 @@ - = - - - - - - = + @@ -1525,20 +1196,7 @@ = -]]> - - The last step is to add jsf-impl.jar = - and el-ri.jar to the war target. Look for = - copy todir=3D"${war.dir}/WEB-INF/lib" and add = the = - following: - - - - - = - - -]]> +]]> = = @@ -1548,7 +1206,6 @@ Building and deploying the seam-gen'd application to Webs= phere = - = Build your application by calling --===============8624837525922830636==--