JHeadstart Blog

Finally, it's there! After several weeks of hard work by the JHeadstart Team to put in the finishing touches, we present you: Oracle JHeadstart 10g for ADF Release 10.1.3.0, with support for JSF and ADF Faces.

Customers that hold a supplement option license can download jhs1013-install.zip from the Consulting Supplement Option
portal.  A limited trial version will be available for evaluation
purposes on OTN later. If you want to acquire a subscription to the
JHeadstart Supplement Option, you can contact your local Oracle
Consulting representative. If you don't have a local Oracle Consulting
representative, please send an e-mail with your name and location to
idevcoe_nl "at" oracle.com.

Fact Sheet, FAQ, online demos, and the new updated JHeadstart 10.1.3 Developer's Guide (with extra chapters compared to the draft version) can be found in the JHeadstart Product Center.

What's New in JHeadstart 10.1.3

• Generation of JSF ADF Faces pages. Instead of generating UIX pages, we generate ADF Faces pages (in .jspx format).
• Generation of Faces-config.
  JSF is used as the Controller instead of Struts. As a result, managed
  bean definitions and navigation rules are generated in the
  faces-config, instead of the old struts-config generation.
• Velocity Generator Templates. The JHeadstart Application Generator is driven by generator templates. These templates now use the Velocity Template Language.
  The content of the generated pages is now 100% driven by these velocity
  generator templates. Everything that is generated on a page can be
  customized by creating a custom template.
• Pluggable Generator Archictecture.
  The JHeadstart Application Generator engine has been completely
  rewritten and is now java-only. XSLT Stylesheets are no longerused. All
  important generator classes are instantiated using the Spring Bean
  Factory. This allows you to plug in your own custom generator classes
  to extendthe JHeadstart Metadata Model used by the generator templates.
• Item-level Templates.
  In 10.1.2, one single generator token represented all items in a form
  or table layout. This limited the flexibility in generating
  non-standard layouts. Item level templates allow for much finer-grained
  customizations of the layout generation. You can even define the exact
  position of each item, by using index-based or named-based item tokens.
• Items included in Application Definition Editor (previously known as Application Structure Editor).
  The separate ADF BC attributes editor no longer exists.Instead, the
  group items (attributes) are defined inside the application definition.
  A "Synchronize" option is provided to automatically load the attributes
  from the Data Control Collection (the View Object Usage in case of ADF
  BC) that is associated with the group.
• Support for Unbound Items.
  In addition to items that are bound to an underlying model attribute,
  unbound items are supported. The existing display types will be
  supported for these items. Unbound items can be made "Action items" by
  using a custom template that generates a hyperlink, button or clickable
  image.
• New Table Overflow Styles. In addition to Detail
  Disclosure (now renamed to "Inline Overflow"), we support "Overflow
  Right" and "Overflow Below" where additional items of the current row,
  not shown in the table itself, are displayed at the right side of the
  table, or below the table.
• Tabbed Regions and Tabbed Child Groups.
  Item Regions and detail groups can now be grouped together in a
  so-called Region Container. A Region Container can have a layout style
  of "horizontal", "vertical" or "stacked". With layout style "stacked"
  you will get tabbed regions. With layout style "horizontal" you will
  get side-by-side regions.
• New Group Properties. New group properties include stack detail groups, Show New Rows At Top and Table Overflow Style (see above).
• New Item properties.
  New item properties include: Bound to Model Attribute, Value, Java
  Type, Display in Table Overflow Area, Prompt in Table Layout, Column
  Alignment, Column Sortable, Column Wrap, Depends on Item, Validator
  Binding, Regular Expression, Regular Expression Error Message, Include
  in Quick Search, Include in AdvancedSearch, Prompt in Search Region,
  Rendered, and Disabled.
• Enhanced List of Values. List of
  values can now be reused accross pages, and can return as many values
  as you like. Since List of Values are now modeled using the group
  element, you also have full control over the items that are displayed
  in the LOV.
• Drag and drop in Application Definition Editor (ADE).
  You can now use drag and drop in the ADE. For example, you can drag and
  drop an item into a region. To copy an element, you can use a
  right-click option or press the CTRL-key while dragging and dropping.
• Domain Definitions Integrated in Application Definition Editor. There is no longer a separate DomainDefinitions.xml. Domains are now maintained in the ADE.
• Deep Linking.
  There is now declarative support to call a page using deep linking
  which allows you to query a specific row and show this row on the page.

We've uploaded a new version of the JHeadstart Developer's Guide,
which now includes a section titled 'Security' in chapter 5, JHeadstart
Extensions to ADF Runtime. This new section describes how you can use
either Java EE security (JAAS) or your own custom security mechanism in
your JHeadstart generated application.



The developer's guide has become rather large (6 MB), so to improve download speed we have moved it to download.oracle.com.

If you want to deploy a JHeadstart 10.1.3 application to an
application server that uses JDK 1.4 (like Oracle Application Server
10.1.2), you need to build your application with JDK 1.4. By default,
JDeveloper 10.1.3 uses JDK 1.5.



To prepare for this, there are two things you should do early in the development process:

1. Generate your JHeadstart application with Server level property JSP Version = 1.2 in the Application Definition
   
   


2. In both Model and ViewController project, go to Project Properties, Compiler, and set Source and Target to 1.4

The first is to ensure that the generated JSPX files are compatible
with JDK 1.4, and the second is to ensure that any Java code you write
is compatible with JDK 1.4.



In a later post I will blog about how to do the actual deployment.

With JDeveloper and ADF 10.1.3 I often see the following runtime error in the browser (summary):

javax.faces.FacesException: #{...an expression...}: 
javax.faces.el.EvaluationException: 
oracle.jbo.common.ampool.ApplicationPoolException: 
JBO-30003: The application pool (...name...) 
failed to checkout an application module 
due to the following exception:
  at ...
Caused by: javax.faces.el.EvaluationException: 
oracle.jbo.common.ampool.ApplicationPoolException: 
JBO-30003: The application pool (...name...) 
failed to checkout an application module 
due to the following exception:
  at ...
	... 26 more
Caused by: oracle.jbo.common.ampool.ApplicationPoolException: 
JBO-30003: The application pool (...name...) 
failed to checkout an application module 
due to the following exception:
  at ...
	... 27 more

Experience
so far has taught me that this error can have many causes, but they are
all related to problems with the ADF Business Components or the JDBC
Connection / Data Source to access the database.

If
you
encounter such an error, the first thing you should try is run the ADF
BC Tester: right-click your Application Module and choose Test. You
cannot use a Configuration that uses a Data Source, if necessary copy
the existing Configuration and change it to use a straight JDBC
Connection. Then use that Configuration for running the tester (from
the dropdown list in the upper right corner of the tester startup page).

Often
the tester will also give an error, and give you a more meaningful
detail message to indicate the cause of the problem. If the tester
works fine, and you use Data Sources to get to the database, check your
data source definitions.

I was googling for an overview of the JSF Expression Language (EL) syntax, and found the topic JavaServer Faces EL Expression Syntax at Sun's Developers site.

This syntax overview was helpful to me when creating EL expressions in JDeveloper's Expression Builder. This Expression Builder is a dialog that helps you build EL expressions by providing lists of ADF data binding objects, as well as lists of managed beans and their properties. The builder also shows a selection of operators you can use, and with the syntax overview I was able to use the more sophisticated JSF Expression Language operators as well.

Updated 20 October 2008:
Found another interesting online source of information: Marty Hall's free instructor materials on the JSF Expression Language.

In the earlier post If you intend to deploy JHeadstart 10.1.3 to OracleAS 10.1.2 I explained which preparation steps to take if you are going to deploy your JHeadstart 10.1.3 application to an
application server that uses JDK 1.4 (like Oracle Application Server
10.1.2). I promised that in a later post I would blog about how to do the actual deployment.

Well, here it is! Below are the steps I took to successfully deploy a JHeadstart 10.1.3 application to Oracle AS 10.1.2 (after trying out several other methods). The steps are so generic that I think they can be used for any JDeveloper 10.1.3 web application using ADF Business Components and JSF or ADF Faces.

1. Create a new OC4J Instance in OracleAS 10.1.2 (for example from the Application Server Home Page).
2. Disable ADF Runtime for this OC4J instance by modifying its [OC4JInstanceHome]/config/application.xml (on the file system of the application server machine). Comment out the following lines:
   

<library path="../../../BC4J/lib"/>
<library path="../../../jlib/ojmisc.jar"/>
<library path="../../../ord/jlib/ordim.jar"/>
<library path="../../../ord/jlib/ordhttp.jar"/>
<library path="../../../jlib/jdev-cm.jar"/>

and


<library path="../../../uix/taglib"/>

3. If necessary, set up Data Sources and other configuration settings for OC4J.
4. In the ViewController project properties, go to Libraries.
   
5. Add the following libraries that are needed for the Model project:
      BC4J Oracle Domains
      Oracle JDBC
      SQLJ Runtime
6. Also add or create any other libraries where needed to get the right jar files in the EAR file.
   
7. In the ViewController project, create a new WAR Deployment Profile (File | New | General | Deployment Profiles | WAR File).
8. In the deployment profile properties, go to WEB-INF/lib Contributors, and select all the libraries (except JSP Runtime).
9. In the deployment profile properties, go to WAR Options, and select Compress Archive.
10. If you use Subversion, go to all Filters categories, then to Patterns, and exclude **/.svn/
11. In web.xml, replace

<web-app
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"  
version="2.4"  
xmlns="http://java.sun.com/xml/ns/j2ee">

by

<!DOCTYPE web-app PUBLIC  
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"  
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>

12. On your development PC, install JDK 1.4 (for example, copy the jdk folder from a JDeveloper 10.1.2 home).
13. In the ViewController Project Properties, go to Libraries.
14. Click the Change button for the J2SE Version.
15. Click the New button to create a new J2SE Definition.
16. Browse to your [JDK1.4Home]/bin/java.exe for the J2SE Executable.
17. When asked to install OJVM, click OK.
18. Accept the default settings for name, class path, source path, and doc path.
19. Choose if you want to define the new J2SE definition at Project level (every deployer needs to have JDK 1.4 in same path), or User level (every deployer needs to create own J2SE definition).
20. Save the settings.
    Warning: after this step (usage of J2SE 1.4), do not try to run Embedded OC4J (see below how to enable Embedded OC4J again).
21. In the Model Project Properties, do the same (define a similar J2SE 1.4 Version).
    
22. Empty your classes folder (the output directory for the compiler). You can do that in JDeveloper via the menu option Run - Clean ViewController.jpr.
    
23. Right-click the deployment profile and choose Deploy to EAR. The log tells you where it creates the EAR file.
    
24. Deploy the EAR file to the new OC4J instance (see this documentation).
    

To use Embedded OC4J, change the J2SE Version of ViewController back to 1.5 and rebuild the project.

This is a long list of steps, isn't it! Fortunately, you only need to do them the first time you are going to deploy. For subsequent deployments you only need to perform the following steps:

• In both the Model and the ViewController Project Properties, go to the Libraries page, and change the J2SE Version to 1.4 (which is now already defined).
• Empty your classes folder (the output directory for the compiler). You can do that in JDeveloper via the menu option Run - Clean ViewController.jpr.
• Right-click the deployment profile and choose Deploy to EAR.
• Deploy the EAR file in the new OC4J instance.
• Change the J2SE Version back to 1.5 (in both Model and ViewController).

As an alternative solution, you can also try to install OC4J 10.1.3 under your Oracle Application Server 10.1.2.