Monday May 21, 2012

Setting up a Fusion Applications Development Environment

With the release of Oracle Fusion Applications, there has also been the release of the Fusion Application extensions for JDeveloper. Installing and configuring these extensions is referred to as the FA Dev Environment.

One very important thing to note, is that creating extensions for Oracle Fusion Applications, is NOT the same as writing extensions for JDeveloper.  You are writing and extending the Application functionality, using JDeveloper as the dev environment.

With that said, I wanted to still cover this topic in this blog, because it involves the installation and configuration of JDeveloper Extensions that help with the customization of those Fusion Applications.

Hope that makes sense.  :-)

Downloading the proper version of JDeveloper and the FA Extensions

The version of JDeveloper and the FA Extensions is directly related to what version of Oracle Fusion Applications you have installed on the servers. You get the different releases, from the eDelivery website, under product pack Oracle Fusion Applications .
DO NOT download a version of JDeveloper off of the OTN website and use it to setup the Fusion Applications Dev environment.

No matter which version you download, you will need two different downloads.

  • JDeveloper installer (Oracle JDeveloper 11g and Oracle Application Development Framework 11g)
  • Fusion Application Extensions Bundle (Oracle Fusion Applications Companion 11g)
Part #'s for FA V1 RUP1 on http://edelivery.oracle.com
Part#: V28727-01 :: Oracle Fusion Applications Companion 11g (11.1.1.5.3)    
Part#: V28726-01 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.5.3) (Part 1 of 3)    
Part#: V28726-01 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.5.3) (Part 2 of 3)    
Part#: V28726-01 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.5.3) (Part 3 of 3)    

Part #'s for FA V1 RUP2 on http://edelivery.oracle.com
Part#: V31524-01 :: Oracle Fusion Applications Companion 11g (11.1.1.6.1)    
Part#: V31523-01 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.6.1) (Part 1 of 3)    
Part#: V31523-01 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.6.1) (Part 2 of 3)
Part#: V31523-01 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.6.1) (Part 3 of 3)

Part #'s for FA V1 RUP3 on http://edelivery.oracle.com
Part#: V31981-01 :: Oracle Fusion Applications Companion 11g (11.1.1.6.2)    
Part#: V31980-01 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.6.2) (Part 1 of 3)    
Part#: V31980-02 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.6.2) (Part 2 of 3)
Part#: V31980-03 :: Oracle JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.6.2) (Part 3 of 3)

(Other releases that come out after this posting will be found in the same  http://edelivery.oracle.com location, with newer part numbers. The naming should remain the same)

TIP: If you are installing on Windows only, you can just download the companion archive and Part 3 of 3 for the JDeveloper IDE.  Part 1 is the .jar installer and Part 2 is the .bin installer for other operating systems.

Once you have the appropriate bits downloaded, and extracted, you can start the steps for getting everything installed and configured.

Installing JDeveloper and FA Dev Extensions 

This is a pretty normal step.  Just install JDeveloper as you would on any other machine. With one exception:

  1. Do not install JDeveloper into a path that contains spaces (the default is C:\Oracle\Middleware)

The entire process for setting the proper environment variables and setting up the Update Center for installing the FA Dev Extensions, is described in detail in the online documentation under the Setting Up Your Development Environment section.

A couple of things to watch for when setting up the environment listed in the docs.

  1. Do Not include the quotes " " around the values for USER_MEM_ARGS variable on Windows.  This is a typo in the docs.
  2. It is best to use the JDK that ships with JDeveloper on Windows.  You do not need to use a 64bit JDK. For other operating systems make sure you use something equal to or above jdk160_24
  3. When the docs tell you to change directories to $MW_HOME/jdeveloper/jdev/bin  and run JDeveloper, this is mainly for non-Windows OS's.  However if you do run on Windows from a command window it could allow you to see some of the error messages if there are any.  You can still run JDev from the Start Menu if you like.  

Configuring the Fusion Domain

Once you've installed the FA Dev Extensions, and restarted JDeveloper, you select either the "Oracle Fusion Applications Developer" or "Oracle Fusion Applications Administrator Customization" role at startup.

As you will see in step of 7 of the online documentation, you will now be prompted to configure the Weblogic Server.  This involves filling out the Fusion Domain Configuration wizard and letting it do it's thing.

A couple of things to watch for before and during the running of the domain config wizard

  1. Make sure you have Python 2.7.2 or higher installed in a path that does not contain spaces. 
  2. DO NOT use Python 3.x
  3. Take a look at your system PATH environment variable and remove any entries that have spaces in them
    1. The easiest way to do this on Windows is to open a command window and set the PATH variable to just contain "." and the path to your Python installation. (e.g. set PATH=.;c:\python272 )
    2. Then start JDeveloper from this command window
  4. When you run the Fusion Domain Configuration wizard, you will be given an option to test the connection to the application server on one of the pages.  If it fails during the tests, but you know FOR SURE that you have the login credentials correct, try entering the IP address of the host instead of the hostname in the connection URL.  We have seen some DNS issues cause errors during the test page.

Follow all of the tips above and you should get the domain configured and extended properly.

Troubleshooting

 There are always exceptions to the rule.  If you run into issues, try looking at these tips.

Error logs

There are two different types of log files that can help find an answer to whatever issue you are running into.  Server logs, and config logs

  • D:\jdevuserhome\system11.1.1.5.38.61.26\DefaultDomain\servers\DefaultServer\logs
  • D:\jdevuserhome\system11.1.1.5.38.61.26\o.apps.fadev.11.1.1

 Some common error messages

"...\Java\jre6\lib\ext\QTJava.zip was unexpected at this time."

 This error is usually caused by the QT entry in the CLASSPATH containing spaces.  You can get around this by removing the Quicktime/QT entry from the end of the CLASSPATH


"... wlst create default authenticator failed" 

or 

 "java.lang.IllegalArgumentException: java.lang.IllegalArgumentException: The provider OIDAuthenticator already exists"

or

"OracleScriptingException: The MBean oracle.wsm:*,name=WSMDocumentManager,type=Repository was not found." 

 All of the above errors, or errors similar that mention *wsm* are usually caused by the owsm_mds schema not existing. If you look at the Dev Guide, in section 2.2.1.6, it explains that this schema is usually not available in production or test databases. The Fusion install doesn't create it in the starter database; it's expected to be in the IDM database. Go back and read this section of the Dev Guide to install and configure the owsm_mds schema.


The configuration script seems to just hang while running "FADevConfigure.py"

If you followed the tips and hints above, you shouldn't hit this issue.  However if you do, make sure you go back and check to see if you have quotes around any of your Windows environment variables, and if your PATH setting has spaces in it.  


When testing your application server connection you see something like:

Testing JSR-160 Runtime ... failed
Cannot establish connection.
Testing JSR-160 DomainRuntime ... skipped
Testing JSR-88 ... skipped
Testing JSR-88-LOCAL ... skipped
Testing JNDI ... skipped
Testing JSR-160 Edit ... skipped
Testing HTTP ... success
Testing Server MBeans Model ... skipped
Testing App Controller ... success

This is usually solved by setting the IP address of the application server in the connection URL instead of the hostname. 

Conclusion

 With the tips and hints listed above, along with the common error messages in the troubleshooting section, you should be able to get up and running pretty quickly.  If you run into other issues setting up the development environment, please don't hesitate to drop a comment below.  Please DO NOT ask me questions about how to do the customization of the FA applications themselves.  If you're trying to edit files, I'm not going to be the person to help you out with that.

Special Thanks to Oliver Steinmeier for a lot of the answers and troubleshooting of customer issues internally, so that we can compile these types of lists. 

Wednesday Aug 31, 2011

Running an audit from the command line with ojAudit

NOTE (UPDATE 9/30/2011):  This post currently does not work with 11gR2 (11.1.2.0.0) because of a bug.  The bug has been fixed in 11gR2 Update 1 (11.1.2.1.0). Please make sure you are running the latest release of R2.


 There is often a need to run an audit profile against a specific application, project, or even a file, and do it all from a script that may be part of a larger task.

JDeveloper provides a tool just for this task.  It's called ojAudit.

By default, you'll find this tool in the <oracle_home>/jdeveloper/jdev/bin directory.

If you run the tool without any arguments, you will get a really good usage guide, complete with examples.

The one thing that is needed by all of the examples, is a profile.  Let's look at how to create an audit profile so you can use it from the command line.

If you run JDeveloper and look under Tools >> Preferences >> Audit >> Profiles you will see a list of the profiles defined by default.

If you want to create your own profile, that is a subset of the existing rules, you can check and uncheck the various rules until you only have the ones that you want to run in your profile.  You will notice that the Profile name at the top of the dialog says that the currently selected profile has been (Modified).


Click on the Save As button and enter a new name for your profile.  You now have your own audit profile created and it can be used from the command line.  You don't need to know the location of the actual profile file, but by default, these audit profile files are saved at:

<UserDirectory>\Application Data\JDeveloper\system11.1.1.5.37.60.13\o.jdeveloper\audit\profiles

In the example above, you see that I am using version 11.1.1.5.37.60.13 of JDev.  In other words, 11gR1 PS4. Your systemXXXX will vary depending on what version of JDev you have installed. The rest of the path should be the same.

If you still can't locate the file, do a search on the name.  If you entered spaces in the profile name when you did the Save As in the dialog, the spaces will be replaced with " - ".  In the example that I used above, I named my profile to "My Audit Profile".  The resulting file is "my-audit-profile.xml". 

Once you have your profile created, you can use it from the command line like this:

ojaudit -profile 'My Audit Profile' -workspace <path-to-workspace(jws)-file>

If you forget exactly how you spelled your profile name, or just can't remember it because you created it a while ago, you can run:

ojaudit -profilehelp

and it will list all of the available profiles that can be used.

You can audit an entire workspace, a project, or a specific file.  If you point to a specific file, you will need to set  -classpath and -sourcepath for the files that you want to audit.

The report will output to stdout by default, so unless you are ok reading a bunch of xml from the command window, I would also add: -output report.xml

The final syntax would look something like:

ojaudit -profile 'My Audit Profile' -workspace <path-to-workspace(jws)-file> -output report.xml


Tuesday Aug 16, 2011

Don't fear the Audit -- Part 2

In Part One of this topic, I covered the basics of creating an extension that will implement the audit framework and find a specific value for the FetchSize property of a ViewObject.  Once we found the value, we sent a Warning to the Editor if the value was greater then 100.

In this part, I'll cover how to create a Transform, or fix, that the end user can select to reset the value to the recommended value of 100, automatically.

An updated .zip of the sample project, with the transform code added, can be downloaded from here.

Just as with Part One, we will work with two separate areas of code.

The declarative entries in extension.xml and the code itself in the Transform class and the Transaction class.

Extension.xml

Previously I setup the <audit-hook> element in the extension.xml file, and I added a <rule-definition> to define what I wanted to report, when I found it. 

Similarly, I will add a <transform-definition> element to the audit-hook to define what the transform will be called, and where the transform class is located.


As you can see, the <transform-definition has one parameter of "id".  This must be a unique value.  As with the <rule-definition> I've set the label and description for this element in the resource file, instead of directly in the extension.xml.


Inside of the transform-definition is the <transform-class>.  I've added the entry that points to the class that I will be using to extend Transform.

Once you have the transform defined, you have to bind the rule to the transform, so that the IDE know which transform to display in the Editor.


Inside of the <rule-definition>, I've added a <transform-binding> element and the <transform> element which points to the ID of the transform definition that we set above.

That's it for the extension.xml.  Let's take a look at the Transform and Transaction classes now.

Transform class

The transform class must be a subclass of oracle.jdeveloper.audit.transform.Transform .

I'm going to be transforming an xml document so I'll make an explicit superclass constructor invocation of XmlTransformAdapter (for Java I would use JavaTransformAdapter).

To make sure all of this is done in a transaction, that can be undone by the end user, I've created the class FixFetchSize and called teh run() method to make everything happen.

Transaction class

The transaction class is a subclass of oracle.bali.xml.model.task.FixedNameTransactionTask.

I've overwritten the performTask() method to do the actual value replacement.

The Final Look

Once you have everything completed, if you run the extension from within the IDE (remember for 11gR2 you have to: Build, Deploy to Target Platform, then Run Extension)  you should find the audit available in the Tools >> Preferences >> Audits >> Profiles and if you run the audit against something like the Storefront demo, you will see something like this


Conclusion

Setting up the extension.xml to point at and use a transform is pretty simple. Getting the proper values from the file and making the modifications is where the real work is at.  In this particular example it took a lot more work to understand how to work with the XML document model and what to look for and replace, then it did to add the few lines in the extension.xml file. Hopefully this example will provide enough information to get you pointed in the right direction.

If you are going to be working with a Java file instead of XML, please take a look at the existing Extension SDK sample project called AuditRefactor for an example on how to work with java files.  It shows how to implement a transform by using the RefactoringManager, which can be very useful.

As with all my posts, if you have any comments, experiences, or questions, please add them to the post so everyone can learn from each other.


Monday Aug 15, 2011

Don't fear the Audit -- Part 1

Have you ever looked at the JDeveloper IDE, while you're writing code, and seen the warnings or errors that come up in the left and right gutters? Have you thought, "wouldn't it be great if the editor caught XYZ in my code?"

Well, you can write your own Audit extension to have the IDE look for just about anything.

The Audit Framework that comes with JDeveloper is very powerful, and really not that hard to extend.  It can help with maintaining company standards, or enforcing efficiency and protocol standards that may be set by your team.

You can even go as far as to write transforms (fixes) that will make the changes to the code for you when it finds something that you pre-defined.

For this topic, I'm going to use a project that I wrote specifically for this example.  You can download the entire project as a .zip file and place it into your work directory if you like.  I'm using JDeveloper 11gR2 for this example project. If you don't have this latest release, you can still follow along and I will try to point out the differences between the R1 syntax and the newer R2 syntax.

UPDATE (02/17/2012): There has been a nice write up about this topic, specifically done for 11gR1 over on Arvinder Singh's blog If you are using 11gR1 (11.1.1.x) then I would head over there as well.

In Part One of this topic, I'll cover the writing of the analyzer, to find the suspect code and send a report to the IDE.  In Part Two, I'll cover how to write a transform to automate the modification of what you report in the analyzer.

For most audits setting up the analyzer and having it report something to the IDE is all you need to do.

This is broken down into two parts.

  • Declarative entries in the extension.xml file
  • Analyzer class

The Extension.xml 

Let's start in the extension.xml file and work from there.

As you can see, we are going to add an <audit-hook> element to the file.  If you are using JDev 11gR1, this will go into the <hooks> section, if you are using 11gR2, this goes into the <triggers> section. Otherwise, the syntax is the same.

Let's take a closer look at each of the elements in the example above.

The <audit-hook> ID parameter must be a unique id.

The <category-definition> is what tells the IDE where to display the rules when you look at the Tools >> Preferences >> Audits >> Profiles dialog.
There is a label, description, and message parameter for the category-definition element. I've set these in a Resource file instead of putting them directly in the extension.xml file.  I've done the same thing for the <rule-definition> element. Here is what that resource file looks like.


The <rule-definition> element is really where everything is setup.


The ID parameter has to be a unique string.

The category is set to the category that you defined above, or an existing category that you know the ID of.

Enabled is set to true or false.  This is very important.  If this is set to true, the IDE will run your audit as soon as the file is loaded in the editor.  It's best to set this to False until you know what impact your audit is going to have on performance of the editor.  If you do something really time intensive in the analyzer class, it could bring the editor to a crawl.

The severity element can be set to one of four options.

  • Error
  • Warning
  • Incomplete
  • Advisory
  • Assist

All of these have a different way of displaying in the IDE when they are encountered by the audit framework. The Error value will stop the compiler from completing until the issue is resolved.

The parameter element is optional.  This is what you will use to pass any values back from the audit.  You may want to pass a value back to be used in the message that is displayed in the editor when you mouse over the issue.  Take a look at the Resource file example that I included above, and you will see how I am using the "currentsize" parameter in my message.

Multiple Rules can be setup in an audit-hook element.  However only one analyzer class can be referenced per audit-hook so it's best to group rules into common analyzers.

The <analyzer-definition> element is set to point to the analyzer class that the rules will be implemented in.

The Analyzer Class

The analyzer class is where all of the real work is done.

An analyzer class must be a subclass of oracle.jdeveloper.audit.analyzer.Analyzer.


Before Audit begins each traversal, it creates new Analyzers instances, creates and configures new Rule instances, and injects the rules into the analyzers. The @ExtensionResource annotation on the INVALID_FETCH_SIZE field instructs Audit to inject the instance of the Invalid Fetch Size rule into the field. The analyzer will need the instance stored in that field to report an issue.

In this class you can implement validation code for the workspace (application), project, document, and element.  In the traversal, the audit framework will visit the objects in the model as follows:

  • Enter Root
  • Enter Workspace
  • Enter Document
  • Enter Element
  • Exit Element
  • Exit Document
  • Exit Workspace
  • Exit Root

For this example, I don't have any validating to do in the workspace or project methods, so I'll skip down the document method and start there.


In this method I check to see if the first node in the document is "ViewObject" and if the file name ends with VO.xml. If this criteria is not met, then we set the setEnabled() method to false, disabling the audit for this traversal.

When the setEnabled() method is set to False, it stops the traversal from going any deeper into the process.  It will immediately start the return trip in the traversal and call the appropriate Exit methods.

If this method passes, then it continues down into the Enter method for the Element. You do not need to do a setEnabled(true).


Here we check to make sure that the FetchSize element exists and if so, and if it does, we check to see if a value has been set. We do our test to see if the value is greater then 100 and if so, we return the report, adding our parameter that we set in the extension.xml.

If we had created multiple rules in the extension.xml file, and they all defined some kind of audit on a ViewObject, we could do multiple validations here in this method. 

You would need to add an additional @ExtensionRegistry and "private Rule" definition for each rule at the top of the class, and then set the report variable to send out the report to the different rules as needed.

To run your audit, you can click on whichever object you want to run the audit against (Workspace, Project, file) and then click on the Build menu in the main menu bar. At the very bottom of the menu list, you will see "Audit <object>".


You'll notice in the example above, I have the Project selected in the Navigator window, and in the Build menu, it is showing "Audit Audit-Sample.jpr" which will run my audit against all of the files in the project.

To make sure your audit rule will be run, look at the Tools >> Preferences >> Audits >> Profiles dialog and make sure your rule is checked.

Getting Audit Extensions to load in 11gR2

If you are working with 11gR2, you will find that the audit extension will not fully load when you run it.  Looking at Help >> About >> Extensions you will see that your extension has "Triggers loaded" but it never gets to "Fully loaded". This is a result of the lazy loading feature introduced with 11gR2.  To get the extension to load when it's first initialized, we add the following element to the <audit-hook> element.

        <trigger>
          <technology>ADFbc</technology>
        </trigger>

The value for <technology> is a technologyKey and will cause the extension to be loaded when a project is initialized that uses this technology.  For this example, I've set it to ADFbc since I am doing an audit against an ADF application with the ADFbc feature enabled.

Conclusion...

In this post I covered the basics of creating an audit extension that audits and XML file. In Part Two I add a transform (fix) to this same project.

A very special Thank You! to Louis Tribble (Audit Framework master) and Jun Shozaki who spent countless hours traveling the internal roads of the Audit framework, and thankfully documenting them. Without these two developers, this topic would not be written.

As usual...  Comments are always encouraged.  Toss out your experiences and questions for others to learn from. All are welcome.
About

profile image
My name is John 'JB' Brock.
This Blog will focus on tips and tricks for working with the JDeveloper Extension SDK.
I hope to bring clarity to some of the mysteries around developing extensions for JDeveloper.


Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today