Kelp 1.1

Enhydra Tools
for 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. JDeveloper Kelp is a set of Enhydra tools for Oracle JDeveloper. This document describes how to use Kelp to develop Enhydra applications with XMLC. It assumes a basic understanding of the JDeveloper IDE and the Enhydra Application Framework. For information on Oracle JDeveloper, visit the Oracle 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 Oracle JDeveloper.

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

  • Enhydra Configure Wizard New 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.

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

System Requirements

The only file that 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 Kelp, you need to already have JDeveloper 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 JDeveloper 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 JDeveloper.

Running Setup

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

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

After selecting the JDeveloper directory 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 JDeveloper. The setup program also creates an Enhydra library for the enhydra.jar so you can use Enhydra with your JDeveloper 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 directory and lists all your selections for confirmation. When you confirm the settings, the installer will copy files into a jdev-kelp directory within the JDeveloper directory. It also modifies the JDeveloper 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 jdev-kelp directory.

The jdeveloper.ini file specifies the class path. The ini file is located in the JDeveloper bin directory. The Windows releases also require updates to the jdeveloper.properties file. If you do not see the XMLC Compiler on the JDeveloper Wizard menu, check the jdeveloper.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.

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

You can check to see if you have installed the 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 both jars in the IDE class path and that jdev-kelp.jar precedes enhydra.jar.

Oracle JDeveloper comes bundled with older versions 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 wizard to run succesfully, the setup program will optionally remove the following three Oracle supplied jars from the IDE class path: dacfdtd.zip, jbodt.zip and xmlparserv2.jar. 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.

Setting the IDE Class Path

All the Kelp classes are included in jdev-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 jdev-kelp.jar file before the enhydra.jar file in the IDE class path.

You can set the IDE class path through the jdeveloper.ini file. The ini file uses the code>Djava.class.path setting to control the class path. Be sure you shutdown JDeveloper before editing the jdeveloper.ini file.

Using the Wizards

Kelp provides three wizards to help you develop Enhydra applications from within JDeveloper. 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 JDeveloper 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 JDeveloper 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.

XMLC Compiler Wizard

The XMLC Compiler wizard can compile HTML files into DOM classes. From the JDeveloper 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 jdev-kelp.jar and enhydra.jar files are listed in the JDeveloper 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 directory 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 directorys 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.sample.presentation

when compiling html pages stored in:

C:\Program File\Oracle\JDeveloper\jdev-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.

If you select the Options tab, you can set Make and Output options 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. Keep generated Java source is a read-only option that shows you if the Java files are saved for use by your IDE.

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, select the Make 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 Directory:
C:\Program Files\Oracle\JDeveloper\jdev-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.

You can set if you want the project to use the map table or no. The filename, directory location and the project source path determine the default name. For example, if the you create a new Enhydra Application in...
C:\Program Files\Oracle\JDeveloper\myprojects\MyProject1
...the values for the Welcome.html file will be:

Source path:
C:\Program Files\Oracle\JDeveloper\myprojects\MyProject1

Directory location:
C:\Program Files\Oracle\JDeveloper\myprojects\MyProject1\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:

MyProject1.presentation.WelcomeHTML

Note: If the 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.

When using the package mapping table the package names is 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.

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:

C:\Program Files\Oracle\JDeveloper\jdev-kelp\sample\KelpSample.jpr

...and have a Replace Text table containing:

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

The resulting configuration files (.conf) will contain...
C:\Program Files\Oracle\JDeveloper\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. Select the option to create a StartMultiServer.java file.

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 JDeveloper'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 Kelp Sample Project

Kelp includes a sample project that demonstrates how to use XMLC, MultiServer and configuration templates within JDeveloper. 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 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 JDeveloper, 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 JDeveloper, 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 =
C:\Program Files\Oracle\JDeveloper\jdev-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 =
C:\Program Files\Oracle\JDeveloper\jdev-kelp\sample\output
Server.LogFile =
C:\Program Files\Oracle\JDeveloper\jdev-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 Getting Started with Enhydra.

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

JDeveloper 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 run the XMLC Compiler wizard, 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.

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

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

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

  • 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

Debugging Enhydra Applications

The only requirement to debug Enhydra applications from JDeveloper is that you start the MultiServer from your JDeveloper 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.
  8. 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 Kelp classes are in the jdev-kelp.jar file. Setup installs the jar file in the jdev-kelp/lib directory within your JDeveloper 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 JDeveloper wizard.

The jdev-kelp.jpr file contains all the source files required to build the jdev-kelp.jar. These classes use Swing and JDeveloper'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 Kelp Working Group

The JDeveloper 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.