NetbeansedSQuirreL

In this tutorial, you will convert SQuirreL SQL Client to a NetBeans project and learn how to build, run, debug, profile and perform test-runs of SQuirreL SQL Client in the NetBeans IDE. </span>

Introduction

The SQuirreL SQL client, a Universal SQL Client by Gerd Wagner and Glenn Griffin, provides a simple graphical interface to relational databases. Because it is built using Java, it can access any JDBC-compliant database running on any machine, allowing remote access to multiple databases. A SQuirreL user can: easily view and edit data in any JDBC-compliant database, view the database’s meta-data, work with multiple databases on both local and remote machines, use a single, consistent interface to work with different database engines, and expand the tool’s capabilities and include DB-specific functionality using plugins.
This tutorial shows you how to use the NetBeans IDE for SQuirreL development.

The NetBeans Integrated Development Environment (IDE) is a free, open-source Integrated Development Environment for software developers. The NetBeans IDE provides developers with all the tools they need to create professional cross-platform desktop, enterprise, web, and mobile applications.

In this tutorial, you learn how to convert the SQuirreL project into a NetBeans project to develop, debug, and profile the SQuirreL within the NetBeans IDE.
In the Exercises section, you will use the preconfigured SQuirreL NetBeans project and perform run, debug, test and profile actions. In the Appendix section, you can find detailed steps for creating a SQuirreL NetBeans project from scratch.

For more information on how to work with the NetBeans IDE, see the Support and Docs page.

Software needed

Before you begin, you need to install the following software on your computer: NetBeans IDE 6.0.
Since NetBeans 6.0 is under development now, use NetBeans IDE 6.0 Beta 1 available from NetBeans IDE 6.0 Beta 2 Download, or check the latest working version at http://bits.nbextras.org/netbeans/6.0/nightly/.

Notations used in this Documentation

• <NETBEANS_HOME> - the NetBeans IDE installation directory
• <USER_HOME> - the user's home directory. Example: "C:\Documents and Settings\user_home" for Windows OS.
• <squirrel_root> - the directory with SQuirreL sources

Exercises

Converting SQuirreL to a Netbeans Project

To download the SQuirreL sources:

1. Download the SQuirreL sources from SQuirreL Downloads page: Downloads. In this case SQuirreL is 2.5.1 release squirrel-sql-2.5.1-src.zip.

2. Extract the archive file (in this case, the file name is squirrel-sql-2.5.1-src.zip).
After the SQuirreL archive file is extracted, you will see a subdirectories under <squirrel_root> called sql12. In this case, <squirrel_root> is the C:\work\squirrel\ directory, and after extract the archive file the C:\work\squirrel\sql12 is created.

To create the SQuirreL NetBeans Project:

1. Download the attached nbproject_NetbeansedSQuirreL.zip file, and extract it into the <squirrel_root>/sql12 directory. Now you see <nbproject> directory and build-nb.xml file under the <squirrel_root>/sql12/build directory.
For more details on how the SQuirreL NetBeans project has been created see Appendix.

2. In the IDE, choose Open Project from the main menu and open the SQuirreL project from your <squirrel_root>/sql12 directory.

Now you see the SQuirreL free-form project in the Projects window.

Note: The project will be marked with a red exclamation mark. This means there are some classes and/or jars which NetBeans does not know the path to. If you want to eliminate red exclamation marks, specify the path to classes in the NetBeans IDE. This tutorial does not cover the details of eliminating exclamation marks because they do not break project building, testing, and running.

Running the SQuirreL Project

To run the SQuirreL project files, do the following:

1. In the Projects window, right-click the SQuirreL project node and choose Run from the pop-up menu.

The IDE will compile the SQuirreL source and run SQuirrel.

Testing the SQuirreL Project

To perform testing of the SQuirreL project, do the following:

1. In the Projects window, right-click the SQuirreL project node and choose Build Plugins from the pop-up menu.

This step is required because the SQuirreL's tests need all plugins to be compiled.

2. In the Projects window, right-click the SQuirreL project node and choose Test from the pop-up menu, or press Alt+F6.

A test run of the SQuirreL project is performed and you see test results in the Output window.

Debugging SQuirreL

1. Open the Main.java class from the net.sourceforge.squirrel_sql.client package and set a breakpoint at line 44.

2. Right-click the SQuirreL project node and choose Debug from the pop-up menu.

Note: Because of know Issue you may need to use workaround: - right-click the SQuirreL project node and choose Properties from the pop-up menu; - in the Project Properties window select Output in the Categories list; - remove squirrel-sql.jar from the Output list; - add the squirrel-sql.jar back to the Output list (<squirrel_root>/squirrel-sql-dist/squirrel-sql/core/dist/lib).

The IDE opens the Debugger windows and runs SQuirreL in the debugger until the breakpoint is reached. You can perform Step Into, Step Over, and other debugging activities.
To finish debugging, close the running SQuirreL application or press the Finish button in the toolbar:

For detailed tips on how the Debug action has been made for SQuirreL see the Appendix section.

Profiling SQuirreL using the Netbeans Profiler

1. In the Projects window, right-click the SQuirreL project node and choose Profile from the pop-up menu. If the SQuirreL project is set as main, you can press the Profile Main Project in the toolbar .

2. In the Profile SQuirreL window, accept the default "CPU > Analyze Performance" option and click Run.

3. In the Select Task for Profiling window, select the profile task from the checkbox, and click OK.

The Profiler tab opens in the Netbeans IDE and the Profiler collects information about running SQuirreL.

Appendix

This section describes how to create a NetBeans Project for SQuirreL from the scratch.

After downloading the SQuirreL source and extracting it into <squirrel_root> (see the Converting SQuirreL to a Netbeans Project section for details), do the following:

Creating the SQuirreL NetBeans project

1. Create build-nb.xml file under the <squirrel_root>/sql12/build directory, containing the following:

<?xml version="1.0" encoding="UTF-8"?>
<project name="SQuirreL" basedir="..">
<import file="./build.xml"/>

</project>

This step is required because we do not want to change the original SQuirreL structure, and we do not want to change SQuirreL's build.xml file.
For adding extra Ant targets for the SQuirreL NetBeans project (which are not in the SQuirreL's build.xml, like run, debug, etc.). So we created a new file, build-nb.xml, under the <squirrel_root>/sql12/build directory and will define the extra Ant tasks in this file. For details, see the Adding extra actions for the SQuirreL NetBeans project section.

2. From the main menu, choose File > New Project.
The New Project wizard opens.

3. In the Categories list, select "Java", in the Projects list, select "Java Project with existing ANT Script," and click Next.

4. At the Name and Location page, specify the following values in the fields listed below:

• Location - <squirrel_root>/sql12
• Build Script - <squirrel_root>/sql12/build/build-nb.xml

In this case, the SQuirreL project files are located at C:\work\squirrel\sql12.

Click Next.

5. At the Build and Run Actions page, specify the following Ant targets in the fields listed below:

• Build Project - compile_app
• Clean Project - clean
• Generate Javadoc - javadoc
• Run Project - empty
• Test Project - test

Click Next.

6. At the Source Package Folders page of the wizard, specify <squirrel_root>/sql12/app/src and <squirrel_root>/sql12/fw/src as the source package folders, and <squirrel_root>/sql12/test/src as the test package folder.

Click Next.

7. At the Java Sources Classpath page, add the following items to the Java Sources Classpath list for packages:

For app/src package, add the following files to the Java Sources Classpath list:

• forms.jar under the <squirrel_root>/sql12/app/lib/
• <squirrel_root>/sql12/fw/src
• commons-cli.jar under the <squirrel_root>/sql12/fw/lib
• log4j.jar under the <squirrel_root>/sql12/fw/lib

For fw/src package, add the following files to the Java Sources Classpath list:

• all .jar files under the <squirrel_root>/sql12/fw/lib directory

For test/src package, add the following files to the Java Sources Classpath list:

• all .jar files under the <squirrel_root>/sql12/test/lib
• <squirrel_root>/sql12/app/src
• <squirrel_root>/sql12/fw/src
• hibernate3.jar under <squirrel_root>/sql12/fw/lib/hibernate3.jar

Click Finish.

The Projects window contains the project node for the SQuirreL project you have just created.

8. In the Projects window, right-click the SQuirreL project node and choose Properties.
In the Project Properties window, select Build and Run in the Categories list.
Click Add button to add custom contextual menu item, and set the following values in the fields listed below:

• Label - Build Plugins
• Ant Target - compile_plugins

This step is required for the SQuirrel testing: before running SQuirrel tests we need to compile all plugins.

9. Specify the Output project property.
For the debugging action of the SQuirrel project we need to specify the Output project property. The debug action we will add in the next section.
Before specifying the Output property, do build (right-click the SQuirrel project node and choose Build).
In the Projects window, right-click the SQuirrel project node and select Properties.
In the Project Properties window, select Output in the Categories list and add the following directories to the output list for packages:

• app/src package - the <squirrel_root>/squirrel-sql-dist/squirrel-sql/core/dist/lib directory. In this case it is the C:/work/squirrel/squirrel-sql-dist/squirrel-sql/core/dist/lib/squirrel-sql.jar directory.

• fw/src package - the <squirrel_root>/squirrel-sql-dist/squirrel-sql/core/dist/lib/fw.jar directory

Click OK.

Adding extra actions for the SQuirreL NetBeans project

Standard NetBeans project actions are build, clean, generate javadoc, run, and test. You set some of these actions while creating the SQuirreL NetBeans project in step 5 (see Creating the SQuirreL NetBeans project). Here you will learn how to add run, debug, and profile actions to the SQuirreL NetBeans project.

1. Open the build-nb.xml file in the Editor window of the NetBeans IDE.

Adding the Run action to the SQuirreL project

To add the Run action to the SQuirreL project, you need to modify the build-nb.xml file and add Run action to the project's contextual menu.

1. Add the run Ant task to the build-nb.xml:

...
    <target name="run" depends="compile_app">
        <java fork="true" classname="net.sourceforge.squirrel_sql.client.Main">
            <classpath>
                <fileset dir="../squirrel-sql-dist/squirrel-sql/core/dist/lib" includes="**/*.jar"/>
            </classpath>
        </java>
    </target>
...

This run task runs the SQuirreL application. A dependency is added here because you must compile code before running it. The next section shows how to implicitly use this run task in the debug and profile tasks. To find out which class is the main class, review the SQuirreL code.

2. In the Projects window, right-click the SQuirreL project node and choose Properties.
In the Project Properties window, select Build and Run in the Categories list and set the Run Project combobox value to run.

You can view build-nb.xml in the attached nbproject_NetbeansedSQuirreL.zip file.

Adding the Debug action to the SQuirreL project

To add the Debug action to the SQuirreL project, you need to modify the build-nb.xml file and add Debug action to the project's contextual menu.

1. Add the debug Ant task to the build-nb.xml:

...
    <target name="debug" depends="compile_app">
        <path id="cp">
            <fileset dir="../squirrel-sql-dist/squirrel-sql/core/dist/lib" includes="*.jar"/>
        </path>
        
        <nbjpdastart addressproperty="jpda.address" name="SQuirreL" transport="dt_socket">
            <classpath refid="cp"/>
        </nbjpdastart>
        
        <java fork="true" classname="net.sourceforge.squirrel_sql.client.Main" classpathref="cp" dir="../squirrel-sql-dist/squirrel-sql/core/work/obj">
            <jvmarg value="-Xdebug"/>
            <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
        </java>
    </target>
...

To define the debug task for this project, you need to specify the NetBeans specific task for debugging (<nbjpdastart>) and then run this task (which was done in the previous section) with the mandatory arguments for JVM that were specified in part of build-nb.xml pasted above.

For more information on how to add a debug project action, see Advanced Free-Form Project Configuration tutorial.

2. In the Projects window, right-click the SQuirreL project node and choose Properties.
In the Project Properties window, select Build and Run in the Categories list.
Click Add button to add custom contextual menu item, and set the following values in the fields listed below:

• Label - Debug
• Ant Target - debug

You can find build-nb.xml in the attached nbproject_NetbeansedSQuirreL.zip file.

Adding the Profile action to the SQuirreL project

To add the Profile action to the SQuirreL project, do the following:

1. Add the profile Ant task to the build-nb.xml:

...
    <target name="profile" depends="compile_app">
        <path id="cp">
            <fileset dir="../squirrel-sql-dist/squirrel-sql/core/dist/lib" includes="*.jar"/>
        </path>
        <nbprofiledirect>
            <classpath refid="cp"/>
        </nbprofiledirect>
        <java fork="true" classname="net.sourceforge.squirrel_sql.client.Main">
            <classpath refid="cp"/>
            <jvmarg value="${profiler.info.jvmargs.agent}"/>
        </java>
    </target>
...

To define the profile task for this project, specify a NetBeans-specific task for profiling (<nbprofiledirect>) and then run this task (which was done in the previous section) with the mandatory argument for JVM that were specified in part of build-nb.xml pasted above.

For more information on how to add the profile action, see tutorial.

We do not need to add Profiler contextual menu item because NetBeans Projects already has it.

Explore build-nb.xml in the attached nbproject_NetbeansedSQuirreL.zip file.

Summary

In this tutorial, you learned how to start SQuirreL development in the NetBeans IDE. You have completed the following exercises:

• Convert SQuirreL into Netbeans Project.
• Build SQuirreL in NetBeans IDE.
• Run SQuirreL in NetBeans IDE.
• Test SQuirreL in NetBeans IDE.
• Debug SQuirreL in NetBeans IDE.
• Profile SQuirreL in NetBeans IDE.

See Also

• How to Work with JRuby in the NetBeans IDE
• How to Work with Tomcat in the NetBeans IDE
• How to Work with JEdit in the NetBeans IDE
• How to Work with JUnit in the NetBeans IDE
• How to Work with Ant in the NetBeans IDE
• How to Work with Derby in the NetBeans IDE

References:

• NetBeans IDE 6.0 Preview Documentation: http://www.netbeans.org/kb/60/index.html
• Got issues: http://www.netbeans.org/issues/enter_bug.cgi
• FAQ List: http://wiki.netbeans.org/wiki/view/NetBeansUserFAQ