Migration from JHeadstart 9.0.4.x or 9.0.5.x to ADF JHeadstart (beta)

You may have seen our AMIS Library System application (ALS). It is shipped as demo-application (for JHeadstart & Toplink) with JHeadstart 9.0.5.x. We also have a BC4J version of this application, see AMIS Library System – JHeadstart 9.0.5.x (BC4J, JSP+JSTL) Demo Application released. Today I took Build 11 of the ADF JHeadstart beta program and tried to migrate this ALS application (BC4J or ADF BC as I should say now, JSP and Struts) to the ADF JHeadstart design-time and run-time. And since ALS was 100% generated, this was a virtually effortless undertaking.

Since we do not have a formal description of the migration yet – the documentation is still very pre-alpha – I just gave it a try, and before too long, I had a successful migration. Here is what I did:

• Create a copy of the ALS directory, including als.jws, als.jpr and all subdirectories
• Create a Model-only ALS project: Delete all non-ADF BC stuff: the directories web , properties, doc, deploy and META-INF
• Start JDeveloper 10.1.2 after installing ADF JHeadstart 10.1.2 (Build 11)

Create a new workspace ALS_ADF, Technology = Web (Default)

• Add the ALS project to the workspace; it gets upgraded to ADF BC 10.1.2, a very simple step
• Change the definition of the JHeadstart Runtime library in the ADF project; instead of the 9.0.5.x Jhsruntime.jar it should contain the 10.1.2 jhsadfrt.jar file
• Edit the Application Module; go to the Java tab and click on the Class Extends button; have the ApplicationModule extend oracle.jheadstart.model.adfbc.JhsApplicationModuleImpl instead of oracle.jheadstart.model.bc4j.JhsApplicationModuleImpl as it used to extend
• Edit the ViewObjects AlsBooksView, AlsAuthorshipsOfBooksView and AuthorshipsOfAuthorView, more specifically the attributes that are defined with displaytype list or choice: they must be set to displayType=null (empty); their displayType is derived from the displayType on the LookUp in which they are used as base value attribute; in ADF JHeadstart, it is an error to define the displayType as list or choice in the VO for attributes against which a lookup is defined
• Edit the Application Module; go to the Data Model tab; instead of having ViewObject (usages) only at the highest level – as we used to do with JHeadstart, since the JHeadstart actions and handler dealt with master-details themselves without caring for the BC4J data model – we now need to define child ViewObject usages under top level VO usages if we want to have have Master-Detail (and more nested levels) structures in the applications. The ADF Runtime does make use of these master-detail definitions in the Application Module Data Model
• Create a new (View) project
• From the Right Mouse Button Menu on the View project, select the option Enable JHeadstart on this Project. This will set up the basic JHeadstart structure, libraries, JSPs, stylesheet etc. Note that in this release we can JHeadstart enable any existing project; we do not necessarily always create a new empty project with the JHeadstart New Project wizard
• From the Right Mouse Button Menu on the View project, select the option New JHeadstart Application Structure File
• Open the AlsApplicationStructure.xml from the RMB menu on that file, picking the Open option; the XML file opens in the XML editor.
• Open the ALSApplicationStructure.xml in the properties directory in the original ALS application in a text-editor; copy the entire file and paste its contents in the XML editor in JDeveloper to overwrite all of the newly created AlsApplicationStructure.xml. Save and Close the editor.
• Open the Application Structure File Editor from the RMB menu on that file, picking the Edit Application Structure File option; the tool will automatically upgrade the Application Structure File to the new XSD for JHeadstart 10.1.2
• Generate the Application from the button in the top left-hand corner of the Application Structure File editor.
• Copy the amisStyles.css file from the original ALS project to the View project’s webjheadstartcss directory
• Run the index.html file

This completed a successful migration in about 20 minutes! The next image gives you an indication.
However, there is no way to tell this migrated application based on the ADF runtime apart from the original JHeadstart runtime that you see illustrated in Overview of ALS 9.0.5.1.

If your application is not completely generated this will take much longer. Any customizations in the DataObjectHandlers is lost – no Handlers are used in ADF JHeadstart. Any custom Struts Actions that make use of the DataObjectHandlers – same story: they have to be rewritten to use the ADF logic. Customizations to JSP or UIX pages have to be reapplied.

It may very well be that a) I did not take the shortest route in the migration and b) a more automated migration procedure will become available with the ADF JHeadstart production release. However, I am already pretty satisfied that – apart from the annoying View Object attribute corrections and the redefinition of the Application Module’s Data Model – the migration is relatively straightforward. Now the developers and their skills….

Moving one step further

Now of course it would be nice to benefit from the new functionality in ADF JHeadstart. Some examples of interesting new functionality: the Parent and Intersection shuttle, the tree layout, the multi-level master-detail, etc. Also see the viewlets on the JHeadstart homepage on OTN.

First I try to make use of the multi-level nesting of Master-Detail links to create a second detail level under Publishers: Publishers => Books => Copies. Previously this could not be generated. Now I simply update the Data Model in the Application Module to create the additional level. I then create a Detail Group under the Detail Group PublisherPortfolio under the Base Group Publishers.; layoutStyle is table-form, samePage is true. The result is here:

Next I try one of Search facilities: for Books I replace the separate FindPage with a Quick Search facility in the BooksTablePage. You can select any attribute, provide a value and run the search. It looks as follows:

and after performinG the Quick Search:

Let’s see whether the tree layout style works in JSP as well as in UIX…No, unfortunately it is not. Looks like the fancy stuff – detail disclosure, partial page rendering, shuttles, tree-style, bread crumbs – is still UIX only. There is however where JSP beats UIX: Graphs!

As described in the viewlet JHeadstart-ADF Demo 4 – Adding a graph to the JSP application on the JHeadstart Homepage (ADF Sneakpreview), it is relatively easy to add Graphs to ADF based JSP pages (not supported for UIX strangely enough). Note that this is a post-generation change to your application; graphs are not generated by JHeadstart. I would like to give it a try. A pretty non-sensical graph would be a pie-chart on the Publisher’s Detailpage that shows the distribution of the number of pages for each of the books in the Publisher’s Portfolio. I opened the Publisher.jsp page. I dragged the PublisherPortfolio1 Data Control as Graph onto my jsp. I then opened the UI Page Model, clicked on the IteratorBinding for PublisherPortfolio1 and selected Edit from the RMB menu. I then indicated that NumberOfPages would provide the Value while Title would provide the label for the graph. I finally edited the BIGraphDepf1.xml object from the Navigator. I changed the Graph-type to Pie Chart, set the 3d Effect and Color Gradients. The result – in less than 5 minutes – is the following: