Home
Mission
Who We Are
FAQs
News
Partners

Community
Getting Involved
Mailing Lists
Case Studies
Online Demos
Working Groups
Community Library
Roadmap
Reference Links
Resources & Events
Bug/Feature Report

Software
Enhydra
Enhydra Enterprise
Downloads
Documentation
CVS Repositories
License

Services & Products
Consulting
Support
Training
Marketing Kit

 

Enhydra Tools
for JBuilder

    Table of Contents

Introduction

This document describes how to use JBuilder to develop Enhydra applications. It assumes a basic understanding of the JBuilder IDE and the Enhydra Application Framework. For information on JBuilder, visit the Borland website. An overview of Enhydra can be found at the Enhydra documentation page. These tools have been developed for the XMLC implementation of presentation objects. While you may use JBuilder to develop JDDI presentation objects, there are currently no wizards for JDDI.

Features:
  • Enhydra Application Wizard
    The application wizard generates an XMLC application allowing you to develop, run and debug your project using Enhydra MultiServer and the XMLC Compiler from within JBuilder.

  • XMLC Compiler Wizard
    The compiler wizard lets you set XMLC options, select HTML files to compile and call the XMLC compiler from with JBuilder.

  • XMLC Sample Project
    This project demonstrates techniques for creating dynamic web pages with XMLC.

System Requirements

The only file the Enhydra Tools for JBuilder requires from Enhydra 2.3 is ennydra.jar. Note that the Enhydra Tools for JBuilder will not work with Enhydra 2.2.1 or earlier versions.

Installing the Tools

Before installing the Enhydra Tools for JBuilder, you need to already have JBuilder 3 and Enhydra 2.3. You can find installation instructions for Enhydra at the Enhydra download page. It is recommended that you go through each step listed on the download page so you can run the Multiserver administration application.  If you install JBuilder prior to installing Enhydra, you can skip the step about downloading Java. You can configure Multiserver to work with the Java 2 files that come with JBuilder. 

Installing on Windows

The jb-kelp.exe file is a self-extracting InstallShield setup program. Before running the installer, close any open instances of JBuilder and note where your JBuilder and Enhydra files reside. You will need to tell the setup program what edition of JBuilder 3 you are running. If you are running the free all Java version, select Foundation. The JBuilder About box includes the name of the edition you are currently running.

The setup program will look up your JBuilder folder in the registry. If you have installed JBuilder in more than one folder, you may need to click on Browse in the Choose JBuilder Folder step to select the location of the JBuilder you want to use with Enhydra. The sample Enhydra project, documentation and tool files will be installed in an jb-kelp folder under the JBuilder folder.

After selecting the JBuilder folder to use for installing the tools, you need to tell the setup program where to look for the enhydra jar files. By default, the setup looks in: 

c:\usr\local\enhydra\lib 

Enter the correct location or use Browse to navigate to where you have installed enhydra.jar. The enhydra.jar file will be added to the JBuilder class path in the JBuilder.ini file. The setup program also creates an Enhydra XMLC library for the jars so you can use them with your JBuilder projects.

The setup program provides you with three types of installations: Typical, Compact and Custom. Typical installs the tools, this documentation and a sample project. Compact installs only the tools. Select the Custom option if you want the Java and C++ open source for the tools.

After selecting the type of installation you want, setup prompts you for the program group folder and lists all your selections for confirmation. When you confirm the settings, the installer will copy files into an jb-kelp folder within the JBuilder folder. It also modifies the library.ini, jbuilder.ini and jbuilder.proeprties files. Some of the modifications will not be reversed if you uninstall the Enhydra Tools for JBuilder. To allow you to restore your original configuration, the setup program creates backup of each the three modified flies and copies the backups to the jb-kelp folder. If you installed the sample project, the setup program also modifies your JBuilder desktop so that the sample project appears the next time you start JBuilder.

Installing on Linux and Solaris

To install the Enhydra Tools for JBuilder on Linux or Solaris, download the jb-kelp.zip file. Unzip this file under your JBuilder installation folder. The zip contains the jb-kelp folder to place within the JBuilder folder. If you have installed JBuilder to /usr/local/jbuilder30, you should end up with the tools installed in /usr/local/jbuilder30/jb-kelp.

After unzipping the file, add the jb-kelp.jar and the enhydra.jar files into the class path that JBuilder uses to startup. The JBuilder startup class path is set in the jbuilder startup script. This script is in the bin directory of your JBuilder folder. The jb-kelp.jar is located the jb-kelp/lib directory. If JBuilder is in /usr/local/jbuilder30, the startup script will be in /usr/local/jbuilder30/bin and the jb-kelp.jar will be in /usr/local/jbuilder30/jb-kelp/lib. Use the enhydra.jar file that is included with Enhydra 2.3. See Setting the IDE Class Path for more information.

You can check to see if you have installed the tools correctly by starting JBuilder and looking for the XMLC Compiler Wizard in the Wizards menu. If the menu does not appear, double check that you have both jars in the IDE class path and that jb-kelp.jar preceeds enhydra.jar.

Configuring the EnhydraSample project

Before using the the Enhydra Sample project (EnhydraSample.jpr), you should move it from the /usr/local/jbuilder30/jb-kelp/sample directory to the jbprojects directory that is located in your home directory.

The html files selected for XMLC are in an html directory rather than in the presentation directory. The DOM classes require a package name of org.enhydra.jbuilder.sample.presentation. To get the correct package name generated, you will need to open the XMLC Compiler Wizard, select the Options tab and click on the Edit button. This opens the mapping table where you can add a new entry that maps the html directory to the correct presentation package. If you copied the sample into a home directory called bob, the mapping would look like this:

Source Folder:
/home/bob/jbproject/sample/org/enhydra/jbuilder/sample/html
Package Name:
org.enhydra.jbuilder.sample.presentation

The sample includes two configuration files that tell Enhydra where to find tings. The first file is the EnhydraSample.conf file. It has a Server.ClassPath[] setting that needs to point to where the compiled class files can be found. For the "bob", example, the classes directory would be /home/bob/myclasses. From JBuilder, you can open up the Project properties dialog and see the required class path listed under Output path.

The EnydraSample.conf also has a AppRoot setting that you need to set to the sample application's root directory. This setting is used by the New Node page to locate the html to insert as a new node. It is also used by the Form page to locate the data property file.

AppRoot = "/home/bob/jbproject/sample/"

Be sure to save any modifications before trying to run the application. MultiServer will ignore any changes that have not been commited to disk.

The multiserver.conf file has a setting for where to find the EnhydraSample.conf file. It also has some settings for logging. The first two settings you need to modify are near the top of the server configuration file. You'll find the third setting near the end of the file. is an example of the settings you would need to edit when running from a /home/bob directory.

Server.ConfDir = /home/bob/jbproject/sample/conf
Server.LogFile = /home/bob/jbproject/sample/log/multiserver.log
Filter.StandardLogger.InitArgs.logFile = /home/bob/jbproject/sample/log/access.log

If cannot run on port 80, you will need to select another port by changing the Connection.HttpConnSample.Port setting in the multiserver.conf file.

The last item you need to change before making or running the sample project is the argument to MultiServer that appears in the StartMultiServer.java program. Here you need to set the argument element to the path of the multiserver.conf file. Following the bob example, the setting would look like:

args[0] = "/home/bob/jbproject/sample/conf/mutliserver.conf";

Setting the IDE Class Path

The Kelp classes are included in both jb-kelp.jar and enhydra.jar. The newer versions are in jb-kelp.jar. Be sure you are running the latest versions of the Kelp classes by placing the jb-kelp.jar file before the enhydra.jar file in the IDE class path.

Note: Earlier versions of Kelp included a jb3enhydra.jar file. If you installed an earlier version, you should delete jb3enhydra.jar and remove it from your IDE class path. The jb3enhyda.jar file was installed into an enhydra/lib directory within your JBuilder directory.

In JBuilder Foundation, the IDE class path is set in JBuilder startup script. The script resides in JBuilder's bin directory. When installed on Windows, the startup script is a batch file and Kelp classes can be set with the tempcp variable.

If you are running one of the Windows only editions of JBuilder 3, you can set the IDE class path through the jbuilder.ini file. The ini file uses the Djava.class.path setting to control the class path. Be sure you shutdown JBuilder before editing the jbuilder.ini file.

The Enhydra Sample Project

The sample project consists of four presentation objects that shows some of the common uses of XMLC. The sample is simplified in that it only contains a presentation layer. Production Enhydra applications will normally contain a least three packages including presentation, business and data. For a detailed explanation on how you can separate applications into these three functional areas, read the Enhydra Architecture White Paper

Each Enhydra page is created through an HTML file and a Java file. The HTML files are located in the sample projects HTML folder. Each HTML file is compiled into a class file using the XMLC Compiler Wizard. There is a corresponding java file that implements HttpPresentation for each HTML file. These files work with the generated HTML classes to create and process input from the web pages. The java files are located in the  com.lutris.jbuilder.sample.presentation package. The four presentation objects consist of the following pages:

  • Greetings Page - This is similar to a traditional Hello World example. This page contains one HTML element that is set through XMLC to greeting the user with a phrase contained in the application configuration file. You can update the configuration file to change the greeting.
  • Table Page - One of the most common tasks for dynamic HTML generation is populating an HTML table. This page shows you how to define a table as a template in HTML and then populate it through Java when a user requests the page. In a real world application, the data would most likely come from an JDBC data source. For the sake of simplicity, this example uses populates the table with an array of values that are hard coded into a Java file.
  • HTML Page - XMLC allows you to add a span containing valid HTML elements to a page. This example shows a page containing a span of HTML that is read in from a text file. You may modify the text file to alter the page without recompiling the HTML or java files.
  • Form Page- You can use XMLC with HTML input fields to create data entry forms. This page shows you how to update a file on the server based on input values from retrieved from a web browser. For simplicity, this example uses a property file to store displayed values. Normally values would be stored in a JDBC data source that would be accessed through the business and data layers of an application.

To run the sample, you will need to first compile the html pages with XMLC. You can do that using the XMLC Compiler Wizard. If port 80 is available, you can start up MultiServer and view the sample pages without modifying any configuration files. If you need to run on another port, you will need to modify the following line in the multiserver.conf file. The configuration file is located in the conf folder of the sample project.

Connection.HttpConnSample.Port = 80

When you modify files within JBuilder, be sure to select File | Save All to commit the file to disk before starting the multiserver. The amplification will ignore any changes made since the last save.  

If you are using a port other than 80, the links within the project HTML file will fail. Add the port you are using to the URL. To use port 8080, enter http://localhost:8080/ as your URL. If localhost fails, try using the IP address 127.0.0.1 in place of localhost.

Using the XMLC Compiler Wizard

The XMLC Compiler Wizard is a JBuilder add-in wizard that can compile HTML files within your project into presentation object using XMLC. From the JBuilder menu, select Wizards | XMLC Compiler Wizard to open the wizard. The wizard is only available when a project is open. 

If you do not see the XMLC Compiler Wizard option on you window menu, make sure that the enhydra.jar and jb-kelp.jar files are listed in the JBuilder IDE class path. This is the class path specified by the jbuilder.ini file. The ini file is located in the JBuilder bin directory. If the files exist as specified in the class path, check the jbuilder.properties file for a line defining the add-in. Although the add-in number may be different, the line should appear similar to the following.

jbuilder.addin.73=com.lutris.jbuilder.wizard.compile.CompileWizard

The wizard is organized into a three tab dialog. The tabs are Pages, Options and Output. The first tab is Pages. This tab displays all the html files in the currently selected project. By default all files are selected except the project HTML file that displays the project name and author. You can use the buttons to add or remove files from the list selected to be compiled. Use the double arrow buttons to add and remove all files from the selection list.

The second tab provides compiler options. By default the XMLC Compiler Wizard uses the current directory name to determine the package name in the generated source. Unless your html files are stored in the same folder as your presentation package Java source files, you will need to use the Mappings option to map the HTML directory to the presentation package name. Since it is recommended that you do not store your HTML files in the same directory as your Java source files, you almost always want to use the Mappings option.

To create mappings, check the Use Package Mapping Table option and click on the Edit button. This will open the map editor that lets you associate source folders with package names. Click on Add Mapping to create a new mapping. You can enter a source folder directory or use the Browse button to navigate to one. In the following dialog shows how to setup the compiler to use the package name com.lutris.jbuilder.sample.presnetaion when compiling html pages stored in the E:\Jbuilder3\enhydra\sample\com\lutris\jbuilder\sample\html folder.

The Output tab is automatically selected when you click on Compile. The Output tab contains a scrollable text area that displays the results of the compile. If you have any errors in your HTML files, the problems will appear on this tab. You can optionally save the output to a text file by checking Output to log file and entering a filename.

The output page displays the files that are created during the compile process. At the start of the compilation process, the wizard will erase any files that it may create during the process. If an HTML file contains a new error, the associated java and class will be erased but not regenerated.

Using the Enhydra Application Wizard

This section describes how to create a new Enhydra epplication with the Enhydra Application Wizard. It also includes a few recommended settings for Enhydra projects. Before you run the Enhydra Application Wizard, you should create a new project for the generated files.

Running the Enhydra Application Wizard while using a project that already contains Enhydra files, may cause unexpected results.

Once you have a opened a new project, select File, New to open JBuilder's Object Gallery. The gallery provides options for quickly generating many common classes. Double click on the Enhydra Application icon to open the wizard. The wizard provides the following four settings to control how your application gets generated.

  • Enhydra Home
    The Enhydra home is the directory where Enhydra is installed. The default for Enhydra 2.3 is /usr/local/enhydra2.3. The wizard needs this information to correctly generate make files.
  • Root to generate new application under
    The wizard will create a new directory to hold application files. The new directory will be in the root directory you specify. You can use the same root for all your Enhydra projects.
  • Name for new application directory to create
    The application name is used as the name of the directory created under the root. It is also used to name the application's top level class and configuration files. The application name must be a valid Java identifier.
  • Package to use in generated classes
    All the generated classes will belong to the package you specify. This must be a single package name. The data, business and presentation packages will be placed within this top level package.

After you have set the options you want, click OK to generate your Enhydra application. After generation is complete, you should view the the newly generated Readme.html file that will be added to your project. The readme contains the steps you need to build and run the application. The steps will very depending on what version of JBuilder you are using.

Setting Project Properties

JBuilder provides many properties for customizing your projects. It is important to configure your projects correctly to work with Enhydra. After opening a project that you want to use with Enhydra, select Project | Properties to configure path, compiler and run settings. Note that you do not need to enter anything in the Servlets tab to work with Enhydra applications.

On the paths page, you'll need to set the root directories and add the Enhydra XMLC library. The Source directory is where the compiler will look for Java files and packages to compile. Packages names start in this directory. If you prefix your packages with com, then the com folder will be located directly under the Source directory. When using package names, all the source files will be in subdirectories under the Source directory. 

The Output directory specifies where you want class files to be created. You should keep the Output separate from the Source to make it the Output directory match what the contents of a production jar file. 

The only required library for Enhydra applications is the Enhydra XMLC library created by the Enhydra Tools for JBuilder setup program. The first time you add this to a project, JBuilder will create dependency files for it. The dependency files help speedup the build process. The Enhydra 2.3 library consists of enhydra.jar. If you are using JDBC in your application, you will also need to add the JDBC driver as a library.

On the Compiler tab, you can check Generate source to output path to keep the generated XMLC java files separate from your HttpPresentation implementations. If you check this option you may get warnings that the compiler cannot locate the source files for your presentation objects. Since the XMLC Compiler Wizard already compiled the presentation objects for you, it is safe to ignore these warnings. You can uncheck the Show warnings option to suppress the warnings.

On the Run/Debug tab, select the Execution Log option under Console I/O. This sends output from your applications to a scrollable window. Before you run something such as a multiserver startup program, you can select View | Execution Log to open the output window.

Debugging Enhydra Applications

The only requirement to debug Enhydra applications from JBuilder is that you start the multiserver from your JBuilder project. The Enhydra Sample Project contains a StartMultiSever class that will lunch Multiserver with the sample application. While it defaults to using configuration files specific to the sample project, you can pass it the location of any mutliserver.conf file. 

To run an Enhydra application you will need two configuration files. One for your application and one for Multiserver. The configuration file for multiserver specifies the location of any application configuration files. A detailed description of Enhydra configuration files is available in the Enhydra Multiserver Administration Guide.

Before you try debugging an application, make sure you can run the Ennydra Sample successfully. If that is working correctly, try stepping through the following procedure to see how easy it is to debug an Enhydra application.

  1. Make sure multiserver is not running.
  2. Open the EnhydraSample project
  3. Select the Table.java file in the com.lutris.jbuilder.sample.presentation package.
  4. Locate the for next loop and click on left edge of the editor to put a breakpoint on the line that reads: table.appendChild(newRow); 
    After setting the breakpoint the line will appear in red.
  5. Select StartMultiServer.java.
  6. From the menu, select Run | Debug. This will start the debugger. Note that the debugger will open an command window even if you have selected Execution Log for console I/O.
  7. Open the table page in your browser. This will trigger the breakpoint as shown below.

  1. From here you can set the value of i to 4 to change how many rows are generated in the table. Note that your browser may time out if you keep the program suspended for too long. 

Working with the Open Source

The XMLC Compiler Wizard consists of the jb-kelpa.jar, winotter.dll and bcjhide.exe. Setup installs the jar file in the jb-kelp/lib folder within your JBuilder directory.  The dll is placed in the JBuilder bin directory and the exe is copied to the Windows directory. If you used the Custom setup option to install the open source, you will have three project files you can use to modify the three components that make up the JBuilder wizard.

The jb-kelp.jpr file contains all the source files required to build the jb-kelp.jar. These classes use Swing and JBuilder's Add-in framework to implement the wizard. To use this file, you will need to create a library called JBuilder classes containing the jbuilder.zip file from the JBuilder lib directory. Documentation for the OpenTools SDK that was used to create the wizard is available with the Professional and Enterprise version of JBuilder.

The bcjhide.bpr is a C++ Builder project for compiling the bcjhide.exe. The wizard uses this file to hide the command window when calling the Borland Java Compiler from XMLC. It works with a bcjhide.ini file that is located in the same directory as the exe.

The winotter.bpr is a C++ Builder project for compiling the java native interface winotter.dll. The wizard calls functions within this dll to navigate through directories and to create bcjhide.ini. A makehead.bat file is included to generate the Native.h header from the Native.java source file.


Copyright 2000 Lutris Technologies, Inc.
All rights reserved.

JBuilder is a trademark of Inprise Corporation.
InstallShield is a registered trademark of InstallShield Corporation.