Kelp Project Documentation:
Enhydra Kelp developer tools and Eclipse plugin

Kelp Project Documentation:
Enhydra Kelp developer tools and Eclipse plugin

Together Teamlösungen EDV-Dienstleistungen GmbH

Elmargasse 2-4 A-1190 Vienna Austria Phone: +43 (0) 5 04 04 - 122 Fax: +43 (0) 5 04 04 - 11 122 E-Mail: Web: http://www.together.at/together/index.html

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written permission of the Together Teamlösungen EDV-Dienstleistungen GmbH.

Together Teamlösungen EDV-Dienstleistungen GmbH DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Table of Contents

1. Introduction
2. Release Notes
3. The Kelp Project Web Site
4. Installing the plugin from kelp.objectweb.org
System Requirements
Install Options
Configuring your Enhydra Kelp plugin
Defining a project class path
Using the installer application
5. CVS modules

Chapter 1. Introduction

The Enhydra Kelp plugin makes it easy to use the Enhydra XML Compiler (XMLC), the Enhydra Data Object Design Studio (DODS) and the Enhydra Application Server within an integrated development environment. Refer to Using Kelp with an Eclipse IDE ( html ) for information on how to use a Kelp plugin to develop web applications with XMLC and DODS.

This document supplements documentation for Kelp plugin and its tools. You'll also find an overview of the open source CVS modules at the end of this document.

You will find more details about earlier versions of Kelp at the Enhydra Kelp project web site along with FAQs (Frequently Asked Questions) and information on checking out the source from the CVS repository.

This documentation assumes a basic understanding of a Eclipse IDE and the servlet programming model. For information on Eclipse, visit the Eclipse website.

The plugin provides wizards and tools to help you develop applications for Enhydra or Enhydra Enterprise Server. The plugin will add the Enhydra Kelp application wizards to your IDE's 'File -> New -> Project' menu. You only need to use an application wizard when starting a new project. Once you have a new Enhydra project, you can use the DODS Generator, the XML Compiler and Kelp Deployer to build and deploy your application.

The DODS Generator, the XML Compiler and Kelp Deployer together with complete Ant Rebuild action are added to the IDE's Tools menu. These tools give you access to Enhydra features from within your IDE. Using the Eclipse integrated build feature, you can invoke these same processes directly within the project builder without opening the wizard. Each tool also has a set of project and node property pages.

The general model for building web or enhydra applications with the Kelp plugin:

  • Create a new empty project from your Eclipse IDE.

  • Use a Kelp application wizard to generate a web application.

  • Use the XML Compiler to generate Java source files for DOM classes. The DOM classes represent the dynamic pages of your application.

  • Deploy the application with the Kelp Deployer.

  • Run or debug your application by launching Enhydra (Enterprise) Server from the IDE.

  • Develop your application invoking the XML Compiler whenever you add or change XMLC documents. The documents are any HTML, XHTML, WML and CHTML files that represent dynamic content.

  • Rerun the Kelp Deployer to rebuild your web application archive (.war) to test any changes you've made to your source, template, or content files.

  • When your application is complete, copy the web archive (.war) to your production server and use an server management and/or administration applications to add and configure the new application.

Chapter 2. Release Notes

Release Notes ( html ) contain late-breaking information that might not have made it into the product documentation. These notes may include additional installation instructions, system requirements, and new feature descriptions.

Chapter 3. The Kelp Project Web Site

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

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

You can use the project mail list (kelp@objectweb.org) to post questions or suggestions regarding any of the Kelp modules. 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, patches and additional functionality implementations.

Chapter 4. Installing the plugin from kelp.objectweb.org

Before installing the plugin, you should already have installed a supported Eclipse IDE and the Enhydra and/or Enhydra Enterprise Application Server.

System Requirements

  • Enhydra and/or Enhydra Enterprise Application Server

  • Supported Eclipse version

Enhydra Kelp requires the Kelp plugin jars, Enhydra 'toolbox jar', Enhydra XMLC and Enhydra DODS classes to be in the plugin class path.

Install Options

Enhydra Kelp add-ins are available in the following packages:

  • Installer application

    Installer application asks user for Eclipse IDE directory and Enhydra (Enterprise) Server directory and makes all necessary configuration steps.

  • Zip Archives

    To use a zip archive, extract the contents into your <ide_root> directory. For example, if you have Eclipse installed at: C:\eclipse, extract the Kelp archive so you end up with:

    C:\eclipse\pluginsorg.enhydra.kelp.eclipse_<version>.<release>
    C:\eclipse\Kelp-Readme.txt
    C:\eclipse\setEasRoot.bat
    C:\eclipse\setEasRoot.sh

    The 'toolbox.jar' is also bundled with the Enhydra. 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' (into Enhydra) from the matching archive.

    <enhydra_root>/multiserver/enhydra/lib/build/toolbox.jar
          

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

Configuring your Enhydra Kelp plugin

The Enhydra Kelp plugin 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 (user) home directory:

/home/toni/.enhydra/toolbox.properties

Enhydra Kelp configuration process sets 'eas.root' property. This property points to adequate enhydra (xmlc, dods) library root in Enhydra or Enhydra Enterprise Server installation.

'toolbox.properties' configuration is executed trough 'setEasRoot' batch/shell script file which comes with Enhydra Kelp plugin (placed in root directory of your Eclipse installation).

To configure Enhydra Kelp plugin, cd to Eclipse root directory (e.g. C:\eclipse) and execute next command:

  • Windows:

    setEasRoot.bat

  • Linux:

    ./setEasRoot.sh

Batch/Shell Script file will configure Enhydra Kelp plugin installation according to local:

  • 'CATALINA_HOME' environment variable which should be set after successful Enhydra Server installation.

  • 'JONAS_ROOT' environment variable which should be set after successful Enhydra Enterprise Server installation.

If you do not have 'CATALINA_HOME' (needed for Enhydra Kelp) and/or 'JONAS_ROOT' (needed for Enhydra Enterprise Kelp), you can transfer Enhydra (Enterprise) Server installation path to kelp configuration executable as 'enhydra.dir' parameter:
  • Windows:

    setEasRoot.bat -enhydra.dir <enhydra_root>/multiserver

  • Linux:

    ./setEasRoot.sh -enhydra.dir=<enhydra_root>/multiserver

NOTE: 'java' executable should be placed on your PATH environment variable

Defining a project class path

The project class path is independent from the Enhydra Kelp plugin class path.

The following jars are required to successfully compile and run projects that use the servlet, Enhydra application, Enhydra DODS or Enhydra XMLC.

  • Enhydra

    <enhydra_root>/multiserver/enhydra/lib/eaf.jar
    <enhydra_root>/multiserver/enhydra/lib/eaf-api.jar
    <enhydra_root>/multiserver/enhydra/lib/util.jar

    <enhydra_root>/multiserver/enhydra/lib/xml-apis.jar
    <enhydra_root>/multiserver/enhydra/lib/xercesImpl.jar
    <enhydra_root>/multiserver/enhydra/lib/jtidy.jar
    <enhydra_root>/multiserver/enhydra/lib/gnu-regexp.jar
    <enhydra_root>/multiserver/common/lib/servlet-api.jar
    <enhydra_root>/multiserver/enhydra/lib/log4j.jar

    <enhydra_root>/multiserver/enhydra/lib/xmlc.jar
    <enhydra_root>/multiserver/enhydra/lib/xhtml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom/xmlc-voicexml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom/xmlc-wml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom/xmlc-chtml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom3-xml-apis.jar

    <enhydra_root>/multiserver/enhydra/dods/lib/dods.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/ejen.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/dbmanager.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/dbmanager-api.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/dsconnection.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/stdcaches.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/stdconnection.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/stdtransaction.jar

    JRE System Library

  • Enhydra Enterprise

    <enhydra_root>/multiserver/enhydra/lib/eaf.jar
    <enhydra_root>/multiserver/enhydra/lib/eaf-api.jar
    <enhydra_root>/multiserver/enhydra/lib/util.jar

    <enhydra_root>/multiserver/enhydra/lib/xml-apis.jar
    <enhydra_root>/multiserver/enhydra/lib/xercesImpl.jar
    <enhydra_root>/multiserver/enhydra/lib/jtidy.jar
    <enhydra_root>/multiserver/enhydra/lib/gnu-regexp.jar
    <enhydra_root>/multiserver/lib/commons/j2ee/servlet-2_4.jar
    <enhydra_root>/multiserver/enhydra/lib/log4j.jar

    <enhydra_root>/multiserver/enhydra/lib/xmlc.jar
    <enhydra_root>/multiserver/enhydra/lib/xhtml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom/xmlc-voicexml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom/xmlc-wml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom/xmlc-chtml.jar
    <enhydra_root>/multiserver/enhydra/lib/dom3-xml-apis.jar

    <enhydra_root>/multiserver/enhydra/dods/lib/dods.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/ejen.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/dbmanager.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/dbmanager-api.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/dsconnection.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/stdcaches.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/stdconnection.jar
    <enhydra_root>/multiserver/enhydra/dods/lib/stdtransaction.jar

    JRE System Library

Using the installer application

You can use the open source installer to install and configure your Enhydra Kelp Plugin.

The setup program will look up for your Enhydra or Enhydra Enterprise Server home directory in the Windows registry. If you have installed more than one supported Enhydra server, you may need to click on Browse in the 'Choose Enhydra directory' step to select the location of the Enhydra or Enhydra Enterprise Server you want to use with Enhydra Kelp. Enhydra Kelp plugin, its documentation and libraries will be installed in a kelp plugin directory within the Eclipse IDE's 'plugins' directory.

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

c:\enhydra

Enter the correct location or use 'Browse' button to navigate to your Enhydra root directory.

The installer will copy Enhydra Kelp files into a kelp plugin directory within the Eclipse plugins directory.

The installer modifies 'toolbox.properties' file placed in '<user_home_dir>/.enhydra' directory.

NOTE: Modifications will not be reversed if you uninstall Enhydra Kelp.

If you want to know more about what the installer does to update your 'toolbox.properties' configuration, refer to the section configuring your Enhydra Kelp.

Chapter 5. CVS modules

The source files for the Kelp plugin modules are available from the CVS page of the Enhydra Kelp project web site. Each module contains an Ant build.xml file.

Kelp includes the following modules.

  • AddinCore contains classes shared by plugin implementation modules. The core classes are used to create property pages, wizards and build tasks for working with XMLC and the Enhydra application server from a Eclipse IDE.

  • Eclipse plug-in org.enhydra.eclipse_<version>.<release> creates all necessary jars for creating enhydra applications in Eclipse with Enhydra Server.

  • Eclipse Enterprise plug-in org.enhydra.eclipse_<version>.<release> creates all necessary jars for creating enhydra applications in Eclipse with Enhydra Enterprise Server.