Oracle JHeadstart

Release Notes


September 2013



Check the JHeadstart-JDeveloper Support Matrix to see which versions of JDeveloper can be used with this version of JHeadstart
For compatibility with application servers, see this link.

What's New in JHeadstart

The following features have been added:

  • UI Tree Checked for Pending Changes: Prior to this release, pending changes were only detected in the model, after the JSF lifecycle phase "Update Model" was executed to update the underlying ADF model bindings. This implied that for menu item commands the immediate property had to be set to false to detect the last changes made by the user that were not yet sent to the server, otherwise the "Update Model" phase was skipped. However, with immediate=false, the end user could not abandon pages with invalid or incomplete data as validation errors occurred before the menu navigation could take place. So, the choice was to either limit the navigation freedom of the end user, or accept the fact that the pending changes alert was not always shown. With this new release this problem is solved. All menu items have immediate=false allowing complete freedom to navigate away, while the latest changes are also detected because JHeadstart now inspects the UI Components in the page UI tree for any changes. The UI Components are always updated with the latest value, also when immdiate is set to true because the UI components are updated in JSF lifecycle phase "Apply Request Values" which is always executed, regardless of the setting of the immediate property. The inspection of the UI tree is performed in a new managed bean class PendingChangesVisitCallBack. This class is generated as managed bean in JhsCommon-beans.xml. If for some reason you want to keep the old behavior, and not inspect the UI tree for pending changes, you can add the following property to the ApplicationDefinition.xml file:
    Note that you need to set this property directly in the xml file, it is not visible in the JHeadstart Application Definition editor. If this property is set to false, the PendingChangesVisitCallBack bean is not generated and the menu item commands are generated again with immediate=false.
  • Ability to override generated item properties: The item-level property "Additional Properties" has been renamed to "Additional / Overriding Properties" can now be used as well to override standard generated properties. If you specify a property in "Additional / Overriding Properties" then this property always 'wins', it will override a property by the same name that was generated by the same item template. This signifcantly reduces the need for custom item templates.
  • Support for Skyros Skin: If you wan to use the new Skyros skin introduced in JDeveloper, you should change the JHS_PAGE_TEMPLATE setting at application level from default/misc/file/jhsPageTemplate.vm to default/misc/file/jhsPageTemplateSkyros.vm. This new template is optmized for the Skyros skin, and also uses the new af:panelGridLayout component.

In addition, a number of bugfixes / small features have been added, see the bug fixes and enhancements list at the bottom.

For a complete list of all existing features, use this link.

Known Issues in JHeadstart

Known issues in this release:

  • Sometimes you can get an error that a dataCollection in the JhsModelService cannot be found. For example: "Data collection JhsModelService.Users does not exist", followed by error "JAG-00007 [ Users ] View object usage 'JhsModelService.Users' does not exist in 'AppModule'.". To fix this error, go to your application module, open it, and rebuild it.
  • Error "Could not instantiate JhsApplicationGenerator class: File not found: \templates\config\jag-config.xml" is shown when you have a directory named "templates" in the root directory of your drive. Work around is to rename or move this directory.
  • JHeadstart Application Generator sometimes hangs when generating application for the first time. This typically happens after message "Start generation of controller config files" appeared. Work around is to close (kill) JDeveloper, restart and generate again.
  • When generating all services at once, the NLS resource bundle entries of all services but the last are lost. Work around is to generate each service separately
  • Attribute not found error when Tree View Object has other attributes than Edit View Object. When your layout style is 'tree-form', you have to specify two data collections in the application structure file: one for showing the tree nodes (Tree Data Collection) and one for selecting and editing a tree node row (Data Collection). If the view object used for editing has an attribute that does not exist in the tree view object, you can get an attribute not found error. Workaround: Let the Tree View Object have the same attributes as the (Edit) View Object. It is enough if they have the same names.
  • When having a JDeveloper multi user install, the 'Enable JHeadstart on this Project' wizard does not work, and local documentation links are not accessible from JDeveloper. In such an installation each user has own system and extensions folder in special path (using SetUserHomeVariable in jdev.conf), and there is no jdevhome/jdev/extensions/oracle.jheadstart.* folder. Workaround: copy the oracle.jheadstart.* folder from userhome/extensions to jdevhome/extensions
  • Nested tables do no work correctly when view Object access mode is set to Range Page mode
  • By default a generated datetime field in a table is not wide enough, the time is not completely visible. Work around is to explicitly set the Column Width property.
  • Group toolbar disappears when Show Display Title property is unchecked. Work around is to set a dummy title, clear the title in the generated resource bundle and uncheck application-level property Override NLS Resource Bundle Entries.
  • Limitations of the JHeadstart Forms2ADF Generator:
    • Blocks based on stored procedures and transactional triggers are not supported. Blocks based on FROM Clause query are partially supported: a read-only viewobject is created based on the query. If the block was updateable, you need to manually change the view object and base it on an entity object.
    • Item property Copy Value From is ignored.

ADF Business Components Related Issues

Changing an Entity attribute to optional still leaves it required in the generated page (JDeveloper 4104337)

After changing an Entity Object attribute from mandatory to optional, JHeadstart still generates required fields for View Object attributes that are based on that Entity Object attribute.


  • Edit the View.xml file outside of JDeveloper
  • Remove the line IsNotNull="true" from the relevant <ViewAttribute> tag

ADF Faces Related Issues

Primary key values must be pre-populated by model (JDeveloper 6894412)

ADF Faces components expect applications to use primary keys on the model which are pre-populated for new records and do not change with any record updates. If primary key values change as a result of user input, the row management in ADF Faces tables gets corrupted. This can result in unexpected behavior in the application. For example, checkbox values assigned to new rows are lost again, and cascading dropdown list do not work correctly. If you are working on an existing datamodel, you need to add an additional ID column to the table, and mark this column as the primary key in ADF Business Components. In the create() method of your entity object class, populate this column with a sequence-generated value. Note that this column does not need to be the primary key column in the database.

Upgrading From a Previous JHeadstart 11.1.1.x Release

Here are the steps to migrate your JHeadstart 11.1.1.x application to JHeadstart

  1. Re-enable JHeadstart on your ViewController project.
  2. Check for changes in default templates which are used as basis for custom templates. Each default template that has been changed for this release, has one or more entries in the revision history at the top of the template describing the change. If you created custom templates which are copied from/based on a default template, then check whether any changes in the default template should be carried forward to the related custom template(s). If you are using a version control system like SubVersion, then a fast way to detect which default templates have been changed is by using the "Check for Modifications" option on the templates directory after re-enabling your project for JHeadstart. SubVersion will then show a list of modified default templates.
  3. Regenerate ALL application definition files before running your application.
  4. Check that all your pages and page fragments are now using the UTF-8 encoding. UTF-8 encoding is the only encoding supported by ADF Faces. Any pages not or no longer generated by JHeadstart that do not have UTF-8 encoding should be changed manually to have UTF-8 encoding.
  5. If you were using JHeadstart dynamic tabs, and you have written custom code that uses the oracle.ui.pattern.dynamicShell.TabContext class, you need to rewrite that code to use the oracle.jheadstart.view.dyntab.DynTabContext class. In addition, you can remove the "Oracle Extended Page Templates" library usage from your ViewController project.
  6. The JhsRegionTemplate.jspx is now generated instead of copied to the file system when enabling the project for JHeadstart. Using the same jhsRegionTemplate.vm Velocity template actually two region template .jspx files are now generated: JhsRegionTemplate.jspx and JhsRegionTemplateNoStretch.jspx. The JhsRegionTemplateNoStretch.jspx template is used when the group does not have stretching enabled. This separate region template is needed to fix issues with redundant white space when a group is displayed in a popup, or inside a panelAccordion. Now, if you created your own region template and changed the default value of the application-level property Region Template (/common/pageTemplates/JhsRegionTemplate.jspx), then you will not get the white space fix applied. We recommend to switch back the Region Template property to its default value, and then make a custom template of the default jhsRegionTemplate.vm to apply any customizations you made in your own region template .jspx file that was used previously.
  7. The add row button in a table no longer has the immediate property set to true. The reason we changed this property is that previously any values entered in items in the overflow below or overflow right area were lost when clicking the add row button. These values are no longer lost, however, a side effect is that you can no longer create multple new rows without filling in any values. If you click the add row button for a second time, it will start validating the previously created new row and will display validation errors, for example for required fields.

Migrating a JHeadstart 10.1.3 Application to 11.1.1

Here are the steps to migrate your JHeadstart 10.1.3 JSF/ADF Faces to JHeadstart 11 with ADF 11 Task Flows and ADF Faces Rich Components:

    • Make a backup of your entire project before you start with the migration.
  1. Install JHeadstart, and perform additional steps to make JDeveloper compatible with JHeadstart, depending on the JDeveloper version (see Compatibility).
  2. Open your project in JDeveloper 11.1.1. You will be asked to upgrade your workspace (.jws) and project (.jpr) files to 11.1.1. Click Yes to do so. The ADF Business Components will be migrated to 11.1.1 as well.
  3. Go to the Project properties of the Model project, and click the Libraries tab. The JHeadstart Runtime 10.1.3 library appears in red. Remove this library, and add the JHeadstart Runtime 11.1.1 library. Make sure your Model project compiles again without errors.
  4. Create a new ViewController11 project in the same application workspace. Easiest way to do this is right-mouse-click on the workspace, then choose "New Project ...". Choose "Web project" in the New Gallery dialog that appears. In the New Web project wizard that appears you must choose between Servlet and JSP versions. Choose Servlet version 2.5. On the Page flow technology tab, choose ADF Page Flow. Click Finish (no need to select any libraries on the last tab of the New Web Project wizard)
  5. Go to the file system, make a new directory "properties" under the root directory of your new ViewController11 project, and copy all the application definition files that you want to migrate to this directory.
  6. Right-mouse-click on ViewController11 project and choose "Project Properties". Expand "Project Source Paths" node, and click on the Resources sub node. Add the properties directory you just created as resource.
  7. Right-mouse-click on ViewController11 project and choose "Enable JHeadstart on this Project". Click through the wizard pages and click Finish. For each 10.1.3 application structure file, you will get a dialog that asks you to upgrade the 10.1.3 application structure file to version 11.1.1. Click Yes each time this dialog appears. When you have clicked Finish again, a new JHeadstartApplicationDefinition.xml file has been added to the project. This file contains a list of all migrated application structure files. You can right-mouse-click on this file and choose "Edit JHeadstart Application Definition". In release 11, you can now maintain all application structure files (which have been renamed to service definition files) in the same Application Definition Editor window.
  8. Remove the "old" 10.1.3 ViewController project(s) from your workspace.
  9. In the Application Definition Editor, click on each service and specify a name for the Menu Model file, for example "/WEB-INF/hrservice_menu.xml"
  10. Check whether you have a detail group with layout style "tree" or "tree-form" while the parent group does not have a "tree" or "tree-form" layout. If you have such a group, you need to change the layout style of these detail groups to "reusableTree" and add a group region that references another top-level group that will generate the form part of the tree-form layout. See the JHeadstart Developer's Guide, chapter 5, section "Creating Tree Layouts" for more information.
  11. Run the JHeadstart Application Generator.
  12. Run and test your application.
  13. Examine all the 10.1.3 custom velocity templates you used during generation. Check the functionality they provided and determine whether the functionality is still required in your R11 application. If so, check whether the functionality can now be implemented through declarative settings in the JHeadstart Application Definition editor. If not, create custom velocity templates based on the R11 standard templates that provide the same functioanlity as your 10.1.3 custom templates.
  14. In case your 10.1.3 application was not 100% generatable, examine the post-generation changes you made in 10.1.3. Check the functionality they provided and determine whether the functionality is still required in your R11 application. If so, check whether the functionality can now be implemented through declarative settings in the JHeadstart Application Definition editor. If not, create custom velocity templates based on the R11 standard templates to provide the same functioanlity as your 10.1.3 post-generaton changes. If you do not mind to keep your application 100% generatable, you can apply the same functionality as post-generation steps

Bug Fixes in

Fixed in
JHeadstart Application Generator / JHeadstart Runtime Breadcrumb does not work when more than one task flow needs to be abandoned
JHeadstart Application Generator NPE when switching between tree nodes of same type that use a shuttle
JHeadstart Runtime LOV item params that reference current binding container evaluate to null during LOV validation
JHeadstart Application Generator ApplyBindParams method action wrongly generated for row specific domains
JHeadstart Runtime Delete row bean should not commit when new row is deleted
JHeadstart Application Generator Task flow input param hideSaveButton is ignored, save button always shown
JHeadstart Application Generator JHeadstart LOV should check auto query property to determine query needed after clearing search items
JHeadstart Runtime When doing a range search on datetime items, the time part is truncated
JHeadstart Application Generator Macro #NUMBER_CONVERTER did not check whether item was databound.
JHeadstart Runtime Custom OrdPlayMediaServlet in web.xml overwritten with JHeadstart version during generating
JHeadstart Runtime All UIComponent bindings in bean classses should use ComponentReference
JHeadstart Runtime Not all bean classes are defined as serializable
JHeadstart Runtime Deeplinking to form page with reusable tree did not select correct tree node
JHeadstart Runtime In tree menu, wrong tree node selected when canceling node selection after pending changes alert
JHeadstart Runtime In pages with tree layouts, wrong tree node selected when canceling node selection after pending changes alert
JHeadstart Application Definition Editor Diacritic characters replaced with question mark when saving service definition, encoding needs to be changed to UTF-8
JHeadstart Runtime Tabbing out JHeadstart item that uses LOV for validation prematurely fires validation of other fields
JHeadstart Runtime Deleting a row in JHeadstart LOV always deletes the first row
JHeadstart Application Generator JHeadstart Lov icon not enabled/disabled when deoendent on another item
JHeadstart Runtime Dependent items of JHeadstart Lov item are not refreshed in browser
JHeadstart Application Generator NumberFormatException when using table sum function with ADF BC formatting hint
JHeadstart Application Generator stackedRegionContainer.vm: Table changes lost when opening accordion in table overflow
JHeadstart Application Generator groupRegion.vm: Duplicate component id when same region referenced twice in recursive tree
JHeadstart Application Generator Region in overflow below/right not refreshed when depends on item displayed in table
JHeadstart Runtime Changed fetch size to -1 for Jhs Translations VO's