IntroductionKelp 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 a set of 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
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 KelpBefore 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 WindowsThe 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 directory, 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 directory within the JBuilder directory. After selecting the JBuilder 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 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 and lists all your selections for confirmation. When you confirm the settings, the installer will copy files into a jb-kelp directory within the JBuilder directory. 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 directory. 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 SolarisTo 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 directory. 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 PathAll 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.
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 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 WizardsKelp 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 WizardThe 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 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 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:
when compiling html pages stored in:
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 WizardThe 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:
...and have a Replace Text table containing:
Text to find: 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 WizardThis 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.
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 PagesProperty 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 PageIf 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 Directory: 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 PageYou 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: 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:
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 PageThe 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 PageThe 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 ProjectKelp 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 SampleKelp 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
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 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. 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.
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 PagesThe 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
Setting Project PropertiesJBuilder 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.
Debugging Enhydra ApplicationsThe 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.
Working with the Open SourceAll the Kelp classes are in the jb-kelp.jar file. Setup installs the jar file in the jb-kelp/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 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:
borland.public.jbuilder.opentools The Kelp Working GroupThe 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. |