Kelp Add-in Documentation


 

Release 2.1

Kelp Add-ins
for Borland JBuilder
and Oracle JDeveloper

    Table of Contents

Introduction

This document describes the how to use the IDE add-ins that are available as part of the open source Enhydra Kelp project. If you are working with a commercial release of Kelp such as the one bundled with the Lutris Enhydra product, you may have additional documentation or features that are not described here. You will find the latest version of this document at the Enhydra Kelp project web site along with FAQs and information on checking out the source from the CVS repository. For information on building Kelp, refer to the README.BUILD that is included in the root of the Kelp project source tree.

Kelp provides IDE add-ins to make it easy to use the Enhydra XML Compiler (XMLC) and the Enhydra application server within an integrated development environment. Kelp 2.1 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 at least one of the web programming models: servlet 2.2 web applications or Enhydra super-servlet applications. For information on JBuilder, visit the Borland website. You can find out more about Oracle JDeveloper from the Oracle Technology Network. If you are new to Enhydra, be sure to review the Getting Started Guide that can be found at the Lutris Enhydra documentation donations page.

Features
  • Application Wizards
    The two Application wizards create simple applications that you can build upon to quickly develop web, wireless and presentation object applications. Enhydra 3.1 users can generate applications for HTML or WML clients. The Kelp wizards also support CHTML and XHTML clients when running with Lutris Enhydra 3.5.

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

    • Enhydra Super-Servlet Wizard
      The Enhydra super-servlet wizard generates an application using XMLC and the Enhydra Presentation Object API.

  • Enhydra Import Wizard
    The import wizard import files from an existing Enhydra project into an IDE project file. You can use this feature to quickly migrate from a make file driven environment.

  • XML Compiler
    The compiler lets you set XMLC options, select documents to compile and call the XMLC from within your IDE. You can use trace options to get detailed output from the XMLC process.

  • XMLC Property Pages
    The XMLC property pages give you full control over how XMLC builds DOM classes. 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. You can specify what extensions to treat as XMLC file types through the XMLC property pages.

  • Enhydra Deployer
    This tool prepares your application for testing and deployment by automating the following tasks:
    • Population of the document root directory.
    • Population of the output path using input templates.
    • Generation of an archive file that you can deploy on a production server using the administration console.
    • Project configuration so you can start Enhydra from your IDE.

  • Deployment and Template Property Pages
    The deployment and template pages let you customize the deployment process. For templates, you can specify a list of strings to search and replace. You can use this feature to create custom configuration (.conf) files from templates (.in).

    Deployment settings allow you to customize the deployment, input, resource and configuration paths. You can specify what extensions to treat as static resource files types through the content types list on the deployment property page.

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

  • Kelp Sample Projects
    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 descriptor, populate HTML tables, insert a block of html into a web page and process data entry forms.

    • Wireless Application Project
      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.

* Not available when running the Kelp Add-in for JDeveloper.

System Requirements

Kelp 2.1 requires the kelp2.1.jar, toolbox.jar and Enhydra XMLC classes to be in the IDE class path. Note that Kelp 2.1 will not work with Enhydra 3.0.1 and may not function correctly with the daily builds of Enhydra Enterprise.

* The JDeveloper implementation of Kelp is no longer supported by Lutris Technologies. It does continue as an open source contribution at kelp.enhydra.org.

Installing Kelp

Before installing the Kelp, you should already have installed a supported Java IDE and the Enhydra application server. Lutris provides an installation guide for the application server at their documentation donations page.

It is recommended that you go through each step listed in the installation guide so you can run the Enhydra administration console. If you install your Java IDE prior to installing Enhydra, you can skip the step about downloading Java. You can configure the application server to work with the Java 2 files that come with the IDE.

Install Options
Kelp is available in the following packages:
  • Commercial Releases

    Commercial releases may include alternate installers and require additional configuration steps. If you are installing Kelp with a commercial product such as Lutris Enhydra Enterprise, refer to the documenation that came with your product.

  • Zip and Tar.gz Archives

    To use an archive, select the desired format and extract the contents into your <ide_root> directory. For example, if you have JBuilder installed at: /home/toni/jbuilder4, extract the Kelp archive so you end up with:

    /home/toni/jbuilder4/kelp2/doc
    /home/toni/jbuilder4/kelp2/lib
    /home/toni/jbuilder4/kelp2/samples

    If you install from an archive, you may also need to install the toolbox.jar from the Tool archive. The toolbox.jar is also bundled with the application server. Kelp will not run correctly if you are not running with a matching version of the toolbox.jar. If you are not sure if your Enhydra installation contains the correct toolbox.jar, you should install toolbox.jar from the matching archive.

    If you need to install the toolbox.jar, download a zip or tar.gz and extract the contents into your <enhydra_root> directory. If your <enhydra_root> directory is /usr/local/enhydra3.1, extract the toolbox.jar into <enhydra_root>/tool/lib.

    /usr/local/enhydra3.1/tool/lib/toolbox.jar

    After installing Kelp from archives, you will need to configure your IDE.

  • Open Source Windows Installer

    The kelp.enhydra.org site provides a Windows installer that automatically configures your IDE. Note that Lutris no longer provides support for the Windows installer. To use, refer to Using the open source Windows installer.

Configuring your IDE

You will need to modify some IDE configuration files to enable the Kelp add-in. The configuration process depends on what IDE you are running. Refer to the steps for your IDE.

After configuring your IDE, you can to create an Enhydra library to use with your Enhydra projects. The library should include the Enhydra classes required to compile the source files generated by XMLC.

Setting up JBuilder

  1. Setup the IDE class path.

    Add toolbox.jar, kelp2.1.jar and Enhydra XMLC classes to your IDE class path. JBuilder 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. What jars you need for Enhydra XMLC depends on what release of Enhydra you are working with as shown below:

    • Enhydra 3.1, Lutris Enhydra 3.5
      enhydra.jar

    • Enhydra Enterprise 4.0
      Boot.jar, Wireless.jar, xmlc.jar, xmlc-support.jar
       
    • Lutris Enhydra Enterprise 4.0
      Boot.jar, xmlc.jar, xmlc-support.jar, Wireless.jar, LutrisWireless.jar
       

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

    If you have JBuilder installed to /home/toni/jbuilder4 and Enhydra 3.1 installed in an <enhydra_root> of /usr/local/enhydra3.1, your addpath statements would be:

    addpath /usr/local/enhydra3.1/lib/enhydra.jar
    addpath /usr/local/enhydra3.1/tool/lib/toolbox.jar
    addpath /home/toni/jbuilder4/kelp2/lib/kelp2.1.jar

    If you have JBuilder installed to /home/toni/jbuilder4 and Lutris Enhydra Enterprise 4.0 installed in an <enhydra_root> of /usr/local/lutris-enhydra4.0, your addpath statements would be:

    addpath /usr/local/lutris-enhydra4.0/lib/Boot.jar
    addpath /usr/local/lutris-enhydra4.0/lib/xmlc.jar
    addpath /usr/local/lutris-enhydra4.0/lib/xmlc-support.jar
    addpath /usr/local/lutris-enhydra4.0/lib/Wireless.jar
    addpath /usr/local/lutris-enhydra4.0/tool/lib/toolbox.jar
    addpath /home/toni/jbuilder4/kelp2/lib/kelp2.1.jar

  2. Create an Enhydra library for defining project class paths

    JBuilder uses libraries to setup the class paths used to build and run your projects. You can create and edit library definitions by selecting Tools | Configure Libraries. Refer to the Defining a project class path for the list of jars required in your Enhydra library.

    Note that if the IDE class path and library entries reference different releases of Enhydra, the XML Compiler may generate java source files that fail to compile.

If you want to use the XML Compiler with non-HTML document types on Linux, you will also need to comment out the vmparam -Xverify:none option in the jdk.config file. Note that commenting out this vmparam setting may prevent access to the project Run properties tab.

You can check to see if you have installed the tools correctly by starting JBuilder and looking for the XML Compiler in the Tools menu. If the menu does not appear, check the IDE class path setting from the Info tab of the JBuilder about box.

Setting up JDeveloper

Kelp 2.1 requires that you run the JDeveloper IDE under JDK 1.2.2 or higher. The Kelp configuration may cause problems when running JDeveloper under JDK 1.1.8. Be sure you shutdown JDeveloper before editing jdeveloper.ini, gallery.ini or jdeveloper.properties.

  1. Setup the IDE class path.

    Add toolbox.jar, kelp2.1.jar and Enhydra XMLC classes to your IDE class path. The jdeveloper.ini file specifies the IDE class path. The jdeveloper.ini file is located in the JDeveloper bin directory. Add the jar files to the PREBCP=-Xbootclasspath setting in the Java2 section of the jdeveloper.ini. For example, if are running with Enhydra 3.1 and your <enhydra_root> is d:\usr\local\enhydra3.1, your Java 2 section should look similar to the following:

    [Java_2]
    JDK=java version "JDK1.2.2_JDeveloper"
    Java2VM=OJVM
    JLP=-Djava.library.path=.;%JAVA_ROOT%\bin;%JAVA_ROOT%\jre\bin;c:\orant\bin
    SLP=-Dsun.boot.library.path=.;%JAVA_ROOT%\bin;%JAVA_ROOT%\jre\bin;c:\orant\bin
    IHS=-Xms12m
    PREBCP=-Xbootclasspath/p:..\kelp2\lib\kelp2.1.jar;
      d:\usr\local\enhydra3.1\lib\enhydra.jar;
      d:\usr\local\enhydra3.1\tool\lib\toolbox.jar;
      ..\classes;..\lib\jdeveloper.zip;..\aurora\lib\vbjorb.jar;...
    ADDBCP=-Xbootclasspath/a:..\lib\debugger.jar;...
     
    What jars you need for Enhydra XMLC depends on what release of Enhydra you are working with as shown below:

    • Enhydra 3.1, Lutris Enhydra 3.5
      enhydra.jar

    • Enhydra Enterprise 4.0
      Boot.jar, xmlc.jar, xmlc-support.jar, Wireless.jar
       
    • Lutris Enhydra Enterprise 4.0
      Boot.jar, xmlc.jar, xmlc-support.jar, Wireless.jar, LutrisWireless.jar
       
  2. Add a gallery page to the gallery.ini file.

    The gallery defines what appears in the new file dialog. The gallery is divided up into pages. The gallery.ini file resides in the <jdeveloper_root>/bin directory. You need to add the following entries to make the Kelp application wizards appear in the new file dialog. You can add the entries into an existing page or create a new page for them

    wizard=Web Application=org.enhydra.kelp.jdeveloper.wizard.WebAppWizard
    wizard=Enhydra Super-Servlet=org.enhydra.kelp.jdeveloper.wizard.Enhydra3AppWizard

  3. Add wizard entries to the jdeveloper.properties file.

    The jdeveloper.properties file is located in the <jdeveloper_root>/lib directory. Each add-in has a numbered entry in the properties file. Locate the last jdeveloper.addin entry and add entries for the Kelp wizards. You can assign any numbers to the add-ins as long as they are unique.

    jdeveloper.addin.90=org.enhydra.kelp.jdeveloper.tool.XMLCTool jdeveloper.addin.91=org.enhydra.kelp.jdeveloper.tool.DeployTool jdeveloper.addin.92=org.enhydra.kelp.jdeveloper.wizard.ImportWizard jdeveloper.addin.93=org.enhydra.kelp.jdeveloper.wizard.WebAppWizard jdeveloper.addin.94=org.enhydra.kelp.jdeveloper.wizard.Enhydra3AppWizard

  4. Create an Enhydra library for defining project class paths

    JDeveloper uses libraries to setup the class paths used to build and run your projects. You can create and edit library definitions from the Libraries tab of the Project Properties dialog. Refer to the Defining a project class path for the list of jars required in your Enhydra library.

    Note that if the IDE class path and library entries reference different releases of Enhydra, the XML Compiler may generate java source files that fail to compile.

  5. Convert paths in the sample projects

    The KelpWebApp.jpr and KelpWireless.jpr sample projects are delivered in JBuilder format. You can quickly convert these files for use by JDeveloper by modifying the relative path values. JBuilder uses / as the file separator and begins relative paths with the file or directory name. JDeveloper uses \ as the file saperator and it uses the .\ prefix for relative paths. For example, the JBuilder entry...

    #12=src/kelp/webapp/resources/Greeting.html

    ...is equivalent to the JDeveloper entry...

    #12=.\src\kelp\webapp\resources\Greeting.html

    If you want to work with a Kelp sample within JDeveloper, open the project file in a text editor and use search and replace to replace all instances of / with \ and then insert .\ before each relative path.

You can check to see if you have installed the Kelp tools correctly by starting JDeveloper and looking for the XML Compiler in the Wizards menu. If the menu does not appear, double check that you have the kelp2.1.jar, toolbox.jar and Enhydra XMLC classes 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 to run successfully, 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.

Defining a project class path

You will need to define a project class path to successfully compile servlet, presentation object and XMLC generated source files within your IDE. Refer to the section on your IDE for more information on how to define a project class path. The lists below show what jar files you need to include for Kelp supported Enhydra releases.

  • Enhydra 3.1, Lutris Enhydra 3.5
    enhydra.jar

  • Enhydra Enterprise 4.0
    Boot.jar, eaf.jar, serlvet.jar, xmlc.jar, xmlc-support.jar, WebService.jar, Wireless.jar
     
  • Lutris Enhydra Enterprise 4.0
    Boot.jar, eaf.jar, servlet.jar, xmlc.jar, xmlc-support.jar, WebService.jar, Wireless.jar, LutrisWireless.jar
     
ToolBox Properties

The IDE add-in uses wizards within the ToolBox library. The ToolBox persists user settings in a toolbox.properties file. This file is created in an .enhydra directory under your home directory:

/home/toni/.enhydra/toolbox.properties

If you experience any problems using the application wizards, verify that you have rights to create files and directories within your home directory.

Using the open source Windows installer

This section describes the open source InstallShield setup program that is available from kelp.enhydra.org. Refer to the Lutris documentation if you are installing Kelp from a commercial release of Lutris Enhydra

Before running the open source 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 kelp2 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.1

Enter the correct location or use Browse to navigate to your Enhydra home directory. 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. The toolbox.jar and template files will also be copied to a tool directory under your Enhydra home directory.

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 configuring your IDE 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. Use custom to select any combination of components.

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 kelp2 directory within the IDE home directory. The installer also copies the toolbox.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 kelp2 directory.

JBuilder automatically detects and loads add-ins 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. If you want to know more about what the installer does to update your IDE configuration, refer to the section configuring your IDE.

Using the Wizards and Tools

Kelp provides several wizards and tools to help you develop Enhydra applications from within your IDE. Use one of the wizards to create new Enhydra projects from the Object Gallery that appears when you select File | New. You only need to use application wizards when starting a new project. If you have an existing Enhydra application that you want to use with Kelp, you can import it into an IDE project file using the Enhydra Import wizard. Once you have a project, you can use the XML Compiler and Enhydra Deployer to build and test your application.

The XML Compiler and Enhydra Deployer are available on the Tools menu. These tools 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 XML Compiler and Enhydra Deployer 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.

The general usage model for working with Kelp is:

  1. Use a Kelp application wizard to generate a basic application or use the Enhydra Import wizard to import an existing application into the IDE.
  2. Use the XML Compiler to generate Java source files for DOM classes. The DOM classes represent the dynamic pages of your application.
  3. Use the IDE build command to compile all Java source files.
  4. Deploy the application with the Enhydra Deployer.
  5. Run or debug your application by launching Enhydra from the IDE.
  6. Develop your application invoking the XML Compiler whenever you add or change XMLC documents. The documents are any HTML, WML, CHTML and XHTML files that represent dynamic content. Also be sure to run the Enhydra Deployer when you make changes to configuration templates or modify static content files.
  7. When your application is complete, run the Enhydra Deployer one last time to ensure the deployment archive is updated. Copy the archive to a production application server and use the administration console to add your new application. The archive is a war file for web applications and a jar file for super-servlets.

Using the Web Application Wizard

This section describes how to create a web application with the Web Application wizard. This is the first of two application wizards available on the Enhydra tab of the Object Gallery. The 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 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 has three pages you can step through to customize your application. The first step consists of client type and directory settings.

  • Client type
    The generated client will consist of a single Welcome page. This page can be targeted for one of several client browsers. Select the HTML client to work with standard browsers such as Internet Explorer or Netscape Navigator. The WML client works with wireless devices such as web enabled cell phones.

  • Project directory name
    The project directory 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 IDE project file. If your JBuilder project file is...

    /WINNT/Profiles/Administrator/jbproject/untitled1/webstore.jpx

    ...then the default project directory 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 project file name. If your project file is webstore.jpx, and you use the default package name, the WelcomeServlet will be generated with:

    package webstore.presentation;

  • Root path
    The root path is the parent directory for a group of projects. The wizard creates the project directory within the root path. If your root path is...

    /WINNT/Profiles/Administrator/jbproject

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

    /WINNT/Profiles/Administrator/jbproject/untitled1

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

    /WINNT/Profiles/Administrator/jbproject/untitled1/webstore.jpx

The second step of the web application wizard allows you to enter copyright information. You can enter copyright information directory or select a text file. The wizard will add this information to the heading of each generated java file. You do not need to include any comment delimiters in your text.

The last step of the wizard lets you generation makefiles, shell scripts and files for use with Enhydra 4. The makefiles allow you to build your application from a unix shell without requiring JBuilder. The shell scripts let you start Enhydra with your application from a unix shell.

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 may very depending on what IDE you are using.

XML Compiler

The XML Compiler can compile XMLC types into DOM classes. From the IDE menu, select Tools | XML Compiler to open the tool. The tool is only available when a project is open. If you do not see the XML Compiler option on your menu, make sure that the toolbox.jar, kelp2.1.jar and Enhydra XMLC classes are in the IDE class path.

The compiler is organized into a three-tab dialog. The tabs are Selections, Options and Output. The Selections tab displays all the XMLC documents in your current project. You can modify what XMLC types by selecting XMLC types on the Options tab. The default types for Enhydra 3.1 are HTML and WML. You can use the > and < buttons to select or deselect a single file for compilation. The >> and << buttons will add or remove all files from the selected list.

The Options tab contains Compile, XMLC Types and Trace options. You can use the Compile options to customize the generated DOM classes. The Trace options let you display detailed information during the compile process. The Options tab also has an Invoke XMLC during Project Make/Rebuild. Select this option to call XMLC without opening the tool's dialog. This will call XMLC when you build or make a project node that contains a XMLC type selected for compilation.

The mappings compile option provides a table for customizing generated class names. By default the XMLC compiler wizard uses the current directory name to determine the package name in the generated source. Unless you keep your XMLC documents in the same directory as the Java source files for your servlets or presentation objects, you will want to use the Mappings option to map your XMLC resources directory to the presentation package name. The Lutris guidelines recommend that keep your XMLC file types 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, click on the Map Table 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 Browse button to navigate to one. In the following dialog shows how to setup the compiler to use the package name:

kelp.webapp.presentation

when compiling html pages stored in:

C:/JBuilder4/kelp2/samples/webapp/src/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 XMLC documents, 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. When you compile, a progress dialog appears with a cancel option. Note that if you click on cancel, the operation will not be terminated until XMLC finishes with the current document.

The output page displays the files that are created during the compile process. Previously generated Java source files are erased prior to regeneration. The tool will not create or remove class files.

Enhydra Deployer

The Enhydra Deployer makes it easy quickly prepare your projects for testing and deployment This wizard does the following tasks:

  • Populates the document root path.
  • Populates the output path using input templates and other input files.
  • Creates an archive file you can deploy using the web based server administration application.
  • Provides a way to launch Enhydra from your IDE project.

There are significant differences between deploying a super-servlet and deploying a web application. However, in either case you should be aware of how path settings effect deployment.

Preparing for deployment consists of configuring paths, content types, replacements and selecting input templates. The path tab displays four paths you can edit and three that are read only.

  • Deploy root
    The deploy root is the root directory that determines the values for the configuration path and the archive file. It also determines the document root when working with a web application.

  • Startup configuration
    The startup configuration file passed as a parameter to the Enhydra startup class. When working with Enhydra 3.x, this file is primarily responsible for configuring the servlet service. It is commonly named multiserver.conf, but any name is allowed. The Kelp application wizard generates a file called servlet.conf as the startup configuration file. The name and location of the servlet.conf are compatible with both the Enhydra 3 and 4 product lines. However, when working with Enhydra 4, the servlet.conf file is found by the file name and location. Enhydra 4 uses a different file for startup. You can optionally generate an Enhydra 4 startup configuration file called bootstrap4.conf using the Kelp application wizard.

  • Input path
    The input path is a directory containing input templates. These templates are normally configuration files with placeholders for file paths that are specific to the current machine.

    If the input path is not contained within a source path, you can use the input path to deploy non-template files. When files are deployed from the input path, they are copied to the deployment root using relative paths.

  • Configuration path
    The read only configuration path is used to locate default startup configuration files. When working with Enhydra 4, it is used to as the parent directory for service configuration files.

  • Archive file
    The archive file is generated for deploying your application to a production server. When working with web applications, the archive is a war file that contains the classes, static content and deployment descriptors required to run the application on a servlet 2.2 compliant server. The wizard creates a jar file that contains the classes and static content required to run the application on an Enhydra server. When deploying a super-servlet you will need the application configuration file in addition to the archive.

  • Resource path
    The resource path is the source location for static content files. These include images, java script libraries, cascading style sheets, java server pages and documents that require no processing by XMLC. Normally the resource path will include XMLC source documents in addition to static pages. Files that are selected for XMLC compilation will not be copied as static resources.

  • Document root
    The location of the document root is determined by what type of application you are deploying. The document root for web applications in a content directory under the deploy root. The document root for super-servlet applications is the classes output location as mapped for XMLC packages.

Web Application Deployment

  1. Copy content from Resource path into Document root

    Content type files are copied from the resource directory to the document root directory. By default content types include jpg, gif, js, css and XMLC types. An XMLC type is only copied if it is not selected for compilation.

    The document root for a Web Application is:

    <deployment root>/content.

    If a <source path>/WEB-INF/web.xml file is found, it will also be copied to the document root.

  2. Process files from Input path into Deploy root

    There are two process that occur for input files. The first is for template files and the second is for all other file types within the input path.

    If the input path is contained within the source path, non template will not be copied to the output path.

    1. Process templates with search and replace and copy result to deploy root
    2. Copy non-template files from input path to deploy root.

  3. Create a web application archive (war) from the document root and classes output path. JBuilder dependency files and generated source files will be excluded from the archive.

    Web application archive files are created as:

    <deployment root>/archive/<project name>.war.

    The layout of the war file is:

    /(files copied from the document root)
    /meta-inf/Manifest.inf
    (created by archiver)
    /WEB-INF/classes/
    (files copied from the classes output path)
    /WEB-INF/web.xml
    (file copied from the document root)

  4. Project configuration for Enhydra startup

    The run configuration process can optionally:

    • Setup project properties to start Enhydra.
    • Create a StartEnhydra.java file for launching Enhydra.

Super-servlet deployment

  1. Copy content from Resource path into Document root

    Content type files are copied from the resource directory to the document root directory. The default content types include jpg, gif, js, jsp, css and XMLC types. An XMLC type is only copied if it is not selected for compilation.

    The document root for a super-servlet is determined by mapping the resource path into the class output path with the XMLC package mapping table.

  2. Process files from Input path into Deploy root

    There are two process that occur for input files. The first is for template files and the second is for all other file types within the input path.

    If the input path is contained within the source path, non-template will not be copied to the output path.

    1. Process templates with search and replace and copy result to deploy root
    2. Copy non-template files from input path to deploy root.

  3. Create an archive file from files in the class output path. JBuilder dependency files and generated source files will be excluded from the archive.

    Super-servlet archive files are created as:
    <deployment root>/archive/<project name>.jar.

  4. Project configuration for Enhydra startup

    The run configuration process can optionally:

    • Setup project properties to start Enhydra.
    • Create a StartEnhydra.java file for launching Enhydra.

Template files

Templates are files within the input path that have the extension ".in". The deployer does a search and replace using the strings in the input table. By default it will search for string with the format @*_PATH@ and replace them with absolute paths. The default search tokens are:

 @JAVA_PATH@
 @DEPLOY_PATH@
 @ENHYDRA_PATH@.

The @JAVA_PATH@ is replaced with the Java home directory path, the @DEPLOY_PATH@ is replaced with the deploy path and the @ENHYDRA_PATH@ is replaced with the Enhydra home directory path.

There is special handling of any replacement tokens that match the @*_PATH@ pattern. These tokens are expanded to also replace instances of @JAVA_*_PATH@, @SHELL_*_PATH@, and @OS_*_PATH@. All replacement values are identical when running under Linux or Solaris.The replacements differ when running on Windows. For example if @ENHYDRA_PATH@ is D:/usr/local/enhydra3.1. The folowing replacements also take effect.


@JAVA_ENHYDRA_PATH@    D:/usr/local/enhydra3.1
@SHELL_ENHYDRA_PATH@    //D/usr/local/enhydra3.1
@OS_ENHYDRA_PATH@    D:\usr\local\enhydra3.1

You can customize the search and replace mechanism by editing Template replacements table on the Input tab. You can also click on the Reset button to let the wizard regenerate the table by reading in placeholders from the templates in the current project. The replace with values can appear with relative paths. Any path that is below the project root directory will be saved as a relative path. For example, if you open the Kelp Web Application project from:

/jbuilder4/kelp2/samples/webapp/KelpWebApp.jpr

...and have a Replace Text table containing:

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

The resulting configuration files (.conf) will contain /jbuilder4/kelp2/samples/webapp/output in place of any @DEPLOY_PATH@ or @JAVA_DEPLOY_PATH@ placeholders that are in each configuration template (.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 StartServer.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 StartServer.java file is only needed when running under Kelp with Oracle JDeveloper.

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.1 DiscRack example.

Here are the steps for running the Enhydra 3.1 DiscRack example using Kelp 2.1 with JBuilder 4.0. They are broken down into three sections:

  1. Importing DiscRack
  2. Building DiscRack
  3. Running DiscRack
  1. Importing DiscRack

    1. First build and run as described in the DiscRack README file to generate the data package source code and copy the instantDB database to the output directory.

    2. Create a new JBuilder project file:

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

    4. Open the Enhydra Import wizard and set the project directory to:

       <enhydra home>/examples/DiscRack

    5. Click on Next to navigate through the wizard accepting all the other default settings and click on Finish to import the project.

  2. Building DiscRack

    1. Open the XMLC Compiler wizard and click on Compile to generate the DOM Java source files using XMLC. Click on Close when you see the output display:

       "--- XMLC finished compiling ---"

    2. From the Project menu select Make to compile the Java source files.

    3. Open the Enhydra Deployer and click on Deploy to copy static content files, process configuration templates and create an deployable archive.

  3. Running DiscRack

    1. Open the Project properties dialog and add an InstantDB library to the required library list. This library should contain version 3.21 of the idb.jar file and a Sun jar that includes the javax transaction packages. See the InstantDB readme.txt file for information on downloading the correct jar from Sun.

    2. Run the project to start the Enhydra server with the deployed DiscRack application.

    3. To view the application open a browser and connect to:

       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 Enhydra 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 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:
/jbuilder4/kelp2/samples/webapp/src/kelp/webapp/resources
Package Name:
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 XMLC Node Property Page

You can open the XMLC node property page by right clicking on an XMLC document (html, wml, xhtml or chtml) 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 documents that have no dynamic content you can use the option: Copy to output as a static resource. Check this to have the Enhydra Deployer copy the selected file to the document root path.

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

Source path: /usr/home/toni/jbprojects/untitled1/src
Directory location: /usr/home/toni/jbprojects/untitled1/src/untitled1/presentation
Filename: Welcome.html

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

untitled1.presentation.WelcomeHTML

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

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

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

The Enhydra Deployment Project Property Page

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

The Enhydra Input Template Property Page

The Enhydra Input Template property page contains the replacement table that appears on the Input tab of the Enhydra Deployer. In addition to the project properties, there is a Deploy checkbox that you can select to a have the template processed to the deploy root during deployment. Selecting the checkbox is the same as selecting the file in the Enhydra Deployer. For more information, refer to the Enhydra Deployer.

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 Application 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 an Enhydra Deployer that you can use to automatically configure the Web Application project. Before running the Enhydra Deployer 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 kelp2 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 Enhydra Deployer. 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 Enhydra Deployer creates a servlet configuration file from a servlet.conf.in template. This file has the port number, document root and logging file paths for the application. The servlet.conf.in template has placeholders for path settings. The path settings are set through Enhydra Deployer.

The Enhydra Deployer 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>
      @JAVA_DEPLOY_PATH@/data
    </param-value>
  </init-param>

If you modify any templates (*.conf.in or web.xml.in files), be sure to run the Enhydra Deployer 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 bootstrap4.conf file to control what services get loaded by the server. This file is not required for Enhydra 3.

The Enhydra Deployer 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 StartServer.java program. In either case, the wizard sets the servlet.conf file as a startup configuration parameter.

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 an explantion on how you can separate applications into these three functional areas, see the Getting Started guide from the Lutris Enhydra Documentation Donations page.

If you have moved a sample project after running Enhydra Deployer, 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 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.

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

    Normally you should set the Source path to a src subdirectory within your project root directory. When you create a project using the Project wizard in JBuilder, it creates a directory for your project under jbprojects in your home directory. The default Source path is set to a src subdirectory within the project root. For example, if you create a project called "untitled1", the Source path would be set to something like:

    /usr/home/toni/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 use: org.enhydra.multiServer.bootstrap.Bootstrap

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

  • Run: Application Parameters

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

    (source directory)/output/conf/bootstrap4.conf

    Note that Enhydra 4 is passed the bootstrap4.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 StartSever class that will start Enhydra 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 the Enhydra server. The configuration file for Enhydra specifies the location of super-servlet 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 the Enhydra server is not already running.
  2. Open the KelpWebApp project.
  3. Select the TableServlet.java file in the 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. If you have generated a StartServer.java file, you can start debugging from that file. Otherwise select Run | Debug Project. This will start the debugger.
  6. Open the table page in your browser. This will trigger the breakpoint as shown below.

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

Working with the Open Source

The source files for Kelp and the ToolBox classes are included with Enhydra source downloads. You can also checkout the latest Kelp source code from the enhydra.org cvs system. Within the Enhydra project, you'll find a Kelp module with a kelp.jpr for working with the Kelp source files from within JBuilder.

To build the JBuilder implementation of Kelp, you need to have jbuilder.jar and help.jar in your class path. Both jar files come with the free download of JBuilder Foundation

To build the JDeveloper implementation of Kelp, you need to have the jbcl2.0.zip and jdeveloper.zip in your class path. These come with Oracle JDeveloper 3.2. JDeveloper is freely available to members of the OTN (Oracle Technology Network). There is no cost to join OTN.

The kelp.jpr file contains all the source files required to build the kelp2.1.jar. These classes use JBuilder's OpenTools API and JDevelopers add-in API. To use this file as delivered you will need to create the following libraries.

  • Enhydra 3.1: enhydra.jar
  • ToolBox: toolbox.jar
  • OpenTools SDK: jbuilder.jar, help.jar
  • JDeveloper add-in SDK: jdeveloper.zip, jbcl2.0.zip

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 4.0 support package
org.enhydra.kelp.jdeveloper - Oracle JDeveloper 3.2 support package

You can also build Kelp through the make system. See the readme that is included with the source download for information on configuring make for the IDE jar files.

Visit the following news groups for information about the developing add-ins and using the JBuilder OpenTools API:

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

 

The Kelp Web Site

The Kelp project web site, http://kelp.enhydra.org is dedicated to making Enhydra technologies easier to use through the use of tools such as application wizards and Java IDE add-ons.

The site serves as the repository for downloads, documentation and mail list archives. It also acts as a gateway to the cvs repository for the open source Kelp and ToolBox modules. The ToolBox module includes application wizards and templates that you can run without using an IDE. The Kelp module integrates the ToolBox wizards and XMLC into an IDE environment.

You can use the project mail list, kelp@enhydra.org 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 are invited to participate in the Kelp project. We welcome contributions in many forms, including documentation, patchs and implementaions of the Kelp and ToolBox wizards within other IDEs.


Copyright 2000-2001 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.