Sunday, March 21, 2010

FAQ #18 - How to get started with the JDeveloper Extension SDK, Part 3

Introduction

With this part, we will conclude the series of getting started with the JDeveloper Extension SDK. We will wrap up the example extension that we started in part 1 by constructing a custom editor and a custom preferences page for specifying the extension settings. Finally we will package the extension, so that it can be installed in JDeveloper through the Help | Check for Updates... feature. So, let's get to it!

Main Theme

Creating a Custom Editor

A custom editor will allow us to display data associated with an extension action in a customized view. A custom editor for the sample Application Module Verifier action is shown below.


We construct a custom editor by creating an editor class that extends the oracle.ide.editor.Editor abstract class and providing an implementation for the abstract method getGUI(). This method is actually defined in the oracle.ide.view.View class from which the Editor class is inherited. It returns the root graphical user interface component of our custom editor. You may also want to override the getEditorAttribute() method to set the characteristics of the editor such as background color, scroll bars and so on. Below is the getGUI() code for our custom editor:


In the code above we construct a oracle.javatools.ui.TransparentPanel panel called AppModuleVerifierEditorPanel, which contains the custom editor GUI. We do this after we ensure that the URL clicked by the user is related to our action since we can add other verifier actions in the future. We will not go into the details of the AppModuleVerifierEditorPanel GUI but in general it constructs a single JTabbedPane pane - called General (see picture above) - that contains two oracle.javatools.ui.HeaderPanel panels the second of which hosts a JTable table. The specific details can be found in the source code below.

It remains to hook-up the custom editor to our extension action. In order to do this, we need first to declare the custom editor in the extension.xml descriptor inside the <hooks> tag and then activate it. For the first part, add the following code to the extension.xml descriptor:

For the second part, we will invoke the custom editor by calling EditorUtil.openDefaultEditorInFrameExternal() from within the launchEditor() method of the Verifier and pass the URL of the file to view.


Finally, what is left is to generate some data to display. Since our action is related to verifying Application Modules Configurations for ADF applications, we will extract certain data from each Application Module Configuration, such as for example the data source and the locking mode. For this purpose we will use the XMLExtractor class. To build our data model - an output XML file - we will use the XMLBuilder class. Again, the specific details can be found in the source code below.

For more information about constructing a custom editor for your extension, take a look at the CustomEditor example extension, which is part of the samples downloaded along the JDeveloper Extension SDK.


Creating a Preferences Panel

We can create a preferences panel to allow the user to configure our extension via the Tools | Preferences... menu option in JDeveloper. Below is a custom preferences panel that we will add in order to configure our ADF Tools extension:


To begin, we first need to add the persistent data model for our extension preferences. We do this by right-clicking on the extension project in the Application Navigator, selecting New... and from the New Gallery dialog under the Extension Development category Data Model (HashStructureAdapter).


This will bring up the Create Data Model dialog where we can specify our extension configuration class and package.


In the configuration class that is created, we need to add a getter and a setter method for each extension setting that can be configured by the user. For example, since we will allow the user to set the ADF application root folder to be verified, we will add the following code in ADFToolsConfigData to save and retrieve the root folder:


The second step is to actually create the preferences page. We do this via the New Gallery Preferences Page wizard under the Extension Development category:


In the Create Preferences Page dialog we specify the details of the preferences page. It is here where we specify the data model that we created in the previous step:


The preferences page class that is created by the wizard overrides the base class' onEntry() and onExit() methods. We will write the necessary code in these methods to retrieve and save respectively the preferences from the data model. For our sample extension, this is shown below:



The last thing that we need to do is to write the necessary UI code to create the look and feel of the preferences page. For more information about constructing a configuration panel, refer to the ConfigPanel example extension.


Packaging the Extension

Once our extension is complete, we need to package it in a format acceptable for installation by the JDeveloper Check for Updates... feature. We do this by firstly creating a deployment profile in the Project Properties dialog and deploying the extension in a jar archive.


The name of the jar archive must include the extension version. In our example we called the jar archive ADFTools.11.1.1.2.36.55.36.2.jar. The version of the extension can be set in the extension.xml descriptor.


To deploy the extension, right-click on the project in the Application Navigator and select Deploy. Once the extension is deployed, we need to create a bundle.xml extension installation descriptor in order to provide the necessary installation details to JDeveloper. A sample bundle.xml file is shown below:


The bundle.xml must be located in a META-INF directory. Finally, the deployed extension jar archive along with the META-INF folder and its contents - the bundle.xml descriptor - must be packaged into a .zip file. The .zip file finally can be installed via the Check for Updates... feature in JDeveloper.



Conclusion

With this FAQ we conclude our introduction to the JDeveloper Extension SDK. The ability to extend the IDE to integrate tasks specific to our development process is a powerful feature of JDeveloper.

Until the next time, keep on JDeveloping!


Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo18.rar
http://jdeveloperfaq.googlecode.com/files/ADFTools.zip







Sunday, March 14, 2010

FAQ #17 - How to get started with the JDeveloper Extension SDK, Part 2

Introduction

In FAQ #16 - How to get started with the JDeveloper Extension SDK, Part 1 we  talked about the basics of getting started with writing your own JDeveloper extensions. In this FAQ we will expand on that knowledge to cover a few more introductory topics. Specifically we will talk about: 1) how to create a progress bar to indicate a long running action and 2) how to create and utilize a log window specific to your extension.

Main Theme

Creating a Progress Bar

You can use a progress bar in a JDeveloper extension to indicate a long running action. Since our sample ADFTools extension will iterate a base directory looking for Application Module configuration files - for the Application Module Verifier action - this is the ideal place to use it.


For more information, check-out the ProgressBar example extension, part of the extensionssdk workspace downloaded along with the JDeveloper Extension SDK. For more information about downloading the JDeveloper Extension SDK refer to FAQ #16 - How to get started with the JDeveloper Extension SDK, Part 1.

To get started, a progress bar is created by instantiating an oracle.ide.dialogs.ProgressBar class. The constructor for the ProgressBar class is documented as follows on the Oracle Fusion Middleware Java API Reference for Oracle Extension SDK Reference 11g Release 1 (11.1.1) on the web:


The constructor documentation is almost self-explanatory. We need to provide the parent window of the progress bar, its title, a Runnable interface implementation and a true/false indicator of whether the task that is to be executed is determinate or not. Thus our main task becomes the implementation of the Runnable interface. For this purpose we will create a Verifier class that implements the Runnable interface by implementing the abstract run() method. In its run() method we will scan the application's root directory for Application Module configuration files. The code below shows the run() method of the Verifier class.


A few things to consider on the code above:
  • FileScanner is a generic utility class that will scan a specific root directory for a file pattern. This is done by calling its scanForFiles() method.
  • logMessage() is a class method that will log a message in our own custom JDeveloper log window. More on this later.
  • progressbar is a ProgressBar class variable that is passed to the Verifier via the setProgressBar().
  • logLink() is a class method that will log a click-able URL link in the custom log window. Again, more on this later when we will talk about the creation of our extension's log window.

Since the Verifier class can be re-used by other types of verifiers, we will also create a specialized Verifier class called ApplicationModuleVerifier. Now, we can write the plumbing code in the ApplicationModuleVerifierCommand doit() that implements the command. This code is shown below:


A few things of interest on the code above:
  •  ApplicationModuleVerifier is the Verifier-derived class specific for this command action.
  • The ProgressBar is created by specifying the IDE main window - Ide.getMainWindow() - as its parent. We also specify the ApplicationModuleVerifier we just created for its Runnable parameter.
  • We call setCancelable() on the ProgressBar to allow the user to cancel the command processing.
  • We pass the ProgressBar to the ApplicationModuleVerifier by calling its setProgressBar().
  • Finally we start the ProgressBar by calling start(). Command will then be passed to the Verifier run() method.

Creating and Utilizing a Log Window

A log window will allow us to perform log actions specific to our extension. For example, we can clear the logs without interfering with other logs made by JDeveloper.


For more information, check-out the ClickableURL example extension. We can create our own log window by creating a class that extends the oracle.ide.log.MessagePage, instantiate it and call it show() method to display it in JDeveloper. All of these are done inside the ApplicationModuleVerifierCommand's doit() as it is shown below:


Also in the code above observe the following:
  • LogManager.getLogManager().showLog() is called to show the JDeveloper Log pane
  • clearAll() is called on our log window to clear its contents
  • setMessageWindow() is called on the ApplicationModuleVerifier to pass the message pane. It will be used by the verifier to add log entries to the log pane.
Log entries are added to the custom log pane in the Verifier run() by calling the logMessage() and logLink() methods (see image above). The logLink() method is shown below. An oracle.ide.log.Href is instantiated and logged in the custom log pane. When the link is clicked the launchEditor() Verifier method is called to display it in an editor.



This pretty much wraps it up. Build the extension and run it. You should be able to see the progress bar while the action is running. You should also see the custom log window open and a number of log messages and links logged in it.


Conclusion

In this FAQ we've seen how to create a JDeveloper progress bar and a custom log pane - based on the ProgressBar and ClickableURL example extensions respectively. We've also seen how to add the plumbing code in the Command doit() method to create them and display them.

Until the next time, keep on JDeveloping!


Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo17.rar







Sunday, March 7, 2010

FAQ #16 - How to get started with the JDeveloper Extension SDK, Part 1

Introduction

The JDeveloper Extension SDK is a framework of Java classes that allows for the development of third party add-ins (extensions) to the JDeveloper IDE. Pretty much any aspect of the JDeveloper user interface and functionality can be tapped into, from menus and toolbars to wizards and editors. This FAQ will focus on how to get started with the Extension SDK.


Main Theme

Downloading and Installing the Extension SDK

The JDeveloper Extension SDK can be downloaded directly from within JDeveloper via the Check for Updates functionality - under the Help menu - or from the Oracle JDeveloper Extensions Update Center on the web.


Once the Extension SDK is downloaded and installed, JDeveloper upon re-starting will give you the option to install the Extension SDK samples.


Selecting to do so will create and open a workspace with all available extension samples called extensionsdk.




In addition, a number of items related to extension development are installed in the New Gallery dialog.


Building Your First Extension

You can build your first JDeveloper extension by selecting Extension Project from the New Gallery dialog and clicking OK. In the Create Extension Project dialog we need to specify a few things related to extension such as the extension name, identifier and version.



Upon clicking OK on the Create Extension Project dialog, the extension project is created and the extension descriptor extension.xml editor is displayed.


The first thing we need to do is to create an extension Addin. An Addin performs programmatic initialization and registration of the extension. To do this, right-click on the extension project in the Application Navigator and select New... In the New Gallery dialog select Addin under the Extension Development category.


This will bring up the Create Addin dialog where we can specify the addin class name and package.


Click OK to go ahead with the creation of the addin. Observe the addin class that is created by JDeveloper. It implements the Addin Java interface which requires the implementation of the initialize() method. We will come back to the addin initialization later on.

Next we need to create an Action. An Action is an operation that may be invoked by JDeveloper. To do this, right-click on the extension project in the Application Navigator and select New... In the New Gallery dialog select to create an Action under the Extension Development category.


This will bring up the Create Action dialog. In this dialog we will specify a few details related to the action that we are about to create such as the name, identifier and classes of the action.


Go ahead and specify the action details and when done click OK. In this case we will create an ADF Application Module Verifier action. This action will do a number of verifications on the Application Module. JDeveloper proceeds with the creation of the action Command and Controller classes.


Observe the Command class generated by JDeveloper. It extends the Command class and implements the abstract method doit(). It is inside this method where code will be written to implement the action.


Now that we have an action created, we can return to the addin initialize() method and write the necessary code to hook-up the action to the JDeveloper Tools menu. We will create an ADF Tools submenu, add the Application Module Verifier action we just created and add the ADF Tools submenu to the JDeveloper Tools menu. This is shown below.

Now we are ready to test our extension! In the Application Navigator right-click on the extension project and select Run Extension.


This will start a second instance of JDeveloper which will include our extension and will allow us to see our extension in action. Indeed, you should be able to see the extension under the Tools menu.



Conclusion

Developing JDeveloper extensions (addins) becomes fairly easy once you install the Extension SDK and start using the Extension Project, Addin and Action wizards in the New Gallery dialog. Your task becomes writing the plumbing code in the Addin initialize() and in the Action Command doit() methods.

Until the next time, keep on JDeveloping!


Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo16.rar







Related Posts Plugin for WordPress, Blogger...