|
|
|
|
|
| Jaffa Migration Notes v1.3.0 |
|
This guide will document the steps that we went through when upgrading an application based on Jaffa v1.2, to the new Jaffa v1.3 release. This upgrade will not involve taking advantage of any new features, just the shortest / quickest path to move an existing project onto the next release. Note: In this document it is assumed that we are working from a sandbox located on d:\sandbox on a Windows 2000 machine. If you have your application in another place or are using a different operating system, you'll have to take this into account when looking at the examples below.
|
| 1. Building the new Jaffa | |
|
Assumption - Rather than taking a download from sourceforge, we will build Jaffa from the source Step 1 - Checked out Jaffa Code (At time of writing, the HEAD branch is the v1.3 release) Step 2 - Edit D:\sandbox\JaffaCore\build\Jaffa.ant.properties, to point to 3rd-party libs
The contents of D:\sandbox\MyJaffa is...
\lib
j2ee.jar
jaxb-api.jar
jaxb-libs.jar
jaxb-ri.jar
msbase.jar
mssqlserver.jar
msutil.jar
mysql-connector-java-3.0.6-stable-bin.jar
oracle12.jar
\build
sandbox.ant.properties
Note: this 'sandbox.ant.properties' contains information about a 'real' database, needed for unit and httpunit tests. By default these tests are configured to run against oracle. For the purpose of this exercise, we are not worried about the tests (we assume jaffa has been full tested!), we just care about getting the 3 distribution files jaffa.jar, jaffa-tools.jar and jaffa-html.zip Step 3 - Using Apache ant (v1.5.3 or higher) run D:\sandbox\JaffaCore\build\build.xml Here is the ant output for comparison with your own version... Buildfile: D:\sandbox\JaffaCore\build\build.xml init: compile: [mkdir/Jaffa] Created dir: D:\sandbox\JaffaCore\dist\classes [depend/Jaffa] Deleted 0 out of date files in 0 seconds [javac/Jaffa] Compiling 655 source files to D:\sandbox\JaffaCore\dist\classes JaffaJAR: [jar/Jaffa] Building jar: D:\sandbox\JaffaCore\dist\jaffa.jar JaffaToolsJAR: [jar/Jaffa] Building jar: D:\sandbox\JaffaCore\dist\jaffa-tools.jar copyHtml: [mkdir/Jaffa] Created dir: D:\sandbox\JaffaCore\dist\html\jaffa [copy/Jaffa] Copying 94 files to D:\sandbox\JaffaCore\dist\html\jaffa [mkdir/Jaffa] Created dir: D:\sandbox\JaffaCore\dist\html\WEB-INF [copy/Jaffa] Copying 6 files to D:\sandbox\JaffaCore\dist\html\WEB-INF JaffaHtmlZip: [zip/Jaffa] Building zip: D:\sandbox\JaffaCore\dist\jaffa-html.zip core: BUILD SUCCESSFUL Total time: 34 seconds |
| 2. Copy Jaffa Libs to Your Project | ||||
|
In this project (D:\sandbox\MyProject) i have a \lib folder for all my required JAR's, I also have \lib\jaffa for all the Jaffa libraries (jaffa.jar, jaffa-tools.jar and jaffa-html.zip) and \lib\jaffaext for all the external jaffa libraries that jaffa needs.
Note, that this project used SQL Server 2000, so only has that set of drivers in \lib Step 1 - Replace the three files in \lib\jaffa with new ones in D:\sandbox\JaffaCore\dist Step 2 - Copy across the supporting JAR's from D:\sandbox\JaffaCore\lib to D:\sandbox\MyProject\lib\jaffaext Step 3 - Remove old JAR's. In this case in D:\sandbox\MyProject\lib\jaffaext the following are now obsolete
Step 4 - Build Your App Now try a 'Clean' build (ie delete any existing compiled code!) on your project and see what you get... We recommend doing the compile with 'deprecation' turned on, so we can see if what Jaffa classes you are using that need to be modified. In this case we get one warning...
[javac] D:\sandbox\MyProject\source\java\com\xxx\user\services\MyUserSessionFilter.java:23:
warning: org.jaffa.presentation.portlet.session.UserSessionFilter in org.jaffa.presentation.portlet.session has been deprecated
[javac] public class MyUserSessionFilter extends UserSessionFilter {
If you look at the release notes for v1.3 you will see the following line...
What's Deleted/Deprecated ===================================================== ... 10) UserSessionFilter has been deprecated as it has been superceded with the new PortletFilter With the use of Struts 1.1 we have stopped using a custom version of the Struts Action Controller, and now put all the Jaffa functionality for security, session management, etc into one filter 'org.jaffa.presentation.portlet.PortletFilter' With v1.2 we used to extend UserSessionFilter, and then provide and implementation for the method
Now we can do a similar thing but we extend PortletFilter, and provide an implementation for the method
So as you can see, all that needs to be done to fix the application, is to extend a different class! WARNING: it is recommended that just don't just do a full compile and assume is all well if your app compiles, as you may have used parts of Jaffa in ways we did not expect, so please review the document "D:\sandbox\JaffaCore\RELEASE_NOTES_1_3.txt") also available on the Jaffa web site, and see if any other changes may impact your code.
|
| 3. Changing Your Configuration | |||||||||||
|
So it build OK, but we're not done yet. The biggest change with Jaffa v1.3 is that we have moved to use Struts v1.1 as the underlying presentation libraries. In v1.2 we used Struts v1.0, and there are some significant changes to some of the struts and web config files that come along with this. Note: If you want more information about how Jaffa v1.3 and Struts 1.1 (and Tiles) interoperate, there is a separate document "D:\sandbox\JaffaCore\StrutsVsJaffa.txt" which discusses the differences and which new struts features are not compatible with Jaffa Step 1 - Change web.xml to use the new Filter Step 1.1 - Make sure were using Servlet spec 2.3, as 2.2 does not support Filters!
Step 1.2 - Add the filter definition Assuming from above that we haven't renamed MyUserSessionFilter, (really we should call this MyPortletFilter now!)
Step 1.3 - Add the Servlet definition
Note: The only change here is that we used to use a different class from Jaffa (org.jaffa.presentation.portlet.PortletServlet) but now we use a filter, and again use the vanilla Struts Controller (org.apache.struts.action.ActionServlet) Step 1.4 - Change the TagLib entries These are the new entries that are used with Struts 1.1
Step 1.5 - Catch ComponentExpired Errors From the v1.3 Release Notes
What's Changed
=====================================================
2) struts-config.xml: Made it compatible with the new Struts1.1 DTD.
Removed the references to the Logon component.
Moved the mapping for pageExpired.jsp from struts-config.xml to web.xml
The new way to map this error to a web page is as follows...
Step 2 - Update struts-config.xml to the new format Step 2.1 - Update the DTD to the latest spec
Step 2.2 - Remove old admin functions (if you still have them)
If you are using 'Code Merging' in your struts-config.xml, a typical Jaffa install will look like...
Step 3 - Update the JDBC Engine config (D:\sandbox\MyProject\source\java\resources\jdbc-engine.xml) From the v1.3 Release Notes
What's Changed
=====================================================
5) Revamped the init.xml to conform to the 'init_1_0.xsd' schema. Some of the major changes are
a) New elements - connection-factory, hitlistSize, jdbcSecurityPlugin, usePreparedStatement
b) The parameters are now children of the connection-factory element
c) New parameters to support DbcpDataSourceConnectionFactory - maxWait, testOnBorrow, testOnReturn, validationQuery
d) New parameters to support JndiDataSourceConnectionFactory - jndiDataSourceName
If you forget to change this file from the v1.2 format and start your web app you will most likely get the following error...
In Jaffa v1.2 my 'jdbc-engine.xml' file looked like this
Note, the parameters inside the << >> brackets are substituted in the ant build process with real values. The new version of this file for Jaffa v1.3 (assuming we still want the same connection pool mechanism as used in v1.2) looks like...
Step 4 - In framework.properties remove the deprecated values
|
| 4. Changes to the JSP's | |
|
From the v1.3 Release Notes
Improvements
=====================================================
3) Made the following changes in ButtonTag, CheckBoxTag, DateTimeTag, DropDownTag, EditBoxTag, FooterTag,
FormTag, GridColumnTag, GridTag, HeaderTag, ImageTag, LookupTag, RadioButtonTag, TableTag, TagHelper,
TreeTag, UserGridColumnTag, UserGridTag
a- Used pageContext.REQUEST_SCOPE when invoking pageContext.setAttribute()
b- Replaced 'pageContext.getAttribute()' invocations with 'pageContext.findAttribute()'
This was done to allow Jaffa widgets to be spread across multiple JSPs in template environments like the
TILES framework. This would allow us to paint the FormTag in a Layout JSP and the widgets in the inner Tile JSP.
Although the patterns have been refactored, there are some changes needed to the JSP's, as we are now setting all the attributes in the request-scope, as opposed to the page-scope in Jaffa v1.2
So all JSP's that use " If you don't do this you the following tag
root cause javax.servlet.ServletException: Define tag can contain only one of name attribute, value attribute, or body content at org.apache.jasper.runtime.PageContextImpl.handlePageException(PageContextImpl.java:533) at org.apache.jsp.results_jsp._jspService(results_jsp.java:554) ... Because the 'name' attribute will be null, as the form name it is no-longer in the page scope.
|
| 5. New Labels |
|
Step 1 - In ApplicationResources.properties add
exception.org.jaffa.exceptions.ComponentExpiredException.componentExpired=The page you are trying to view has expired! exception.org.jaffa.presentation.portlet.session.UserSessionSetupException.setupException=Error in setting up the UserSession
|
| 6. Congratulations |
|
Test You App, it should now be working with Jaffa v1.3
|
|
|