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

Lucas Jellema 11
0 0
Read Time:8 Minute, 35 Second

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.

About Post Author

Lucas Jellema

Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director and Oracle Developer Champion. Solution architect and developer on diverse areas including SQL, JavaScript, Kubernetes & Docker, Machine Learning, Java, SOA and microservices, events in various shapes and forms and many other things. Author of the Oracle Press book Oracle SOA Suite 12c Handbook. Frequent presenter on user groups and community events and conferences such as JavaOne, Oracle Code, CodeOne, NLJUG JFall and Oracle OpenWorld.
0 %
0 %
0 %
0 %
0 %
0 %

Average Rating

5 Star
4 Star
3 Star
2 Star
1 Star

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

  1. Hi,
    We are developping applications with ADF and JHeadStart and have noticied that the performance is extremely different depending on the browser used.
    These are the times we noticed:
    *Execute Search:
    -IE: 7”
    -FF: 2”
    -Safari: 1”
    *Next N rows:
    -IE: 5”
    -FF: 3”
    -Safari: 1”
    *Insert new row:
    -IE: 7”
    -FF: 3”
    -Safari: 1”
    *Insert, update, delete, undo row:
    -IE: 8”
    -FF: 3”
    -Safari: 1”
    Have you seen something similar ?
    Thanks and best regards.

  2. Jan, I assume that when you write about “keep up with subsequent releases of JHeadstart”, you refer to the effort of upgrading your custom generator templates to the new JHeadstart release. When you have made a customization of any of the default JHeadstart templates, and a new JHeadstart release ships a modified version of that default template, then it is a good idea to check if you want the same modifications in your customized template.
    There are 3 main reasons why JHeadstart could modify a default template: 1) to add a new generation feature, 2) to fix a bug, 3) to comply with changed requirements of the underlying technology, like a new release of ADF Faces with different component names (see also Upgrading to JDeveloper R11 and Beyond). All 3 reasons are excellent reasons to want to change your custom templates as well. Reason 1 to give you even more long-term payback, and reasons 2 and 3 to ensure that your application works correctly. The changes for reason 2 and 3 you would have to make anyway, and the nice thing when using JHeadstart generator templates is that you don’t have to make them in every page, but only in the templates you customized, which are easy to find.
    To make sure that the generated part of your custom built application can keep up with subsequent releases of JHeadstart, I recommend applying the best practice described in section 4.7.2 of the JHeadstart Developer’s Guide ( : If your custom template is based on a default template, name it such that you can easily see on which default template it is based, and clearly mark in the content which lines differ from the default template (using Velocity comments preceded by ##). Also describe in comment why the change was made (what you want to achieve). In addition, we recommend using SubVersion (see section 2.1 Setting Up Version Control System) for easy identification of the changes in the default templates after installing a new JHeadstart version, so that you can also apply these changes to your custom templates if necessary.
    Then, if you want to upgrade to a higher JHeadstart version, you can install the new JHeadstart which overwrites the default templates, and before committing those changes to Subversion, check which ones have changed. For the custom templates based on changed default templates, check exactly which changes were made to the default templates (see the screenshots in and determine if you need to copy those changes to your own template. That should be easy to determine depending on the kind of customization you made, which you can read in the Velocity comments.

  3. hi (I am not the other “Jan” who also posted comments here.) While Lucas Jellema is writing about “a mix of completely generated pages, non-generated pages and in-betweenies”, and Sandra Muller writes “However, the payback is in the medium to long-term.”. I wonder, how to make sure that your custom built ((partly) generated) application can keep up with subsequent releases of JHeadstart, to get that long-term payback? Or is “long-term payback” something one should not be looking for in our agile industry?
    Jan Vervecken

  4. Lucas, you said: 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. I agree that it is very important that the developers are trained and coached in ADF basics as well as JHeadstart generation. That is why our ADF JHeadstart workshop spends 3 days on ADF without JHeadstart and only 1 day on JHeadstart generation! The last day is spent on using your ADF knowledge to customize JHeadstart (exactly the thing that people that rely too much on the generator cannot do) and on implementing Java EE security.

    I agree with Lonneke that most IT cost is not in development, but in maintaining and supporting an application. I don’t agree that if 100% generation of the last 5% is time absorbing, you should not do it. There is more to JHeadstart than just the time gain in building the pages. I refer back to an old article by Steven Davelaar about 100% generating with Designer/Forms Generator: 100% Generation: No More Excuses! (see ) Some of the aspects described there apply here as well (though I think that JHeadstart provides more gain in the first incarnation than Headstart did for Forms):

    The cost vs. benefit of 100% generation is one that must be looked at over its entire payback period, not just in the first incarnation. In the first release of a system, using a rigorous metadata-based approach to engineering systems may require additional design time. However, the payback is in the medium to long-term. The iterative phases of system development, and especially its maintenance and enhancement phases are when payback for generation occurs. […] One of the most important prerequisites for achieving 100% generation is in the very beginning of the project: a reasonable project planning! If you have relatively inexperienced developers on your project, do not underestimate the learning time.

    For this reason I think that we should also try to 100% generate the last 5%, at least if the pages involve reading or writing data collections.

  5. “Sorry if I hammered away too enthusiastically, I did not mean to hit you…”

    Come on! I think/thought your post was right on the mark Lonneke – no need to apologize, you didn’t call names now did you?
    I for one whole heartily agree that JHeadstart lures in the Designer/Forms crowd and gets them acquainted with bad practices from day one. UI generation is bad for anything that is beyond emp|dept, and the 100% generation promise a myth. It was then with ‘Headstart’ and now is with ‘JHeadstart’

  6. Lucas,

    I agree with you: JHeadstart will give you more than just generation. But it is not very informative nor fun to read the posts of two bloggers who agree with each other: I decided to focus on the point I disagree with. That concerns the statements that there are only small risks. In my experience, Oracle shops that are experts in Forms and Designer start using JHeadstart. This means they use it *because* it generates code. Because they aren’t expert Java users, and are used to creating PL/SQL procedures and not used to refactoring, they will take everything that is generated at face value. Moreover a lot of people that are used generating Forms from Designer feel you should only generate everything or nothing (this is what I have encountered over the years, not my view of how it should be). Novice or intermediate programmers are intimidated by all the code that is generated at once, they don’t know where to start. Project managers don’t estimate enough time to program because it is generated etc etc. Extending JHeadstart or maintaining the generator is far out of their reach and interest.
    Second of all, with ADF BC without JHeadstart you have the same problem: people will take a shortcut and generate business components from the datamodel to build their GUI with. Leading to the problems in the user interface I described. It will reflect the datamodel instead of the conceptual model that it should represent.
    To conclude: the problem is that the tool (in this case JHeadstart and/or business components) will lure people into bad habits where it can do real damage. It is something that I have seen with other tools as well: once you get the user interface wrong, you spend a lot of time fixing and rebuilding.
    Now, this does not mean you should never use JHeadstart of course: you made a great case for using it that I don’t need to repeat. Also Sandra Muller made a good point: you could easily design the user interface, decide to use ADF faces, create the business components you need and then generate the code you need. You can then save you some days of development in the lifetime of an application. Again, most IT cost is not in development, but in maintaining and supporting an application. It all depends on the business case.
    To conclude: No need to change the title: I get your point, I agree with most of it, I just don’t agree with everything 😉 Sorry if I hammered away too enthusiastically, I did not mean to hit you…

  7. Hi Lonneke,

    Thanks for your reaction. Reading your comment here and the article on your blog, I realize that I have failed to get my main point across. I wanted to make it clear that in my mind there is no such thing as a JHeadstart application. We develop ADF applications, with their own specific UI, interaction patterns and functionality. You should not and need not be able to see whether that ADF application was developed by a team of 10 programmers in Canada or a team of 5 whizkids in India working with 3 project leaders in The Netherlands and nor should you have to see whether JHeadstart has been a tool in developing that application. JHeadstart does not define what the application looks like or offers in terms of functionality. The end-user does, and the implementation technology, i.e. ADF, should make it possible.

    My whole point was that JHeadstart can be used in certain ways. I very much regard it as an electric screwdriver – or whatever rocking term is used for such an appliance. At first I was hesitant to use one for my DIY jobs. Suppose its battery would run out or the thing would break, then what? But of course when your piece of furniture is done, it does not matter whether you benefited from your power tool or struggled to get those screws in by hand. And if the power tool breaks after half the screws are done, well at least you had the benefit for those first 50% screws.

    On my current project, we develop an ADF application. The User Interaction Design was done my someone who does not know ADF. The application we develop, does not look like ‘typical ADF’ in anyway. You would not be able to readily tell the technology used for implementing the application. We also use JHeadstart. In fact, we use more of it than I would have expected, as it turns out that much more of that very un-JHeadstart style UI turns out to be fit for generating after all. However, we can stop generating at any point and continue by hand. Without JHeadstart we would have to do everything by hand anyway, so whatever we got from JHeadstart – as long as it is in the right direction – is beneficial.

    For that same reason, I am not afraid of a dependency on the JHeadstart team, as in my view there is none. I get a generator that I can use or not use. If I do not use it, I do everything by hand. If I use it, the first 30-80% of many of my pages is done for me – and then I do it the rest by hand. If the generator is no longer available, I drop it. Nothing lost and potentially a lot gained. As far as the run-time infrastructure is concerned: they consist of a number of well documented sources; my colleague could have written them, but some Oracle team in The Netherlands did it instead. I do not see much danger of a dependency here. We can take these components and start refactoring, extending and complementing them. Again, the gain is obvious, the risks are small.

    Furthermore, an important point I was trying to make is that JHeadstart is not only a generator. It is a combination of two things, and even for ADF applications that are completely hand-built, I put it that JHeadstart provides a run-time infrastructure that benefits most ADF applications, regardless of whether they aree generated completely, generated at first than manually finished or not generated at all.

    You keep hammering away at the Generation topic. Suggesting that generation will inevitably lead to an application that does not fulfill the user’s requirements in an optimal way. While my whole point was that JHeadstart is not just for generation and is certainly in my view not to be used for complete generation. So in effect, I pretty much agree with all your arguments – only they do not apply to the case I was making.

    I was not making a case for generation of all applications when I stated that almost all ADF applications could benefit from JHeadstart. I merely pointed out that for any ADF application you need generic infrastructure, on top of the standard features/functionality of ADF. And JHeadstart provides a set that could well be the first step in that generic infrastructure, saving you many days of development.

    Maybe I should have used a different title for my article. Something like: JHeadstart, it is not (just) about generation.

    best regards,


  8. Mais oui Nigel! It is a parallel that had struck me in the past as well. Both the benefits and the dangers: you can develop Oracle Forms applications through the use of Oracle CASE Generator or Oracle Designer without knowing the first thing about Oracle Forms. That may lead to a needlessly limited or even sometimes erroneous use of the technology. And the single minded focus on 100% generation that makes generation of the last 5% (or even 1%) of a page a nightmare and a real time absorber! At the same, developers – either Oracle Forms or Oracle ADF today – need to be willing to let go of some of their freedom in order to benefit from the structured and productive (at least first shot) approach offered by either Designer or JHeadstart. It is often perceived as a corset that restricts a developer’s freedom – though at the same time you can claim it provides support and structure to the developer and it allows her or him to focus on the specific functionality rather than generic components and repetitive actions.

    Thanks for your reaction and best regards,


  9. Lucas

    It is no coincidence that 15 years ago you could have written the exact same article talking about use of the Forms Generator component of Oracle CASE (now Designer). Same generic issues; same 70/30 or 80/20 split between simple and complex generation cases (and same 30/70 or 20/80 split between effort spent on simple and complex modules).

    Here’s a 1992 posting about the Forms generator mentioning the regeneration functionality added in V2 – which moved it from a one shot (your third category) to roundtrip engineering (your second).

    Plus la change, plus c’est la meme chose!

Comments are closed.

Next Post

How to maintain entity validation (JboException) and ORA-20xxx messages in a central resource bundle in your ADF application that uses JHeadstart

As you can imagine, with many validators on many entity objects you will end up with equally many generated message bundles. When you start localizing the error messages, that means you have to maintain many classes. Keeping those messages consistent can become an error-prone task. In this article I will […]
%d bloggers like this: