Using the 10 Core and 1.1 UI Derby plug-ins
This paper lists the components and functionality of the Derby plug-ins for Eclipse. Also, installation and how to use the plug-ins is discussed. It's helpful to have some knowledge of Eclipse prior to reading this paper, however, the accompanying help for the plugin is sufficient to allow new Eclipse users to succeed in creating a simple application in Eclipse using the Derby plug-ins.
Architecture of the plug-ins
The Derby Core, UI and Help plug-ins are all available in source and binary form.
Listed below are the contents of the most recent versions of the three plug-ins:
|Binary Zip file name||Plugin name||Source location||Contents|
|derby_core_plugin_10.3.1.zip||Derby Core Plug-in, org.apache.derby.core_10.3.1||The Derby Core plug-in can be built when the Derby jar files are built
Follow the instructions in BUILDING.TXT on the Apache Derby: Downloads page, in the How to build Derby section.
|derby.jar, derbytools.jar, derbynet.jar, derbyclient.jar, plugin.xml|
|derby_ui_plugin_1.1.1.zip||Derby UI Plug-in, org.apache.derby.ui_1.1.1||trunk/plugins/eclipse/org.apache.derby.ui||ui.jar, plugin.xml|
|derby_ui_plugin_1.1.1.zip||Derby Plug-in Documentation, org.apache.derby.plugin.doc_1.1.1||trunk/plugins/eclipse/org.apache.derby.plugin.doc||html and image files contained in the topics directory, plugin.xml, toc.xml|
The instructions in this guide assume that you have downloaded these releases. If a more current release is available, download it instead and adjust these instructions accordingly.
After installing the Derby core plug-in the following jar files are present in the Eclipse plug-ins subdirectory of org.apache.derby.core_10.3.x:
- derby.jar, derbytools.jar, derbynet.jar, derbyclient.jar
The functionality of the core plug-in makes available these jar files, and thus the Derby database to Eclipse users, however no menu items or UI additions to the Eclipse environment are available.
After installing the Derby UI plug-in, UI components such as menu items and pop-up windows are available from any Eclipse project which has the Apache Derby nature added to it. After installing the Help plug-in, the Derby plug-in Users Guide is installed in the Eclipse help system. The UI plug-in has the core plug-in as one of its dependencies. In other words, this plug-in will not work, and no menu items will appear if the core plug-in is not already installed. The specific functionality added to the Eclipse environment after the UI plug-in is installed is:
- Add or remove the Derby nature from any Eclipse project
- 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
Installing the plug-ins
Prior to installing the plug-ins Eclipse 3.1M6 or higher must be installed. The current version of the plug-ins have been tested with Eclipse 3.2 GA.
The downloads page at eclipse.org has the Eclipse 3.x SDK downloads.
The binary version of the core plug-in, which does not include the source, is available for download on each Derby release page at downloads.html. Download the derby_core_plugin_10.3.1.zip from the Derby 10.3.1.4 release page. To obtain the source for the UI and documentation plug-ins in the form of an Eclipse PDE (Plug-in Development Environment) project first check out the source at trunk/plugins/eclipse/org.apache.derby.ui for the UI plugin, and trunk/plugins/eclipse/org.apache.derby.plugin.doc for the documentation plugin. See the document Readme.txt for complete instructions on how to build these two plugins from the source.
Note that both the Core and the UI plug-in need to be installed if any UI functionality is required, such as adding the Apache Derby nature, running the Derby network server, etc. is desired.
Unzip the core plugin files into the Eclipse home directory. The location where you installed Eclipse is referred to as ECLIPSE_HOME. For instance, this might be /eclipse in a Linux or Unix environment or C:/eclipse on Windows. Unzip the files to the ECLIPSE_HOME directory. Copy the entire directory from the ui and help file plugin projects into the plugins directory. For instance you should have a a folder called org.apache.derby.ui_1.1.1 and org.apache.derby.plugin.doc_1.1.1 after downloading and creating the plug-in project in Eclipse. Three new subdirectories should now exist under the ECLIPSE_HOME/plugins directory:
Incompatibilities with earlier version of the plug-ins
Earlier versions of the plug-ins, specifically versions of the core plug-in prior to 10.1.1 and version 1.1.1 of the UI plug-in are not supported or any combination of the two.
Uninstalling Previous Versions of the Plug-ins
If you are already using previous versions of the plug-ins, pre 10.1.1 for the Core and pre 1.1.1 for the UI plug-in you may uninstall them or simply install the new versions of the plug-ins on top of them.
Launching Eclipse and Bringing up the Help
If you are new to Eclipse, this section will help you get started in using Eclipse by following the information contained in the Derby Plug-ins User's Guide which is part of the Eclipse Help system. This guide is useful for both novice Eclipse users and experienced users. If you are already familiar with Eclipse, skip this section, but refer to the Help for the plug-ins under Help >> Help Contents >> Derby Plug-ins User Guide. Each task described in this paper is described in detail in this help document.
Launch either eclipse.exe on Windows under the ECLIPSE_HOME directory, or eclipse in Linux or Unix environments under the ECLIPSE_HOME directory. Accept the suggested default workspace called workspace. If this is the first time you have started Eclipse a Welcome window will appear. Close this window.
Now bring up the Help for the Derby plug-ins which contains a tutorial and examples of how to create an Eclipse project, add the Apache Derby nature, and use the other menu items associated with the plug-ins. From the main Eclipse menu at the top select Help >> Help Contents >> Derby Plug-ins User Guide. Expand the Getting Started section in the Derby Plug-ins User Guide and refer to each step to learn how to create an Eclipse project, add the Apache Derby nature and ultimately build a stand-alone application which accesses a Derby database.
Adding the Apache Derby Nature to an Eclipse Project
If you skipped the section above, Launching Eclipse and Bringing up the Help, launch Eclipse now after installing the plugins if you have not already done so. Either create a new project, or open an existing project. The Apache Derby menu item will appear when the project folder is right-clicked.
To add the Apache Derby Nature to a project, right-click it and select Apache Derby >> Add Apache Derby nature.
Adding the Derby nature to your Eclipse project does the following:
Adds the derby.jar, derbynet.jar, derbytools.jar,
derbyclient.jar jar files to the Java Build Path of the project.
Enables the Derby features for the project. Several other menu items now
appear under the Apache Derby menu item.
The ij and sysinfo
tools are now accessible from this menu, and the Apache Derby Network
Server can now be started and stopped using this menu.
- Allows Apache Derby properties such as the port number the Network Server listens on, and the value for derby.system.home to be set for the project.
Follow the Getting Started section in the Plug-in documentation or use the Derby Plug-in Users Guide in the Help to learn how to start the Network Server, use ij and sysinfo and build a Java application which uses Derby.
Last updated: January 4, 2007