Should we use JHeadstart for our ADF Project? It is NOT a black or white decision!

One of things we do at AMIS is develop sometimes fairly complex applications built on the Oracle ADF technology stack. On several occasions, we have been working closely together with customers with their own development staff, often very experienced in the classic Oracle development tools (primarily Oracle Forms, often Oracle Designer). The objective of our collaboration is twofold: deliver an ADF application and bring the customer’s development team up to speed with Oracle ADF technology. This type of project fits very well with our organization’s culture and the drive of my colleagues and me. We very much like to work together and share information, knowledge and skills. (this blog being an example of that ingrained quality).

Now a question we have to address in each of the situations described above is whether or not to use JHeadstart in each project. Sometimes people approach this question as very "black or white": either we use JHeadstart, or we don’t. However, like on so many occasions, the question is one with several gray-shades as well.....

JHeadstart is a combination of a tool (a generator) and a run-time framework. The first allows you to generate ADF artefacts – primarily JSF pages, ADF PageDefinitions, Menu, Resource Bundles – based on declaratively defined meta-data (such as blocks, items, layout style, regions, prompt, default values etc.). The second provides a generic layer or infrastructure on top of standard ADF with faclities required in many if not all applications (think for example security, query capability, i18n, File processing and context rich navigation).

My claim in this article is that there are very few ADF projects that will not benefit from using JHeadstart.

The essential nuance we need to talk about before continuing this discussion, is establishing what it means to ‘use JHeadstart’ on a project. For many people, using JHeadstart equates to 100% generating the entire ADF application. While very few applications are suitable for such a complete generation approach, the (rash) conclusion then often is that JHeadstart is suitable for very few applications. And that is the wrong conclusion.

So what does it mean to use JHeadstart?

The one thing using JHeadstart entails is leveraging its run-time ADF infrastructure. The development of JHeadstart’s generators – starting back in 2001 – has always gone hand-in-hand with the development of run-time components that the generated pages and other artefacts benefit from. These run-time components can be leveraged from non-generated pages as well as from the pages generated by the JHeadstart application generator. They embody many best practices for using ADF, gathered over the years. Some of them are similar to or even copied from elements in the SRDemo, many are original implementations of ADF patterns.

Among the facilities available from the JHeadstart run-time infrastructure are:

  • advanced i18n implementation, including database based (and run-time maintainable) resource bundles
  • breadcrumbs
  • context rich inter-page navigation (deep-linking)
  • Security (authentication and authorization), both for JAAS and custom implementations
  • complex default values
  • advanced search
  • custom (or flex) items that can be configured at run-time
  • file uploading and downloading (from/to the database)
  • plumbing for List of Values, Wizards, Trees and Shuttles
  • table (multi-record) layout with insert as well as update and delete capability
  • client side (JavaScript) support, for example for warning the end user when she is about to leave a page that has outstanding, unsubmitted changes

Note: the JHeadstart run-time comes with all source code and documentation. It can easily be extended, overridden and decorated. If would even be useful to use it as an example for developing your own generic ADF infrastructure.

The next level of using JHeadstart would be to utilize the JHeadstart Application Generator. However, that is not an all or nothing approach. Pages in the application can be categorized in four categories:

  • complete generation – the page design and functional requirements are such that the JHeadstart generation result is satisfactory
  • complete customized generation – generation followed by post-generation manual changes to for example the JSF page or the managed beans, Page Definitions that is then made generatable through the use of custom templates
  • initial generation only – the page is initially generated with the main data usages in place; this results in a JSF page with ADF PageDefinition and integrated into the generic JHeadstart resources (regions, stylesheets, main menu, navigations, resource bundles). After this initial head start provided by generation, the page is further manually developed and never generated again
  • no generation – the page is completely hand-built, since generation would offer no benefits at all. This is a very rare case, that applies for example to generic regions that will be included in many pages, the login page or the Dashboard (introduction, portal) page

In my experience, the ratio of numbers of pages in these four categories varies of course, but by and large would be something like 70%-20%-5%-5%. I should mention at this point that the complexity of the pages probably by and large increases from left to right, from 100% generateable to at least initial integration only.

It is very important to realize that an ADF application that uses JHeadstart to some extent can be a mix of completely generated pages, non-generated pages and in-betweenies. They are all ADF application components and will all work together, though perhaps without sharing some potentially common infrastructure. So even if the ratio for your application – numbers that I would challenge! – would be something like 10%-20%-30%-40%, you can still make a perfectly valid case for using JHeadstart.


What is the cost of using JHeadstart?

In order to use JHeadstart, you have to pay a license fee, for every developer on the development team. The price is in the order (I do not know the exact number) of $2000-$2500. Of course you will have to invest time and perhaps tuition or consultancy fees to get up to speed with JHeadstart. For example at AMIS we offer a three-day training course on top of a five-day ADF training. Frequently we follow this training up with on-site coaching (on both ADF and JHeadstart). However, I also know of individuals who are autodidact on using JHeadstart.

What are the risks of using JHeadstart?

There are two real dangers in using JHeadstart that I would like to point out to you. The first is that once your developers or you yourself start to generate, the JHeadstart Application Generator becomes the hammer that you will not let go off and every page to develop has to be nail since that is the only tool you have at your disposal. I have seen teams go through hoops to continue to generate certain pages that in my eyes were not fit to be (completely) generated. You really need to know when to abandon generation and continue in ‘normal’ ADF – in the JSF page, the ADF Page Definition, the faces-config files and the managed beans.

Which brings us to the second real danger: by relying too much on the generator, fed by declarative, functionally oriented meta-data, developers may not gain enough knowledge – or confidence!- to go in to the generated objects and do manual tweaking of those objects or even built pages from scratch by hand. JHeadstart provides a great way for relatively inexperienced developers to become productive, but it can be a trap if developers are not
coached and even coaxed to
look in depth at what is generated, how the run time JHeadstart infrastructure facilitates generic functionality and how these can be manipulated and refined. In the end the technology used for developing the application is called ADF. It is not JHeadstart!

Shortly after publishing this article, my colleague Wouter pointed me at yet another risk that should be mentioned: the run time facilities of JHeadstart are somewhat of a package deal. They integrate and closely interrelate. If the implementation of for example the Resource Bundles or the Search functionality is not to your liking (or your users’ requirements) you basically do two things:

  • use the hooks and extension points provided by the JHeadstart run-time components to refine the out-of-the box functionality
  • you replace the standard JHeadstart facility by your own facility that you add to – and integrate into – the run time infrastructure of the application

These interventions are very well possible, but usually not trivial. While extending JHeadstart classes is easy – and through configuration of Managed Beans also easily applied in the application, it requires quite thorough understanding of what the standard JHeadstart facilities are. This usually requires some research. Not fathoming the impact may lead to incomplete or inconsistent extensions or replacements of JHeadstart components with errors or at least incomplete functionality as a consequence. If the generic facilities in your application are substantially different from those offered by JHeadstart, you may well be better off building your own alternative to the JHeadstart run-time components – instead of perpetually tuning, tweaking and fumbling with the original components.

What are the potentials gains from using JHeadstart?

The potentials gains that can be won by using JHeadstart include:

  • high productivity – rapid development of a substantial percentage of the web-tier components of the application
  • head start and (lead) time savings – by leveraging the JHeadstart run time infrastructure, you will save enormously on the effort otherwise required to build generic facilities into your ADF application; this is all the more valuable as this effort is among the most complex tasks in the project and requires the most experienced developers (who typically offer the highest productivity in developing the business specific elements in the application)
  • structured, best practices based approach – JHeadstart is based on many best practices, collected since 2000 and refined over the course of many years and projects; it provides/suggests a structured way of working that decreases risk, increases productivity and repeatability. While probably not MDA in the strict sense of the word, JHeadstart offers many of the advantages of Model Driven Architecture.


Concluding I would like to suggest that when Oracle ADF has been selected as the technology stack of choice for the development of an application, it takes a somewhat exotic set of circumstances indeed to make JHeadstart not a valuable asset for the development team. However, care should be taken to apply JHeadstart in the most effective manner, avoiding the potential pitfalls and gaining the largest benefits.


  1. Valerie Kalusinski June 17, 2008
  2. Sandra Muller February 25, 2008
  3. Jan Vervecken February 23, 2008
  4. Sandra Muller February 22, 2008
  5. Jan February 22, 2008
  6. Lonneke Dikmans February 21, 2008
  7. Lucas Jellema February 21, 2008
  8. Lucas Jellema February 21, 2008
  9. Lonneke Dikmans February 21, 2008
  10. Lucas Jellema February 20, 2008
  11. Nigel Thomas February 20, 2008