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

 

JBuilder Kelp 1.1

The Enhydra Tools
for JBuilder

    Table of Contents

Introduction

Kelp is a set of Enhydra tools that extend a Java IDE to make it easy to create XMLC applications within an integrated development environment. JBuilder Kelp is the Enhydra Tools for JBuilder. This document describes how to use Kelp to develop Enhydra applications with XMLC. 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.

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.

  • Enhydra XMLC Property Pages New for 1.1
    The XMLC property pages give you full control over how XMLC builds DOM classes from your HTML files. You can open property page directly from the project navigator's short-cut menu.

  • Enhydra Configure WizardNew for 1.1
    The configure wizard sets up your project to launch your application with Enhydra MultiServer. It also updates configuration files to match your current environment.

  • Enhydra Configure Property Pages New for 1.1
    The Enhydra Configure property pages let you specify a list of strings to search and replace when generating a configuration files (.conf) from configuration templates (.conf.in).

  • Build Integration New for 1.1
    Through property pages, you can setup JBuilder to invoke XMLC and the Enhydra Configure processes whenever you do a make or rebuild of your JBuilder project. This lets you quickly ensure your files are updated without having to run a wizard.

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

Some features are only available when running in JBuilder 3.5 or JBuilder 3 Foundation. For example, the property pages and integrated build features are not supported under the Windows specific releases of JBuilder 3 Professional or Enterprise.

System Requirements

The only file that JBuilder Kelp 1.1 requires from Enhydra is the enhydra.jar. However, you should install the complete set of Enhydra files so that have access to the complete set of documentation and administration files. Note that Kelp will not work with Enhydra 2.2.1 or earlier versions.

Installing Kelp

Before installing the JBuilder Kelp, you need to already have JBuilder and Enhydra. 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-kelp1.1b1.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 version of JBuilder you are running. Open the JBuilder About box to view what version number that you are currently running.

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

After selecting the JBuilder folder to use for installing, you need to tell the setup program where to look for the enhydra.jar file. The setup program will check the Windows registry and common locations to determine a default such as:

c:\usr\local\Enhydra\enhydra3.0\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 IDE class path that is set when starting JBuilder. The setup program also creates an Enhydra library for the enhydra.jar so you can use Enhydra with your JBuilder projects.

Note: If you have previously installed Kelp with a different enhydra.jar, you may need to modify the IDE class path to ensure that it only contains a single enhydra.jar file. See the section on setting the IDE class path for more information.

The setup program provides you with three types of installations: Typical, Compact and Custom. Typical installs the libraries, documentation and a sample project. Compact installs only the library files. Select the Custom option if you want to install a copy of Kelp's open source code.

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 a jb-kelp folder within the JBuilder folder. It also modifies the JBuilder library, startup and user configuration settings. Some of the modifications will not be reversed if you uninstall Kelp. To allow you to restore your original configuration, the setup program creates backup of each of the modified flies and copies the backups to the jb-kelp folder.

When using the Windows specific releases of JBuilder 3, the jbuilder.ini file specifies the class path. The ini file is located in the JBuilder bin directory. The Windows releases also require updates to the jbuilder.properties file. If you do not see the XMLC Compiler on the JBuilder Wizard menu, 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=org.enhyda.ide.jbuilder.win32.wizard.xmlc.XMLCWizard

JBuilder 3.5 automatically detects and loads addins from the jar files that are listed in the IDE class path. It checks the manifest of each jar in the IDE class path to see if it contains a loadable add-in.

Installing on Linux and Solaris

To install Kelp on Linux or Solaris, download the jb-kelp1.1b1.zip file. Unzip this file within your JBuilder installation directory. The zip contains the library, documentation and sample files within a jb-kelp directory. If you have installed JBuilder to /usr/local/jbuilder35, you should end up with Kelp installed in usr/local/jbuilder35/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 configuration file. This file 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/jbuilder35, the startup configuration file will be in /usr/local/jbuilder35/bin and the jb-kelp.jar will be in /usr/local/jbuilder35/jb-kelp/lib. Use the enhydra.jar file that is included with Enhydra. See Setting the IDE Class Path for more information.

JBuilder 3.5 uses JBuilder.config as the startup configuration file. JBuilder 3.0 uses a shell script to set configuration options. Refer to the JBuilder documentation for more information on adding jars to the IDE class path.

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 precedes enhydra.jar.

Setting the IDE Class Path

All the Kelp classes are included in jb-kelp.jar. They are also included in the Enhydra 2.3 enhydra.jar file. If you are running with Enhydra 2.3, 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: Kelp 1.0 included a jb3enhydra.jar file. If you previously installed Kelp 1.0, 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.

JBuilder 3.5 uses a JBuilder.config file for setting the IDE class path. You can use the addpath setting to add jars to the IDE class path. Here is an example of the lines you need to add the JBuilder.config file to install Kelp.

addpath /usr/local/jbuilder35/jb-kelp/lib/jb-kelp.jar addpath /usr/local/enhydra3.0/lib/enhydra.jar

In JBuilder 3.0 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 code>Djava.class.path setting to control the class path. Be sure you shutdown JBuilder before editing the jbuilder.ini file.

Using the Wizards

Kelp provides three wizards to help you develop Enhydra applications from within JBuilder. Use the Enhydra Application wizard to create new Enhydra projects from the Object Gallery. You only need to use the Enhydra Application wizard when starting new projects. Once you have a project, you can use the XMLC Compiler and Enhydra Configure wizards to work with the project.

The XMLC Compiler and Enhydra Configure wizard available on the JBuilder Wizards menu. These wizards let you invoke Enhydra specific parts of the make system. Using the integrated build feature, you can invoke these same processes directly within the JBuilder project builder without opening either wizard. The XMLC Compiler and Enhydra Configure wizards use a similar interface where you can select files, set options and view the build process using a three-tabbed dialog. The settings on the Options tab are the same as those found on the associated project property pages.

XMLC Compiler Wizard

The XMLC Compiler wizard can compile HTML files into DOM classes. From the JBuilder menu, select Wizards | XMLC Compiler to open the wizard. The wizard is only available when a project is open. If you do not see the XMLC Compiler option on you window menu, make sure that the jb-kelp.jar and enhydra.jar files are listed in the JBuilder IDE class path.

The wizard is organized into a three-tab dialog. The tabs are Selections, Options and Output. The Selections tab displays all the html files in the currently selected project. 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 Options tab displays Make and Output options. You can use the Make options to customize the generated DOM classes. The Output options let you display detailed information during the compile process without effecting the generated classes. The Options tab also has an Invoke XMLC during Project Make/Rebuild. Select this option to call XMLC without opening the XMLC Compiler wizard. This will call XMLC when you build or make a project node that contains a selected html file.

One common make option is to use a mapping table to customize generated class names. 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. The Lutris guidelines recommend that keep your HTML files in a resources directory and map them to the presentation package when generating the DOM classes. Both the Kelp sample project and the Enhydra DiscRack example store HTML files in a resources directory.

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:

org.enhydra.jbuilder.sample.presentation

when compiling html pages stored in:

/usr/local/jbuilder35/jb-kelp/sample/org/enhydra/kelp/sample/resources

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.

Enhydra Configure Wizard

The Enhydra Configure wizard makes it easy quickly configure projects for your current environment and directory structure. The wizard can do two tasks. The first task is to generate configuration files from configuration templates. The second is to setup your project so you can launch your application using MulitServer.

Configuration templates files with the extension conf.in. These files are configuration files with placeholders that are replaced with system specific information by the wizard. The default placeholder is @OUTPUT@ and it is replaced with the absolute path of your current output directory. While you do not need to use configuration templates for the Enhydra applications you develop, it is recommended as a way to quickly adapt your applications to different environments.

You can customize the search and replace mechanism by editing Replace Text table on the Options tab of the wizard. The default option lets you quickly restore the default project settings. The replace with values can refer to relative paths. If you enter a value starting with a period, the wizard will substitute the directory containing the project file for the period. For example, if you open the Kelp sample project from:

/usr/home/bob/jbprojects/sample/KelpSample.jpr

...and have a Replace Text table containing:

Text to find: @OUTPUT@
Replace with: ./output

The resulting configuration files (.conf) will contain /usr/home/bob/projects/sample/output in place of the @OUTPUT@ placeholders that are in each of the templates (.conf.in).

Setting up your project to run MultiServer can be done by setting the main class for the project to run or by creating a StartMultiServer.java helper class. If you are running JBuilder 3.5, select the first option to start up the MultiServer without the helper class. The option to create a StartMultiServer.java file is only needed when running under the Windows specific versions of JBuilder 3.

Using the Enhydra Application Wizard

This section describes how to create a new Enhydra application 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 3.0 is /usr/local/enhydra3.0. 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 newly generated Readme.html file that will be added to your project. The Readme.html shows the steps you need to build and run the application. The steps will very depending on what version of JBuilder you are using.

Using the Property Pages

Property pages are dialogs where you set build options for the entire project or for a selected node. Project property pages appear as tabs in the Project Properties dialog. Node property pages let you customize options for a specific file in your project.

The Kelp project property pages add to JBuilder's existing Code Style, Paths, Run and Compiler property pages. The Paths property page is where you set what library files your project requires. From the menu, select Project | Project Properties to open the Project Properties dialog.

To open a node property page, right-click on a file in your project and select Properties from the short-cut menu. JBuilder will open a property page specific to the file you've selected. If you right-clicked on a Java source file, the property page will have RMI and JNI settings. Right-click on a file with a conf.in extension to open the Enhydra Configure node property page. The XMLC node property page displays for html files.

The XMLC Project Property Page

If you open the Project properties dialog and select the Enhydra XMLC tab, you will see the XMLC project properties page. The page shows the same Make and an Output options that you can set on the Options tab of the XMLC Compiler wizard. The Make tab includes three sections. The section for Generated Java Source informs you of what XMLC options need to be set for the current IDE. The Mappings section determines how to generate class names while the XMLC Option File section lets you select an XMLC Options file to set XMLC command line options. Refer to the XMLC documentation for a list of command line options you can use in an XMLC options file.

Within the Mappings section, you can define a mapping table and set what nodes to use with the table. The mapping table lets you specify package names to use when generated DOM classes for a given directory. For example, the Kelp sample project uses a mapping table to map all the html files in a resources directory into the org.enhydra.kelp.sample.presentation package.

To view or edit the package name mapping, 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 a directory to the correct presentation package. Here is an example mapping for the Kelp sample project:

Source Folder:
/user/local/jbuilder35/jb-kelp/sample/org/enhydra/kelp/sample/resources
Package Name:
org.enhydra.kelp.sample.presentation

The Output settings do not effect the generated DOM classes. These settings cause the XMLC to stream out additional information when compiling the html files. For faster compiles, you should deselect all the Output options.

The XMLC Node Property Page

You can open the XMLC node property page by right clicking on an html file and selecting properties from the short-cut menu. This page has for options: Generate DOM class, Keep generated Java source, Generated class name and XMLC option file. Check the Generate DOM class option to select this file for compilation with XMLC. The other options are only available when Generate DOM class is checked. Keep generated Java source is a read-only option that shows you if the Java files are saved for use by your IDE.

You can use the Generated class name section to select how to generate the class name. There are three choices. The filename, directory location and the project source path determine the default name. For example, if the you create a new Enhydra Application in /home/bob/jbprojects/untitled1 the values for the Welcome.html file will be:

Source path: /home/bob/jbprojects/untitled1
Directory location: /home/bob/jbprojects/untitled1/untitled1/presentation Filename: Welcome.html

The source path is removed from the directory location to create the new package name. The new class name is formed by removing the ".html" extension and adding "HTML". So the resulting default class name for Welcome.html becomes:

untitled1.presentation.WelcomeHTML

Note: If the selected HTML file is not located in a subdirectory of one of the Project source path settings, Kelp may not be able to generate a valid default class name.

Select the Custom option to enter your own class name. When using custom, be sure anything you enter conforms to a valid Java identifier.

The Mapped options uses the package mapping table to set custom package names based on the directory of the HTML file. This is normally used to map a resources directory to a presentation package. There is only one mapping table per project. For more information, refer to the XMLC project property page and XMLC Compiler wizard sections.

The Enhydra Configure Project Property Page

The Enhydra Configure project property page contains the same settings that appear on the Options tab of the Enhydra Configure wizard. There are two tabs: Make and Startup. For more information, refer to the Enhydra Configure wizard.

The Enhydra Configure Node Property Page

The Enhydra Configure node property page contains the same settings that appear on the Make tab of the Enhydra Configure project properties page. In addition to the project properties, there is a Generate .conf checkbox that you can select to a generate configuration file for the current template. Selecting the checkbox is the same as selecting the file in the Enhydra Configure wizard. For more information, refer to the Enhydra Configure wizard.

The Kelp Sample Project

Kelp includes a sample project that demonstrates how to use XMLC, MultiServer and configuration templates within JBuilder. If you are new to both Enhydra and Kelp, you can start learning Enhydra by running the Kelp sample application. The Kelp sample only demonstrates a small part of Enhydra's capabilities. Once you feel comfortable with the Kelp sample, you should examine the DiscRack example that comes with Enhydra 3.0. The DiscRack example provides a more complete application that incorporates JDBC access. You can run the DiscRack example using most JDBC compliant data sources including Oracle, Microsoft SQL Server and InstantDB. If you are already familiar with Enhydra, you can use this project to see how you can setup a project for your own applications.

Configuring the Sample

Kelp includes the Enhydra Configure wizard that you can use to automatically configure the Kelp sample project. Before running the Enhydra Configure wizard or the Kelp sample, be sure to review the steps provided in the KelpSample.html file that is included with the project.

If you are running under Linux or Solaris and you do not have root privileges, you may need to copy the Kelp sample project to your home directory before working with it. To do this copy the sample directory from jb-kelp to a jbprojects directory under your home directory.

If port 9000 is available, you can start up MultiServer and view the sample pages without modifying the configuration templates. If you need to run on another port, you will need to modify the following line in the multiserver.conf.in file. The configuration templates are located in sample project's org/enhydra/kelp/sample directory.

Connection.HttpConnSample.Port = 9000

When you modify files within JBuilder, be sure to select File | Save All to commit the file to disk before running the Enhydra Configure wizard. The wizard may ignore changes made since the last save.

If you are using a port other than 9000, the links within the KelpSample.html 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.

The Enhydra Configure wizard creates two configuration files from the templates. The first file is the KelpSample.conf file. It has a Server.ClassPath[] setting that needs to point to where the compiled class files can be found. From JBuilder, you can open up the Project properties dialog, select the Paths tab and see the required class path listed as the Output path.

The KelpSample.conf also has a AppRoot setting that the Enhydra Configure wizard sets 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 = /user/local/jbuilder35/jb-kelp/sample/output/..

If you modify the configuration templates (conf.in files), be sure to run the Enhydra Configure wizard to regenerate the configuration files in the output directory. MultiServer will ignore any changes made to the templates that have not been regenerated as conf files in the output directory.

The multiserver.conf file has a setting for where to find the KelpSample.conf file. It also has some settings for logging. You can find the first two settings near the top of the multiserver.conf file.

Server.ConfDir = /user/local/jbuilder35/jb-kelp/sample/output
Server.LogFile =
/user/local/jbuilder35/jb-kelp/sample/output/multiserver.log

You'll find the additional logging filter setting near the end of the multiserver.conf file. If you want to take advantage of additional logging features, update these settings in the configuration template to match the version of Enhydra you are using.

The Enhydra Configure wizard also sets up the sample project so that you can launch the application with MultiServer. It does this by setting the project's main run class or by generating a StartMultiServer.java program. In either case, the wizard sets the multiserver.conf file as a parameter to the MultiServer.

The Sample Pages

The sample project consists of four presentation objects that show 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 (PDF, 18 pages).

If you have moved the Kelp sample after running Enhydra Configure wizard, you should run the wizard again before using the sample. See Configuring the Kelp sample project for more information.

Each Enhydra page is created through an HTML file and a Java file. The HTML files are located in a resources directory. 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 org.enhydra.kelp.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.
  • New Node Page - XMLC allows you to insert HTML blocks from external sources into an existing 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.

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. Most of the settings, you will need to work with are found on the Paths page.

  • Paths: Output path

    Output directory specifies where you want class files to be created. This is also where MultiServer will look for images that have relative references to the presentation objects. For example, the new Enhydra Application wizard creates images under:
    (source directory)/(package directory)/presentation/media

    When you build the project inside of JBuilder, the image is copied to output directory along with the compiled class files. In order for the image to display properly the output directory must be set to a classes subdirectory under the source directory.

    If you have JBuilder Foundation, you can use the jar command line utility that is include with the JDK to create a jar from the contents of the output directory. The Professional and Enterprise versions of JBuilder include a wizard for helping you build jar files from the IDE.

  • Paths: Source

    The Source path is where the compiler will look for Java files and packages to compile. When using package names, the source files will be in subdirectories under the Source directory. For example, if your highest-level package is "com", then the "com" folder will be located directly under a Source path.

    You can set the Source path to the same location as the project file. When you create a project using the Project wizard in JBuilder Foundation, it creates a directory for your project under jbprojects in your home directory. You can use this same directory as your source.

    JBuilder allows you to set multiple source paths. This can be useful when you are working on several modules from the Enhydra source code. If you have checked out the Enhydra source code from cvs, you'll see that it is divided into several modules. Each module contains its own source directory. You should remove any source paths that your project does not require.

  • Paths: Required Libraries

    Enhydra applications require that the enhydra.jar be in their class path. You can add jars to an application class path by using JBuilder libraries. If you installed Kelp using the Windows installer, you will already have an Enhydra library defined for you. If you are using JDBC in your application, you will also need to add the JDBC driver as a library.

    If you need to define an Enhydra library in JBuilder Foundation, use the Add button under libraries, and select New. You can then give your library a name and add the enhydra.jar file through the Add button on the class tab.

  • Compiler: Generate source to output path

    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 pick this option the Java source files for the DOM classes will be created in a Generated Source directory under your output classes directory

  • Run: Main class

    JBuilder Foundation lets you specify the class to run when you run the project. This class does not need to be part of your project's source files.

    If you have an Enhydra library selected under Required Libraries, you can use the Main class to launch Enhydra MultiServer. Use the Set button to select the MultiServer startup class.

    For Enhydra 3.0 use: com.lutris.multiServer.MultiServer

    For Enhydra 2.3 use: com.lutris.servlet.multiServer.MultiServer

  • Run: Application Parameters

    If you have set the Main class to launch MultiServer, you can use the application parameters to pass in a configuration file. For example, if you create an application using the Enhydra Application wizard, the application parameters is set to:

    (source directory)/output/multiserver.conf

    Note that MultiServer is passed the multiserver.conf and not the application specific conf file. If you are using an application specific conf file, you can specify it using the application.(application name).ConfFile setting in multiserver.conf.

  • Run/Debug: Execution Log

    In the Windows specific release of JBuilder 3, you can select the Execution Log option under Console I/O. This is on a combined Run and Debug tab. This option 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. In JBuilder Foundation, output is sent to a scrollable pane at the bottom of the IDE work area.

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 multiserver.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 (PDF, 57 pages)..

Before you try debugging an application, make sure you can run the Kelp 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 already running.
  2. Open the Kelp Sample project.
  3. Select the Table.java file in the org.enhydra.kelp.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-kelp.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 Addin Jars containing the pthelp3.1.jar, jbuilder.jar, jbuilder.zip and jdeveloper.zip. The pthelp3.1.jar and jbuilder.jar files are available with of JBuilder Foundation. The jbuilder.zip file is available with the Windows specific releases of JBuilder 3. The jdeveloper.zip file is available with Oracle JDeveloper 3.

To work with a single IDE such as JBuilder Foundation, you can leave out the unrelated library files and remove the appropriate packages from the project. The IDE specific packages are as follows:

org.enhydra.ide.jbuilder.primetime - Java based JBuilder
org.enhydra.ide.jbuilder.win32 - Windows specific JBuilder 3
org.enhydra.ide.jbuilder.jdeveloper - Oracle JDevleoper 3

Visit the following news groups for information about the developing addins and using the JBuilder OpenTools API:

borland.public.jbuilder.opentools
borland.public.jbuilder.thirdpartytools

The bchide.exe and winotter.dll files are only used when running Kelp with a Windows specific release of JBuilder 3. If you are working with an all Java release of JBuilder, you can ignore the bcjhide.brp and winotter.bpr projects.

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.

The Kelp Working Group

The Enhydra Tools for JBuilder is part of Enhydra Kelp family of products. The Kelp Working Group is dedicated to making Enhydra technologies easier to use through the use of Java IDE add-ons.

The working group has a mail list that use can use to post questions or suggestions for this or other Kelp products. You can also use the Kelp Working Group to contribute to the Kelp open source project.


Copyright 2000 Lutris Technologies, Inc.
All rights reserved.

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