By Oracle ACE Director Wilfred van der Deijl and Oracle ACE Richard Orlichs
Continued from Part 1
4. Create the Extension Application
We now have our test application set up. It's time to create the extension that will include the audit rule(s). In this section, we will create a new application that holds the audit rules to run against the previously created “Bad Practise” application.
Within JDeveloper, select New:
From the New Gallery, select General > Applications > Extension Application:
(Note: the extension application is available only if the Extension SDK is installed.)
Fill in a Name, Directory and a default package Application Package Prefix:
Since we're going to accept all the defaults again, you can either click Finish, or browse through the pages using Next if you want to see what you can configure.
Once you've clicked Finish, the framework creates an application with three files for you:
4.1 Extension.xml
We start by opening the extension.xml file:
The Display Name and Owner fields refer to a variable that is defined in the res.properties using an Expression language (EL)-like syntax.
Now, navigate to the Dependencies tab:
Here, we're going to add dependencies that we need in our project. Click the green + button, search for oracle.jdeveloper, check its box, and click OK:
oracle.jdeveloper is added to the required bundles list:
Note: Sometimes you need to close and open extension.xml to see the changes you made.
Add the following bundles, which include framework code from the JDeveloper integrated development environment (IDE) and the audit framework; we will use these framework codes in our own application:
- oracle.ide
- oracle.jdeveloper
- oracle.ide.audit
- oracle.ide.audit.core
- oracle.ide.xmlef
- oracle.javatools
- oracle.javatools-nodeps
- oracle.jdeveloper.properties
Here's the result:
Now, navigate to the bottom, where you'll find the Source for extension.xml:
Notice that this xml file does not contain any of the information we just added. This is because a lot of the information you configure in extension.xml actually belongs in MANIFEST.MF. Open the MANIFEST.MF file from your Applications navigator:
This information is kept in the MANIFEST.MF, but you can view and change it in a declarative way in the extension.xml overview.
Let's go back to extension.xml and navigate to the Hooks tab:
We're going to declaratively add an audit rule inside an audit hook—a pre-defined hook within the triggers framework.
Right click the triggers, go to Insert Inside triggers and then select Browse:
Scroll down to audit-hook, select it, and click OK:
We need to give this audit-hook an ID, but we can't do it from the Overview. Navigate to the Source tab and enter an ID for the audit-hook in the xml element:
Navigate back to the Overview.
Right click on the audit-hook, select Insert Inside and select trigger.
Now, right click on trigger again, and select Insert Inside, technology, creating a structure like this:
You configure this technology to tell JDeveloper when to load your audit-hook. In this case, we are creating a JSF rule, so there is no need to execute this rule on xml files that are in an Application Development Framework–Business Components (ADF-BC) project, for example.
You cannot enter this technology in the Overview; you have to navigate to the Source and add JSF within the technology xml tags:
Navigate back to the Overview tab and notice how the Overview picked up the inserted JSF value.
Now we're going to insert a category-definition within the audit-hook. Right click on the audit-hook again, select Insert Inside, and pick category-definition:
A popup will appear, where you can enter information about the category you're about to create. In this case, let's create a pageDef-rules category in which we can bundle multiple rules about pageDefinitions:
After the category-definition, we want to insert a rule-definition in the audit-hook. Right click audit-hook again, select Insert Inside and pick rule-definition.
Again, a popup will appear; this time, add information about the rule:
Choose a unique ID, in this case “invalid-iter-cache,” and set enabled to “true,” to let this rule be enabled by default.
Next, we'll add more elements inside the rule-definition.
Right click the rule-definition, choose Insert Inside, and select category.
When the popup asks you to, enter the ID we defined earlier, in this case, pageDef-rules.
Again, right click on the rule-definition, then choose Insert Inside and severity.
Select warning:
We're now done declaring our rule definition inside the audit-hook:
There is one step left to take within extension.xml, and that is to define an analyzer-definition. This is a Java class that we'll create to do the actual work.
Right click on the audit-hook and select Insert Inside.
Choose analyzer-definition:
Within this analyzer-definition, you have to add an analyzer-class:
Just as with the trigger technology, we have to add this analyzer-class through the Source.
Click on the Source tab and look for the analyzer-class tags.
We haven't created the Java class yet, but we are in control of naming this class as well as choosing the package, so let's add org.example.ruletutorial.analyzer.jsf.PageDefAnalyzer as analyzer class within the XML source.
The following extension.xml source results:
If you go back to the Overview, the result should look like this:
4.2 The Analyzer Class
After you have set up your rule in the extension.xml, it is time to create an analyzer class.
Right click on your package and choose New > Java Class:
In the popup, enter "PageDefAnalyzer" as the Name, and edit the package to: org.example.ruletutorial.analyzer.jsf
For the Extends option, check the Browse Classes option:
In the popup, enter Analyzer in the Match Class Name field:
It should find the oracle.jdeveloper.audit.analyzer.Analyzer class. If so, click OK. If not, you might have to restart JDeveloper. Sometimes,JDeveloper picks up only the required bundles you have added in the extension.xml after a restart.
Deselect Constructors from Superclass and Implement Abstract Methods, then click OK:
The result will be an empty Java class:
For now, we will implement two simple methods that contain System.out.println log statements so we can see them called and understand how the rule is processed when applied in future steps.
Create the following two methods in your PageDefAnalyzer:
These two methods will show you the main functionality of the Analyzer—it will enter and exit the constructs, and you'll be able to build your logic around this. Let's generate a simple log file with System.out.println to take a closer look at what is happening.
On your Extension project, select Deploy to Target Platform:
In your log window, you should see a successful deployment:
Right click your Extension project again. This time, select Run Extension:
This should result in another JDeveloper instance starting up:
Once this JDeveloper has started, select the Open Application option from the Applications navigator:
Navigate to the BadPractise workspace you created earlier, and open the BadPractice.jws file:
Within the ViewController project in the Applications navigator, open the Application Sources node and browse to the org.example.badpractive.view.pageDef package, then double click the PagePageDef.xml file to open it:
Select the pageDef file in the Applications navigator. Go to the Build menu in JDeveloper and choose Audit PagePageDef.xml. The Build menu reacts to what you have selected in the Applications Navigator (it does not matter whether you have the file open in the editor or not).
Accept the defaults in the popup and click Run:
Navigate back to your first JDeveloper and check the log messages. Here is a snippet of the first few lines:
You can see how the Analyzer traverses through your Workspace, through the project into the files that it contains. Once we hit the pageDef file, which is an XML document, it provides an enter and exit method for every element and attribute that the XML document contains.
The best practice is to collect information in the enter methods while reporting violations during traversal back up through the exit methods, when all collected information on children has been collected.
>>Continue to Part 3>>
About the Authors
Oracle ACE Director Wilfred van der Deijl has been working with Oracle's development tools and database ever since getting his degree in Computer Science in 1995. An active member of the Oracle community, Wilfred is a blogger, author, Oracle customer advisory board member, and a frequent presenter at international conferences, including ODTUG and Oracle OpenWorld.
Oracle ACE Richard Olrichs is an Oracle Developer at MN, a techology company based in the Netherlands. Richard has extensive expertise in Oracle Fusion Middleware with deep specialization in the Oracle Application Development Framework. Richard initiated an open source project creating an ADF EMG Audit Rules extension for both JDeveloper 11g and JDeveloper12c, and was also one of the initiators of ADF EMG XML DataControl, an open source project for both JDeveloper ADF 11g and JDeveloper ADF 12c. Richard is has spoken at TECH13, Tech 14, and Oracle Open World 2014.