Wednesday, September 3, 2014

Annotation Driven Bean and EJB DataControls in ADF 12c


So as the trend of using annotations over XML configurations goes on and on in software development there is no exception to  ADF. Many developers asked for more annotations to configure metadata on Bean DataControls. Since ADF 12c finally there is support for annotations on Bean and EJB DataControls. Let's have a look on it.

Sample POJO DataModel
In my sample I am using a simple Data Model that I want to expose as Bean DataControl to check the new annotation features. We use simple POJOs „Person and a PersonService". See next figure


Next we want to see some of the annotation features in action.

Primary Key Definition
In order to make your DataModel functioning correctly in most cases you should define a primary key. You can do this now with the @Id-Annotation: (No need to generate an XML file for these kind of metadata)


(If using JPA-based entity classes make sure to use the javax.persistence.Id annotation)

Setting UI Hints
To set specific UI Hints like label, tooltip, display, width, height, autoSubmit, controlType, formatType, format, timezoneId, etc. you can leverage the @AttributeHint, @DateFormatter and @Formatter Annotations. Further it is possible to define custom properties through @Property annotations



Note a: If you set UI hints for an attribute both using annotations and in an XML data control structure file, the settings in the data control structure file take precedence. 
Note b: When you apply annotations for UI hints, you can not see the affect of the hints in the design-time view of pages that you create based on the data controls. However, you can test and verify the hints using the ADF Model Tester. 

BTW: Everything looks easy so far, but: The most challenging part for me was to recognize that these annotations only work on METHOD level and not on FIELD level although there are no compile errors! It felt natural for me to put these annotations on fields, but believe me, it won't have any effect in ADF 12.1.3. So remember

Interesting to note: The @Id Annotation works also on FIELD level!

Testing the result
Running the sample we see that the annotation driven meta data is recognized correctly. It has been applied to Table Column Headers and Form Labels, Formatters and Input-Types.


Setting AccessMode for Collections
For collections you can define the AccessMode (Scroll, Range-Paging or None).

For SCROLLABLE or RANGE_PAGING Mode to work correctly you need to implement the following method signatures (for every collection) 

List<Person> getPersons(int firstResult, int maxResults)
long getPersonsSize() 

Note: These annotations only work on getter methods.

Testing Metadata Using the Oracle ADF Model Tester 
For EJB and Bean Data Controls you can go to the DataControls.dcx file select the given DataControl and exceute „Run" from the context menu.


=> This is pretty cool. As your deployment roundtrips can be reduced ;)

Gotchas
First everything looks promising. But if you try to do some real world developer roundtrips some gotchas appear. Commenting some annotation out, testing changes etc you notice that some information are not refreshing properly inside JDeveloper. So, e.g.

Step 1: Change primary key definition

Step 2: Open DataControls.dcx

=> The change is recognized correctly by the DataControls Editor.

Step 3: Go to the  structure definition file (Person.xml)

=> The old attribute is still displayed as primary key! Expected: firstname, because of the recent changes. Hhhm. Is this a bug? It could lead to frustration and unexpected behaviour. Workaround is to close the JDeveloper application and open it again. Looks like a caching/synchronization failure.

Conclusion
The support for annotations is getting better in ADF. Besides some caching problems at design time views there is missing support for Validation. As JSR 303 (Bean Validation) is Java industry standard and widely adopted it would be cool to see ADF moving in that direction too! At this time Validations on POJO DataModel must be done in the DataControl structure files per entity. Due to the "sparse bean nature" the XML file only for the given entities needs to be generated.


Download
Sample application build with JDeveloper 12.1.3: enpit.sample.dc.annotations-jdev1213.zip

Further information

Tuesday, July 29, 2014

Using FlexSlider as Declarative Component in ADF

In the www there are a lot of cool photo slideshow components which one might want to use in ADF applications too. For example the FlexSlider.


Technically it should be easy to be integrated, e.g. like
..
<flexslider:FlexSlider animation="fade“ id=" fs1="" imagelist="#{someBean.imageList}" />
..

Environment

The following sample is based on ADF 11.1.1.7

How to do it

Well - in theory - it is quite simple. Take a look at the plain JavaScript/HTML Sample from http://www.woothemes.com/flexslider/ and put all necessary files in your component project which will be bundled as ADF Library for reuse. However based on your use cases (integrate inside a fragment based taskflow) there will be some challenges.
- How to deal with more then one instance on one page
- How to hook the javascript, which typically hooks into the onload javascript phase

        $(window).load(function() {
          $('.flexslider').flexslider({
            animation: "fade" /* or "slide" */
          });
        });


So here is my solution.
Step 1: Setup an ADF component project und copy all relevant files from the FlexSlider


Step 2: Next create the declarative component FlexSlider.jspx (by using the JDeveloper wizard, generate the component class and TagLibrary). The important part is to generate a unique id for the slider DIV and to make sure to call the needed javascript method to setup the slideshow. The FlexSlider.jspx looks as follows


and for the FlexSlider.java define the following methods



To make the Javascript call we use a known trick to bind the Call to a getter on an af:outputText with visible=„false“.

How to use it

Define a simple bean (or could also be a DataControl) that serves a List of Images


Drop the declarative component „FlexSlider“ from the component palette onto the given page and bind the given list via EL


As result you will get a reusable UI component to integrate slideshows into ADF applications.

Gotchas

The font resources like ttf, eot, woff, svg (that are referenced from the flexslider.css and are being used as the previous/next font-icons) are not served as expected from the ADF Library which holds the custom component. For now the workaround is to copy these resource into your master viewcontroller project. This way you make sure that all resources are loaded.

See ADF EMG Issue https://java.net/jira/browse/ADFEMG-244 for the current progress.

Download

enpit.sample.flexslider-jdev11117.zip