db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scott hutinger <s-hutin...@wiu.edu>
Subject Re: [VOTE] Accept contribution of Apache Derby UI and Help plugins for Eclipse
Date Mon, 16 May 2005 17:34:09 GMT
vote: +1

It would be nice to include the following:
IBM® DB2® plug-ins for Eclipse, Version 1.0.2 Beta is a tool to browse 
and create Cloudscape™ Version 10.0 (GA) database objects.

But that could be deferred to someone out in the world creating some 
type of visual interface instead :-)

scott

Rajesh Kartha wrote:

> In order to provide the Derby functionality as UI components in Eclipse,
> IBM released the IBM Integration plugin for Derby as a free download.
>
> See: 
> http://www-106.ibm.com/developerworks/db2/library/techarticle/dm-0501cline/ 
>
>
> This 'ui' plugin depends on the existing 'core' Derby plugin and allows a
> seamless integration between Eclipse 3.x and Derby. The core plugin is 
> available
> at the Apache Derby web site on the downloads page.
>
> IBM is now contributing the Integration plugin to the Apache Derby 
> project. A CCLA for this
> contribution was faxed to Apache on May 3.
>
> With regards to this please find attached:
> - a functional spec. This document covers functionality, testing and 
> packaging
> information.
> - a readme.txt that describes setting up the plug-in projects using 
> Eclipse
>
> Following are the links to the source files for both the 'ui' and the 
> 'help' plugins:
>
> http://people.apache.org/~fuzzylogic/org.apache.derby.ui.jar - the 
> source of the 'ui' plugin in jar form
> preserving its Eclipse project directory structure.
>
> http://people.apache.org/~fuzzylogic/org.apache.derby.plugin.doc.jar - 
> the source for the help plugin in jar form.
>
> We are calling for a vote to accept the Derby UI plugin and the Help 
> plugin by the
> end of next week. Our votes +1,+1 (2 votes).
>
> Also, we need to resolve the structure of the source code for this 
> contribution,
> if accepted.
>
> Proposal:
> - Create a new folder called plugins/eclipse under the trunk/ for
> all the plug-in related code to reside.
>
> For example:
> The locations for the above plug-ins would be:
> /trunk/plugins/eclipse/org.apache.derby.ui & 
> /trunk/plugins/eclipse/org.apache.derby.plugin.doc
>
>
> Regards,
> Susan/Rajesh
>
>
> ------------------------------------------------------------------------
>
> ------------------------------------------------------------------------
>
>
>     Apache Derby Plug-ins for Eclipse
>
> ------------------------------------------------------------------------
>
>
>       Contents
>
>    *
>
>
>     * Background and Overview <#overview> Rationale for two plug-ins
>       <#rationale>
>     * Source and Binaries at Apache <#source>
>     * Eclipse Java Build Path <#build_path>
>     * Tools <#tools>
>     * Product layout and versioning <#product_layout>
>     * Comparision with previous plug-ins <#compare>
>     * Testing <#testing>
>     * Documentation <#doc>
>     * TO DO or Questions to Resolve <#items>
>
> ------------------------------------------------------------------------
>
>
>       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
>           o 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
>       <http://cvs.sourceforge.net/viewcvs.py/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 
> <http://incubator.apache.org/derby/derby_downloads.html> 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.
>
>     * Forrest:
>       http://svn.apache.org/viewcvs.cgi/forrest/trunk/tools/eclipse/
>     * WTP:
>       http://www.eclipse.org/webtools/testtutorials/developingwtp/DevelopingWTP.html
>
>     * DBEdit: http://cvs.sourceforge.net/viewcvs.py/dbedit/.
>
> 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://incubator.apache.org/derby/derby_downloads.html, or more 
> frequently if desired, such as when a new milestone of Eclipse is 
> released.
>
>    1. Unzip the plug-ins into the $ECLIPSE_HOME directory. For
>       instance, if Eclipse is installed under /eclipse, unzip the
>       plug-ins into /eclipse.
>
>    2. 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.
>
>    3. 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.
>
>    4. 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.
>
>    5. 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';
>      
>
>    6. 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.
>
>    7. Issue a disconnect and exit from ij. Verify the ij console
>       window terminates.
>
>    8. 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.
>
>    9. 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.
>
>   10. 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.
>
>   11. 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.
>
>   12. 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.
>
>   13. 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.
>
>   14. From the same project the network server was started from, stop
>       the derby network server. Verify it stops.
>
>   15. 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.
>
>   16. 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.
>
>   17. 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.
>
>    1. Determine source code structure for the repository of the UI
>       source.
>    2. 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.
>    3. Modify org.apache.derbyBuild.plugin.DerbyEclipsePlugin.java to
>       add the new derbyclient.jar to the list of jars contained in the
>       core plug-in.
>    4. Provide a second document contained in the new source code
>       structure explaining how to build the UI plugin in the Eclipse
>       environment.
>    5. Provide new documentation for the Apache Web site on how to use
>       the new plug-ins.
>    6. Updating existing documentation on the Apache Web site for the
>       old plug-in.
>    7. Provide the help files for the new plug-in on the Apache Web site.
>
> ------------------------------------------------------------------------
>
> Table of Contents <#toc>
>
>------------------------------------------------------------------------
>
>Readme
>======
>
>Steps for creating the Apache Derby UI Plug-in project:
>
>1) Unjar the contents of the org.apache.derby.ui.jar into a desired location.
>
>   for example: c:\derby\plugin
>  
>2) Install Eclipse 3.x and the JDK needed
>
>3) Install the Apache Derby 10.1.0 Eclipse Core plug-in from:
>   http://incubator.apache.org/derby/derby_downloads.html
>
>   It is available as a zip file:
>
>   for example; derby_core_plugin_10.1.0.165185.zip
>
>   Unzip this file into the directory where the eclipse executable is located.
>   For instance, if Eclipse is installed in C:\eclipse, unzip the Derby
>   Core plug-in zip file to C:\eclipse.
>
>4) Invoke the Eclipse IDE, provide an appropriate location as the workspace
>
>   for example: c:\derby\plugin
>
>5) Import the Apache Derby UI project:
>  File -> Import -> Existing Project into Workspace
>  - Click Next
>  - Click Browse and point to the "org.apache.derby.ui" directory (created in Step 1)
>  - Click Finish
>
>6) Switch to the Plug-in perspective
>   Window -> Open Perspective -> Other -> Select Plug-in Development
>
>7) To invoke and test the Apache Derby UI Plug-in in this development environment
>   
>   Run ->Run As -> Eclipse Application (Eclipse 3.1)
>   OR
>   Run --> Run As --> Run-time Workbench (Eclipse 3.0)
>   
>   An alternate way would be to open the plugin.xml and select the 
>   'Launch a runtime workbench' link.
>
>   This will open a new Eclipse window with all the current plug-ins under development
>   in its environment.
>
>Follow the same steps as above for creating the Help plug-in project.
>


Mime
View raw message