Kelp 1.2 (beta 4)

Enhydra Tools
for Borland JBuilder
and Oracle JDeveloper

    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. Kelp 1.2 supports Borland JBuilder and Oracle JDeveloper. This document describes how to use Kelp to develop Enhydra applications with XMLC. It assumes a basic understanding of the Java IDE and the Enhydra Application Framework. For information on JBuilder, visit the Borland website. You can find out more about Oracle JDeveloper at the Oracle website. If you are new to Enhydra, be sure to review the Getting Started Guide that can be found at the Enhydra documentation page.

Features

  • CodeGen Wizards New for 1.2
    The four CodeGen Wizards create simple applicatons that you can build upon to quickly develop web, wireless and presentation object applications.

    • Web Application Wizard
      The web application wizard generates an application using XMLC, the Servlet 2.2 API and XML deployment descripters.

    • Wireless Web Application Wizard
      The wireless web application wizard generates an WAP application using WML, XMLC, the Servlet 2.2 API and XML deployment descripters.

    • PO Application Wizard
      The PO Application wizard generates an web application using XMLC and the Enhydra Presentation Object API.

    • Wireless PO Application Wizard
      The wireless PO application wizard generates an WAP application using WML, XMLC and the Enhydra Presentation Object API.

  • XMLC Compiler Wizard
    The compiler wizard lets you set XMLC options, select HTML and WML files to compile and call the XMLC compiler from within your IDE.

  • XMLC Property Pages*
    The XMLC property pages give you full control over how XMLC builds DOM classes from your HTML and WML files. You can open property page directly from the project navigator's short-cut menu. You set XMLC options on project, package, folder and file nodes.

  • Local Deployment Wizard
    This wizard deploys configuration and deployment descriptor files for testing your application with a local instance of the Enhydra server. The wizard can also set your project run properties so you can easily start the Enhydra server by running the project.

  • Local Deployment Property Pages
    The local deployment property pages let you specify a list of strings to search and replace when generating a configuration files (.conf) from configuration templates (.conf.in). It also takes care of copying policy files and deployment descripters into runtime directories.

  • Build Integration*
    Through property pages, you can setup the IDE to invoke XMLC and the local deployment processes whenever you do a make or rebuild of your project. This lets you quickly ensure your files are updated without having to run a wizard.

  • The Web Application Sample
    These projects demonstrate techniques for creating dynamic content with XMLC and the Servlet 2.2 API.

    • Web Application Project
      The web application project demonstrates using XMLC with the Servlet 2.2 API. It shows how to retrieve values from a deployment descripter, populate HTML tables, insert a block of html into a web page and process data entry forms.

    • Wireless Application Project New for 1.2
      The wireless application project demonstrates retrieving information from a wireless device, creating dynamic content with XMLC and working with multi-card WML pages. You try out this application using an emulator such as the Nokia WAP Toolkit.

  • Enhydra Import Wizard New for 1.2
    The import wizard import files from an existing Enhydra project into a IDE project file. You can use this feature to quickly migrate from a make file driven environment to using Kelp.
* These features are only available when running Kelp within JBuilder.

System Requirements

Kelp 1.2 requires the kelp1.2.jar, enhydra.jar, codegen4.0.jar files to be in the IDE class path. It also requires codegen templates for the CodeGen wizards. The kelp1.2.jar, codegen4.0.jar and templates are supplied with the Kelp install and zip files. Note that Kelp will not work with Enhydra 2.3 or earlier versions.

Installing Kelp

Before installing the Kelp, you need to already have a supported Java IDE 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 Enhydra administration application. If you install your Java IDE prior to installing Enhydra, you can skip the step about downloading Java. You can configure Enhydra to work with the Java 2 files that come with the IDE.

Installing on Windows

The kelp1.2b4.exe file is a self-extracting InstallShield setup program. Before running the installer, close any open instances of the IDE and note where your IDE and Enhydra files reside. You will need to tell the setup program what version of the IDE you are running. Open the IDE's About box to view the version number that you are currently running.

The setup program will look up your Java IDE home directory in the Windows registry. If you have installed more than one supported IDE, you may need to click on Browse in the Choose IDE directory step to select the location of the IDE you want to use with Enhydra. The sample projects, documentation and libraries will be installed in a kelp1.2 directory within the Java IDE's home directory.

After selecting the Java IDE home directory to use for installing, you need to tell the setup program where your Enhydra home directory is located. The setup program will look for a lib directory containing enhydra.jar within your Enhydra home directory. The setup program will check the Windows registry and common locations to determine a default such as: 

c:\usr\local\enhydra3.0

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 the IDE. The setup program also creates an Enhydra library for the Enhydra runtime jar files.

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, templates, documentation and the sample projects. Compact installs only the library and template 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 and lists all your selections for confirmation. When you confirm the settings, the installer will copy files into a kelp1.2 directory within the IDE home directory. The installer also copies the codegen4.0.jar and template files to your Enhydra home directory.

The installer modifies IDE configuration files.. Some of the modifications will not be reversed if you uninstall Kelp. To allow you to restore your original configuration, the setup program creates a backup of each of the modified files and copies the backups to the kelp1.2 directory.

JBuilder 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.

Setting up JDeveloper for Kelp

Kelp 1.2 requires that you run the JDeveloper IDE under Java 2. The Kelp configuration may cause problems when running JDeveloper under JDK 1.1.8.

The jdeveloper.ini file specifies the class path. The jdeveloper.ini file is located in the JDeveloper bin directory. The installer updates the jdeveloper.properties file. If you do not see the XMLC Compiler on the JDeveloper Wizard menu, check the jdeveloper.properties file for lines defining the Kelp wizards. Although the add-in numbers may be different, the lines should appear similar to the following.

jdeveloper.addin.81=
org.enhydra.kelp.jdeveloper.wizard.conf.ConfWizard
jdeveloper.addin.82=
org.enhydra.kelp.jdeveloper.wizard.xmlc.XMLCWizard
jdeveloper.addin.83=
org.enhydra.kelp.jdeveloper.wizard.newapp.EnhydraAppWizard

You can check to see if you have installed the Kelp tools correctly by starting JDeveloper and looking for the XMLC Compiler wizard in the Wizards menu. If the menu does not appear, double check that you have the jbuilder.jar, kelp1.2.jar and enhydra.jar files in the IDE class path.

Oracle JDeveloper comes bundled with an older implementation of the org.wc3.dom classes that are not compatible with XMLC. The enhydra.jar file contains updated org.wc3.dom classes. To allow the XMLC compiler to run succesfully, the setup program places the enhydra.jar at the start of the IDE class path. Under JDK 1.1.8 the enhydra.jar will cause conflicts with the dacfdtd.zip, jbodt.zip and xmlparserv2.jar files. If you need to run JDeveloper under 1.1.8, you should remove those jar files from the IDE class path.. This will disable some of JDeveloper's HTML tag support. If you want to use the HTML tag wizards, you will need to restore the Oracle files back into the IDE class path and remove Kelp.

Installing on Linux and Solaris

  1. Install the Kelp and CodeGen files from the kelp1.2b4.zip download.

    The zip file contains separate directory structures for Kelp and CodeGen. Unzip the kelp1.2b4.zip file into a temporary directory. You can then copy the CodeGen files from the temporary directory into your Enhydra home directory and copy the Kelp files into your JBuilder home directory.

    • Copy the CodeGen templates into your Enhydra home directory.

      The CodeGen templates unzip into enhydra/codegen. If your Enhydra home directory is /usr/local/enhydra3.0, copy the codegen directory into your Enhydra home directory to create the following directory structure:

      /usr/local/enhydra3.0/codegen/en3app
      /usr/local/enhydra3.0/codegen/en3wml
      /usr/local/enhydra3.0/codegen/webapp
      /usr/local/enhydra3.0.codegen/wmlapp
    • Copy the codegen4.0.jar file into a tools/lib directory under Enhydra.

      The codegen4.0.jar file unzips as enhydra/tools_tech/ib/codegen4.0.jar. If your Enhydra home directory is /usr/local/enhydra3.0, copy the jar to:

      /usr/local/enhydra3.0/tools_tech/ib/codegen4.0.jar
    • Copy the Kelp files into your JBuilder home directory.

      The Kelp files unzip to a kelp1.2 directory. If your have JBuilder installed as /usr/local/jbuilder35, copy the Kelp files so you end up with:

      /usr/local/jbuilder35/kelp1.2/doc
      /usr/local/jbuilder35/kelp1.2/lib
      /usr/local/jbuilder35/kelp1.2/samples
      /usr/local/jbuilder35/kelp1.2/src

  2. If you are running Kelp under JBuilder 3.0 or 3.5, locate the kelp1.2/lib directory and delete the kelp1.2.jar and rename the file kelp1.2.jb3 to kelp1.2.jar.

  3. Add enhydra.jar, codegen4.0.jar and kelp1.2.jar to the IDE class path.

    With JBuilder closed, edit the JBuilder.config file to add an addpath statement for each of the three jar files. Also be sure to remove any addpath statements that refer to older versions of Enhydra or Kelp.

    If you have JBuilder installed to /usr/local/jbuilder35 and your Enhydra home directory is /usr/local/enhydra3.0, your addpath statements would be:

    addpath /usr/local/enhydra3.0/lib/enhydra.jar
    addpath /usr/local/enhydra3.0/tools_tech/ib/codegen4.0.jar
    addpath /usr/local/jbuilder35/kelp1.2/lib/kelp1.2.jar
  4. Set the Enhydra home directory within JBuilder.

    The first time you launch CodeGen, you will need to tell it your Enhydra home directory. To do this, start JBuilder and create a new project. With the new project selected, initialize CodeGen by choosing File | New from the menu and double-clicking on any of the wizards on the Enhydra tab. CodeGen will open a Configure Enhydra Home dialog from which you can set the Enhydra home directory.

    CodeGen uses this setting to locate template files. The setting is stored a codegen.properties file within an ".enhydra" subdirectory of your home directory.

  5. Create an Enhydra library to use with your Enhydra projects.

    With a project open, select Project | Project Properties and choose the Required Libraries tab. Use the Add button to see a list of available libraries. If Enhydra appears in the list, edit the library to make sure it is pointing to the latest enhydra.jar file. If you don't have an Enhydra library, choose New and name your new library Enhydra and then choose the enhydra.jar file.

    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 the jbuilder.jar, kelp1.2.jar and enhydra.jar files in the IDE class path.

Setting the IDE Class Path

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/kelp1.2/lib/kelp1.2.jar
addpath /usr/local/enhydra3.0/tools_tech/ib/codegen4.0.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 Oracle JDeveloper, you can set the IDE class path through the jdeveloper.ini file. The ini file uses the code>IDEClassPath setting to control the class path. Be sure you shutdown JDeveloper before editing the jdeveloper.ini file.

Using the Wizards

Kelp provides several wizards to help you develop Enhydra applications from within your IDE. Use one of the CodeGen wizards to create new Enhydra projects from the Object Gallery that appears when you select File | New. You only need to use CodeGen wizards when starting a new project. Once you have a project, you can use the XMLC Compiler and Local Deployment wizards to work with the project.

The XMLC compiler and local deployment wizards are available on the 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 project builder without opening either wizard. The XMLC compiler and local deployment 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 IDE 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 codegen4.0.jar, kelp1.2.jar and enhydra.jar files are in the 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 and wml files in the current 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 wizard. This will call XMLC when you build or make a project node that contains a selected html or wml 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 directory as your presentation package Java source files, you will need to use the Mappings option to map your html/wml resources directory to the presentation package name. The Lutris guidelines recommend that keep your html and wml files in a resources directory and map them to the presentation package when generating the DOM classes. The Kelp Web Application 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 directories with package names. Click on Add Mapping to create a new mapping. You can enter a source directory or use the Set button to navigate to one. In the following dialog shows how to setup the compiler to use the package name:

org.enhydra.kelp.webapp.presentation

when compiling html pages stored in:

(ide home)/kelp1.2/samples/webapp/src/org/enhydra/kelp/webapp/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. Previously generated Java source files are erased prior to regeneration. The XMLC compiler will not create or remove class files.

Local Deployment Wizard

The local deployment 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 and deployment descriptors from templates. The second is to setup your project so you can launch Enhydra with your application.

Configuration templates have the extension conf.in. Deployment descriptor templates have the extension xml.in. Templates are text files with placeholders that are replaced with system specific information by the wizard. One of the default placeholders is @CLASSES@ and it is replaced with the current class output directory specified by your project.

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 Web Application project from:

/usr/home/bob/jbprojects/samples/webapp/KelpWebApp.jpr

...and have a Replace Text table containing:

Text to find: @CLASSES@
Replace with: ./classes

The resulting configuration files (.conf) will contain /usr/home/bob/jbprojects/samples/webapp/classes in place of the @CLASSES@ placeholders that are in each of the templates (.conf.in).

Setting up your project to run Enhydra 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, select the first option to start up Enhydra without the helper class. The option to create a StartMultiServer.java file is only needed when running under Kelp with Oracle JDeveloper..

Using the Web Application Wizard

This section describes how to create a web application with the Web Application wizard. This is one of four CodeGen wizards available on the Enhydra tab of the Object Gallery. The CodeGen wizards use a shared user interface.

This section also includes a few recommended settings for Enhydra projects. Before you run the Web Application wizard, you should create a new project for the generated files.

Once you have a opened a new project, select File | New to open the Object Gallery. The gallery provides options for quickly generating many common classes. Select the Enhydra tab and double click on the Web Application icon to open the wizard. The wizard provides the following settings to control how your application gets generated.

  • Project name
    The project name is used in conjunction with the destination directory to determine where the wizard will generate source files. The default for JBuilder projects is the name of the directory containing the JBuilder project file. If your JBuilder project file is...

    /usr/home/bob/jbproject/untitled1/untitled1.jpr

    ...then the default Project name will be untitled1.

  • Package
    All the generated classes will be at or under the package you specify here. The default package name is derived from the IDE project file name. If your project file is untitled1.jpr, and you use the default package name, the WelcomeServlet will be generated with:

    package untitled1.presentation;

  • Destination
    The destination is the root directory for your projects. The wizard combines the destination directory and the project name to determine where to generate files. If your destination directory is...

    /usr/home/bob/jbproject

    ...and you have a project name of untitled1, the wizard will create all generated files under:

    /usr/home/bob/jbproject/untitled1

    When using JBuilder, the default root is the parent of the directory containing your project file.

    /usr/home/bob/jbproject/untitled1/untitled1.jpr




After you have set the options you want, click Finish to generate your web 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 IDE you are using.

Enhydra Import Wizard

The Enhydra import wizard lets you quickly import source files from an existing Enhydra project into an IDE project file. Here are the steps for importing the Enhydra 3.0 DiscRack example.

Note that the JBuilder project file that comes with Enhydra 3.0 is not compatible with Kelp 1.2. It is recommened that you follow these steps to create a new project for use with Kelp 1.2.

Here are the steps for running the Enhydra 3.0 DiscRack example using Kelp 1.2b4 with JBuilder 3,5. They are broken down into three sections:

  1. Importing and building discRack
  2. Creating the InstantDB database with JDBC Explorer
  3. Configuration and local deployment.
If you already have the database up and running, you can skip section B. If you have the application running outside of JBuilder, you should also be able to skip section C.

  1. Importing and building discRack

    1. Create a new JBuilder project file within:

       <enhydra home>/examples/DiscRack
       

    2. Open the Enhydra Import wizard from the Wizards menu.

    3. Click on Next, Next, Finish to import the project with the following default values:

      Project directory:
       <enhydra home>/examples/DiscRack

      Source directory:
       <enhydra home>/examples/DiscRack

      Resource directory:
       <enhydra home>/examples/DiscRack/resources

      Project root package:
       discRack

      Package Map - Source directory:
       <enhydra home>/examples/DiscRack/discRack/resources

      Package Map - package:
       discRack.presentation

    4. Open the XMLC Compiler wizard and check the Show full paths option.

    5. Add following to the list of selected pages:

 <enhydra home>/examples/DiscRack/presentation/discMgmt/DiscCatalogScript.html

 <enhydra home>/examples/DiscRack/resources/Exit.html

    1. Compile the pages and close XMLC Wizard

    2. From the Paths tab on the project properties page, create and add an InstantDB library to the required libraries.

  1. Creating the InstantDB database with JDBC Explorer

    Note that if you don't have JBuilder Professional, you can use the InstantDB SQLBuilder to execute the SQL commands required to create the tables.

    1. Download and install InstantDB 3.14. It is available from:

      http://instantdb.enhydra.org

    2. Create a <enhydra home>/examples/db directory and copy the sample.prp from the InstantDB Examples directory to the new directory and rename it to discRack.prp.

    3. Add the InstantDB JDBC driver to the IDE class path by editing the JBuilder.config file and inserting an addpath statement.

       addpath c:/idb3_14/classes/idb.jar

    4. Restart JBuilder and open the JDBC Explorer from the tools menu.

    5. Select File | New and select the driver:

       org.enhydra.instantdb.jdbc.idbDriver

    6. Enter the URL pointing to the discRack.prp file created in B.2.

       jdbc:idb:c:/usr/local/enhydra3.0/examples/db/discRack.prp

    7. Apply the changes and open the database leaving the login values blank.

    8. Select the Enter SQL tab and click on the Browse button to select a SQL file.

    9. View all files so you can select and execute the file:

      <enhydrahome>/examples/DiscRack/discRack/data/create_tables.sql.InstantDB

  2. Configuration and local deployment

    1. Open the application configuration template file. This is the discRack.conf.in file that is located in the discRack folder of the newly imported project.

    2. Update the database driver entry to match the driver class used in the current version of InstantDB.

       DatabaseManager.DB.sid1.JdbcDriver =
         "org.enhydra.instantdb.jdbc.idbDriver"

    3. Update the connection URL to match the your discRack.prp file as done in B.6.

       DatabaseManager.DB.sid1.Connection.Url =    "jdbc:idb:c:/usr/local/enhydra3.0/examples/db/discRack.prp"

    4. Save the file to commit your changes.

    5. Use the Local Deployment Wizard to create a new application configuration from your newly modified template.

You should now be able to run the project and then view application in a browser using the URL:

http://localhost:5555/

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.

Note that property pages are currently not supported when running Kelp under Oracle JDeveloper.

The Kelp project property pages add to the IDE'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. The IDE 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 Local Deployment node property page. The XMLC node property page is available on package, folder, wml and html nodes. XMLC options set at the package and folder levels apply to all wml and html files that descend directly from that node.

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. This page include same Compile, Trace and Resource tabs that you can set on the Options tab of the XMLC compiler wizard. The Compile 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 Optionse section lets you select an XMLC Options file and directly enter command line options for XMLC. Refer to the XMLC documentation for a list of command line options you can use with XMLC.

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 Web Application sample project uses a mapping table to map all the html files in a resources directory into the org.enhydra.kelp.webapp.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 Web Application sample project:

Source Directory:
/user/local/jbuilder35/kelp1.2/samples/webapp/src/org/enhydra/kelp/webapp/resources
Package Name:
org.enhydra.kelp.webapp.presentation

The Trace 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 Trace options.

The Resources tab controls where to copy files that you've marked as static resources. You mark files as static resources from the XMLC node property page. By default, the local deployment wizard sets the classes output directory as the document root directory. The resource document root path refers to the source directory that maps to a document root. If you set the root path, the XMLC wizard will copy the directory structure under the set path to the classes output directory along with any files marked as static resources. The wizard will not copy html or wml files that are not marked as static resources.

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 several options including: Copy to output as a static resource, Generate DOM class, Generated class name and XMLC options. Check the Generate DOM class option to select this file for compilation with XMLC. Related 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.

If your application has html files that have no dynamic content you can use the option: Copy to output as a static resource. Check this to have the wizard copy the selected file to the class output directory. The output path for static resources depends on the setting on the Resources tab of the Enhydra XMLC project properties page. From there you can use the package mapping table or set what directory to copy as the servers document root.

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 Web Application in /usr/home/bob/jbprojects/untitled1 the values for the Welcome.html file will be:

Source path: /usr/home/bob/jbprojects/untitled1
Directory location: /usr/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 Local Deployment Project Property Page

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

The Local Deployment Node Property Page

The Local Deployment node property page contains the same settings that appear on the Make tab of the Local Deployment 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 Local Deployment wizard. For more information, refer to the Local Deployment wizard.

The Kelp Web Application Sample

Kelp includes two sample projects that demonstrates how to use use XMLC and Enhydra to create web and wireless applications. If you are new to both Enhydra and Kelp, you can start learning Enhydra by running the Kelp Web Applicatoin sample project. This sample only demonstrates a small part of Enhydra's capabilities. Once you feel comfortable with the Web Application sample, you should examine the DiscRack example that comes with Enhydra. 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.

Deploying the Web Application

Kelp includes the Local Deployment wizard that you can use to automatically configure the Web Application project. Before running the Local Deployment wizard or the sample, be sure to review the steps provided in the readme.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 projects to your home directory before working with it. To do this copy the samples directory from kelp1.2 to a jbprojects directory under your home directory.

If port 9000 is available, you can start up Enhydra and view the sample servlets without modifying the configuration templates. If you need to run on another port, you will need to modify the following line in the servlet.conf.in file. The configuration templates are located in sample project's test/servlet directory.

Connection.p9000.Port = 9000

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

If you are using a port other than 9000, the links within the readme.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 local deployment wizard creates two configuration files from the templates. The first file is the servlet.conf file. Along with the port number, it controls the document root and logging file paths. The servlet.conf.in template has placeholders for path settings. The path settings are set through local deployment wizard.

The local deployment wizard creates the web.xml deployment descriptor using the same placeholder replacement mechanism used to create the servlet.conf file. The web.xml file contains a testDataPath parameter to set where the servlets can text and property files used within the sample.

  <init-param>
    <param-name>
      testDataPath
    </param-name>
    <param-value>
      @CLASSES@/../test/data
    </param-value>
  </init-param>

If you modify any templates (*.conf.in or web.xml.in files), be sure to run the local deployment wizard to regenerate the configuration files and descritors descriptors. Enhydra will ignore any changes made to the templates that have not been deployed.

Enhydra 4 also uses a kernel.conf file to control what services get loaded by the server. This file is not required for Enhydra 3.

The Local Deployment wizard also sets up the sample project so that you can launch the application with the Enhydra server. 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 Servlets

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 web applications will normally contain a least three packages including presentation, business and data. For a detailed explantion on how you can separate applications into these three functional areas, read the Getting Started with Enhydra.

If you have moved a sample project after running Local Deployment wizard, you should run the wizard again before using the sample. See Deploying the Web Application sample for more information.

Each servlet dynamically generates HTML files using XMLC. The HTML source 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 HttpServlet 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.webapp.presentation package. The four servlets demonstrate the following :

  • Greetings Servlet - This is similar to a traditional Hello World example. This servlet contains one HTML element that is set through XMLC to greeting the user with a phrase contained in the Java source.
  • Table Servlet - One of the most common tasks for dynamic HTML generation is populating an HTML table. This servlet 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 Servlet - 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 Servlet- You can use XMLC with HTML input fields to create data entry forms. This servlet 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

Your IDE 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 the default location for the a servlet's document root directory. 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" directory will be located directly under a Source path. The default source path is a src subdirectory under your project directory.

    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, it creates a directory for your project under jbprojects in your home directory set the Source path to a src subdirectory for example:

    /usr/home/bob/jbprojects/untitled1/src

    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. In addition, Enhydra 4, requires additional jars to support services. You can add jars to an application class path by using 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, 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 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 4.0 use: org.enhydra.multiServer.bootstrap.Bootstrap

    For Enhydra 3.01 use: com.lutris.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 Web Application wizard, the application parameters is set to:

    (source directory)/output/servlet/kernel.conf

    Note that Enhydra is passed the kernel.conf and not the servlet.conf file.

Debugging Enhydra Applications

The only requirement to debug Enhydra applications from the IDE is that you start the Enhydra server from your project file. The Kelp Web Application sample 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 project 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 KelpWebApp project.
  3. Select the TableServlet.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

All the Kelp classes are in the kelp1.2.jar file. Setup installs the jar file in the kelp1.2/lib directory within your JBuilder 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 kelp.jpr file contains all the source files required to build the kelp1.2.jar. These classes use JBuilder's OpenTools API and JDevelopers add-in API. To use this file as delivered you will need to create four library files: Enhydra 4.0, CodeGen 4.0, OpenTools SDK, JDeveloper add-in SDK. OpenTools SDK should contain the help.jar, jbuilder.jar and gnuregexp.jar that are available with JBuilder Foundation. To work with the JDeveloper support packages, you will need a JDeveloper add-in SDK containing the jdeveloper.zip file that comes 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.kelp.jbuilder - JBuilder 3.5 support package
org.enhydra.kelp.jdeveloper - Oracle JDeveloper 3 support package

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 Kelp Working Group

The JBuilder Kelp 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. View the mail list archive to get information on recent releases and tips on how to make the most of Kelp. 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.
JDeveloper is a trademark of Oracle Corporation.
InstallShield is a registered trademark of InstallShield Corporation.