Using the 10 Core and 1.1 UI Derby 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:

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

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:

• org.apache.derby.core_10.3.1
• org.apache.derby.ui_1.1.1
• org.apache.derby.plugin.doc_1.1.1

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.

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.

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.

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.