FAQ #39 - Handling session expiration redirection in ADF 12c

Introduction

So how is this handled in 12c? I asked this to myself when I had to migrate an 11g ADF application to 12c. It seems that other people are asking about it too (see: https://community.oracle.com/thread/3952768, https://community.oracle.com/message/12531687#12531687, https://community.oracle.com/message/12497105#12497105 and so on) but no answers yet. The tried and tested implementation in 11g was to implement a custom filter, detect a session expiration and if that occurs redirect to a session-expired page. This is all good but... it does not work in 12c.

Main Theme

Google this

It is unfortunate for yet another instance there is practically no documentation on this at all. After googling intensly on the topic for a couple of days (talk about "agile" programming), I landed on this Oracle A-TEAM blog post, which seemed promising: http://www.ateam-oracle.com/customizing-session-time-out-pop-ups/. The post details how to customize the session expiration dialogs. Right at the top of the post there is a link with tips-on-dealing-with-the-session-time-out-popup. Eureka! As an older Greek colleague once said. So I navigated to it (http://www.ateam-oracle.com/tips-on-dealing-with-the-session-time-out-popup/) only to find out - to my dissapointment - that this was the good old 11g approach. Bammer.

Deep poetry

Well, not everything was lost. A small glimpse of hope appeared thanks to an initially seeming esoteric comment at the bottom by Deep Saurabh (Thank you Mr. Saurabh). And the comment goes something like this:

"If neither of above two is working , override NewSessionURLProvider service/provider.
( http://docs.oracle.com/middleware/1212/adf/FACAR/oracle/adf/view/rich/context/NewSessionURLProvider.html )
In the web lib’s META-INF/services folder you should have file:
oracle.adf.view.rich.context.NewSessionURLProvider
(for quick test run from jdev create META-INF/services under your ViewController/public_html/WEB-INF/classes/)

Which should contain FQCN of your custom overridden AdfcNewSessionURLProvider class."

Hmm? What did the Deep poet mean?

Enter NewSessionURLProvider

Well, other than the Deep comment above - which at the time I did not quite understand - the only other thing I had to go was the NewSessionURLProvider class. Here is the 12.2.1 class JavaDoc: https://docs.oracle.com/middleware/1221/adf/api-reference-faces/oracle/adf/view/rich/context/NewSessionURLProvider.html
The class is simple enough. It is an abstract class that needs to be overridden in the 12c ADF application by implementing the getNewSessionURL() method. As the documentation states, getNewSessionURL() is "Used to provide the view with a URL to create a new session if the current session expires while the current page is displayed.". Like I said, simple enough. That would be the first step. Override NewSessionURLProvider in your ADF application and provide an implementation for getNewSessionURL(). The code should look like this:

package com.jdeveloper.faq.services;

public class MyNewSessionURLProvider extends NewSessionURLProvider {
  @override
  public String getNewSessionURL(FacesContext fc) {
    return "pages/YourSessionExpirationPage.html";
  }
}

All you have to do is return the page that you want the application to redirect upon session expiration.

What next?

It is unclear what needs to happen next, to miraculously connect your ADF 12c application to the ADF framework and instruct it to redirect to your page. If you decypher the line "In the web lib’s META-INF/services folder you should have file: oracle.adf.view.rich.context.NewSessionURLProvider" from the comment above, it simply states what needs to be done next:

In your application's JDeveloper web ViewController project, under the src/META-INF directory create a new directory called services.In the src/META-INF/services directory create a text file (no extension) literally called oracle.adf.view.rich.context.NewSessionURLProvider. Edit the src/META-INF/services/oracle.adf.view.rich.context.NewSessionURLProvider text file and in it type the FQCN of your overridden NewSessionURLProvider class. This is what the src/META-INF/services/oracle.adf.view.rich.context.NewSessionURLProvider text file should look like:

com.jdeveloper.faq.services.MyNewSessionURLProvider

That's all?

Pretty much. The only other thing that needs to be done is to ensure that the src/META-INF/services/oracle.adf.view.rich.context.NewSessionURLProvider file in included in your deployed WAR file (during the application EAR deployment). In order to do that, edit the web ViewController deployment profile properties and under the WEB-INF/classes file group Contributors ensure that the Project Source Path is checked. Verify that the services/oracle.adf.view.rich.context.NewSessionURLProvider is included in the file list by selecting Filters under the WEB-INF/classes file group. Once you deploy your application, open the WAR and ensure that the services/oracle.adf.view.rich.context.NewSessionURLProvider text file is indeed included in the archive.

You are now ready to test it. Don't forget to remove the 11g custom filter implementation from web.xml.

Conclusion

I personally like the session expiration redirection implementation in 12c. No need to come with custom filters and all. Hopefully this will be documented in future releases of ADF.

Until the next post,(and that may be a long long time...) have fun with JDeveloping!

Oracle JDeveloper 11gR2 Cookbook

After almost a year of truly great effort by everyone involved, I am happy to announce that my Oracle JDeveloper 11gR2 Cookbook book is published by Packt Publishing. This book accumulates to a large degree my practical experience amassed over the last four years working on real world ADF projects.

Special Thanks goes to Frank Nimphius, Edwin Biemond and Spyros Doulgeridis for their insight, knowledge and advice.  

 

For further details about the book click here. 

Here are some peer references/reviews of the book from the blog sphere:

• https://blogs.oracle.com/shay/entry/new_adf_book_oracle_jdeveloper 
• http://monkeyonoracle.blogspot.com/2012/02/preparing-to-work-with-adf.html
• http://antonis-antoniou.blogspot.com/2012/03/new-adf-book-oracle-jdeveloper-11gr2.html 
• http://www.adftips.com/2012/03/oracle-jdeveloper-11gr2-cookbook-new.html 
• http://nickaiva.blogspot.com/2011/12/preview-of-oracle-jdeveloper-11gr2.html
• https://blogs.oracle.com/grantronald/entry/book_to_review_oracle_jdeveloper11gr2
• https://blogs.oracle.com/jdeveloperpm/entry/new_adf_book_oracle_jdeveloper
• http://www.oraclemagazine-digital.com/oraclemagazine_twitter/20120304?pg=31#pg31
• https://forums.oracle.com/forums/thread.jspa?threadID=2351960
• https://blogs.oracle.com/onesizedoesntfitall/entry/oracle_jdeveloper_11gr2_cookbook_book 
• http://serafeimk.blogspot.com/2012/04/adf-11g-oracle-jdeveloper-11gr2.html 
• http://xmlandmore.blogspot.com/2012/04/book-review-oracle-jdeveloper-11gr2.html 
• http://www.amazon.com/Oracle-JDeveloper-11gR2-Cookbook-ebook/product-reviews/B00719PC60/ref=dp_top_cm_cr_acr_txt?ie=UTF8&showViewpoints=1 

FAQ #38 - How to add help to an ADF application

Introduction

Adding help to an ADF Fusion Web application is thoroughly explained in section 19.5 Displaying Help for Components of the Web User Interface Developer’s Guide for Oracle Application Development Framework guide. Yet, as it seems from this post https://forums.oracle.com/forums/message.jspa?messageID=10190922#10190922 in the JDeveloper and ADF forum at OTN, some of us still have questions around this subject. In this post I will attempt to clarify the subject of adding help to your ADF application by presenting pretty much the same information but in a different approach, so I suggest that before continuing with the reading this post you first take a look at the aforementioned link in the guide. Then, if you still have questions, read on.

Main Theme

Help added to an ADF Fusion Web application is categorized based on where the help contents are stored. Currently the help contents can be stored in any of the following mediums:

• In a resource bundle
• In a managed bean, or 
• In an XML Localization Interchange File Format (XLIFF) XML file

So the first step would be to determine where your help contents will be stored. As mentioned, you have the choices listed above. So the first step entails having to make a design decision which one to use. What gets a little bit confusing is that each one of the three choices above allows you to display help using an external URL, which will open the help contents in a separate browser window.

So how do you add help to your ADF Fusion Web application? Simply by adding a help-provider tag to the adf-settings.xml configuration file. The adf-settings.xml file resides in the .adf/META-INF directory and it is accessible in JDeveloper in the Application Resources part of the Application Navigator via the Descriptors | ADF META-INF node. Depending on the help contents location (one of the three choices listed above) you need to provide values for the help-provider-class and property tags under the help-provider tag. Here is an example for the case where the help contents are stored in a resource bundle:

In the table below I have listed the appropriate help provider classes and property names/values depending on the location of the help contents:

You can provide external URL help in each case (resource bundle, managed bean, XLIFF) by providing your own custom help provider class. Just make sure that in each case you extend the appropriate default help provider class (shown in the table above), i.e. oracle.adf.view.rich.help.ResourceBundleHelpProvider for resource bundle based help or oracle.adf.view.rich.help.ELHelpProvider for managed bean or XLIFF based help.

For the remainder of this post, we will see how to add help utilizing the resource bundle method, which is in my opinion the most straightforward case. In this case all you have to do is to create a resource bundle, i.e. a text file with the file extension .properties and add the help contents to it. The help contents are made up of text lines that conform to the following naming convention:

help_topic_id=help_topic_data

where help_topic_id is the help topic identifier and help_topic_data is the actual help shown to the user. Here is an example:

PREFIX_TOPIC1_INSTRUCTIONS=Example for help instructions
PREFIX_TOPIC1_DEFINITION=Example for help definition

A few things to notice about the help topic identifiers:

• For the same topic (TOPIC1 in the example above), you can define both instructions help and definition help by appending _INSTRUCTIONS and _DEFINITION to the end of the id respectively. Instructions help usually appears as you tab from one UI component to another, while definition help usually appears as a help icon in front of the UI component but this may vary depending the UI component. Again, take a look at section 19.5 Displaying Help for Components of the Web User Interface Developer’s Guide for Oracle Application Development Framework guide for more information on this.
• Notice the prefix (PREFIX_ in the example above) used by the help topic identifiers. The prefix identifies the help provider and is specified in the help-provider tag in the adf-settings.xml configuration file.

Finally, how do you assign help topic identifiers to UI components? For this you can use the HelpTopicId property under Appearance in the Property Inspector, just don't add the _INSTRUCTIONS or _DEFINITION part of the help topic id:

The result of using PREFIX_TOPIC1 for an af:inputText UI component is shown below:

As soon as you tab into the inputText component the instructions help is shown. The definition help is shown by hovering the mouse on the question mark icon added by the framework in front of the inputText component.

One last thing: the question mark icon could actually become a button that when clicked will display help from an external URL in a separate browser window. As mentioned earlier, you do this by extending the default help provider. But again, this is explained nicely in the documentation.

Conclusion

Hopefully this post clarified any additional questions that you might have had related to adding help to your ADF Fusion Web application.

Until the next post, have fun with JDeveloping!