Thursday, December 6, 2012

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

Updated on April 2nd, 2012

Win Free Copies of the Oracle JDeveloper 11gR2 Cookbook

Packt Publishing is giving away three copies of my latest book Oracle JDeveloper 11gR2 Cookbook. Luckily for you, winning it is quite simple. Keep reading to find out how you can be one of the Lucky Winner.

 
How to Enter?
All you need to do is head on over to the book page here : http://www.packtpub.com/oracle-jdeveloper-11gR2-to-build-adf-applications-cookbook/book, and look through the product description of this book and drop a line via the comments below to let us know what interests you the most about this book. It’s that simple.
Winners from the U.S. and Europe can either choose a physical copy of the book or the eBook. Users from other locales are limited to the eBook only.

Deadline
The contest will close soon. Winners will be contacted by email, so be sure to use your real email address when you comment!

Updated on March 27th, 2012
 
Here are some peer references/reviews of the book from the blog sphere:

Friday, March 9, 2012

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!

Thursday, March 8, 2012

FAQ #37 - How to create audit trail records using ADFBC, Pt. 2

Introduction

In this second part of creating historical audit trail records using ADFBC we will see how to integrate, in a generic way, the stored procedures introduced in part 1 of these series. For more information on the database schema and stored procedures that are required to support this technique refer to FAQ #36 - How to create audit trail records using ADFBC, Pt. 1.

Main Theme

As explained in part 1 (FAQ #36 - How to create audit trail records using ADFBC, Pt. 1), historical audit trails are generated by calling the stored procedures AUDIT_TABLE and AUDIT_DETAILS. Both of these procedures are part of the AUDIT_PKG database package.

The AUDIT_TABLE procedure is called to create a historical audit trail of the corresponding table. As explained in part 1, corresponding history tables are created for each table being audited. These history tables conform to the following naming convention: table_name_HISTORY where table_name is the table being audited.  For example the corresponding history REGIONS table is called REGIONS_HISTORY.

To create a generic implementation, we will need to create framework extension classes for both the oracle.jbo.server.EntityImpl and oracle.jbo.server.ApplicationModuleImpl classes. Once these framework extension classes are created ensure that the ADFBC project settings are changed to reflect this fact. You do this by bringing up the Project Properties dialog and selecting ADF Business Components | Base Classes as it is shown in the picture below:

The next step is to override the EntityImpl doDML() method for the EntityImpl extension framework class and add the following code to it:

Note a few things about this overridden doDML() method:

  1. We call getEntityDef().getProperty(DISABLE_AUDIT_PROPERTY) to determine whether auditing for the specific entity object has been disabled. This is controlled by the presence of an entity object property identified by the constant DISABLE_AUDIT_PROPERTY. As long as this property has not been defined in the entity object, auditing is enabled by default.
  2. We call getEntityDef().getSourceType() to determine the source type of the entity object. We will audit entity objects based on database tables only. This is done by comparing the return value of getEntityDef().getSourceType() to DBOBJ_TYPE_TABLE. DBOBJ_TYPE_TABLE is a constant defined in oracle.jbo.server.EntityDefImpl indicating that the entity object is based on a database table.
  3. The first parameter required by the AUDIT_TABLE stored procedure is the user's current session identifier. This can be retrieved by calling SessionImpl.findOrCreateSessionContextManager().getCurrentSession().getId(). Take a look at this post for information on this: Bit #39 - Retrieving the current session id at the ADFBC layer.
  4. The second parameter passed to AUDIT_TABLE stored procedure is the commit identifier. We would like to keep track changes for each commit done in the same user session. We retrieve the commit identifier from a database sequence by calling the helper getCommitId() (see source code below).
  5. We pass the DML operation as a string (INSERT, UPDATE or DELETE) based on the value of the operation parameter passed to doDML() by the ADFBC framework.
  6. We call getEntityDef().getSource() to get the name of the table associated with the entity object.
  7. Finally we call the getEntityId() helper (see code below) to get the entity object's primary key. Note that we convert the primary key to a string before passing as a parameter to the AUDIT_TABLE stored procedure.
Here is the code for the getCommitId() and getEntityId() helpers:

Notice a couple of things about these helper methods:
  1. In getEntityId() we iterate through the entity object attributes in order to determine the primary key attribute. We do this by first calling getStructureDef().getAttributeDefs() to get the attribute definitions and then by calling isPrimaryKey() for each attribute to determine if it is a primary key attribute. If it is, we call getAttribute() to retrieve and return its value. Notice that you will have to expand this implementation if you have an entity object with a composite primary key.
  2. In getCommitId() we add the commit identifier returned from the database sequence to the session user data by calling getDBTransaction().getSession().getUserData(). We do this because we will need the same commit identifier at a later stage when calling the AUDIT_DETAILS stored procedure.
As explained in part 1 of this post, to create the specific details of the audit trail we need to call AUDIT_PKG.AUDIT_DETAILS stored procedure. To do this, override the afterCommit() in the ApplicationModuleImpl framework extension class and add the following code to it:


Notice in this case how we call getSession().getUserData().get(ExtEntityImpl.COMMIT_ID) to get the same commit identifier and pass it as a parameter to the AUDIT_DETAILS stored procedure. Also, notice that we remove the commit identifier from the session user data once we are done with calling the stored procedure.

Conclusion

In this two-part series we've seen a custom implementation of creating a historical audit trail based on a stored procedure implementation in the database. Notice that this technique is fairly generic as it does not require any additional implementation in the specific entity objects used throughout the application. As mentioned above, auditing is enabled by default and can be disabled by the presence of a property defined in the entity object. This can be easily reversed so that auditing is not done by default. If you found this useful, let me know so I can email you or post the source code as well.

Until the next time, have fun JDeveloping!


Related Posts Plugin for WordPress, Blogger...