In the following bubble graph that we are going to create, the Life expectancy (y-axis), income a year (x-axis) and the population (bubble size) is shown. This in steps of 10 years, for the last 50 years (1970, 1980, 1990, 20000 and 2010). So for each country 5 bubbles are shown. The location of the bubble has a meaning; for example in Japan (grey) the life expectancy is the highest and in Pakistan the lowest (green).
-Have developing countries moved forward their income?
-Do they have longer lifes than 10, 20, 30, 40 or 50 years ago?
A picture says more than thousand words – you can see it immediately in the graph.

Bubble Graph

A bubble graph is a type of chart that displays three dimensions of data (three series of data). The bubbles are shown on the chart at their X and Y location and the third (Z) through its size. Bubble charts can facilitate the understanding of social, economical, medical, and other (scientific) relationships. For example, Hans Rosling shows here amazing bubble charts. Use a bubble chart when you want specific values to be more visually represented in your chart by different bubble sizes.

How to create a bubblegraph in ADF

Here are the steps I took:

Database:
-Prepare the database: run
bubble_create_script.sql
This will create the database table and the country statistics that we are going to use for the bubble graph.

Model project:
-Create a standard new Fusion Web Application
-Create a new read-only ADF ViewObject called PopulationIncomeLifeExpectancyView with the following SQL query:

[code language="SQL"]
select country,
year,
avg_life_exp avg_life_expectancy,
avg_income,
population
from total_population_by_ctr
where country = nvl(:p_country, country)
and year =nvl(:p_year,year)
order by country, year
[/code]

Further for this ViewObject:
-Create a bind parameter: p_year (String)
-Create a bind parameter: p_country (String)
-Set the Year and the Country attribute as key attribute of the ViewObject

Next:
-Create a new ApplicationModule
-Add the new ViewObject PopulationIncomeLifeExpectancyView to your ApplicationModule
-Add another usage of PopulationIncomeLifeExpectancyView – now called PopulationIncomeLifeExpectancyView1 - to your ApplicationModule

ViewController project:
-Create a new JSF page called LifeExpectancyByCountry.jspx:
-Drag and drop a af:panelStrechLayout and in that an af:panelGroupLayout component on the new page
-Drag and drop the PopulationIncomeLifeExpectancyView from your dataControl on the JSPX page:
-Choose Graph and Bubble

Set the X, Y, Z, color and tooltip properties as follows:

-After running the page, the result should look like this:

-Now lets make the graph a bit better looking by adding the following properties to the dvt:bubbleGraph

styleClass=”AFStretchWidth”
hideAndShowBehavior=”withRescale”
dynamicResize=”DYNAMIC_SIZE”
inlineStyle=”height:550px;”
imageFormat=”PNG”

-Change the colors, We can do this by adding dvt:series in the dvt:serieSet component
-We set a graph-, x-as- and y-as title
-We set an x-as and y-as min and max scale
-The legendarea we place at the bottom

The dvt:bubbleGraph code should look as follows:

If you run the page the page looks like this:

Interactive Bubbles

To make the bubbles interactive, add a clickListener to the bubbleGraph:

clickListener=”#{LifeExpectancyBean.onClick}”

and in our managed bean we retrieve the value of our ViewObject Country attribute. We need this (after a bubble-click):

[code language="Java"]
public void onClick(ClickEvent clickEvent) {
ComponentHandle componentHandle = clickEvent.getComponentHandle();
if (componentHandle instanceof DataComponentHandle) {
DataComponentHandle handle = (DataComponentHandle)componentHandle;
Attributes[] attr = (handle).getGroupAttributes();
for (int i = 0; i < attr.length; i++) {
Attributes a = attr[i];
Object obj = a.getValue(a.ID_ATTRIBUTE);
//Check if we have our ViewObject ID attribute
if ("Country".equals(obj.toString())) {
selectedCountry = (String)a.getValue(a.ID_VALUE);
System.out.println("selectedCountry=" + selectedCountry);
}
}
}
//Do something interesting with selectedCountry
BindingContainer bindingContainer = BindingContext.getCurrent().getCurrentBindingsEntry();
OperationBinding operationBinding = bindingContainer.getOperationBinding("ExecuteWithParamsSelectedCountry");
operationBinding.getParamsMap().put("p_year", null);
operationBinding.getParamsMap().put("p_country", selectedCountry);
operationBinding.execute();
renderDetailGraph = true;
renderGraph = false;
AdfFacesContext.getCurrentInstance().addPartialTarget(panelStrech);
}
[/code]

In the code above we execute a second usage of our ViewObject that is used for a second bubble graph – the detail bubble graph.
We render the detail graph and do not render the master graph anymore. To make this example working, we refresh our panelStrechlayout component. Now, after clicking on a bubble, a detail bubble graph is shown that zooms in into the country:

Download here the bubble demo app (JDeveloper 11.1.1.6)

Part 1  – Overviews

Chapter 1 starts with an overview of Fusion development and ADF. What is the Oracle Fusion brand, its history and architecture?  It’s good to have an overview how ADF relates to all the other technologies but to really understand the contents you must already have some knowledge of all the Oracle Fusion technologies.

Chapter 2 is a general introduction to the JDeveloper IDE. It is a good read for newbie’s but also for experienced developers to browse – there is much possible in JDeveloper 11. For example a file comparison, keyboard shortcuts (tools/preferences), refactoring (renaming or moving files), working with Subversion, the help center (JDeveloper menu, context-sensitive help page: F1).

Chapter 3 is on JDeveloper tools; amongst others:  the application navigator, the project panel, the new gallery, wizards, the structure window, the component palette and the property inspector. Also very useful to know: JavaScript editing, running/debugging PL/SQL code and the JDeveloper debugger:  explained are all the various useful debug windows (smart data, data, ADF data, EL Evaluator, breakpoints).

Chapter 4 is a very general introduction to Java Enterprise Development. It describes the JEE architecture model; Java, HTTP, Servlets, AJAX and what level of knowledge people need to start working with the ADF Fusion technology.

Part 2 – ADF Business Components

This part (chapter 5, 6, 7 and 8 ) is an excellent introduction and extensive reference guide for ADF Business Components. Only for this part already this book is worth buying. Figure 5-1 on page 152 gives a good insight on the relationships that the different ADF BC objects have with each other. For example the differences between Entity Object definitions, -instances and –usages. Every subject of ADF BC (Entity Objects, associations, ViewObjects, ViewLinks, ApplicationModules) is described and explained well, also new ADF BC subjects like declarative SQL mode, View Accessors and ViewObject instances used as LOV.

Part 3 – ADF View and Controller

Part 3 starts with chapter 9 and 10 with an introduction to JavaSever faces (JSF) and a small hands-on on this subject.

Chapter 11 is on the ADF Controller and taskflows. This is the most important subject to understand when you work with an ADF Fusion application. It explains the problem with JSF and why the ADF Controller and taskflows are created, the different scopes (pageFlow, view, and backingBean, request, session), the taskflow components and advanced taskflow subjects. Unfortunately, after reading this chapter the whole concept of taskflows did not became clear to me, even not after reading it again. I think this chapter should have been more understandable and detailed about this crucial subject. The chapters in the Fusion Developer Guide are much more informative and give you insight on this subject.

Chapter 12 is on ADF Faces Rich Client. It gives you a good introduction and overview off all the components, different layout containers and facets that exist. A worthwhile read, if you want to be able to create a perfect layout.

Part 4 – ADF Model

Chapter 13 is on ADF Model basics. It explains how you can make data-bound pages while dragging and dropping collections and attributes from the data control palette. Table 13-1 on page 468 is very informative.

Chapter 14 is on advanced bindings. This is not an easy subject and it is explained well with examples of the different types of bindings like attribute-, table-, tree-, list of values-, action-, method bindings-.  Very helpful for reference.

Chapter 15 is on iterators and executables.  The different types of executables are discussed (invokeAction-, taskFlow-, page-,searRegion executable) and how to control execution using their properties – valuable information.  Also the Fusion lifecycle,  customizing error handling and Contextual Events are quickly discussed, but I think a little bit too quickly and could have been more extensive.

Part 5 – Developing the Sample Application

In part 5 – almost one third of the book – is on the hands-on sample application called The Ultimate Human Resources Application (TUHRA) . The instructions are clear, well written and tested instructions, divided over nothing less than 250 pages.  First it starts in chapter 16 starts with a discussion about design principles and a typical Fusion page design and the design of the sample application. The rest of part 5 is a big hands-on: a basic CRUD application based on the HR schema:

You can become familiar with many of the new concepts and techniques that are discussed in this book and that are typical of an ADF Fusion application, like taskflows, page templates, page fragments, ADF Faces RC components (layout, popup  menu),  new ADF BC subjects (ViewCriteria, ViewAccessors, List of values ), PPR, etc. Also by creating  the sample application you learn to find your way around in JDeveloper; for example where to find all numerous properties on the property inspector, how to work with the structure window (dragging and dropping components, surrounding or converting components), get insight in the use of the different tabs (source, design, bindings) on a JSFF or JSPX file.  In chapter 21 ADF security is discussed and added to the sample application.

Very valuable is also the last chapter (22) about the deployment process to a Weblogic server. This explains how you can setup your own standalone Weblogic Server for testing. It shows you how to create and run a Weblogic Domain, run the administration console, how to create a JDBC datasource, and how to deploy your application from a EAR or directly from JDeveloper.

Unfortunately I could make this sample application only with an old version of JDeveloper , version 11.1.1.1, as one crucial ViewObject (AllEmployees ) uses Declarative SQL mode that for some unexplainable reason did not work for me on newer JDeveloper versions. There is an errata page, but I did not find this here. A good thing is that you can download all the specific completed sub-steps of the application so that you can skip parts if you want or the review your code.

Conclusion

All in all I think this is a book that you should have on your shelve as a ADF Fusion developer. A book to learn the basics and for reference of the JDeveloper IDE, and many ADF Fusion subjects like ADF Business Components and the ADF Model. If you’re a starter with ADF Fusion development the hands-on part is a very valuable one to absorb the concepts and worth to take your time for it. It is like a complete starter’s course in ADF Fusion development.

But it should not be the only book – it still doesn’t give you complete insight into difficult subjects like the ADF Controller and taskflows, the ADF Fusion lifecycle or Contextual Events. For real business problems and a more in depth discussion of the technology, the Fusion Developer Guide is a clearer, more comprehensive (and advanced) book and should be the next step of mastering the ADF Fusion technology.  I think both books should be on your shelf as an ADF developer.

You can buy the book here.

Calling a webservice programmatically without webservice library like JAX-WS or Apache Axis

In this example I make use of a simple webservice: a weather webservice available on: http://www.deeptraining.com/webservices/weather.asmx?WSDL .

The following method is an example how to create a SOAP message request and call a remote webservice using a HttpURLConnection object, receive and process the SOAP message response. It returns the weather of a specific city.

[code language="Java"]
public String getWeather(String city) throws MalformedURLException,
IOException {

//Code to make a webservice HTTP request
String responseString = "";
String outputString = "";
String wsURL = "http://www.deeptraining.com/webservices/weather.asmx";
URL url = new URL(wsURL);
URLConnection connection = url.openConnection();
HttpURLConnection httpConn = (HttpURLConnection)connection;
ByteArrayOutputStream bout = new ByteArrayOutputStream();
String xmlInput =
" <soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:web=\"http://litwinconsulting.com/webservices/\">\n" +
" <soapenv:Header/>\n" +
" <soapenv:Body>\n" +
" <web:GetWeather>\n" +
" <!--Optional:-->\n" +
" <web:City>" + city + "</web:City>\n" +
" </web:GetWeather>\n" +
" </soapenv:Body>\n" +
" </soapenv:Envelope>";

byte[] buffer = new byte[xmlInput.length()];
buffer = xmlInput.getBytes();
bout.write(buffer);
byte[] b = bout.toByteArray();
String SOAPAction =
"http://litwinconsulting.com/webservices/GetWeather";
// Set the appropriate HTTP parameters.
httpConn.setRequestProperty("Content-Length",
String.valueOf(b.length));
httpConn.setRequestProperty("Content-Type", "text/xml; charset=utf-8");
httpConn.setRequestProperty("SOAPAction", SOAPAction);
httpConn.setRequestMethod("POST");
httpConn.setDoOutput(true);
httpConn.setDoInput(true);
OutputStream out = httpConn.getOutputStream();
//Write the content of the request to the outputstream of the HTTP Connection.
out.write(b);
out.close();
//Ready with sending the request.

//Read the response.
InputStreamReader isr =
new InputStreamReader(httpConn.getInputStream());
BufferedReader in = new BufferedReader(isr);

//Write the SOAP message response to a String.
while ((responseString = in.readLine()) != null) {
outputString = outputString + responseString;
}
//Parse the String output to a org.w3c.dom.Document and be able to reach every node with the org.w3c.dom API.
Document document = parseXmlFile(outputString);
NodeList nodeLst = document.getElementsByTagName("GetWeatherResult");
String weatherResult = nodeLst.item(0).getTextContent();
System.out.println("Weather: " + weatherResult);

//Write the SOAP message formatted to the console.
String formattedSOAPResponse = formatXML(outputString);
System.out.println(formattedSOAPResponse);
return weatherResult;
}
[/code]

In the code above I make use of two util methods (one that makes use of a Xerces.jar library, you can download it at http://xerces.apache.org/mirrors.cgi):

[code language="Java"]
//format the XML in your String
public String formatXML(String unformattedXml) {
try {
Document document = parseXmlFile(unformattedXml);
OutputFormat format = new OutputFormat(document);
format.setIndenting(true);
format.setIndent(3);
format.setOmitXMLDeclaration(true);
Writer out = new StringWriter();
XMLSerializer serializer = new XMLSerializer(out, format);
serializer.serialize(document);
return out.toString();
} catch (IOException e) {
throw new RuntimeException(e);
}
}

private Document parseXmlFile(String in) {
try {
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
DocumentBuilder db = dbf.newDocumentBuilder();
InputSource is = new InputSource(new StringReader(in));
return db.parse(is);
} catch (ParserConfigurationException e) {
throw new RuntimeException(e);
} catch (SAXException e) {
throw new RuntimeException(e);
} catch (IOException e) {
throw new RuntimeException(e);
}
}

[/code]

If you put this 3 methods together in a class with a main method, than you can simply call the weather webservice. Thats all!

[code language="Java"]
public class WeatherWebserviceTester {
public static void main(String[] args) {
WeatherWebserviceTester weatherWebserviceTester =
new WeatherWebserviceTester();
try {
weatherWebserviceTester.getWeather("Washington");
} catch (MalformedURLException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}
[/code]

Download this class WeatherWebserviceTester.java

Create the servlet webservice tester

On our project we have a challenge where calling a webservice directly from Java is useful: because of very strict security reasons our client proxy application can access a remote webservice from only one single IP-address. This address is the machine where our production Weblogic server (WLS11g) is located and where we need to deploy our client application.  This webservice is new and unfortunately it has many child-diseases: we often need to test, analyze and adjust the exact XML exchange of the SOAP-messages.  See also http://technology.amis.nl/blog/12004/how-to-remove-unwanted-soap-header-elements-in-jax-ws. Testing is very problematic if you don’t have a webservice tester available. Every WLS normally contains a test webservice facility – like a simple SoapUI in the server.  It should be standard available at http://host:port/wls_utc. In my JDeveloper’s locally embedded WLS I can directly find it but not use it – my IP-address is not authorized to get information from this webservice.  Unfortunately on our production WLS we cannot reach its internal WLS webservice tester. I will show you how to create a servlet webservice tester. After deploying this tester on our production WLS, we were able to test and analyze the SOAP message exchange.

The steps in JDeveloper:

• create a new application and a new project.
• Use the wizard to make a new Servlet, check the doGet() and the doPost() methods:

• We will have to add HTML code to the servlet  doGet() and doPost() method to let it write two textarea’s – one for the SOAP message request and one for the SOAP message response.  Also an input field for the webservice endpoint and a checkbox whether to format the response in XML is needed. You can first quickly make a test HTML page to create the HTML you need for this:

[code language="XML"]
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Webservice tester</title>
</head>
<body>
<form action="soaprequestservlet" method="post">
<label for="wsdl">Webservice endpoint</label>
<input type="text" name="wsdl" size="120" id="wsdl"
style="font-size: 11px; color: blue;"/>
<label for="FormatXML">Format XML</label>
<input id="FormatXML" type="checkbox" name="formatXML"
value="formatXML" checked="checked"/>
<table cellspacing="0" cellpadding="0" border="0">
<tr>
<td width="45%">
<h3>SOAP Request</h3>
<textarea style="font-size: 11px; color: blue;"
name="soapmessage" cols="80" rows="40"
title="SOAP MessageRequest" id="soaprequest"></textarea>
</td>
<td width="45%">
<h3>SOAP Response</h3>
<textarea style="font-size: 11px; color: blue;"
name="soapmessageresponse" cols="80" rows="40"
title="Soap Request" id="soapresponse"></textarea>
</td>
</tr>
</table>
<input type="submit" name="Test SOAP Request"
value="Test SOAP Request"/>
</form>
</body>
</html>
[/code]

When you run this page you can check the exact HTML that you want to put later into your doGet() and doPost() methods of your servlet:

• Add the HTML code of this page to both the servlet doGet() and doPost() methods in the println() method of the PrintWriter. Then we can now add the real code that calls the webservice. The most important is the doPost() method where the webservice is called with the request SOAP message and the endpoint destination that you entered in the input fields:

[code language="Java"]
public void doPost(HttpServletRequest request,
HttpServletResponse response) throws ServletException,
IOException {
//Whether to format the SOAP message response or not.
String formatXML = request.getParameter("formatXML");

//Get the endpoint
if (!request.getParameter("endpoint").equals(""))
wsURL = request.getParameter("endpoint");
else
throw new ServletException("Missing endpoint location!");

//Get the SOAP message request
String xmlInput = request.getParameter("soapmessage");
requestMessage = xmlInput;

//Code to make a webservice HTTP request
URL url = new URL(wsURL);
URLConnection connection = url.openConnection();
HttpURLConnection httpConn = (HttpURLConnection)connection;
String responseString = "";
String outputString = "";
//Optional: set your action
//String SOAPAction =
// "http://litwinconsulting.com/webservices/GetWeather";
ByteArrayOutputStream bout = new ByteArrayOutputStream();
OutputStream out = null;
InputStreamReader isr = null;
BufferedReader in = null;
byte[] buffer = new byte[xmlInput.length()];
buffer = xmlInput.getBytes();
bout.write(buffer);
byte[] b = bout.toByteArray();

// Set the appropriate HTTP parameters.
httpConn.setRequestProperty("Content-Length",
String.valueOf(b.length));
httpConn.setRequestProperty("Content-Type", "text/xml; charset=utf-8");

//Optional: set your action
//httpConn.setRequestProperty("SOAPAction", SOAPAction);
httpConn.setRequestMethod("POST");
httpConn.setDoOutput(true);
httpConn.setDoInput(true);
out = httpConn.getOutputStream();

// write the content of the request to the outputstream of the HTTP Connection.
out.write(b);
out.close();
// ready with sending the request

// Read the response.
isr = new InputStreamReader(httpConn.getInputStream());
in = new BufferedReader(isr);

//Write the SOAP message response to a String.
while ((responseString = in.readLine()) != null) {
outputString =
outputString + responseString + (formatXML == null ? "\n" :
"");
}
//Format the message when the checkbox is checked.
if (formatXML != null)
outputString = format(outputString);

//write the XHTML response.
response.setContentType(CONTENT_TYPE);
PrintWriter printWriter = response.getWriter();
printWriter.println("<?xml version=\"1.0\"?>");
printWriter.println(DOC_TYPE);
printWriter.println("<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\">");
printWriter.println("<head><title>Webservice tester</title></head>");
printWriter.println("<body>");
printWriter.println("<form action=\"soaprequestservlet\" method=\"post\">");
printWriter.println("<label for=\"wsdl\">Webservice endpoint</label>");
printWriter.println("<input type=\"text\" name=\"endpoint\" value=\"" +
wsURL +
"\" size=\"120\" id=\"wsdl\" style= \"; font-size: 12px; color: blue;\" />");
printWriter.println("<label for=\"FormatXML\">Format XML</label>");
printWriter.println("<input id=\"FormatXML\" type=\"checkbox\" name=\"formatXML\" value=\"formatXML\" checked=\"checked\"/>");
printWriter.println("<p/><table cellspacing=\"0\" cellpadding=\"0\" border=\"0\">");
printWriter.println("<tr>");
printWriter.println("<td width=\"45%\">");
printWriter.println("<h3>SOAP Message Request</h3>");
printWriter.println("<textarea style= \"; font-size: 11px; color: blue\"; name=\"soapmessage\" cols=\"80\" rows=\"40\" title=\"SOAP Message Request\" id=\"soaprequest\">" +
requestMessage + "</textarea>");
printWriter.println("</td>");
printWriter.println("<td width=\"45%\">");
printWriter.println("<h3>SOAP Message Response</h3>");
printWriter.println("<textarea style= \"; font-size: 11px; color: blue\"; name=\"soapmessageresponse\" cols=\"80\" rows=\"40\"");
printWriter.println("title=\"SOAP Message Response\" id=\"soapresponse\"");

//write the SOAP message response to the textarea.
printWriter.println(outputString);

//Continue writing XHTML
printWriter.println("</textarea>");
printWriter.println("</td>");
printWriter.println("</tr>");
printWriter.println("</table>");
printWriter.println("<input type=\"submit\" name=\"Test SOAP Request\" value=\"Test SOAP Request\"/>");
printWriter.println("</form>");
printWriter.println("</body></html>");
printWriter.close();
}

[/code]

In the servlet, the doGet() method is called when you call the servlet for the first time. After clicking on the button to test the SOAP request, the doPost() method is called and the SOAP message request is send to the webservice endpoint . The SOAP message response is red and written in the second textarea. Your webservice tester is ready for real use !

Download this whole servlet project SoapRequestTester.

In the WSDL file the element  <wsaw:UsingAddressing wsdl:required=”true”/> is present. Following the contract of the WSDL – this means that the SOAP header must contain addressing elements. The runtime libraries of JAX-WS take care of  this and creates in the SOAP header the elements (see picture):

• <wsa:To>
• <FaultTo>
• <wsa:ReplyTo>
• <wsa:MessageId>
• <wsa:Action>

This remote webservice cannot accept <wsa:To>, <wsa:ReplyTo>, <FaultTo> elements (validation of incoming SOAP requests will fail), but <wsa:MessageId> and <wsa:Action> are mandatory. We cannot simply remove  <wsaw:UsingAddressing wsdl:required=”true”/> from the WSDL and regenerate our client proxy in JDeveloper, because then we miss also the mandatory MessageId and Action elements.

We can use a JAX-WS SOAPHandler to inspect  the SOAP header and remove certain elements.  In the handleMessage() method we can get the SOAP header , retrieve the direct child elements of this header, inspect them and delete the unwanted ones:

Now the elements are removed from the SOAP header and we can call the webservice without validation errors:

Download this SoapHandler:  SOAPHandler

Part 1 – Create the country webservice client with JAX-WS

We are going to create a webservice client proxy for a country webservice available on:

http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL

Look at the wsdl file of this webservice and lets have a look at it so that we know to which webservice we talk to. Open de wsdl in de browser, for example in Firefox. At the bottom are all the wsdl operations that we are interested in:

These operations (for example CountryIntPhoneCode) have input (tns:CountryIntPhoneCodeSoapRequest) and output (tns:CountryIntPhoneCodeSoapResponse) messages. These messages are also in the wsdl defined:

The part ‘parameters’ is also referring to their own definition:

In this example a standard ISO country-code is submitted to the webservice as request parameter for the operation CountryIntPhoneCode. The webservice will give back the international telephone-code back. We are going to use also 3 other operations from this webservice.

1-Create in JDeveloper a new application and call it for example ‘CountriesBatchJob’ and the project ‘WsClientproxy’.

2-Create a webservice proxy (JAX-WS Style) for the wsdl describing the country webservice:

http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL

Give appropiate package names. Click next –> next –> finish.

Regenerate the webservice proxy in case you see any red crosses in the generated overview.

The client class CountryInfoServiceSoapClient will open. Save all.

3-Add in the main() method:

System.out.println("Code ZW; "+countryInfoServiceSoapType.countryName("ZW"));

Test the webservice. (select CountryInfoServiceSoapClient –> right mouse –> run)

OK, the client is ready en works!

Part 2: ADF Business Components

The current database table COUNTRIES from Oracle’s HR schema is used in this example. Use might need to unlock it first. We will synchronise the rows of the COUNTRIES table with up-to-date countries data from the webservice.
Fortunately the table has already a column COUNTRY_ID that is the PK and is the ISO-landcode.

1- Add columns to the table COUNTRIES with the following script:

alter table
COUNTRIES
add
(
CAPITAL varchar2(500) ,
INTPHONECODE varchar2(500) ,
COUNTRYFLAG varchar2(500) ,
LANGUAGENAME varchar2(500)
)

2-Add a new generic project in this application and call it for example ‘ADFBC’.

3-Start the wizard ‘ADF Business Components from tables’ to create the objects for de Country table. Create a database connection in the wizard with the HR schema. Test it.

Walk through the wizard steps. We only need 1 EntityObject (call it: Country), 1 ViewObject (call it: CountryVw) and an ApplicationModule (call it: AppModule).

Click finish. In the end it should look like this:

4-Change the ViewObject usage name from CountryVw1 to CountryVw. (Click the pencil on the right bottom)

5- Test the ApplicationModule AppModule (select AppModule in tree –> right mouse –> run):

6-Create a Java class. Call it BatchJobSynchronizeCountries. Deselect constructors and select main method;

7-Type ‘bc4jclient’ followed by CTRL + ENTER .
Test-code is generated by JDeveloper:

8-The generated names (amDef and config) need to be changed to your names. Look in bc4j.xcfg for the correct names: This file is in the common folder of your ADFBC project. On my computer:

C:\JDeveloper\mywork\CountriesBatchJob\ADFBC\src\nl\amis\services\common

The selected part are the (amDef and config names) we need. Use these names in BatchJobSynchronizeCountries.java

Replace ViewObject to CountryVw:
Add:
System.out.println("Number of countries in CountryVw: "+vo.getEstimatedRowCount());

9-Run the client:

Fortunately the call to the countries table succeeded.

10-Query and print all countries and country-codes. Add:

//Query and print all countries
vo.executeQuery();
int rownr = 0;
while (vo.hasNext()) {
rownr++;
Row curCountry = vo.next();
String isoCountryCode = (String)curCountry.getAttribute("CountryId");
System.out.println("(" + rownr + ") isoCountryCode: " + isoCountryCode);
}

Oracle comes standard with 25 country records in the sample Countries table in the HR schema.

Part 3 – Synchronize your countries table with data from the webservice

Let’s return to the client (proxy) project in JDeveloper.
1-We see 2 lines of code that instantiate a proxy object. With this object we can later call the operations from the webservice. Copy these lines.

2-Return to our ADFBC project to BatchJobSynchronizeCountries.java.
Paste the 2 copied lines under the code we just edited. We can see red compiler lines under our copied code:

This is because JDeveloper cannot find the previous generated client proxy classes. The ADFBC project doesn’t know from the existence of our client project. Go to ADFBC project –> right mouse –> properties –> dependencies.
3-Add a dependency:

Save all. Now JDeveloper is able to find the classes and with ALT+ENTER you have can select the import we need and except for one the red lines disappear. It cannot find the variable countryInfoService. We need to declare it.

4- Add :

private static CountryInfoService countryInfoService;

Now the class will compile.

5-Add the following code under the proxy instantiation:

System.out.println("--- (" + rownr + ")\t: " + isoCountryCode+" country : "+countryInfoServiceSoapType.countryName(isoCountryCode));
System.out.println("--- (" + rownr + ")\t: " + isoCountryCode+" capitalCity : "+countryInfoServiceSoapType.capitalCity(isoCountryCode));
System.out.println("--- (" + rownr + ")\t: " + isoCountryCode+" countryFlag : "+countryInfoServiceSoapType.countryFlag(isoCountryCode));
System.out.println("--- (" + rownr + ")\t: " + isoCountryCode+" IntPhoneCode: "+countryInfoServiceSoapType.countryIntPhoneCode(isoCountryCode));

Run this class.

Now, all country-codes are retrieved from the our database. For each country a request is send to the webservice for the country name, the capital city, the country flag and the international phone the data from this webservice is printed out:

6- Updating our COUNTRIES table with the data from the webservice

We need to update/synchronize all data from the webservice with our COUNTRIES table. Look at the specific ViewObjectRow attribute names in CountriesVw:

We need to use these names to map the values from the webservice to the Country ViewObject attributes.
Replace the whole main() method with:

public static void main(String[] args) {
String amDef = "nl.amis.adfbc.services.AppModule";
String config = "AppModuleLocal";
ApplicationModule am =
Configuration.createRootApplicationModule(amDef, config);
ViewObject countryVw = am.findViewObject("CountryVw");

// Work with your appmodule and view object here
System.out.println(“Number of countries in CountryVw: “+countryVw.getEstimatedRowCount());

//Get generated webservice proxy classes form the client project
countryInfoService = new CountryInfoService();
CountryInfoServiceSoapType countryInfoServiceSoapType = countryInfoService.getCountryInfoServiceSoap();

//1- First update existing country rows in the COUNTRIES table
countryVw.executeQuery();
int rownr=0;
while (countryVw.hasNext()) {
rownr++;
Row curCountry = countryVw.next();
String isoCountryCode = (String)curCountry.getAttribute(“CountryId”);
System.out.println(“— UPDATING (” + rownr + “)\t isoCountryCode: ” + isoCountryCode+” country: “+countryInfoServiceSoapType.countryName(isoCountryCode));

//Put attributes on your ViewObject row
curCountry.setAttribute(“Capital”, countryInfoServiceSoapType.capitalCity(isoCountryCode));
curCountry.setAttribute(“Intphonecode”, countryInfoServiceSoapType.countryIntPhoneCode(isoCountryCode));
curCountry.setAttribute(“Countryflag”, countryInfoServiceSoapType.countryFlag(isoCountryCode));
curCountry.setAttribute(“Languagename”, countryInfoServiceSoapType.languageName(isoCountryCode));
curCountry.setAttribute(“CountryName”, countryInfoServiceSoapType.countryName(isoCountryCode));
}
//commit transaction
am.getTransaction().commit();
System.out.println(“Country-batch SUCCEFULLY updated the COUNTRIES table”);
Configuration.releaseRootApplicationModule(am, true);
}

7-This will update all current country records we have in the COUNTRIES table with data from the webservice. Run the class.

This will update all our country records with the country information from the webservice and commit them. Our update-batch job has been successful!

Part 4 – Adding new countries from the webservice

Now, only existing records of the COUNTRIES table are updated. New countries are not yet added and we will do that now.

1-Add just above //commit transaction:

<code>//-----------------------START------------------------------
//Query all countries and put them in a HashMap.
//Purpose: separate an UPDATE and an INSERT in COUNTRIES table
countryVw.executeQuery();
HashMap landCodesMap = new HashMap();
while (countryVw.hasNext()) {
Row curCountry = countryVw.next();
landCodesMap.put(curCountry.getAttribute("CountryId"),curCountry.getAttribute("CountryName"));
}</code>

//2- Insert new country rows in the COUNTRIES table
//Get all countrycodes from the webservice
ArrayOftCountryCodeAndName arrayOftCountryCodeAndName = countryInfoServiceSoapType.listOfCountryNamesByCode();
List tCountryCodeAndNameList = arrayOftCountryCodeAndName.getTCountryCodeAndName();
for(TCountryCodeAndName tCountryCodeAndName:tCountryCodeAndNameList){

String isoCountryCode = tCountryCodeAndName.getSISOCode();
//Add it country to table COUNTRIES when it does not yet exists
if (!landCodesMap.containsKey(tCountryCodeAndName.getSISOCode())) {
System.out.println(“— INSERTING IN COUNTRIES TABLE isoCountryCode: “+tCountryCodeAndName.getSISOCode()+” – country: “+tCountryCodeAndName.getSName());
// Create new row and add it to the rowset
Row newCounrtyRow = countryVw.createRow();
countryVw.insertRow(newCounrtyRow);

newCounrtyRow.setAttribute(“CountryId”, tCountryCodeAndName.getSISOCode());
newCounrtyRow.setAttribute(“Capital”, countryInfoServiceSoapType.capitalCity(isoCountryCode));
newCounrtyRow.setAttribute(“Intphonecode”, countryInfoServiceSoapType.countryIntPhoneCode(isoCountryCode));
newCounrtyRow.setAttribute(“Countryflag”, countryInfoServiceSoapType.countryFlag(isoCountryCode));
newCounrtyRow.setAttribute(“Languagename”, countryInfoServiceSoapType.languageName(isoCountryCode));
newCounrtyRow.setAttribute(“CountryName”, countryInfoServiceSoapType.countryName(isoCountryCode));
}
}
//———————–END ——————————

First, we need to identify countries that do not exist yet in our COUNTRIES table. We need a collection (for example a HashMap) with all our current country-records. Later, if the webservice returns a countrycode our hashMap doesn’t contain, we know that we have to insert that country in our table.

countryVw.executeQuery();
HashMap landCodesMap = new HashMap();
while (countryVw.hasNext()) {
Row curCountry = countryVw.next();
landCodesMap.put(curCountry.getAttribute("CountryId"),curCountry.getAttribute("CountryName"));

Secondly, we need to get all available country codes from the webservice:

ArrayOftCountryCodeAndName arrayOftCountryCodeAndName = countryInfoServiceSoapType.listOfCountryNamesByCode();
List tCountryCodeAndNameList = arrayOftCountryCodeAndName.getTCountryCodeAndName();

Then, we are going to loop through all the country codes and check whether we need to insert it or not:

for(TCountryCodeAndName tCountryCodeAndName:tCountryCodeAndNameList){
String isoCountryCode = tCountryCodeAndName.getSISOCode();
//Add it country to table COUNTRIES when it does not yet exists
if (!landCodesMap.containsKey(tCountryCodeAndName.getSISOCode())) {
…………………………..
……………..
}
}

Then we create a new row and add it to the rowset:

Row newCounrtyRow = countryVw.createRow();
countryVw.insertRow(newCounrtyRow);

And we can set all attribute values:

newCounrtyRow.setAttribute("CountryId", tCountryCodeAndName.getSISOCode());
newCounrtyRow.setAttribute("Capital", countryInfoServiceSoapType.capitalCity(isoCountryCode));
newCounrtyRow.setAttribute("Intphonecode", countryInfoServiceSoapType.countryIntPhoneCode(isoCountryCode));
newCounrtyRow.setAttribute("Countryflag", countryInfoServiceSoapType.countryFlag(isoCountryCode));
newCounrtyRow.setAttribute("Languagename", countryInfoServiceSoapType.languageName(isoCountryCode));
newCounrtyRow.setAttribute("CountryName", countryInfoServiceSoapType.countryName(isoCountryCode));

At the last moment we need to commit the transaction:

am.getTransaction().commit();

2-Run the class. Now, First existing countries are updated and then new countries from the webservice are inserted:

And when we look at our COUNTRIES table we see all the new countries from the webservice;

Our synchronize-batch task – which took approximately 10 minutes to run – has succeeded!

Download this complete sample project from here: CountriesBatchJob.zip
Download this hands-on in word: Hands-on JAX-WS.doc

Requery is needed with SQL-calculated attributes

View objects can include SQL-calculated attributes. A calculated attribute is an attribute that gets its value from the SQL statement that queries the data of the View object. Therefore, anything you can conjure up in the “SELECT” part of an SQL statement can be used to fill this attribute, from simple concatenations or decodes to PLSQL function calls and entire sub-SELECT statements.
 

After an insert or update of an employee, the query needs to be executed again if we want to see the value of the calculated attribute:

Requery is sometimes needed when many attributes are set by database triggers

If you know that the underlying column value will be updated by a database trigger during insert or update operations, you can check the ‘refresh after insert’ or ‘refresh after update’ checkboxes to have the framework automatically retrieve the modified value to keep the entity object and database row in sync. The entity object uses the Oracle SQL RETURNING INTO feature, while performing the insert or update to return the modified column back to your application in a single database round-trip.
 

In nearly most cases this works very well. However, in some special cases this does not seem to work. For example, this happened in our case when we made a custom implementation (override) of some of the key ADFBC framework methods of an EntityImpl class. We had defined several updatable view objects that were referencing attributes from more than one updatable entity object, and we had overridden some key methods of the <EntityName>Impl.java like the postChanges() and refreshFKInNewContainees() method. In our special case, the ‘refresh after insert’ or ‘refresh after update’ did not update the value, and a requery was needed.
 

Flow of the ADFBC View Object

For a requery, we could call the standard view object method executeQuery(), but then a view object will lose its current row – after a call to executeQuery() on the view object, the current row will always be reset to the first row your view object iterator points to. If you need to keep the current row you can use a refresh-but-stay-where-you-were requery method ‘refreshQueryKeepingCurrentRow()’ Steve Muench described in the afterCommit() method of your the view object. A big disadvantage of calling an executeQuery() or a refreshQueryKeepingCurrentRow() in the aftercommit() method is, that the requery will always be executed, even when their were no changes at all to the data of the view object. I tested this and noticed that the ADFBC framework method afterCommit() is called for every view object that has already been queried once in the current session, even for view objects that had nothing at all to save to the database. Apparently the ADFBC framework flow calls the afterCommit() method for every view object that has already been queried once (and for which entity objects exist in the entity cache). If we requery all these view objects, we will unnecessary query many of them again that did not have any changes at all. Of course this is not what we want. We need to recognize in the afterCommit() method whether the data of the view object was ‘dirty’ or not before we requery it; did the view object had any new or updated underlying entity objects for which data was posted and committed to the database?

Let your entity objects register themselves as dirty on the oracle.jbo.Session object

How can we recognize a dirty view object? Unfortunately, a method like ‘isDirty()’ does not exist on the ViewObjectImpl class. Neither does a method like getPostState() on the ViewRowImpl class that calls its status. But on the EntityImpl class we can get the status of an entity object by calling the getPostState() method, for example in the overridden framework method postChanges(). The EntityImpl framework method postChanges() will always be called when attribute values of a modified or new entity object are posted to the database. Your EntityImpl custom base class is a good place to override this postChanges() method and set a property on the session object that indicates that for this entity type dirty entity objects exists. A custom base class extends an ADF BC framework base class – for entity objects oracle.jbo.server.EntityImpl – to add a generic feature that all of your view objects need. This is a convenient place in the class hierarchy to add our overridden postChanges(), so now this method is called automatically for all your entity objects when they are new or have any changes. An oracle.jbo.Session object (NOT javax.servlet.http.HttpSession) represents a root application module’s session, and an implementation of this interface is instantiated for each root application module. The session object is garbage collected when the root application module is garbage collected. This is exactly the scope we need for our dirty entity objects. First we can check in the postChanges() method whether the status of an entity object is new or modified by calling the getPostState():

if (getPostState() == STATUS_NEW) {…} 

if (getPostState() == STATUS_MODIFIED){…}

and call the session object from the DBTransaction object:

Session session = transactionEvent.getDBTransaction().getSession();

Then we can get the userdata Hashtable object of the session by calling session.getUserData(), and set the current entity as being dirty by adding the current entity definition name to the session properties in the userData hashtable:

session.getUserData().put(getEntityDef().getName(),"dirty");

Our complete EntityImpl custom-base class:

package HR.model.framework;
import oracle.jbo.Session;
import oracle.jbo.server.EntityImpl;
import oracle.jbo.server.TransactionEvent;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class HREntityImpl extends EntityImpl {
    public HREntityImpl() {}
    private static Log sLog = LogFactory.getLog(HREntityImpl.class);   
        
     /**
     * Check whether the status of an entity object is new or modified by calling the getPostState().
     * If the status is new or modified, call the session object from the DBTransaction object.
     * The userdata hashtable of the session is retrieved by calling session.getUserData(),
     * and then the current entity is set as being dirty by adding the current entity definition name
     * to the session properties in the userData hashtable.
     */
    public void postChanges(TransactionEvent transactionEvent)
    {   
        if (getPostState() == STATUS_NEW)
        {
            sLog.debug(getEntityDef().getName()+" in postChanges()....STATUS_NEW");
            Session session = transactionEvent.getDBTransaction().getSession();
            session.getUserData().put(getEntityDef().getName(),"dirty");      
        }
        if (getPostState() == STATUS_MODIFIED)
        {
            sLog.debug(getEntityDef().getName()+" in postChanges()....STATUS_MODIFIED");
            Session session = transactionEvent.getDBTransaction().getSession();
            session.getUserData().put(getEntityDef().getName(),"dirty");
        }
        super.postChanges(transactionEvent);
    }
}

Make a view object superclass that recognizes when it’s dirty

We have to check for ‘dirtiness’ before a commit is send to the database, because after a commit we cannot check the entity objects anymore whether they were new or had changed attribute values that were committed to the database or not. After a commit the status of all entity objects is ‘STATUS_UNMODIFIED’. We have to do the check before the commit, in an overridden view object framework method beforeCommit():

    /**
     * Check if any entity object this view object is based on is 'dirty’ in the current transaction.
     * A ViewObject is dirty when any of its underlying EntityImpl objects returns
     * STATUS_NEW or STATUS_MODIFIED on getPostState().
     * They have already been set in the userData hashtable properties of the session object
     * in the custom base class of EntityImpl in postChanges().
     * Now we can check the userData hashtable if it contains any entity object names this view object is based on.
     */
     public void beforeCommit(TransactionEvent transactionEvent)
     {
         super.beforeCommit(transactionEvent);  
        
         //Call the oracle.jbo.Session object from the DBTransaction object:
         Session session = transactionEvent.getDBTransaction().getSession();

         //Make a Set of all the keys (=dirty entity class names)
         Set<String> set = session.getUserData().keySet();
 
         //Get all the EntityDefImpl objects this view object is based on.       
         EntityDefImpl[] entityDefs = getEntityDefs();
       
         //Check the whether there exists dirty EntityImpl objects for this EntityDefImpl class,
         // and if yes, mark this view object as dirty.        
         for(EntityDefImpl entityDefImpl:entityDefs)
         {
              if(set.contains(entityDefImpl.getName()))
              {
                 sLog.debug("Viewobject "+getName()+" will be requeried in afterCommit(), underlying entity "+entityDefImpl.getName()+" is DIRTY...");
                 dirty=true;
              }
         }
     }

First we call the oracle.jbo.Session object from the DBTransaction object and make a set of all the keys that represent the dirty EntityDefImpl class names in the current transaction:

Session session = transactionEvent.getDBTransaction().getSession();
Set<String> set = session.getUserData().keySet();

Then we get all the EntityDefImpl objects this view object is based on:

EntityDefImpl[] entityDefs = getEntityDefs();       

Now, this view object checks whether there exists dirty EntityImpl objects for this EntityDefImpl class, and if yes, mark this whole view object as dirty:

 
for(EntityDefImpl entityDefImpl:entityDefs)
         {
              if(set.contains(entityDefImpl.getName()))
              {
                 sLog.debug("Viewobject "+getName()+" will be requeried in afterCommit(), underlying entity "+entityDefImpl.getName()+" is DIRTY...");
                 dirty=true;
              }
         }

So if any entity object this view object is based on is new or modified the view object will mark itself as being dirty in the beforeCommit(). Then, in the overridden view object method afterCommit(), a view object can check whether it is marked as dirty or not and in case it’s dirty execute a requery by calling refreshQueryKeepingCurrentRow(). After that, all old dirty EntityDef names must be removed from the session hashtable with userData to be reset for the next transaction:  

     /**
     * Only requery when an entity this view object is bases on was 'dirty' in beforeCommit().
     * Then, remove all old dirty EntityDef names from the session userData Hashtable object.
     */
    public void afterCommit(TransactionEvent transactionEvent)
    {      
        super.afterCommit(transactionEvent);                      
        if(getCurrentRow()!=null)
        {
            if(dirty==true)
            {
                 sLog.debug("Viewobject "+getName()+" REQUERIED in afterCommit().");
                 refreshQueryKeepingCurrentRow();           
                 dirty=false;
            }
        }   
      
        //Remove all old dirty EntityDef names from the session userData Hashtable object.
        //Get the session’s userData Hashtable object.
        Session session = transactionEvent.getDBTransaction().getSession();
        Hashtable hashtable = session.getUserData();       
       

        //Check if the hashtable contains any dirty entitydef names.
        if(hashtable.contains("dirty"))
        {          
            //Make a set with all the keys of the userData properties.
            Set<String> setKeysUserData = session.getUserData().keySet();
           
            //Make a second set that contains all the names of the old dirty EntityDefs.
            Set<String> setKeysOfDirtyEntities=new HashSet<String>();
            for(String key:setKeysUserData)
            {
                if (hashtable.get(key).equals("dirty")) setKeysOfDirtyEntities.add(key);
            }
           
            //Use the second set to remove the names of the old dirty EntityDefs.
            for(String key:setKeysOfDirtyEntities)
            {
                hashtable.remove(key);
            }
        }
    }  
}   

I think it is a good idea to set your own custom project base class of the ViewObjectImpl base class as the superclass of this RefreshQueryAfterCommitViewObjectImpl class. In this code our base class is the HRViewObjectImpl class. Complete code of RefreshQueryAfterCommitViewObjectImpl:

package HR.model.framework;
import java.util.HashSet;
import java.util.Hashtable;
import java.util.Set;
import oracle.jbo.Session;
import oracle.jbo.server.EntityDefImpl;
import oracle.jbo.server.TransactionEvent;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

         //Make a Set of all the keys (=dirty entity class names)
         Set<String> set = session.getUserData().keySet();
 
         //Get all the EntityDefImpl objects this view object is based on.       
         EntityDefImpl[] entityDefs = getEntityDefs();
       
         //Check the whether there exists dirty EntityImpl objects for this EntityDefImpl class,
         // and if yes, mark this view object as dirty.        
         for(EntityDefImpl entityDefImpl:entityDefs)
         {
              if(set.contains(entityDefImpl.getName()))
              {
                 sLog.debug("Viewobject "+getName()+" will be requeried in afterCommit(), underlying entity "+entityDefImpl.getName()+" is DIRTY...");
                 dirty=true;
              }
         }
     }

    /**
     * Only requery when an entity this view object is bases on was 'dirty' in beforeCommit().
     * Then, remove all old dirty EntityDef names from the session userData Hashtable object.
     */
    public void afterCommit(TransactionEvent transactionEvent)
    {      
        super.afterCommit(transactionEvent);                      
        if(getCurrentRow()!=null)
        {
            if(dirty==true)
            {
                 sLog.debug("Viewobject "+getName()+" REQUERIED in afterCommit().");
                 refreshQueryKeepingCurrentRow();           
                 dirty=false;
            }
        }   
      
        //Remove all old dirty EntityDef names from the session userData Hashtable object.
        //Get the session’s userData Hashtable object.
        Session session = transactionEvent.getDBTransaction().getSession();
        Hashtable hashtable = session.getUserData();       
       

        //Check if the hashtable contains any dirty entitydef names.
        if(hashtable.contains("dirty"))
        {          
            //Make a set with all the keys of the userData properties.
            Set<String> setKeysUserData = session.getUserData().keySet();
           
            //Make a second set that contains all the names of the old dirty EntityDefs.
            Set<String> setKeysOfDirtyEntities=new HashSet<String>();
            for(String key:setKeysUserData)
            {
                if (hashtable.get(key).equals("dirty")) setKeysOfDirtyEntities.add(key);
            }
           
            //Use the second set to remove the names of the old dirty EntityDefs.
            for(String key:setKeysOfDirtyEntities)
            {
                hashtable.remove(key);
            }
        }
    }  
}    

You can add the refresh-but-stay-where-you-were functionality method refreshQueryKeepingCurrentRow() to this class or (better) add it to your own view object custom base class, so that all of your view objects in your project could call this very useful method of Steve Muench:

       /**
     * refresh-but-stay-where-you-were functionality
     * Steve Muench http://radio.weblogs.com/0118231/2004/11/22.html
     */
    public void refreshQueryKeepingCurrentRow()
     {  
       sLog.debug("refreshQueryKeepingCurrentRow().. ");
       Row currentRow = getCurrentRow();
       Key currentRowKey = currentRow.getKey();
       int rangePosOfCurrentRow = getRangeIndexOf(currentRow);
       int rangeStartBeforeQuery = getRangeStart();
       executeQuery();
       setRangeStart(rangeStartBeforeQuery);
       if (rangePosOfCurrentRow >= 0) {
         findAndSetCurrentRowByKey(currentRowKey,rangePosOfCurrentRow);
       }         
     }

Set the RefreshQueryAfterCommitViewObjectImpl class as the superclass of your view objects that need a requery

Now you have a general solution for this type of refresh issues. When you are confronted with a refresh issues involving calculated attributes or involving attributes set by database triggers, the only thing you will have to do is to set this class as the superclass of your view object. In the hierarchy, you just place the RefreshQueryAfterCommitViewObjectImpl class between your own custom base class and the view object that you want to refresh:

In JDeveloper you can do this in the View Object Editor:

Now your dirty view object will be refreshed after an insert or an update.

Refreshing your view objects with SQL-Calculated attributes automatically without having to look after them

Alternatively, you even don’t have to set a new superclass for your view objects with SQL-Calculated attributes. Your ViewObject can detect automatically whether it contains SQL-Calculated attributes or not, and only requery when it does. A view object can ask for its attribute definitions and for each attribute definition it’s kind of attribute. If the kind is ATTR_SQL_DERIVED, it’s SQL-Calculated. You could add all the three methods beforeCommit(), afterCommit and refreshQueryKeepingCurrentRow() to your custom ViewObjectImpl base class and add an overridden create() method to it. This method is called by the framework every time a ViewObjectImpl object is created, and a good place for us to check whether this view object contains SQL-Calculated attributes or not:
 

private boolean hasSQLCalculatedAttribute=false;


protected void create()
{
        super.create();
        //Get an array of all attribute definitions of this ViewObjectImpl.
        AttributeDef[] attributeDefs = getAttributeDefs();
        //Check whether any attribute definition exists that is SQL-Calculated.
        for(AttributeDef attributeDef:attributeDefs) {
             if(attributeDef.getAttributeKind()==AttributeDef.ATTR_SQL_DERIVED) {
                 sLog.debug("Viewobject "+getName()+" has SQL-Calculated attributes - if dirty, it's requeried after a commit.");
                 hasSQLCalculatedAttribute=true;
                 break;
                }
         }       
}

Then, in the afterCommit() method, before the requery, also check whether it has SQL-Calculated attributes or not:

if(getCurrentRow()!=null)
    {
    if(dirty==true)
       {
         if(hasSQLCalculatedAttribute==true)
            {
              sLog.debug("Viewobject "+getName()+" REQUERIED in afterCommit().");
              refreshQueryKeepingCurrentRow();           
            }
            dirty=false;
       }
     } 

 
Now all your view objects with SQL-Calculated attributes are refreshed automatically without having to look after them any more.
 

Normally, in a Java web-application a session timeout is configured (in minutes) in the deployment descriptor (DD) web.xml. This means that if the client doesn’t make any requests on this session for 35 minutes the application server will invalidate the session.

<web-app …>
  <servelet>
  …
 </servlet>
  <session-config>
        <session-timeout>35</session-timeout>
    </session-config>
</web-app>

We use a servlet filter to check the session and attributes on the session. When the session is no longer valid, the servlet container redirects the request to our configured Login page.

Javascript solution in the browser

A very simple but for many ADF applications not yet complete solution could be that you add a single <afh:script> component to a region-JSPX that is included in every JSPX, for example a menu region. This <afh:script> component calls a JavaScript function (which calls another function):

<afh:script id="popupSessionTimeout" text="timerpopupSessionTimeout('Your session has expired. Do you want to go to the Login page?', '2100000');" />

With your message from your resourcebundle and the maximum inactive interval time red from a backing bean:

<afh:script id="popupSessionTimeout"  text="timerpopupSessionTimeout('#{nls['SESSION_TIMEOUT_MESSAGE']}', '#{SessionTimeout.maxInactiveIntervalInMilliSeconds}');" />

In JavaScript we can call a standard JavaScript function, setTimeout(), which calls the function specified in the first parameter, after an interval (in milliseconds) specified in the second parameter. In this case, setTimeout() calls our function popupSessionTimeout() after the number of milliseconds specified in the parameter maxInactiveIntervalInMilliSeconds (2.100.000 milliseconds is 35 minutes) . This is red by an EL expression from a backing bean who calls getMaxInactiveInterval() on the HttpSession object, which reflects the session-timeout time specified in the DD.

var timeoutMessagePopup=null;
function timerpopupSessionTimeout(timeoutMessage,maxInactiveIntervalInMilliSeconds)
{
        timeoutMessagePopup=timeoutMessage;
        setTimeout("popupSessionTimeout()", maxInactiveIntervalInMilliSeconds);
}
function popupSessionTimeout()
{
        var answer = confirm(timeoutMessagePopup);
 if (answer){               
  window.location = "/myApplication/start";
 }
}

Now, every time a JSPX is rendered, the JavaScript function timerpopupSessionTimeout() is called, and a JavaScript confirm-popup is showed to the user after the session-timeout.
 

Problem with JavaScript-only solution

This approach has one disadvantage: because of dialogs, Lists Of Values (LOV’s),  and Partial Page Rendering (PPR) the session timeout time in the browser is not always reflecting the current inactive interval of the user in the application server.
In our current application we have a lot of dialogs, LOV’s and PPR in the application. The ADF Faces Dialog and Process framework provides an easy way to jump to a page, or a series of pages, to get information from the user and then return to the original page to use that information. In ADF Faces this is called "processes". One special type of process supported by ADF Faces is a "dialog:" it’s shown in a separate popup window instead of in the same window.  

For example, when our ‘customize mode’ link is clicked, the application shows a dialog with customizable prompts. When the user chooses and saves these prompts and closes the popup window, the server receives a request to save data and to close the window. But it will also reset the session timeout time, starting again from the beginning with the time in minutes specified in the DD, for example 35 minutes. At the same time in your browser, your afh:script component in the JSPX will not refresh and will not start over from the beginning but continues to count down and will be maybe already around 34 minutes. Now our popup message might come too early – we don’t want smart users to click the message away and still continue with the application. We need to make sure the session is already invalidated when our message is displayed to the user. For the same reason Partial Page Rendering is a problem for this solution. PPR is a technology provided by ADF Faces that allows a portion of a page to be redrawn rather than reloading the entire page. If there are many components redrawn by PPR in a JSPX and our afh:script is not redrawn, the browser session timeout time won’t be reset. We need a better and saver solution to make sure the session is invalidated. We can do that making use of the af:poll component.

Solution using an af:poll component

The main idea is this: An <af:poll> component can trigger an event (a so called PollEvent) after the time that is specified by the interval attribute. We will trigger a request just before (one minute) the session is about to be expired on the server. On the ‘pollListener’ attribute we can specify with EL a listener in a backing bean to this pollEvent. In this listener we can set the rendered property an afh:script component to true. This afh:script that now will be rendered will call a slightly different version of the JavaScript function ‘timerpopupSessionTimeout()’ from above and will display our message to the user. At the same time, the user session is invalidated in this backing bean.

<!--start: destroy a session after session timeout and show a popup window informing the user. -->
        <af:panelGroup id="pollPanelGroup" partialTriggers="timer">
        <af:poll interval="#{PollListener.sessionTimeoutLaunchPopup}" id="timer" pollListener="#{PollListener.pollaction}"/>       
        <afh:script id="pollTriggeredPopupSessionTimeout" rendered="#{PollListener.sessionTimeoutPopupRendered}"
                    text="timerpopupSessionTimeout('#{nls['SESSION_TIMEOUT_MESSAGE']}');"/> 
        </af:panelGroup>
  <!--end: destroy a session after session timeout and show a popup window informing the user. -->

This code could be added to each JSPX page. But most applications have a general region-JSPX that is part of every JSPX where they offer some general functionality (a region with menu- or help links). Then it can be added only to this page.
After the interval, in our case 34 minutes, a pollEvent is triggered and the listener method is called in our backing bean called PollListener.java. We make this backing bean available by registering it in faces-config.xml:

<managed-bean>
    <managed-bean-name>pollListener</managed-bean-name>
    <managed-bean-class>HR.session.PollListener</managed-bean-class>
    <managed-bean-scope>session</managed-bean-scope>
</managed-bean>

If we want the af:poll component to trigger an event before the session is invalidated on the server, we must be sure to take enough time. There is a start-time difference between the time the container receives the request (=HttpSession. getLastAccessedTime(), from this point in time the server starts counting), and the time the poll-interval from the JSPX starts in the client’s browser. When, for example, a JSPX request with an af:poll component takes 30 seconds to respond and to display in the browser after the webcontainer (server) receives the user-request, the poll interval start-time in the browser begins 30 seconds LATER than the container starts the session inactive-interval. To be safe, we use 60 seconds because we have several JSPX pages that can take up to a 30 seconds before the browser receives a response and the browser interval starts. When a response takes even longer than 60 seconds, the pollEvent will be triggered after the session is invalidated by the container, and that is of course a situation we don’t want.

First, in the constructor, we will set the HttpSession object and the attribute ‘sessionTimeoutLaunchPopup’. This attribute has a value binding with the ‘interval’ attribute of the af:poll component. Its value is the maximum inactive interval in seconds that is specified in the DD (returned by session.getMaxInactiveInterval() ) multiplied by 1000 to get milliseconds and then subtract the result with 60.000 milliseconds (1 minute):

public PollListener() {
        FacesContext ctx = FacesContext.getCurrentInstance();
        HttpServletRequest request = (HttpServletRequest)ctx.getExternalContext().getRequest();
        session = request.getSession(false);         
        int maxInactiveIntervalInSeconds = session.getMaxInactiveInterval();
        sessionTimeoutLaunchPopup = ((maxInactiveIntervalInSeconds * 1000) - 60000);
      }

When the interval time of our af:poll component is passed, a pollEvent is triggered and our listener method is called:

public void pollaction(PollEvent pe) {
        sLog.debug("pollaction()...");
        sessionTimeoutPopupRendered=true; 
        Thread thread = new Thread(new SessionInvalidator());
        thread.start();
    } 

As you can see, the ‘sessionTimeoutPopupRendered’ attribute in the listener is set to true, now the ‘rendered’ property of the afh:script component will evaluate to true and will be rendered in response to the pollEvent:

<afh:script id="pollTriggeredPopupSessionTimeout" rendered="#{PollListener.sessionTimeoutPopupRendered}" text="timerpopupSessionTimeout('#{nls['SESSION_TIMEOUT_MESSAGE']}');" /> 

Note that we have set the ‘partialTriggers’ attribute on the parent component af:panelGroup:

 <af:panelGroup id="pollPanelGroup" partialTriggers="timer" >

Now the timerpopupSessionTimeout(‘#{nls['SESSION_TIMEOUT_MESSAGE']}’) JavaScript function is called which renders our message (Complete JavaScript code is coming below).

We have still one problem: we have to make sure our session object is invalidated. If we do it straight away in the listener, our response won’t be rendered because it needs a valid session object. Without a valid session object the essential FacesContext object won’t be available anymore to render the response. The application will immediately go back to the Login page without showing the popup message. The response must be completed before the session can be made invalid. This pollEvent is a small PPR request, so the response won’t take that long. We can make the session invalid in a separate thread and let it sleep for 5 seconds before the session is invalidated. This to first allow the PPR-response to be rendered and to show our JavaScript popup message:

Thread thread = new Thread(new SessionInvalidator());
thread.start();

And with an inner class that implements Runnable the session can be made invalid:

class SessionInvalidator implements Runnable {
        public void run() {
            try {
                sLog.debug("in run()... sleep 5 seconds before session is destroyed, to first allow a PPR-response to render a session-has-expired JavaScript popup message…"); 
                Thread.sleep(5000);
            } catch (InterruptedException e) {
                 sLog.debug("exc: "+e);  
            }
            if(session!=null){
                session.invalidate();
                sLog.debug("in run()...session has been invalidated");
            }
        }
    }

Our complete PollListener.java:

package HR.session;
import javax.faces.context.FacesContext;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;
import oracle.adf.view.faces.event.PollEvent;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class PollListener {
    private boolean sessionTimeoutPopupRendered = false;
    private int sessionTimeoutLaunchPopup;
    private HttpSession session;
    private static final Log sLog = LogFactory.getLog(PollListener.class);
   
    public PollListener() {
        FacesContext ctx = FacesContext.getCurrentInstance();
        HttpServletRequest request = (HttpServletRequest)ctx.getExternalContext().getRequest();
        session = request.getSession(false);        
        int maxInactiveIntervalInSeconds = session.getMaxInactiveInterval();
        sessionTimeoutLaunchPopup = ((maxInactiveIntervalInSeconds * 1000) - 60000);
      }
   
    public void pollaction(PollEvent pe) {
        sLog.debug("pollaction()...");
        sessionTimeoutPopupRendered=true;
        Thread thread = new Thread(new SessionInvalidator());
        thread.start();
    } 

    public boolean isSessionTimeoutPopupRendered() {
        return sessionTimeoutPopupRendered;
    }

    public int getSessionTimeoutLaunchPopup() {
        return sessionTimeoutLaunchPopup;
    }

    class SessionInvalidator implements Runnable {
        public void run() {
            try {
                sLog.debug("in run()...sleep 5 seconds before session is destroyed, to first allow a PPR-response to render a session-has-expired JavaScript popup message...");
                Thread.sleep(5000);
            } catch (InterruptedException e) {
                 sLog.debug("exc: "+e);  
            }
            if(session!=null){
                session.invalidate();
                sLog.debug("in run()...session has been invalidated");
            }
        }
    }
}

Because we make the session invalid at the server, in a separate thread 5 seconds after the listener method is called, we must show our message in the browser 5 seconds later to make certain the session is already invalidated before the message is showed. We can do that by calling the standard JavaScript function setTimeout() and by specifying 5000 milliseconds in the second parameter (the same time the separate thread in Java sleeps):

setTimeout("popupSessionTimeout()", 5000);

Our final JavaScript file:

var timeoutMessagePopup=null;
function timerpopupSessionTimeout(timeoutMessage){
        timeoutMessagePopup=timeoutMessage;
        setTimeout("popupSessionTimeout()", 5000);
}
function popupSessionTimeout(){
        var answer = confirm(timeoutMessagePopup);
 if (answer){               
  window.location = "/myapplication/start";
 }
}

Now we are sure the session is already invalidated when the user sees our message. All the user has to do to return to the Login page is pressing the enter key. When ‘Cancel’ is choosen, the application won’t return to the login page but the session will – of course – still be invalid and the user won’t be able to do anything before logging in again.

Maintaining a user session while the application is open in the browser

Maybe you don’t want users to be thrown out of the application server, and maintain all user sessions while their application is open in the browser. One option is to set the session-timeout in the DD to the value of -1, and sessions won’t timeout on the application server. But this option has a big disadvantage: if you have thousands and thousands of users and when they do close the application using the browser X close-button on the right upper side, the user session will unnecessary stay alive in the application server, and still use valuable memory space. Many users do not click on a logout link which should invalidate their session in the application server using HttpSession.invalidate().

A second and in my opinion better option is to maintain a user session only when the application is open in the browser. We can also use an af:poll component for this:

<af:poll interval="2040000"/>

As long as the application is open in the browser, you can trigger a request just before the session is about to be expired on the server. You simply specify an interval time a little bit smaller (for example 1 minute) than your maximum inactive interval time. In our case 2.040.000 milliseconds could be specified on the af:poll component (34 minutes, our session timeout time minus 1). Now this af:poll will take care of triggering an event on the client and deliver it at the server, and the session timeout time will start from the beginning again and the session won’t be invalidated. When a user closes his browser using the browser X close button, no more poll events will be triggered AND the application server will invalidate the session after 35 minutes and save valuable memory space.

Currently we have a challenge in our JHeadstart ADF application;

after an insert or update many of our precious breadcrumbs are missing or don’t refresh to their updated value. In a JHeadstart application, items that are set as a group ‘descriptor item’ can become a breadcrumb and appear on the breadcrumb stack. We have many descriptor items which values are set by a database trigger or are an SQL-calculated attribute in the VO (View Object). For example: we have an address that is set by a trigger that concatenates the street name, street number, postal code and city. After each insert, update or delete our application navigates to a different JSPX called a ‘Success Page’, which (only) purpose is to tell the user that the insert, update or delete has been committed successfully. For example, If we want to change the first name of a ‘kandidaat’ (English: candidate), lets say Boris Becker to Boris Brown, the application navigates to our ‘Success’ JSPX.  The breadcrumb is still on the breadcrumb stack, but the problem is that the breadcrumb still reflects the old last name! And our new organization name and organization address, both set by a database trigger, do not even appear at all on the stack! Of course this is not a desired situation.

In our application, its not a problem of the ADFBC layer; after a commit is executed, VO attributes set by a database trigger are already refreshed in the ADFBC layer by setting the ‘refresh after insert’ and ‘refresh after update’ on the EO (Entity Object). And for SQL-calculated attributes a requery is needed in the afterCommit() method of the VO; like a refresh-but-stay-where-you-were requery method ‘refreshQueryKeepingCurrentRow()’ Steve Muench described.

Implementation of Breadcrumbs by JHeadstart (version 10.1.3.2)

First, before we can look for a solution we have to figure out how breadcrumbs are implemented in an ADF application that uses JHeadstart. Breadcrumbs are standard JHeadstart functionality. The only documentation I could find about JHS (JHeadstart) breadcrumbs was in an old JHeadstart developers guide (release 10.1.2.1, 2005, based on Jakarta Struts instead of JSF, but a major part of the breadcrumb documentation is still valid). It tells us that “In (almost) 100% generated applications, chances are you’ll never need to know how the mechanism behind the breadcrumbs functionality works, and how you can influence its behavior. However, if you are manually creating complex pageflows in a JHeadstart application, you might need to have some control over the way the breadcrumbs work.” So, the first challenge is to understand how these breadcrumbs are implemented. I will explain only the relevant basic parts in relation to our issue.  

<af:menuPath> tag

In each JSPX file a breadcrumb area is generated with a <af:menuPath> tag. A menuPath component is used in hierarchical site layouts to indicate the path back to the root page of the hierarchy with links. A child representing the current page should be the last child. This menuPath tag has a value of #{jhsBreadcrumbStack}. The nodes in the breadcrumb stack are stamped out with the ‘nodeStamp’ facet, which contains a commandLink component with their corresponding actions ( #{bc.goToDestination} ) (which uses the default JSF actionListener mechanism for page navigation), and labels ( #{bc.label} ).  The EL expression #{jhsBreadcrumbStack} will result in a call to the JhsBeadcrumbStack managed bean which extends ViewIdPropertyMenuModel. A ‘MenuModel’ object represents the menu structure of a page or application.

<ServiceName>-Breadcrumb-beans.xml

In <ServiceName>-Breadcrumb-beans.xml, JHeadstart creates for each JHeadstart group a managed bean called ‘<GroupName>Breadcrumb’ of type BreadcrumbConfiguration.java. The JHS template ‘breadcrumbFacesConfig.vm’ is used to create this managed bean. For example the AllEmployees group:

Breadcrumb and BreadcrumbConfiguration

A BreadcrumbConfiguration object is used for the creation of a Breadcrumb object. As we can see, 4 properties of a BreadcrumbConfiguration are set by the JSF Managed Bean facility: a (destination) page, a label (rendered as label for the breadcrumb commanLink), a label-parameter-expression (EL-expression, a parameter for the label), and a unique key (JSPX name without slash and .jspx). A BreadcrumbConfiguration object is a simple JavaBean with getters and setters for these properties and some other. The BreadcrumbManager, responsible for managing/processing the current stack of breadcrumbs, creates a Breadcrumb object by using the properties of a corresponding BreadcrumbConfiguration object. When a new Breadcrumb is created, his destination (a ViewId) is set using the page property, so that clicking on the breadcrumb link will execute the goToDestination() method on the Breadcrumb. The ViewId of the breadcrumb will be set as the new viewRoot and the application navigates to the page corresponding to its breadcrumb.

The label and label-parameter EL-expression of a breadcrumb is the text that that is shown to the end user in the page for this breadcrumb, and is therefore derived from the application’s resource bundle to allow for internationalization. The key for the current breadcrumb is derived as follows:
BREADCRUMB_< JSPX name in uppercase>.  It is possible to have ‘dynamic’ labels, by having the value in the resource bundle contain substitution parameters like {0}:

The EL expression of a JHS group descriptor item (generated in the labelParamExpressions property in <ServiceName>-Breadcrumb-beans.xml) will result in the substitution value for ‘{0}’, and pass them to the label of the breadcrumb. 

Most important methods of a Breadcrumb object are:

• goToDestination() – The viewed of this Breadcrumb is set as the new ViewRoot of the application.
• getLabel() – returns the current label and parameter value.
• resetLabel() -  This method reevaluates the label of the breadcrumb, reevaluates the parameters, and reconstructs the ‘label’ based on the original key and the new parameter values. It calls deriveParamValues() that takes the ‘labelParamExpressions’ property of the BreadcrumbConfiguration, and evaluates the EL expression(s) in it. It will take that EL expression, for example from the AllEmployeesBreadcrumb labelParamExpression ‘bindings.AllEmployeesLastName.inputValue’ and evaluate it:

              String paramExp = "#{"+paramExps+"}";
      paramValue = JsfUtils.getExpressionValue(paramExp);

             Soo, if you are updating employee Bates, the breadcrumb label ‘Edit employee {0}’ should become ‘Edit employee Bates’.

A JHS template ‘common_labels.vm’ creates these labels and ‘labelParamExpressions’ in the resource bundle. In common_labels.vm there are 4 macros:

• BREADCRUMB_LABEL_FORM_PAGE
• BREADCRUMB_LABEL_TABLE_PAGE,
• BREADCRUMB_LABEL_SEARCH_PAGE
• BREADCRUMB_LABEL_SELECT_PAGE

For example:

#macro (BREADCRUMB_LABEL_FORM_PAGE $page)
${JHS.nls(${page.group.displayTitleSingular}, "BREADCRUMB_${page.nameUppercase}", "EDIT_TITLE",false,true)}#end

‘EDIT_TITLE’ in the macro will be replaced by its value in GeneratorText.properties:
EDIT_TITLE = Edit {0} ‘{’0}
For Employees, the generated resource bundle entry will be ‘Edit employee {0}’.

BreadcrumbStack

Represents the current stack of breadcumbs (Breadcrumb objects – simple javaBean objects) for the current application’s ViewRoot. BreadcrumbStack extends ViewIdPropertyMenuModel (which extends BaseMenuModel, which extends MenuModel), A BreadcrumbStack object can be treated as a MenuModel object what is exactly what a af:menuPath tag needs as its value, so an EL expression of #{jhsBreadcrumbStack} will return the collection of Breadcrumb objects. It is generated in JhsCommon-beans.xml and created/retrieved using the JSF Managed Bean facility. Don’t forget to set the showBreadcrumbCurrentPage to true (default is false) if you want a breadcrumb representing your current page:

 Important methods:

• getBreadcrumbStack(). This static method will retrieve and if not present create a Breadcrumb stack object from the session.
• Add(Object o). Adds a Breadcrumb object to the stack.

BreadcrumbManager

Responsible for managing and processing the current stack of breadcrumbs. The BreadcrumbStack is created/retrieved using the JSF Managed Bean facility. Most important method:

• processBreadcrumbs() – This is the ‘main’ method, it will create and remove breadcrumbs, process the Breadcrumb stack and perform any actions necessary on this stack needed to synchronize it with the current state of the application.

 Algorithm

1. JhsPageLifecycle calls, in its method prepareModel(), the ‘main’ method of the BreadcrumbManager, that processes the breadcrumb stack.
2. BreadcrumbManager retrieves the current BreadcrumbStack object.
3. BreadcrumbManager gets the BreadcrumbConfiguration object for the requested page.
4. The BreadcrumbManager retrieves the BreadcrumbConfiguration object in the breadcrumbConfigs HashMap (corresponding to the requested page), creates a new Breadcrumb object (by setting the BreadcrumbConfiguration object as an argument in the constructor). The Breadcrumb uses the properties of the BreadcrumbConfiguration object to set its own properties like a (destination) page, a label, a label-parameter-expression, and a unique key (JSPX).
5. The Breadcrumb object is added to the stack. If the Breadcrumb is already on the stack, it is ‘rolled back’ to the Breadcrumb before the one that is ‘the same’ as the current breadcrumb, and then the current breadcrumb is added.
6. JhsPageLifecycle calls the ‘main’ process-method of the BreadcrumbManager again, now in the prepareMode phase in prepareModel(). 2, 3, 4 and 5 are repeated.
7. The EL expression #{jhsBreadcrumbStack} in the JSPX is evaluated and the breadcrumb stack is rendered.

Solution

OK, now that we have gained some insight how breadcrumbs are implemented in a JHeadstart application, we can figure out the solution. The main problem, in our case, is that breadcrumbs generated by JHeadstart are created and its labelParamexpressions (EL expressions) are evaluated too early in the ADF lifecycle; in the prepareModel phase. As we saw in the previous section, the JhsPageLifecycle instance calls in its method prepareModel() the method processBreadcrumbs() of the BreadcrumbManager object. This method creates the Breadcrumb instance, gets its label from the resourcebundle (by using the labelKey property) and evaluates the LabelParameter EL expression(s), and adds the Breadcrumb object to the BreadcrumbStack.

The JhsPageLifecycle instance calls, in the ADF prepareRender phase in prepareRender(), again the processBreadcrumbs() method of the BreadcrumbManager object. In a standard JHeadstart application, after an update or insert, the user navigates back to the same page, the processBreadcrumbs() is called twice in the ADF lifecycle and in the prepareRender phase the breadcrumb is nicely refreshed to the current state of the updated or new breadcrumb. This is in most cases desired behavior when you use the standard JHeadstart pageflow. In our application, we use a different pageflow, and our breadcrumbs are not evaluated again to reflect current row changes, because we don’t navigate to the same page. Our current ViewId changes after an update or insert and we navigate to a new JSPX file, in our application called a ‘Success’-page (we give the user a new page with a message that the insert, update or delete has been successful).

In our application, refreshing is not possible anymore in the prepareRender phase, because we navigate to a new JSPX file (our Success.jspx), and in the prepareRender phase the BindingContainer object does not contain the reference values of the binding objects of the previous JSPX anymore. Values that binding objects refer to have request-scope: they are only valid during a request in which that binding container has been prepared by the ADF lifecycle. If the application is navigating to a different viewed, in the prepareRender phase the BindingContainer has already been prepared by the ADF lifecycle to contain the binding objects and the values they reference to serve the new JSPX, and the values of the binding objects of the previous JSPX are released and not accessible anymore.

So, reevaluation of breadcrumbs must be done earlier in the ADF lifecycle phase. After the invokeApplication phase seems to be the right time. 

The reference values of the binding objects of the BindingContainer are still accessible for our page, and are now able to access the refreshed values from the ADFBC layer. In the JSF invokeApplication phase new or updated rows are send to the database, a commit is executed, VO attribute values are refreshed in the ADFBC layer by a ‘refresh after insert’ on the EO, an executeQuery() method on the VO or a refresh() method on the EO or VO. If we make a JSF PhaseListener, that listens for the JSF invokeApplication phase, we can access ADFBC’s refreshed values directly after the invokeApplication phase in the afterPhase() method of this PhaseListener. In our case after an update or insert, the ViewId() is changed between the  between the beforePhase() and  afterPhase() of the invokeApplication phase, so we should set the previous ViewId() in the beforePhase() method, and we can use it in the afterPhase() method:

BreadcrumbManager bcm = (BreadcrumbManager)BreadcrumbManager.getBreadcrumbManager();
        if(getOldViewId()!=null) bcm.processBreadcrumbs(null, getOldViewId() , null, null);

Now the label and the EL expression of its parameter(s) are reevaluated (in reality removed from stack and newly created).

<p>public class BreadcrumbRefreshPhaseListener implements PhaseListener {<br />&nbsp;</p><p>private String oldViewId = null;<br />private static final Log sLog = LogFactory.getLog(BreadcrumbRefreshPhaseListener.class);</p><p>public BreadcrumbRefreshPhaseListener() {}</p><p>public PhaseId getPhaseId() {<br />         	return PhaseId.INVOKE_APPLICATION;<br /> 	}<br /><br />public void beforePhase(PhaseEvent e) {<br />		sLog.debug(&quot;PhaseId.INVOKE_APPLICATION - beforePhase() - ViewId() now: &quot;+getCurrentViewId());<br />		setOldViewId(getCurrentViewId());<br />	}</p><p>public void afterPhase(PhaseEvent e) {<br />		sLog.debug(&quot;PhaseId.INVOKE_APPLICATION - afterPhase() - ViewId() now: &quot;+getCurrentViewId());<br />		BreadcrumbManager bcm = (BreadcrumbManager)BreadcrumbManager.getBreadcrumbManager();<br />		bcm.processBreadcrumbs(null, getOldViewId(), null, null);<br />	}</p><p>public static String getCurrentViewId() {<br />		return FacesContext.getCurrentInstance().getViewRoot().getViewId();<br />	}</p><p>public void setOldViewId(String oldViewId) {<br />		this.oldViewId = oldViewId;<br />	}</p><p>public String getOldViewId() {<br />		return oldViewId;<br />	}<br />}</p>

We also have to register this phaseListener in JhsCommonBeans.xml (and in the JHS template JhsCommonBeans.vm) :

<p>&nbsp;</p><p><code>&lt;lifecycle&gt;<br />    &lt;phase-listener&gt;oracle.jheadstart.controller.jsf.lifecycle.JhsADFPhaseListener&lt;/phase-listener&gt;<br />    &lt;phase-listener&gt;nl.myproject.jheadstart.controller.BreadcrumbRefreshPhaseListener&lt;/phase-listener&gt;<br />&lt;/lifecycle&gt;</code></p>

Now, our breadcrumbs are added or refreshed after an insert or update when we navigate to the Success.jspx:

Entity validation error messages

By default, the built-in validators of ADF BC throw subclasses of JboException, AttrValException (attributelevel validation) and ValidationException (entity-instance-level validation). Depending on whether the exception is an attribute-level or entity-instance-level validator they are automatically called during the set<Attribute> or validateEntity() method respectively. When an error occurs, a message you specified in the entity object editor is displayed to the user, which includes the error message you specified for the validator in the entity object editor, including a reference to the class name of the exception.

Any message you specify when creating a built-in validator or method validator is stored in an entity-specific, automatically generated message (resource) bundle, for example ‘HR.model.entities.EmployeesImplMsgBundle’.

For our current project what we would like to have instead is an errorcode in the validation rule error-message, as a key to a text error-message later retrieved from a centralized resource bundle. This errorcode will be saved in the standard <EOImpl>MsgBundle file. We want our (custom) key format code to be ‘CXS-xxxxx’. Now JboExceptions thrown by entity validation will provide the NLS key as the message text:

Resource bundle

A resource bundle is a Java class that contains a two-dimensional array of key-value pairs representing fixed “boilerplate text”, for example prompts, labels, titels but it can also contain error messages, for example:

package mypackage; import java.util.ListResourceBundle; public class MyMessageBundle extends ListResourceBundle { private static final Object[][] sMessageStrings = new String[][] ( {"CXS-00001", "Telephone number not more than 15 numbers, please!"}, {"CXS-00002", "Job must be CLERK, MANAGER, PRESIDENT, or SALESMAN"}, {"TABLE_TITLE_ALLEMPLOYEES", "All Employees"} ); protected Object[][] getContents() { return sMessageStrings; } }

When using the newest JHeadstart version (10.1.3.2) on your project, you can specify whether the resource bundle is generated as a property file, a Java class or a database table. In this article we use a database table, but the other 2 resource bundle types could be used as well. In fact any resource bundle could be used. Using a database table, JHeadstart generates a Java resource bundle as well. This Java class resource bundle acts as a “façade” to our database table.

The Java resource bundle class delegates retrieval of the translatable strings to its JHeadstart superclass, TranslationTableresourceBundle, which uses a ViewObject in the nested JhsModelService to read the translatable text strings from the JHS_TRANSLATIONS table for the given locale.  For each user session all key-value pairs from this table are queried and are available at the ApplicationResources object (the Java façade resource bundle) on the session context. Calling the method protected getContents() on the ApplicationResources object will cause this method to be invoked on its super class, TranslationTableResources, and return the two-dimensional array of key-value pairs.

Button labels, page header titles, database constraints and other fixed text generated by JHeadstart are generated into this resource bundle. Now we want to maintain our error-code and error-text messages from the EO validation as well in this database table.  To do this ErrorReportingUtils, a class generated by JHeadstart, must be extended. 

ErrorReportingUtils

Exceptions thrown by any part of an ADF application, so also by EO validation, are by default caught by the binding container. When an exception is encountered, the binding container routes the exception to the application’s active error handler, which by default is the DCErrorHandlerImpl class. The reportException() method on this class passes the exception to the binding container to process. The binding container then processes the exception by placing it on the exception list in a cache. During the Prepare Render phase, the ADF lifecycle executes the reportErrors() method. By default, the reportErrors() method on the FacesPageLifecycle class accesses the exception list from the binding container, calls the addError() method, which creates and adds the messages to the FacesContext and clears the exceptions list in the binding container.

JHeadstart customizes this default framework behavior by having created a custom ADF lifecycle class, JhsPageLifecycle, which extends the default ADF Faces lifecycle and changes how the lifecycle reports errors by overriding the reportErrors() method:

As you can see a custom error handler, ErrorReportingUtils (a managed bean), is created. This class will transform exceptions into Faces error messages. It will do this only for certain types of exceptions, which can be configured in JhsCommon-beans.xml:

ErrorReportingUtils accesses the exception list from the binding container. For all existing exceptions ErrorReportingUtils will process each exception individually and will finally add the exception message(s) to the FacesContext. It will recursively process detail exceptions wrapped inside a JboException (often a JboException has detail exceptions). In our case, the most important methods of ErrorReportingUtils are:

• reportErrors() // accesses the exception list from the binding container. For each individual exception the method translateExceptionToFacesErrors(exception,..,..) will be called.
• translateExceptionToFacesErrors() // translates exceptions to the FacesContext. First this method will call processException(exception,..,..,..,..) for this exception to do all the process to get the error message. This method will finally add the exception error message(s) to the FacesContext.
• processException() // Processes each exception individually. This method looks what kind of exception it is and populates a list of error messages for current exception. For JboExceptions, and in our case the subclasses AttrValException and ValidationException, this method calls getMessage(exception,..) to get the exception error message.
• getMessage() // returns the complete exception message:  {productCode}-{errorCode}: {messageBody}

A proper entry point in this class is needed to intercept our specific EO validation JboException where the {messageBody} part of the message has our errorcode with our syntax ‘CXS-xxxxx’. Then, we could subclass ErrorReportingUtils and retrieve the corresponding errortext from our resourceBundle.

In our case, the best place for interception is (and to override in a subclass) the getMessage() method. This method calls the method getLocalizedMessage() on the Exception and returns the complete message for the current locale:

method getMessage() in ErrorReportingUtils

To do this we must create and then configure our subclass called HRErrorReportingUtils in JhsCommon-beans.xml (to replace ErrorReportingUtils):

You have to make a JHS template to generate the correct values in JhsCommon-beans.xml. In our case: HR\misc\facesConfig: JhsCommon-beans.vm.

In the getMessage() method of our subclass we have access to the error message of the Exception, we can check whether this error message starts with our {productCode}, ‘CXS-‘. In that case we can create an object instance of a custom subclass of JboException, called HRMyCustomException:

HRMyCustomException mcex = new HRMyCustomException(productAndErrorCode);

All Exceptions thrown from the ADF BC framework should be subclasses of JboException. Translation of a message’s text occurs at the time the exception calls getLocalizedMessage(). JboExceptions have an attribute that stores the {productCode} part of a message.  A subclass of a JboException could be provided with a value for the error code (product- and error code as one String) in a specialized constructor and, importantly, an own resource bundle.

In our custom subclass, we hard-coded our resource bundle (ApplicationResources.class) in the constructor. When the method getLocalizedMessage() is called on a HRMyCustomException object instance, ApplicationResources.class is used as message bundle, and returns the complete message corresponding to the productAndErrorCode key. The constructor has a product- and error code as one String (first 9 characters) as parameter, and calls his super class constructor (JboException) with our hard-coded resource bundle:

  public HRMyCustomException(String productAndErrorCode)
  {   
    super(ApplicationResources.class, productAndErrorCode, null);   
  } 

The super class of our resource bundle, TranslationTableResourceBundle, extends the (standard) java.util.ListResourceBundle to format its messages, and supports NLS translation.

Finally, the last thing you have to do is copy the error text-messages from all the entity-specific message bundles to the JHS_TRANSLATION table, and give the entity object validators in the entity object editor a specific ‘CXS-xxxxx’ errorcode.

Our JHS_TRANSLATIONS database table in Toad.

When our entity validator throws an exception, now our exception error message is derived from the JHS_TRANSLATIONS table.

ORA-20xxx error messages

For our current project we also want to use our centralized resource bundle for ORA-20xxx error messages. ORA-20xxx errors are SQLExceptions in the range from ORA-20000 to ORA-20999, which is reserved for user-defined PL/SQL raise_application_errors.

Just like the getmessage() of ErrorReportingUtils method is a great entry point to override and modify JboExceptions (as is shown previously for entity validation exceptions), the method  getOra20xxx(SQLException) in the same class ErrorReportingUtils is a perfect entry point for ORA-20xxx exceptions, because all SQLExceptions are passing trough it.

Method getOra20xxx() in ErrorReportingUtils

This method can be overridden (like we did before with the getMessage() method) in our subclass, HRErrorReportingUtils. The same kind of solution as with entity validation is chosen: when the overridden method getOra20xxx(SQLException) is called in our subclass, we know that a SQLException has arrived, and we can substitute our HRMyCustomException for the SLQException.

To get a message from our centralized resource bundle we can call our previously created getMessage() method in the same class, HRErrorReportingUtils (explained above in ‘entity validation error messages’, overridden from ErrorReportingUtils):

String sqlMessage = this.getMessage(sqlException,userLocale);

Now the if-condition in getMessage() of HRErrorReportingUtils can be adjusted to also recognize ‘ORA-20xxx’ exceptions by checking the first part of the errorcode (‘ORA-20’):

if (message.startsWith("CXS-")    ||      message.startsWith("ORA-20") )      {…//as previously …} 

Exactly the same as for the entity validation errors is done, a HRMyCustomException object is created, with the product-code (ORA) and specific error-code(20xxxx) as a String parameter. Then the super.getMessage() method is called (at ErrorReportingUtils) that will return the localized message, but now derived from our database resourcebundle.

We can easily test our application whether our ORA-20xxx errors will have error messages from our centralized resource bundle or not. To do this, you can make a simple database procedure:

create procedure testORA20xxx( p in number := 20001 ) is begin raise_application_error( – p, ‘Hallo’ ); end;

In JDeveloper a trigger can be made, for example one an after update trigger for the email attribute of the employees entity object (Connections Navigator, Your database, Triggers, New):

TRIGGER TRIGGERTEST AFTER UPDATE OF EMAIL ON EMPLOYEES BEGIN   testORA20xxx; END; 

And finally, the corresponding error-message will be retrieved out of the centralized database resource bundle:

Custom JboException error messages

The simplest method for displaying your own error messages is to throw a JboException:

throw new oracle.jbo.JboException("<your message>");

This stops the transaction and displays your error message text. But most likely you don’t want to hard-code your error messages. You can throw this JboException for example from a custom method on your application module (AM) or from another object from your BC layer. The strategy described above can also be applied to these kind of custom JBOExceptions. The JboException will be intercepted by our HRErrorreportingUtils class in the getMessage() method, and we can get the error message out of our centralized resource bundle.

public void testCXEException() throws JboException   {    throw new JboException("CXS-00003");   }   

But you could also make a custom method on an AM that can be called for example by a backing bean that adds a product- and error code as parameter:

public void throwHRMyCustomExceptionByProductAndErrorCode(String productAndErrorCode) throws JboException   {    throw new JboException(productAndErrorCode);   }

The product- and error code code can be anything as long as it is in the format ‘XXX-xxxxx’. So arbitrary codes like  ‘NGN-00001’ are possible. You only need to add your specific start-part (officially called ‘product’ code) of ‘XXX-xxxxx’ to the if-condition in the getMessage() method in HRErrorReportingUtils. For example ‘NGN-’:

if (message.startsWith("CXS-")    ||         message.startsWith("ORA-20")  ||         message.startsWith("NGN-"))            {…//as previously …}

Then you can call your AM custom method from another method on your AM or from a backing bean  and throw a JboException with your specific product- and error code:
(For this example, the custom operation throwHRMyCustomExceptionByProductAndErrorCode must be present in the pageDefinition)

The corresponding error-message will now be retrieved out of the centralized database resource bundle.

• Which files are updated correctly?
• Which files, if any, are NOT updated correctly by JDeveloper (bugs)?
• Solutions – in case JDeveloper does not correctly update your renamed object.
• Does renaming an ADF BC object have any consequence when using JHeadstart?

When you rename an object, it is best to rename only one object at a time, and then test whether your application still works fine. For ADF BC objects you can test it directly in de JDeveloper test-browser.  

Overview of issues and bugs when refactoring (or renaming) ADFBC objects in JDeveloper 10.1.3.3   

Solution details for issues when refactoring (or renaming) ADFBC objects in JDeveloper 10.1.3.3     

Overview of issues when renaming a group-, item- and region name in JHeadstart 10.1.3.2.51