Project Setup

Before we can start developing the invoicing application, we must setup the Java project. In this chapter you will learn to:

• download and install the relevant packages and files,
• configure the IDE,
• setup the project directory,
• prepare the database.

Overview of the Downloads and Resources

If you haven't already done so, please download the JDK and the Netbeans IDE. In principle you can use any other IDE, but some essential steps like the GUI-design will work differently, the Ant build scripts must be modified and you cannot make use of the code-generation plugins for Netbeans. If your favorite IDE isn't Netbeans, this is a great opportunity for a test ride...
The tutorial refers to the JDK 1.6 and Netbeans 6.1.
You don't need to be a Netbeans expert to follow this tutorial. All essentials will be explained. However, setting up the JDK and installing Netbeans is beyond the scope of this tutorial. Please refer to the appropriate documentation.
Furthermore, you need the Tentackle framework and the Wurbelizer, which is a code generator used by Tentackle. Both are Open Source as well.
Optionally, you can install some jars for features like office-integration, jdbc-drivers or additional look-and-feels. Recommended are the JGoodies Look-and-Feel and Apache's POI to generate spreadsheet files from tables.
And, of course, you will need to download the tutorial snapshots.
Here are the links to all relevant download URLs:

1. The current JDK
2. Netbeans IDE
3. Tentackle
4. Tentackle Tutorial
5. Wurbelizer
6. JGoodies Look-and-Feel
7. Apache POI

Which files you need and where to store them in the project directory is covered in the next sections.

Setting up the IDE

Please start the Netbeans-IDE and follow the next steps:

• If you haven't already done so, download the Java SE 6 Documentation and unpack the docs (jdk-6-doc.zip) and the sources (bundled with the JDK as src.zip) to $JAVA_HOME/docs and $JAVA_HOME/src, respectively. In the Netbeans platform manager (Tools -> Java Platforms) make sure that the JDK 1.6 is correctly configured, along with the sources and the docs.
• Download and install the plugins from the Wurbelizer's Netbeans update center as described in Netbeans Update Center (NB ≥ 6.1).
• Create a general download directory (not related to any project!) and add this directory to the Favorites. Open the favorites view (Window -> Favorites), right click somewhere in the empty space of the view and execute Add to favorites. Navigate to the directory and click on Add.
  
• Download the Tentackle framework (three files) into the newly created download directory:
  1. tentackle.jar (the class files)
  2. tentackle_src.jar (the source files)
  3. tentackle_apidoc.zip (the javadocs)
  Unpack the javadocs into a subdirectory.
• Open the Netbeans Library Manager (Tools -> Libraries), create a new library called Tentackle and add tentackle.jar to the Classpath-tab, tentackle_src.jar to the Sources-tab and the unpacked doc directory to the Javadoc-tab.

  

  Note: don't add the javadoc archive as this will cause the Netbeans javadoc system to fail. Use the directory!
• Likewise, download the Wurbelizer and setup the library called Wurbelizer:
  1. wurbelizer.jar (the class files)
  2. wurbelizer_src.jar (the source files)
  3. wurbelizer_apidoc.zip (the javadocs)
• In the same way, download and setup the JGoodies Look-and-Feel (Library name Looks) and Apache POI (library name POI). You can omit the sources and javadocs and just install the class jars.
  Optionally, you may want to download the JDBC-driver for your database backend. For Postgres and MySQL Netbeans already provides preconfigured libraries out-of-the-box.

Important: The spelling of the library names is relevant because the libraries are referenced from within the Ant scripts by their names (for example: the Tentackle library is refenced by the Ant property ${libs.Tentackle.classpath}).

Next, execute Tools -> Palette Manager -> Swing/AWT-Components. Click on New Category and create a palette named Tentackle. Execute Add from Library and select the Tentackle library. All Tentackle beans will be shown and you should select them all (Ctrl-A), like this:

Click on Next, select the previously created palette Tentackle and click on Finish. The Tentackle beans are now availabe within the Matisse GUI-Designer.

In a last step we will install the Tentackle templates. Download tentackle_templates.jar, execute Tools -> Template Manager and create a new folder for the Tentackle templates. The recommended name is Tentackle. Close the template manager. From the favorites view expand tentackle_templates.jar. Select all files, except META-INF. Right click on one of the selected files and execute Save as template....

Select the Tentackle folder and click OK. The templates are now installed.

Setting up the Project Directory

Create an empty project directory of your choice, for example Invoicer. Download and unzip snapshot1.zip into that directory. You should see the following directories and files:

The tutorial is based on a standard Netbeans project-type called Java Application, which has been extended by some Ant-targets for the generation of Java code and sql-scripts. The project contains the following directories and files:

• cg: Holds the extensions for the code generation. Tentackle projects differ from standard projects basically by their additional code generation phase. The Ant tasks and targets are described in codegen.xml while the properties can be found in codegen.properties. Usually, you only have to customize the properties file. The xml-file is included by build.xml, which is the only modification to the standard Netbeans-generated Ant-files. The cg-directory also provides a lib-directory, which holds the jar-files to run the code generation. We will cover that later.
• client: runtime directory for the desktop client. The file Db.properties configures the logical database connection (either 2- or 3-tier) and logging.properties specifies that the logfiles are stored in the subdirectory log.
• db: configuration and sql-scripts for the (various) database backend(s). The platform independent database model will be stored in the subdirectory model.
• nbproject: Netbeans-generated project configuration. Managed by the IDE.
• src: the Java sources. The initial snapshot already contains the empty package directories.
• test: the unit tests.
• build.xml: the Ant build script. This is the Netbeans-generated build script with an extra include for cg/codegen.xml.
• manifest.mf: the manifest for the application's jar-file.

Next, download the Tentackle-wurblets to the download directory, go to cg/lib and make sure that it contains three jars that you downloaded already:

• wurblets.jar: the Tentackle wurblets (small generators anchored within your sources)
• wurbelizer.jar: the Wurbelizer (for executing the wurblets)
• tentackle.jar: the Tentackle framework (necessary during code-generation only for apt-processing of Tentackle-annotations. Covered later in this tutorial)

On Linux- or Unix-Systems it is sufficient to create symbolic links to the jar-files in the download directory. On Windows, you have to copy the files!

Now open the project in Netbeans with File -> Open Project.... The Invoicer-project should open without errors:

In a last step we'll create a shortcut to the code-generation target, which we need frequently later in this tutorial. In the Files-tab expand the file build.xml, scroll down and right-click on the wurbel-target and execute Create Shortcut.... A dialog will open:

Check the first three options and follow the instructions. The recommended keyboard shortcut which is used throughout the rest of this tutorial is Ctrl-Shift-F11. Of course, you are free to choose another one.

Prepare the Database Backend

During the rest of the tutorial, we will refer to MySQL as the database backend. However, you are free to use other databases as well. Tentackle supports the major databases out-of-the-box. Currently supported are:

• Db2
• Ingres
• Informix
• MySQL (≥ 5.0)
• MS-SQL
• Oracle (≥ 9.0)
• Postgres

The database type is easily configured in cg/codegen.properties by setting the property dbtype. Note that this property is only necessary for generating the database-dependent SQL scripts (to create tables or to migrate to an updated data model). It does not affect in any way the Java code or the application at runtime, because Tentackle applications are database agnostic.

Adding support for other databases is possible, but beyond the scope of this tutorial. So you better stick to one of the above.

Please create a database named invoicer and make sure that there is a user with sufficient privileges.

Congratulations! The project has been successfully setup.

... Here we go ...

Notes

• At the time of this writing (may 2008) there is an annoying bug in NB 6.1: in the library manager you can add either java source directory folders or java source archives, for example tentackle_src.jar. However, only archives work reasonably. If you add folders, viewing a source file from a library will not resolve the imports properly. Furthermore, the javadoc-view (Window -> Other -> Javadoc View) will fail.
  Unfortunately, the JDK's javadoc tool cannot handle archives within the -sourcepath option. To generate the javadocs for the invoicer application with all external references, you should edit nbproject/project.properties and change ${libs.Tentackle.src} to a folder holding the unpacked tentackle_src.jar.