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. JDeveloper Kelp is a set of Enhydra tools for Oracle JDeveloper. This document describes how to use Kelp to develop Enhydra applications with XMLC. It assumes a basic understanding of the JDeveloper IDE and the Enhydra Application Framework. For information on Oracle JDeveloper, visit the Oracle website. An overview of Enhydra can be found at the Enhydra documentation page. Features
System Requirements
The only file that Kelp 1.1 requires from Enhydra is the enhydra.jar. However, you should install the complete set of Enhydra files so that have access to the complete set of documentation and administration files. Note that Kelp will not work with Enhydra 2.2.1 or earlier versions. Installing KelpBefore installing the Kelp, you need to already have JDeveloper and Enhydra. You can find installation instructions for Enhydra at the Enhydra download page. It is recommended that you go through each step listed on the download page so you can run the MultiServer administration application. If you install JDeveloper prior to installing Enhydra, you can skip the step about downloading Java. You can configure MultiServer to work with the Java 2 files that come with JDeveloper.
Running SetupThe jdev-kelp1.1.exe file is a self-extracting InstallShield setup program. Before running the installer, close any open instances of JDeveloper and note where your JDeveloper and Enhydra files reside. You will need to tell the setup program what version of JDeveloper you are running. Open the JDeveloper About box to view what version number that you are currently running. The setup program will look up your JDeveloper directory in the Windows registry. If you have installed JDeveloper in more than one directory, you may need to click on Browse in the Choose JDeveloper directory step to select the location of the JDeveloper you want to use with Enhydra. The Kelp sample project, documentation and libraries will be installed in a jdev-kelp directory within the JDeveloper directory. After selecting the JDeveloper directory to use for installing, you need to tell the setup program where to look for the enhydra.jar file. The setup program will check the Windows registry and common locations to determine a default such as: c:\usr\local\Enhydra\enhydra3.0\lib Enter the correct location or use Browse to navigate to where you have installed enhydra.jar. The enhydra.jar file will be added to the IDE class path that is set when starting JDeveloper. The setup program also creates an Enhydra library for the enhydra.jar so you can use Enhydra with your JDeveloper projects. Note: If you have previously installed Kelp with a different enhydra.jar, you may need to modify the IDE class path to ensure that it only contains a single enhydra.jar file. See the section on setting the IDE class path for more information. The setup program provides you with three types of installations: Typical, Compact and Custom. Typical installs the libraries, documentation and a sample project. Compact installs only the library files. Select the Custom option if you want to install a copy of Kelp's open source code. After selecting the type of installation you want, setup prompts you for the program group directory and lists all your selections for confirmation. When you confirm the settings, the installer will copy files into a jdev-kelp directory within the JDeveloper directory. It also modifies the JDeveloper library, startup and user configuration settings. Some of the modifications will not be reversed if you uninstall Kelp. To allow you to restore your original configuration, the setup program creates backup of each of the modified flies and copies the backups to the jdev-kelp directory. The jdeveloper.ini file specifies the class path. The ini file is located in the JDeveloper bin directory. The Windows releases also require updates to the jdeveloper.properties file. If you do not see the XMLC Compiler on the JDeveloper Wizard menu, check the jdeveloper.properties file for a line defining the add-in. Although the add-in number may be different, the line should appear similar to the following.
jdeveloper.addin.81=
You can check to see if you have installed the tools correctly by starting JDeveloper and looking for the XMLC Compiler wizard in the Wizards menu. If the menu does not appear, double check that you have both jars in the IDE class path and that jdev-kelp.jar precedes enhydra.jar. Oracle JDeveloper comes bundled with older versions of the org.wc3.dom classes that are not compatible with XMLC. The enhydra.jar file contains updated org.wc3.dom classes. To allow the XMLC Compiler wizard to run succesfully, the setup program will optionally remove the following three Oracle supplied jars from the IDE class path: dacfdtd.zip, jbodt.zip and xmlparserv2.jar. This will disable some of JDeveloper's HTML tag support. If you want to use the HTML tag wizards, you will need to restore the Oracle files back into the IDE class path and remove Kelp.
Setting the IDE Class PathAll the Kelp classes are included in jdev-kelp.jar. They are also included in the Enhydra 2.3 enhydra.jar file. If you are running with Enhydra 2.3, be sure you are running the latest versions of the Kelp classes by placing the jdev-kelp.jar file before the enhydra.jar file in the IDE class path. You can set the IDE class path through the jdeveloper.ini file. The ini file uses the code>Djava.class.path setting to control the class path. Be sure you shutdown JDeveloper before editing the jdeveloper.ini file. Using the WizardsKelp provides three wizards to help you develop Enhydra applications from within JDeveloper. Use the Enhydra Application wizard to create new Enhydra projects from the Object Gallery. You only need to use the Enhydra Application wizard when starting new projects. Once you have a project, you can use the XMLC Compiler and Enhydra Configure wizards to work with the project. The XMLC Compiler and Enhydra Configure wizard available on the JDeveloper Wizards menu. These wizards let you invoke Enhydra specific parts of the make system. Using the integrated build feature, you can invoke these same processes directly within the JDeveloper project builder without opening either wizard. The XMLC Compiler and Enhydra Configure wizards use a similar interface where you can select files, set options and view the build process using a three-tabbed dialog.
XMLC Compiler WizardThe XMLC Compiler wizard can compile HTML files into DOM classes. From the JDeveloper menu, select Wizards | XMLC Compiler to open the wizard. The wizard is only available when a project is open. If you do not see the XMLC Compiler option on you window menu, make sure that the jdev-kelp.jar and enhydra.jar files are listed in the JDeveloper IDE class path. The wizard is organized into a three-tab dialog. The tabs are Selections, Options and Output. The Selections tab displays all the html files in the currently selected project. You can use the buttons to add or remove files from the list selected to be compiled. Use the double arrow buttons to add and remove all files from the selection list.
The Options tab displays Make and Output options. You can use the Make options to customize the generated DOM classes. The Output options let you display detailed information during the compile process without effecting the generated classes. The Options tab also has an Invoke XMLC during Project Make/Rebuild. Select this option to call XMLC without opening the XMLC Compiler wizard. This will call XMLC when you build or make a project node that contains a selected html file. One common make option is to use a mapping table to customize generated class names. By default the XMLC Compiler wizard uses the current directory name to determine the package name in the generated source. Unless your html files are stored in the same directory as your presentation package Java source files, you will need to use the Mappings option to map the HTML directory to the presentation package name. The Lutris guidelines recommend that keep your HTML files in a resources directory and map them to the presentation package when generating the DOM classes. Both the Kelp sample project and the Enhydra DiscRack example store HTML files in a resources directory. To create mappings, check the Use Package Mapping Table option and click on the Edit button. This will open the map editor that lets you associate source directorys with package names. Click on Add Mapping to create a new mapping. You can enter a source directory or use the Set button to navigate to one. In the following dialog shows how to setup the compiler to use the package name:
when compiling html pages stored in:
The Output tab is automatically selected when you click on Compile. The Output tab contains a scrollable text area that displays the results of the compile. If you have any errors in your HTML files, the problems will appear on this tab. You can optionally save the output to a text file by checking Output to log file and entering a filename.
The output page displays the files that are created during the compile process. At the start of the compilation process, the wizard will erase any files that it may create during the process. If an HTML file contains a new error, the associated java and class will be erased but not regenerated. If you select the Options tab, you can set Make and Output options The Make tab includes three sections. The section for Generated Java Source informs you of what XMLC options need to be set for the current IDE. The Mappings section determines how to generate class names while the XMLC Option File section lets you select an XMLC Options file to set XMLC command line options. Refer to the XMLC documentation for a list of command line options you can use in an XMLC options file. Keep generated Java source is a read-only option that shows you if the Java files are saved for use by your IDE. Within the Mappings section, you can define a mapping table and set what nodes to use with the table. The mapping table lets you specify package names to use when generated DOM classes for a given directory. For example, the Kelp sample project uses a mapping table to map all the html files in a resources directory into the org.enhydra.kelp.sample.presentation package. To view or edit the package name mapping, select the Make tab and click on the Edit button. This opens the mapping table where you can add a new entry that maps a directory to the correct presentation package. Here is an example mapping for the Kelp sample project:
Source Directory: The Output settings do not effect the generated DOM classes. These settings cause the XMLC to stream out additional information when compiling the html files. For faster compiles, you should deselect all the Output options.
You can set if you want the project to use the map table or no. The filename, directory location and the project source path determine the default name. For example, if the you create a new Enhydra Application in...
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 HTML file is not located in a subdirectory of one of the Project source path settings, Kelp may not be able to generate a valid default class name. When using the package mapping table the package names is based on the directory of the HTML file. This is normally used to map a resources directory to a presentation package. There is only one mapping table per project. Enhydra Configure WizardThe Enhydra Configure wizard makes it easy quickly configure projects for your current environment and directory structure. The wizard can do two tasks. The first task is to generate configuration files from configuration templates. The second is to setup your project so you can launch your application using MulitServer. Configuration templates files with the extension conf.in. These files are configuration files with placeholders that are replaced with system specific information by the wizard. The default placeholder is @OUTPUT@ and it is replaced with the absolute path of your current output directory. While you do not need to use configuration templates for the Enhydra applications you develop, it is recommended as a way to quickly adapt your applications to different environments. You can customize the search and replace mechanism by editing Replace Text table on the Options tab of the wizard. The default option lets you quickly restore the default project settings. The replace with values can refer to relative paths. If you enter a value starting with a period, the wizard will substitute the directory containing the project file for the period. For example, if you open the Kelp sample project from:
...and have a Replace Text table containing:
Text to find:
The resulting configuration files (.conf) will contain... Setting up your project to run MultiServer can be done by setting the main class for the project to run or by creating a StartMultiServer.java helper class. Select the option to create a StartMultiServer.java file.
Using the Enhydra Application WizardThis section describes how to create a new Enhydra application with the Enhydra Application wizard. It also includes a few recommended settings for Enhydra projects. Before you run the Enhydra Application wizard, you should create a new project for the generated files. Running the Enhydra Application wizard while using a project that already contains Enhydra files, may cause unexpected results. Once you have a opened a new project, select File, New to open JDeveloper's Object Gallery. The gallery provides options for quickly generating many common classes. Double click on the Enhydra Application icon to open the wizard. The wizard provides the following four settings to control how your application gets generated.
After you have set the options you want, click OK to generate your Enhydra application. After generation is complete, you should view the newly generated Readme.html file that will be added to your project. The Readme.html shows the steps you need to build and run the application. The Kelp Sample ProjectKelp includes a sample project that demonstrates how to use XMLC, MultiServer and configuration templates within JDeveloper. If you are new to both Enhydra and Kelp, you can start learning Enhydra by running the Kelp sample application. The Kelp sample only demonstrates a small part of Enhydra's capabilities. Once you feel comfortable with the Kelp sample, you should examine the DiscRack example that comes with Enhydra 3.0. The DiscRack example provides a more complete application that incorporates JDBC access. You can run the DiscRack example using most JDBC compliant data sources including Oracle, Microsoft SQL Server and InstantDB. If you are already familiar with Enhydra, you can use this project to see how you can setup a project for your own applications. Configuring the SampleKelp includes the Enhydra Configure wizard that you can use to automatically configure the Kelp sample project. Before running the Enhydra Configure wizard or the Kelp sample, be sure to review the steps provided in the KelpSample.html file that is included with the project.
If port 9000 is available, you can start up MultiServer and view the sample pages without modifying the configuration templates. If you need to run on another port, you will need to modify the following line in the Connection.HttpConnSample.Port = 9000 When you modify files within JDeveloper, be sure to select File | Save All to commit the file to disk before running the Enhydra Configure wizard. The wizard may ignore changes made since the last save. If you are using a port other than 9000, the links within the KelpSample.html will fail. Add the port you are using to the URL. To use port 8080, enter http://localhost:8080/ as your URL. If localhost fails, try using the IP address 127.0.0.1 in place of localhost. The Enhydra Configure wizard creates two configuration files from the templates. The first file is the KelpSample.conf file. It has a Server.ClassPath[] setting that needs to point to where the compiled class files can be found. From JDeveloper, you can open up the Project properties dialog, select the Paths tab and see the required class path listed as the Output path.
The KelpSample.conf also has a AppRoot setting that the Enhydra Configure wizard sets to the sample application's root directory. This setting is used by the New Node page to locate the html to insert as a new node. It is also used by the Form page to locate the data property file. If you modify the configuration templates (conf.in files), be sure to run the Enhydra Configure wizard to regenerate the configuration files in the output directory. MultiServer will ignore any changes made to the templates that have not been regenerated as conf files in the output directory. The multiserver.conf file has a setting for where to find the KelpSample.conf file. It also has some settings for logging. You can find the first two settings near the top of the multiserver.conf file.
You'll find the additional logging filter setting near the end of the multiserver.conf file. If you want to take advantage of additional logging features, update these settings in the configuration template to match the version of Enhydra you are using. The Enhydra Configure wizard also sets up the sample project so that you can launch the application with MultiServer. It does this by setting the project's main run class or by generating a StartMultiServer.java program. In either case, the wizard sets the multiserver.conf file as a parameter to the MultiServer. The Sample PagesThe sample project consists of four presentation objects that show some of the common uses of XMLC. The sample is simplified in that it only contains a presentation layer. Production Enhydra applications will normally contain a least three packages including presentation, business and data. For a detailed explanation on how you can separate applications into these three functional areas, read Getting Started with Enhydra. If you have moved the Kelp sample after running Enhydra Configure wizard, you should run the wizard again before using the sample. See Configuring the Kelp sample project for more information.
Each Enhydra page is created through an HTML file and a Java file. The HTML files are located in a resources directory. Each HTML file is compiled into a class file using the XMLC Compiler wizard. There is a corresponding java file that implements
Setting Project PropertiesJDeveloper 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 JDeveloper is that you start the MultiServer from your JDeveloper project. The Enhydra Sample Project contains a StartMultiSever class that will lunch MultiServer with the sample application. While it defaults to using configuration files specific to the sample project, you can pass it the location of any multiserver.conf file. To run an Enhydra application you will need two configuration files. One for your application and one for MultiServer. The configuration file for MultiServer specifies the location of any application configuration files. A detailed description of Enhydra configuration files is available in the Enhydra MultiServer Administration Guide (PDF, 57 pages). Before you try debugging an application, make sure you can run the Kelp Sample successfully. If that is working correctly, try stepping through the following procedure to see how easy it is to debug an Enhydra application.
Working with the Open SourceThe Kelp classes are in the jdev-kelp.jar file. Setup installs the jar file in the jdev-kelp/lib directory within your JDeveloper directory. If you used the Custom setup option to install the open source, you will have three project files you can use to modify the three components that make up the JDeveloper wizard. The jdev-kelp.jpr file contains all the source files required to build the jdev-kelp.jar. These classes use Swing and JDeveloper's Add-in framework to implement the wizard. To use this file, you will need to create a library called JBuilder Addin Jars containing the pthelp3.1.jar, jbuilder.jar, jbuilder.zip and jdeveloper.zip. The pthelp3.1.jar and jbuilder.jar files are available with of JBuilder Foundation. The jbuilder.zip file is available with the Windows specific releases of JBuilder 3. The jdeveloper.zip file is available with Oracle JDeveloper 3. To work with a single IDE such as JBuilder Foundation, you can leave out the unrelated library files and remove the appropriate packages from the project. The IDE specific packages are as follows:
borland.public.jbuilder.opentools The Kelp Working GroupThe JDeveloper Kelp is part of Enhydra Kelp family of products. The Kelp Working Group is dedicated to making Enhydra technologies easier to use through the use of Java IDE add-ons. The working group has a mail list that use can use to post questions or suggestions for this or other Kelp products. View the mail list archive to get information on recent releases and tips on how to make the most of Kelp. You can also use the Kelp Working Group to contribute to the Kelp open source project. |