Getting started with an Extension

Sue had blogged on how to get an extension started in jdev in 10 steps. In the presentation at OOW, I showed how little code it could take to start an extension and said we'd get a skeleton out of how to start one yourself. Well here's the Skeleton and here's a zip of it. With this skeleton, there's 3 steps to getting started with an extension.

Step 1: Download the zip.

Step 2: Got to [unziped location]/etc and update the contents of the build.properties. Here's the content of the file and the only line that has to be updated is the sdev.home which points to your install of SQL Developer 1.1

build.dir=built

sdev.home=/Users/klrice/Documents/workspace/raptor_trunk/ide

extension.id=sample.skeleton

extension.name=Skeleton Sample

extension.author=Kris Rice

extension.author.url=http://krisrice.blogspot.com

extension.descr=A Skeleton of an extension

update.url=http://esdev.sf.net

Step 3: Run ant deploy

Well it's done and deployed to your local copy of sqldeveloper. Wasn't that easy and painless? :-) Take a look at the Help->About and the Extensions tab will show the name from Step2.

This added 2 things. First an ls command when a script is run ( F5 ). Second a Reconnect on the connection. Here's a screen capture of both.

In case you didn't look in the source of the extension, it adds 2 things. First just like in the OOW presentation I mentioned there's a new hook in the scripting engine which allows custom command to be added. In this case we add ls as a command here. This extends the abstract class CommandListener which has a few methods:

public abstract class CommandListener {

    public abstract boolean handleEvent(Connection conn, ScriptRunnerContext ctx, SQLCommand cmd);

    public abstract void beginEvent(Connection conn, ScriptRunnerContext ctx, SQLCommand cmd);

    public abstract void endEvent(Connection conn, ScriptRunnerContext ctx, SQLCommand cmd);

    public void beginScript(Connection conn, ScriptRunnerContext ctx, SQLCommand[] cmd){
    }

    public  void endScript(Connection conn, ScriptRunnerContext ctx, SQLCommand[] cmd){        
    }
}

}



By implementing and registering a command listener, an extension writer has the ability to add new command and listen in on when commands are run as scripts. Hopefully the names on the methods are pretty simple. The beginScript is before anything is run and endScript is after everything. The other 3 are before each command, after each command and the command itself.

So in this case I only implemented the handleEvent so I could process the ls then finally return a true to say I did something.

public boolean handleEvent(Connection conn, ScriptRunnerContext ctx, SQLCommand cmd) {
   44         ResultSet rs = null;
   45         if (cmd.getSql().equals("ls")) {
....
   68             return true;
   69         }
   70         return false;
   71     }

The second extension for the Reconnect has been explained here and here. What's new in this example is that the xml references a java class: className="sample.ReconnectAction" . This class extends another abstract here :

public abstract class AbstractMenuAction { 
   public abstract void launch(); 
   public abstract void setArgs(String args); 
} 

In this launch, all we did was get a handle to the connection which will cause the framework to reconnect if the connection was dropped and put a status out to the toolbar.

  // get the connection 
  // this will force a reconnect
  getDBObject().getDatabase().getConnection();
  // status basr entry
  Ide.getStatusBar().setText("Reconnected.");

Now that everyone knows how to get started with extension, we should see lots of cool stuff. When you do create an extension drop Sue or myself a note and we'll add it to the list of known extensions.

As some people may know I have a project on sourceforge for a couple examples on what could be created in an extension. The examples I had out there for Excel via Apache's POI project and support for XMLType support are not that useful anymore since the base sqldeveloper 1.1 now has both of those in it. So, I'm in the process of getting a couple other examples out there which will be roughly based on the presentation from OOW.

The first extension I've done is pretty simple but makes the tool look much nicer on OSX by adding Quaqua as a choice for the Look-and-feel. Non-OSX users can also install this extension and get the UI. Also only on OSX, it adds some support for Growl when a connection is opened or when a script is run. The sources for these are in the esdev project in subversion .

To add these in just do a check-for-update and add http://esdev.sourceforge.net/center.xml as a new update center.

For those on OSX this screen with the blocky buttons probably looks quite normal.

After loading the extension, go into the preferences and there's a Look and Feel Combo box. Choose Quaqua and restart.


With Ququa loaded the screen looks much nicer.


The same could be done to load some of the other LAFs out there like napkin mentioned for jdev by Shay.

XML Extension Points ( Context Menus )

To follow up from last week on how to share reports. The same holds true for context menus. The explanation here about how to create the xml to create a menu action is the same. The method to add context menu is the same as reports. Although these menu actions are not (yet) on the exchange, the preferences can still point to any url, so the shared file could reside on a web server.

Also like with the reports there's also an api call to register context menus:

XMLBasedObjectAction.registerContextMenus(URL);

Even though the explaintion is the same and the way to add them is just like reports there are some new things in this area. The first and probably most useful is we have an XML Schema for what these context menus dialogs.xsd. I'll put up the xml schema for the other extension points and I'll be adding annotations to the schema but most of the things in it should be fairly easy to follow.

There are a few areas in this which changed for example now the prompts can be required and have validators for things like checking what the user has entered against the database charset. To make a prompt and have it checked the xml would look something like this:

<prompt required="true" validator="charset">

<label>Table Name</label> </prompt>

These validators must implement a very simple interface which is :

oracle.dbtools.raptor.controls.validators.IValidator

public boolean isValid(String conn,Object o);

public String getMessage();

Then the validator simply need be registered with a call to

ValidatorRegistry.registerValidator(name,class);

Currently the only other one shipping is "numeric" which checks the input to ensure it's a number.

XML Extension Points ( Reports )

Hopefully, some people came to the presentation at openworld. In the presentation I showed how with just XML and "a couple" lines of java the tool can be extended. After getting settled in and the first EA of sqldev out, I got the "couple" lines out so it's now really simple to have things like shared reports, editors, navigator extensions, context menu actions.

I'll do a blog on each of these options. This preference pane now takes the place of some of the command line flag which were being used in 1.0 and adds some new ones.

Now I'm sure everyone knows about the SQL Developer Exchange since Sue mentioned it before. So now let's add the reports everyone has defined in the exchange. In the exchange if you navigate to the My Folders page there's a download link under the list of folder.

Now save the link which the Download leads to and we'll need that in the next step which is to tell SQL Developer where to get the reports. In the preferences there's a Database->User Defined Extensions. After clicking the add row button there's a drop list of type to pick from, for this we'll choose reports. Then just put in the url we copied into the Location. This location can be any url or file location. For example /Users/klrice/reports.xml or on windows Z:\myshared\folder\reports.xml

The preference doesn't yet warn that a restart is needed but it will before it gets stamped production. However, now that you know it needs a restart. Restart SQL Developer. Once it's restarted take a look at the Reports and you should see something that looks quite like the structure from the exchange under shared reports.

Now that my report is listed I can run it and see that I can save some space by issuing the command listed.

While the exchange was used in this example. The same could apply to simply exporting some reports created and hosting the resulting xml file internally or on the public net. For those who will look and I know there's some, I'll explain how the xml in the reports changed in a later blog.

Now the last thing to mention on this is for people who are writing extension there's a java call to register reports also and it's about as easy:

ReportAddin.registerReport(URL);