Wednesday, 31 January 2007

Where's the cheese? ah, Javadoc?

Ever had this scenario?

You're hellishly coding in JDeveloper, 1001 lines of code in just 2 hours, writing some fancy-pancy JSF backing bean that will solve world poverty, and you need to see the Javadoc for one of the underlying JSF core spec API classes. You highlight the class, press F1, JDeveloper then tells you it's searching a http address, and then, um....., ah....., er...... fails to load the Javadoc, or worse hangs..... for some time....., ah......, ah.....ARGH!.... then finally times-out and returns to your code page after a minute or so.

Poof! So much for programmer productivity and being in the programmer "ZONE".

This is a particular problem for me in JDeveloper when my wireless link slows right down, Sun has blocked my IP for spamming again, I'm on the end of a dial-up line (yes, we still have telephones in Australia) or I've taken my laptop to where (iGod forbids) there isn't actually an internet connection (@ my folks' place who are internet heathens and still use the bush telegraph to talk to their friends).

Q) Ignoring why I would undertake such an insane, harming and self isolating action, why does JDeveloper behave in this manner?

A) Because for the respective JSF API, JDeveloper's distribution doesn't point at a local copy of the API Javadoc, but instead references the online doco at Sun's own website via a URL. If JDeveloper can't connect to the internet, it just doesn't show the doco. If the connection is slow, the IDE interface hangs waiting on a timeout or the page finally downloading.

The obvious fix to this problem is to have copy of the JSF API doco locally and JDeveloper will use it rather than the external source.

To do this you can download the Sun JSF 1.1.01 Reference Implementation from here that JDev requires, and unzip to your favourite directory on your local PC.

Next in JDeveloper, select Tools->Manage Libraries->Libraries tab. If you look down the list of extensions, you'll find one called "JSF".

On selecting the JSF option you can see the Doc Path for this particular library is a Sun URL. Unfortunately none of the buttons are enabled to allow you to change this.

The easiest way to fix this, is to create your own library. Return to the User node at the top of the Libraries tab, then select the New button. This displays the Create Library dialog:

You can then create a new managed library that contains the JSF doco. Give the library whatever name you like, and then under the Doc Path tab, select Add Entry button, and specify the root of the API documentation you unzipped (in this case [install-dir]\jsf-1_1_01\javadocs).

Once you've created the new library you then need to include it in your project. You do this by selecting the project you want the library to be added to. For the JSF program example it would be the ViewController project.

To do this you first select the right-mouse button to show the context menu, select Project Properties, then the Libraries node. The Project Properties dialog under the Libraries node shows you all the Managed Libraries used by this project. To add your library, select the Add Library button, select your new library, and you're right to go.

Now when you press F1 on a core JSF class, the Javadoc will display immediately without hitting the internet for the actual documents. As you can probably guess, there are a number of Managed Libraries in JDeveloper that you can make use of local copies of the API Javadoc instead to keep you in the programmer "ZONE".


Anthea said...

I did all the steps you mentioned but it still did not work. :(

Chris Muir said...

Can you give more detail please? I assume you mean JDev is still heading to the Sun site to download this document? Or did you get an error message? In turn what version of JDev are you using? .... a little more detail of why it didn't work would be useful in me assisting you.


Patrik said...

if you don't want to add and use a user library, then there is another solution. You can edit %JDEV_HOME%/jdev/extensions/oracle.j2ee.10.1.3.jar/META-INF/extensions.xml and change the properties of every library according to your needs.