![]() |
|
|||||
![]() |
![]() |
![]() |
![]() |
|||
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. Kelp 2 supports Borland JBuilder and Oracle JDeveloper. This document describes how to use Kelp to develop Enhydra applications with XMLC. It assumes a basic understanding of the Java IDE and 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 Enhydra documentation page. Features
System Requirements
Kelp 2 requires the kelp2.0.jar, enhydra.jar, toolbox.jar files to be in the IDE class path. It also requires templates for the application wizards. The kelp2.0.jar, toolbox.jar and templates are supplied with the Kelp install and zip files. Note that Kelp 2 will not work with Enhydra 2.3 or Enhydra 4.0. Installing KelpBefore installing the Kelp, you need to already have a supported Java IDE and Enhydra. You can find installation instructions for Enhydra at the Enhydra download page. It is recommended that you go through each step listed on the download page so you can run the Enhydra administration application. If you install your Java IDE prior to installing Enhydra, you can skip the step about downloading Java. You can configure Enhydra to work with the Java 2 files that come with the IDE.
Installing on WindowsThe kelp2.0.exe file is a self-extracting InstallShield setup program. Before running the installer, close any open instances of the IDE and note where your IDE and Enhydra files reside. You will need to tell the setup program what version of the IDE you are running. Open the IDE's About box to view the version number that you are currently running. The setup program will look up your Java IDE home directory in the Windows registry. If you have installed more than one supported IDE, you may need to click on Browse in the Choose IDE directory step to select the location of the IDE you want to use with Enhydra. The sample projects, documentation and libraries will be installed in a 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 setting the IDE class path for more information. The setup program provides you with three types of installations: Typical, Compact and Custom. Typical installs the libraries, templates, documentation and the sample projects. Compact installs only the library and template files. 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 are using JBuilder on Windows and want to know more about what the installer does to update your JBuilder configuration, refer to the section installing on Linux. Setting up JDeveloperKelp 2 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. The jdeveloper.ini file specifies the class path. The jdeveloper.ini file is located in the JDeveloper bin directory. The installer updates the jdeveloper.properties file. If you do not see the XMLC Compiler on the JDeveloper Wizard menu, check the jdeveloper.properties file for lines defining the Kelp wizards. Although the add-in numbers may be different, the lines should appear similar to the following.
jdeveloper.addin.81=
You can check to see if you have installed the Kelp tools correctly by starting JDeveloper and looking for the XMLC Compiler wizard in the Wizards menu. If the menu does not appear, double check that you have the kelp2.0.jar, toolbox.jar and enhydra.jar files in the IDE class path. Oracle JDeveloper comes bundled with an older implementation of the org.wc3.dom classes that are not compatible with XMLC. The enhydra.jar file contains updated org.wc3.dom classes. To allow the XMLC compiler to run succesfully, the setup program places the enhydra.jar at the start of the IDE class path. Under JDK 1.1.8 the enhydra.jar will cause conflicts with the dacfdtd.zip, jbodt.zip and xmlparserv2.jar files. If you need to run JDeveloper under 1.1.8, you should remove those jar files from the IDE class path. This will disable some of JDeveloper's HTML tag support. If you want to use the HTML tag wizards, you will need to restore the Oracle files back into the IDE class path and remove Kelp.
Installing on Linux and Solaris
Setting the IDE Class PathJBuilder 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.
If you are running Oracle JDeveloper, you can set the IDE class path through the jdeveloper.ini file. The ini file uses the Using the WizardsKelp provides several wizards 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 XMLC Compiler and Enhydra Deployment wizards to build and test your application. The XMLC compiler and Enhydra Deployment wizards are available on the Wizards menu. These wizards let you invoke Enhydra specific parts of the make system. Using the integrated build feature, you can invoke these same processes directly within the project builder without opening either wizard. The XMLC compiler and Enhydra Deployment wizards use a similar interface where you can select files, set options and view the build process using a three-tabbed dialog. The settings on the Options tab are the same as those found on the associated project property pages. ![]() The general usage model for working with Kelp is:
Using the Web Application WizardThis 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 a opened a new project, select File | New to open the Object Gallery. The gallery provides options for quickly generating many common classes. Select the Enhydra tab and double click on the Web Application icon to open the wizard. The wizard has three pages you can step through to customize your application. The first step consists of client type and directory settings.
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.
XMLC Compiler WizardThe XMLC compiler wizard can compile XMLC types into DOM classes. From the IDE menu, select Wizards | XMLC Compiler to open the wizard. The wizard is only available when a project is open. If you do not see the XMLC Compiler option on your menu, make sure that the toolbox.jar, kelp2.0.jar and enhydra.jar files are in the IDE class path. The wizard is organized into a three-tab dialog. The tabs are Selections, Options and Output. The Selections tab displays all the 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 without effecting the generated classes. The Options tab also has an Invoke XMLC during Project Make/Rebuild. Select this option to call XMLC without opening the wizard. This will call XMLC when you build or make a project node that contains a 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:
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 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 wizard will not create or remove class files.
Enhydra Deployment WizardThe Enhydra Deployment wizard makes it easy quickly prepare your projects for testing and deployment This wizard does the following tasks:
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 imput templates. The path tab displays four paths you can edit and three that are read only.
Web Application Deployment
Super-servlet deployment
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@
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.
![]() 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:
...and have a Replace Text table containing:
Text to find: 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 WizardThe 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 with JBuilder 4.0. They are broken down into three sections:
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. 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 PageIf you open the Project properties dialog and select the Enhydra XMLC tab, you will see the XMLC project properties page. This page include same Compile, Trace and Resource tabs that you can set on the Options tab of the XMLC compiler wizard. The Compile tab includes three sections. The section for Generated Java Source informs you of what XMLC options need to be set for the current IDE. The Mappings section determines how to generate class names while the XMLC Optionse section lets you select an XMLC Options file and directly enter command line options for XMLC. Refer to the XMLC documentation for a list of command line options you can use with XMLC. Within the Mappings section, you can define a mapping table and set what nodes to use with the table. The mapping table lets you specify package names to use when generated DOM classes for a given directory. For example, the Kelp Web Application sample project uses a mapping table to map all the html files in a resources directory into the org.enhydra.kelp.webapp.presentation package. To view or edit the package name mapping, open the XMLC Compiler wizard, select the Options tab and click on the Edit button. This opens the mapping table where you can add a new entry that maps a directory to the correct presentation package. Here is an example mapping for the Kelp Web Application sample project:
Source Directory: 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 PageYou 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 Deployment wizard 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: 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 Deployment Project Property PageThe Enhydra Deployment project property page contains the same settings that appear on the Options tab of the Enhydra Deployment wizard. There are two tabs: Make and Startup. For more information, refer to the Enhydra Deployment wizard. The Enhydra Input Template Property PageThe Enhydra Input Template property page contains the replacement table that appears on the Input tab of the Enhydra deployment wizard. 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 Deployment wizard. For more information, refer to the Enhydra Deployment wizard. The Kelp Web Application SampleKelp 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 ApplicationKelp includes the Enhydra Deployment wizard that you can use to automatically configure the Web Application project. Before running the Enhydra Deployment wizard or the sample, be sure to review the steps provided in the readme.html file that is included with the project.
If you are running under Linux or Solaris and you do not have root privileges, you may need to copy the Kelp sample projects to your home directory before working with it. To do this copy the
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 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 Deployment wizard. The wizard may ignore changes made since the last save. If you are using a port other than 9000, the links within the readme.html will fail. Add the port you are using to the URL. To use port 8080, enter http://localhost:8080/ as your URL. If localhost fails, try using the IP address 127.0.0.1 in place of localhost. The Enhydra Deployment wizard 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 Deployment wizard.
The Enhydra Deployment wizard creates the web.xml deployment descriptor using the same placeholder replacement mechanism used to create the servlet.conf file. The web.xml file contains a
<init-param>
If you modify any templates (*.conf.in or web.xml.in files), be sure to run the Enhydra Deployment wizard to regenerate the configuration files and descritors descriptors. Enhydra will ignore any changes made to the templates that have not been deployed. Enhydra 4 also uses a bootstrap4.conf file to control what services get loaded by the server. This file is not required for Enhydra 3.The Enhydra Deployment wizard also sets up the sample project so that you can launch the application with the Enhydra server. It does this by setting the project's main run class or by generating a StartServer.java program. In either case, the wizard sets the servlet.conf file as a startup configuration parameter. The Sample ServletsThe sample project consists of four presentation objects that show some of the common uses of XMLC. The sample is simplified in that it only contains a presentation layer. Production web applications will normally contain a least three packages including presentation, business and data. For a detailed explantion on how you can separate applications into these three functional areas, read the Getting Started with Enhydra. If you have moved a sample project after running Enhydra Deployment wizard, you should run the wizard again before using the sample. See Deploying the Web Application sample for more information.
Each servlet dynamically generates HTML files using XMLC. The HTML source files are located in a resources directory. Each HTML file is compiled into a class file using the XMLC Compiler wizard. There is a corresponding java file that implements
Setting Project PropertiesYour 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.
Debugging Enhydra ApplicationsThe 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.
Working with the Open SourceThe 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.1. 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.0.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.
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:
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 The Kelp Web SiteThe 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 Lutris Technologies, Inc.
JBuilder is a trademark of Inprise Corporation. |
||||||
![]() |