Font size:

Derby 1.0 UI Plug-in for Eclipse

Derby 1.0 UI Plug-in for Eclipse

Derby 1.0 UI Plug-in for Eclipse

Background and Overview

In its present form the Derby Core plug-in contains only three jar files - derby.jar, derbytools.jar, derbynet.jar. The functionality of the core plug-in makes available these jar files, and thus the Derby database to Eclipse users. Using only this plug-in means manually adding the Derby jar files to the Java Build path in Eclipse. The plug-in is available for download (or to build) at the Apache Derby web site. Note: the core plug-in does not add these jars to an Eclipse user's classpath. They are installed in the Eclipse plug-ins directory, but are not associated with any particular project.

Another set of plug-ins which is currently available as sister plug-ins to the Derby Core plug-in is the IBM Integration plug-in for Derby. These plug-ins contain db2jcc.jar, db2jcc_license_c.jar, ui.jar and the html help files. The db2jcc.jar file contains the IBM DB2 JDBC Universal driver which acts as a client to the Derby Network server.

By installing the IBM Integration plug-ins in addition to the Derby Core plug-in the following functionality is provided:

Ability to configure the Derby network server for each project, including the port number and derby.system.home
All Derby jar files are added to the Java Build Path of an Eclipse project
Run ij and entire SQL scripts from within Eclipse
Start and stop the network server from within Eclipse and track them for each project
Run sysinfo from within Eclipse
Integrated help and tutorial on using the plug-ins.

These plug-ins are available for download as one zip file at the IBM developerWorks web site.

Proposal for new plug-ins with addition of Derby Network Client

With the creation of the Derby Network Client, we are proposing that the Derby Core plug-in and the IBM Integration plug-in be changed into three new plug-ins. The new Derby core plug-in will contain derby.jar, derbytools.jar, derbynet.jar and derbyclient.jar. The new UI plug-in, Derby tools plug-in (this name has not been finalized and is open for discussion), will contain ui.jar and the help plug-in will contain the html help files.

Rationale for separate plug-ins

Current plug-ins

Currently there are two plug-ins required to make use of the Derby tools like ij and sysinfo and to start the Derby network server from within Eclipse. The core plug-in adds the Derby jar files and the IBM Integration plug-in adds the DB2 network client jar files and the UI components to the Eclipse platform.

There are several reasons for having two plug-ins:

Legal requirements
- By using the db2jcc and db2jcc_license_c.jar files we needed to have customers agree to the license agreement prior to downloading the UI plugin. This meant the plug-in had to be hosted at IBM.
The core plug-in can be built at the same time the Derby jar files are built using the ant script available at Apache Derby. By separating the plug-ins the core plug-in can be built from the latest available source at the Derby site. The UI plug-in just contains the DB2 JDBC driver jar files, the UI components which change infrequently.
Plug-ins frequently depend on other plug-ins and require they already be present or that they be installed at the same time. Also, it's part of the design of Eclipse to separate the UI components - the View layer from the Model layer. An example of this can be found at the CVS repository for the DBEdit plug-in.

New plug-ins

We believe it is best to have two plug-ins, a UI and a Core, as this follows the pattern generally adhered to for Eclipse plug-ins. The core functionality is separated from the UI functionality. A third plug-in, the help, would document the functionality associated with the UI plug-in.

Listed below are the scenarios to first build the plug-ins and second, download the plug-ins from the Apache Derby web site.

Source and Binaries at Apache

Presently there is only one plug-in hosted at Apache, the Derby core plug-in. The core plug-in can be downloaded via a web page as a zip file, from the Apache web site downloads page. The source for the existing Derby plug-in can be checked out via SVN and built using the same ant script used to build the derby jar files. The source for the new plug-in should also be able to be checked out, as well as downloaded in its binary form.

Starting with the release of the plug-in that contains the new Derby network client, we would like to propose some changes to the way the source tree holds the new ui plug-in, as well as ways to obtain the binary version of both the core and ui plug-ins. To obtain or update the 'binary' version of the plug-ins an Eclipse Update Manager site would need to exist at the Apache web site. To check out the source to build the ui plug-in will require a new branch off of the trunk directory at the Apache Derby source tree. Additional information about these options are discussed below.

Downloading the binary version of the plug-ins via the Eclipse Update Manager

The most commonly used and efficient way for Eclipse users to download plug-ins is to use the Eclipse Update Manager feature. This tool allows users to point Eclipse to a web site (common http URL) to download a plug-in and any plug-in it depends upon. For instance, if we have two plug-ins we can allow users to download only the core plug-in, or both plug-ins. If they choose to download the UI plug-in they will either have to download the core plug-in, or else Eclipse will check to see if they already have the core plug-in and allow the download to continue.

We know how to do this, all we need is to determine if we want to have an Update Site now, when it is possible the URL for Apache Derby may change in the future. If we change the URL we will have to redirect users to a new URL when it changes.

Obtaining the source for the UI plug-in

We propose creating a new directory/location off the current source tree to get all source files from subversion as an Eclipse plug-in project. Once the source files are imported into the Eclipse workspace as a plug-in project the user would be able to build the plug-in from the source. The html documentation for the help plug-in would be included in this source.

The specific details will be worked out on derby-dev@db.apache.org if the vote accepting this contribution passes.

Some examples of this style of checking out source code suitable to import as an Eclipse project are at the Apache Forrest site, Web Tools Project (Eclipse) and the DBEdit (SourceForge) plugins sites.

Some proposed structures, subject to community approval, for the source tree at Derby could be,

/trunk/tools/eclipse
/trunk/plugins/eclipse

The first option is the way forrest has the source tree for Eclipse plug-ins and the second option is something we thought would be nice if Derby ever had a plug-in for something like the NetBeans IDE. For instance the second structure would lend itself to adding a /trunk/plugins/netbeans directory for the NetBeans IDE and would make the use of the term plugins generic. The idea is to put these options as a vote to the Derby list as well as to ask for other suggestions.

Eclipse Java Build Path

derby.jar, derbynet.jar, derbytools.jar and derbyclient.jar are added to the Eclipse project Java Build Path when the Apache Derby nature is added to the Eclipse project.

Tools

The 'ui' plugin adds the derbytools.jar to the project build/run path, this enables the Derby tools like 'ij' and 'sysinfo' to be run within the Eclipse environment. The ability to run the 'dblook' utility has not been yet been provided.

Product layout and versioning

The Derby core plug-in will contain derby.jar, derbytools.jar, derbynet.jar and derbyclient.jar. The UI plug-in will contain ui.jar and the help plug-in with contain the html help files. The version of the core plug-in will be the version of the Derby release which is offered at the time of release of the plug-in, currently thought to be 10.1.0.0. The version of the UI and help plug-ins will be 1.0.0.

The information contained in the Eclipse help files associated with the plug-in and the sample program have been changed to reflect the new Derby client database connection URL.

Since the core plug-in will now have an addtional jar file contained in it, namely derbyclient.jar, the java class, DerbyEclipsePlugin.java, that creates the plugin.xml file for the existing core plug-in will need to be modified to include derbyclient.jar.

Comparision with previous plug-ins

At this time the functionality between the previous versions of the plug-in and the newer versions will be identical except for any differences due to changes in behaviour of the Derby Client replacing the DB2 Universal Driver client.

Testing

Below is a list of manual testing steps which have been completed at the time of this contribution. The timing of this testing should occur whenever a new binary version of the plug-ins is made available at http://db.apache.org/derby/derby_downloads.html, or more frequently if desired, such as when a new milestone of Eclipse is released.

Unzip the plug-ins into the $ECLIPSE_HOME directory. For instance, if Eclipse is installed under /eclipse, unzip the plug-ins into /eclipse.
Create a simple project in Eclipse and add the Apache Derby nature to the project. Verify the following jar files have been added to the project and the Java Build path of the project contains the following: derby.jar, derbynet.jar, derbyclient.jar, derbytools.jar.
The Java Build path can be verified by right-clicking the project and selecting Properties. Once the Properties window appears select Java Build Path from the left frame, then select the Libraries tab. The Libraries tab should contain all of the jar files mentioned above.
Create a java project in Eclipse and add the Apache Derby nature to the project. Verify the following jar files have been added to the project and the Java Build path of the project contains the following: derby.jar, derbynet.jar, derbyclient.jar, derbytools.jar.
From one of the projects created above, start the derby network server at the default port on the localhost by right-clicking the project, then selecting Apache Derby >> Start Derby Network Server. Verify it starts.
From the project which started the network server, select Apache Derby >> ij (Interactive SQL), from the menu. Verify connection to the network server with a database URL in this format:
```
connect 'jdbc:derby://localhost:1527/myDB;create=true;user=me;password=mine';
```
After the connection is made to the network server via ij, create a table in the myDB database, and verify rows can be inserted into the table.
Issue a disconnect and exit from ij. Verify the ij console window terminates.
From the project which started the network server, create a new file, File >> New >> File, and give it a .sql extension. Enter the following SQL in the file, once the file appears in the editor.
```
connect 'jdbc:derby://localhost:1527/myDB;user=me;password=mine';
create table foo (id integer, name varchar(20));
insert into foo values (1, 'derby');
insert into foo values (2, 'derby plug-ins');
disconnect;
exit;
```
Right click the file just created and select Apache Derby >> Run SQL Script using 'ij'. Verify the script ran correctly, including connecting to the existing myDB database and inserting values into the foo table.
From the same project the network server was started from, stop the derby network server at the default port on the localhost. Verify it stops.
Select a project which has the Apache Derby nature added to it and select the menu item Apache Derby >> sysinfo (Derby System Information). Ensure the Derby Information section includes the following jar files: derby.jar, derbynet.jar, derbyclient.jar and derbytools.jar.
Select a project which has the Apache Derby nature added to it and select the menu item Properties. Verify in the Properties window the Apache Derby item is available in the left hand frame. Select it. Change the value of the Network Server Port to some other available port number (not 1527, the default value), and change the Network Server Host value to the ip address of the host running eclipse. For instance, 9.10.111.11. Change the value of the derby.system.home Derby System Property to a path on the file system. For instance, /eclipse/mynewdir on Unix and Linux, or C:/temp, on Windows. Apply the changes, then click OK.
Select the project just modified above with new values for the network server and derby.system.home settings. Start the Derby Network Server. Verify it starts on the newly set values for host and port.
From the project which started the network server, launch ij (Interactive SQL), from the menu. Verify connection to the network server with a database URL like this:
```
connect 'jdbc:derby://9.10.111.11:9999/differentDB;create=true;user=me;password=mine';
```
Substitute the actual values entered in the Properties window in step 11 above. Verify the database, differentDB, was actually created in the directory for derby.system.home entered in step 11. For instance, either in /eclipse/mynewdir or in C:/temp, there should now be a differentDB directory.
From the same project the network server was started from, stop the derby network server. Verify it stops.
Select a project which has the Apache Derby nature added to it and select the menu item Apache Derby >> Remove Apache Derby nature. Verify the following jar files have been removed from the project and the Java Build path of the project no longer contains the following: derby.jar, derbynet.jar, derbyclient.jar, derbytools.jar.
Verify the Help documentation is installed. Select the menu item Help >> Help Contents >> Derby Plug-ins User Guide. Expand the Getting Started section to see the various topics.
Follow each step, complete all examples and build and run the sample application contained in the Derby Plug-ins User Guide.

Documentation

The html files included with the help plug-in have been updated with the following changes to reflect the changes due to the addition of the derby network client being used to connect to the network server, instead of the DB2 JDBC Driver:

package name
jar file name
database connection URL
screen shots

TO DO or Questions to Resolve

This document has listed a few items which need to be resolved, and others that have not yet been mentioned. These items which need action or further discussion on the derby-dev mailing list are shown below.

Determine source code structure for the repository of the UI source.
Update BUILDING.TXT to include instructions on how to build the core plug-in.
- Presently the instructions on how to build the core plug-in is only referenced in an email. These instructions need to be contained in the source tree.
Modify org.apache.derbyBuild.plugin.DerbyEclipsePlugin.java to add the new derbyclient.jar to the list of jars contained in the core plug-in.
Provide a second document contained in the new source code structure explaining how to build the UI plugin in the Eclipse environment.
Provide new documentation for the Apache Web site on how to use the new plug-ins.
Updating existing documentation on the Apache Web site for the old plug-in.
Provide the help files for the new plug-in on the Apache Web site.