Enhydra Tools
for JBuilder
|
|
Introduction
This document describes how to use JBuilder to develop Enhydra applications.
It assumes a basic understanding of the JBuilder IDE and the Enhydra
Application Framework. For information on JBuilder, visit the
Borland website.
An overview of Enhydra can be found at
the Enhydra
documentation page. These tools have been developed for the XMLC
implementation of presentation objects. While you may use JBuilder
to develop JDDI presentation objects, there are currently no wizards
for JDDI.
Features:
- Enhydra Application Wizard
The application wizard generates an XMLC application allowing you to
develop, run and debug your project using Enhydra MultiServer
and the XMLC Compiler from within JBuilder.
- XMLC Compiler Wizard
The compiler wizard lets you set XMLC options, select HTML files to
compile and call the XMLC compiler from with JBuilder.
-
XMLC Sample Project
This project demonstrates techniques for creating dynamic
web pages with XMLC.
System Requirements
- Windows Systems
- Linux Systems
- Solaris Systems
The only file the Enhydra Tools for JBuilder requires from Enhydra 2.3
is ennydra.jar. Note that the Enhydra Tools for JBuilder will not work
with Enhydra 2.2.1 or earlier versions.
Installing the Tools
Before installing the Enhydra Tools for JBuilder, you need to already have
JBuilder 3 and Enhydra 2.3. You can find installation
instructions for Enhydra at
the Enhydra
download page. It is recommended that you go through each step
listed on the download page so you can run the Multiserver
administration application. If you install JBuilder prior to
installing Enhydra, you can skip the step about downloading Java.
You can configure Multiserver to work with the Java 2 files that
come with JBuilder.
Installing on Windows
The jb-kelp.exe file is a self-extracting InstallShield setup
program. Before running the installer, close any open instances of
JBuilder and note where your JBuilder and Enhydra files reside.
You will need to tell the setup program what edition of JBuilder 3 you
are running. If you are running the free all Java version, select
Foundation. The JBuilder About box includes the name of the
edition you are currently running.
The setup program will look up your JBuilder folder in the
registry. If you have installed JBuilder in more than
one folder, you may need to click on Browse in the Choose JBuilder
Folder step to select the location of the JBuilder you want to use
with Enhydra. The sample Enhydra project, documentation and tool
files will be installed in an jb-kelp folder under the JBuilder
folder.
After selecting the JBuilder folder to use for installing the tools, you
need to tell the setup program where to look for the enhydra jar
files. By default, the setup looks in:
c:\usr\local\enhydra\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
JBuilder class path in the JBuilder.ini file. The setup program
also creates an Enhydra XMLC library for the
jars so you can use them with your JBuilder projects.
The setup program provides you with three types of installations:
Typical, Compact and Custom. Typical installs the tools, this
documentation and a sample project. Compact installs only the tools.
Select the Custom option if you want the Java and C++ open source
for the tools.
After selecting the type of installation you want, setup prompts you for
the program group folder and lists all your selections for
confirmation. When you confirm the settings, the installer will copy
files into an jb-kelp folder within the JBuilder folder. It also
modifies the library.ini, jbuilder.ini and jbuilder.proeprties
files. Some of the modifications will not be reversed if you
uninstall the Enhydra Tools for JBuilder. To allow you to restore
your original configuration, the setup program creates backup of
each the three modified flies and copies the backups to the jb-kelp
folder. If you installed the sample project, the setup program also modifies
your JBuilder desktop so that the sample project appears the next
time you start JBuilder.
Installing
on Linux and Solaris
To install the Enhydra Tools for JBuilder on Linux or Solaris, download
the jb-kelp.zip file. Unzip this file under your JBuilder installation
folder. The zip contains the jb-kelp folder to place within the JBuilder
folder. If you have installed JBuilder to /usr/local/jbuilder30, you should
end up with the tools installed in /usr/local/jbuilder30/jb-kelp.
After unzipping the file, add the jb-kelp.jar and the enhydra.jar files
into the class path that JBuilder uses to startup. The JBuilder startup
class path is set in the jbuilder startup script. This script is in the bin
directory of your JBuilder folder. The jb-kelp.jar is located the
jb-kelp/lib directory. If JBuilder is in /usr/local/jbuilder30, the
startup script will be in /usr/local/jbuilder30/bin and the jb-kelp.jar
will be in /usr/local/jbuilder30/jb-kelp/lib. Use the enhydra.jar
file that is included with Enhydra 2.3. See
Setting the IDE Class Path for more information.
You can check to see if you have installed the tools correctly by starting
JBuilder and looking for the XMLC Compiler Wizard in the Wizards menu. If the
menu does not appear, double check that you have both jars in the IDE class path
and that jb-kelp.jar preceeds enhydra.jar.
Configuring the EnhydraSample project
Before using the the Enhydra Sample project (EnhydraSample.jpr), you should
move it from the /usr/local/jbuilder30/jb-kelp/sample directory to the
jbprojects directory that is located in your home directory.
The html files selected for XMLC are in an html directory rather than in the
presentation directory. The DOM classes require a package name of
org.enhydra.jbuilder.sample.presentation. To get the correct package
name generated, you will need to 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 the html directory to the correct
presentation package. If you copied the sample into a home directory called
bob, the mapping would look like this:
Source Folder:
/home/bob/jbproject/sample/org/enhydra/jbuilder/sample/html
Package Name:
org.enhydra.jbuilder.sample.presentation
The sample includes two configuration files that tell Enhydra where to
find tings. The first file is the EnhydraSample.conf file. It has a
Server.ClassPath[] setting that needs to point to where the
compiled class files can be found. For the "bob", example, the classes
directory would be /home/bob/myclasses. From JBuilder, you can open
up the Project properties dialog and see the required class path listed under
Output path.
The EnydraSample.conf also has a AppRoot setting that you need to
set 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.
AppRoot = "/home/bob/jbproject/sample/"
Be sure to save any modifications before trying to run the application.
MultiServer will ignore any changes that have not been
commited to disk.
The multiserver.conf file has a setting for where to find the
EnhydraSample.conf file. It also has some settings for logging. The
first two settings you need to modify are near the top of the server
configuration file. You'll find the third setting near the end of the file.
is an example of the settings you would need to edit when running from
a /home/bob directory.
Server.ConfDir = /home/bob/jbproject/sample/conf
Server.LogFile = /home/bob/jbproject/sample/log/multiserver.log
Filter.StandardLogger.InitArgs.logFile = /home/bob/jbproject/sample/log/access.log
If cannot run on port 80, you will need to select another port by
changing the Connection.HttpConnSample.Port setting in the
multiserver.conf file.
The last item you need to change before making or running the sample project
is the argument to MultiServer that appears in the StartMultiServer.java
program. Here you need to set the argument element to the path of the
multiserver.conf file. Following the bob example, the setting would look like:
args[0] = "/home/bob/jbproject/sample/conf/mutliserver.conf";
Setting the IDE Class Path
The Kelp classes are included in both jb-kelp.jar and enhydra.jar. The
newer versions are in jb-kelp.jar. Be sure you are running the
latest versions of the Kelp classes by placing the jb-kelp.jar file
before the enhydra.jar file in the IDE class path.
Note: Earlier versions of Kelp included a jb3enhydra.jar file. If
you installed an earlier version, you should delete jb3enhydra.jar and
remove it from your IDE class path. The jb3enhyda.jar file was installed
into an enhydra/lib directory within your JBuilder directory.
In JBuilder Foundation, the IDE class path is set in JBuilder startup
script. The script resides in JBuilder's bin directory. When installed on
Windows, the startup script is a batch file and Kelp classes can be set
with the tempcp variable.
If you are running one of the Windows only editions of JBuilder 3, you
can set the IDE class path through the jbuilder.ini file. The ini file uses
the Djava.class.path setting to control the class path. Be
sure you shutdown JBuilder before editing the jbuilder.ini file.
The
Enhydra Sample Project
The sample project consists of four presentation objects that shows 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 the Enhydra
Architecture White Paper.
Each Enhydra page is created through an HTML file and a Java file. The
HTML files are located in the sample projects HTML folder. Each HTML
file is compiled into a class file using the XMLC Compiler Wizard.
There is a corresponding java file that implements HttpPresentation
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 com.lutris.jbuilder.sample.presentation
package. The four presentation objects consist
of the following pages:
- Greetings
Page - This is similar to a traditional Hello World example.
This page contains one HTML element that is set through XMLC to
greeting the user with a phrase contained in the application
configuration file. You can update the configuration file to
change the greeting.
- Table
Page - One of the most common tasks for dynamic HTML
generation is populating an HTML table. This page 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.
- HTML
Page - XMLC allows you to add a span containing valid HTML
elements to a 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
Page- You can use XMLC with HTML input fields to create
data entry forms. This page 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.
To run the sample, you will need to first compile the html pages with
XMLC. You can do that using the XMLC Compiler Wizard. If port
80 is available, you can start up MultiServer and view the sample
pages without modifying any configuration files. If you need to run
on another port, you will need to modify the following line in the
multiserver.conf file. The configuration file is located in the conf
folder of the sample project.
Connection.HttpConnSample.Port = 80
When
you modify files within JBuilder, be sure to select File | Save All
to commit the file to disk before starting the multiserver. The amplification
will ignore any changes made since the last save.
If
you are using a port other than 80, the links within the project
HTML file 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.
Using
the XMLC Compiler Wizard
The
XMLC Compiler Wizard is a JBuilder add-in wizard that can compile
HTML files within your project into presentation object using XMLC.
From the JBuilder menu, select Wizards | XMLC Compiler Wizard to
open the wizard. The wizard is only available when a project is
open.
If
you do not see the XMLC Compiler Wizard option on you window menu,
make sure that the enhydra.jar and jb-kelp.jar files
are listed in the JBuilder IDE class path. This is the class path
specified by the jbuilder.ini file. The ini file is located in the
JBuilder bin directory. If the files exist as specified in the class
path, check the jbuilder.properties file for a line defining the
add-in. Although the add-in number may be different, the line
should appear similar to the following.
jbuilder.addin.73=com.lutris.jbuilder.wizard.compile.CompileWizard
The
wizard is organized into a three tab dialog. The tabs are Pages,
Options and Output. The
first tab is Pages. This tab displays all the html files in the
currently selected project. By default all files are selected except
the project HTML file that displays the project name and author. 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
second tab provides compiler options. 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 folder 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. Since it is recommended that you do
not store your HTML files in the same directory as your Java source
files, you almost always want to use the Mappings option.
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 folders with package names. Click on Add
Mapping to create a new mapping. You can enter a source folder
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 com.lutris.jbuilder.sample.presnetaion when compiling html
pages stored in the E:\Jbuilder3\enhydra\sample\com\lutris\jbuilder\sample\html folder.
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.
Using the Enhydra Application Wizard
This
section describes how to create a new Enhydra epplication with the
Enhydra Application Wizard. It also includes a few recommended settings
for Enhydra projects. Before you run the Enhydra Application Wizard, you should create
a new project for the generated files.
Running the Enhydra Application Wizard while using a project
that already contains Enhydra files, may cause unexpected results.
Once you have a opened a new project, select File, New to
open JBuilder's Object Gallery. The gallery provides options for
quickly generating many common classes. Double click on the Enhydra
Application icon to open the wizard. The wizard provides the following
four settings to control how your application gets generated.
- Enhydra Home
The Enhydra home is the directory where Enhydra is installed. The
default for Enhydra 2.3 is /usr/local/enhydra2.3 . The
wizard needs this information to correctly generate make files.
- Root to generate new application under
The wizard will create a new directory to hold application files.
The new directory will be in the root directory you specify. You can
use the same root for all your Enhydra projects.
- Name for new application directory to create
The application name is used as the name of the directory created
under the root. It is also used to name the application's
top level class and configuration files. The application name
must be a valid Java identifier.
- Package to use in generated classes
All the generated classes will belong to the package you specify. This
must be a single package name. The data, business and presentation
packages will be placed within this top level package.
After you have set the options you want, click OK to generate your
Enhydra application. After generation is complete, you should view
the the newly generated Readme.html file that will be added to your
project. The readme contains the steps you need to build and run the
application. The steps will very depending on what version of JBuilder
you are using.
Setting Project Properties
JBuilder 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.
On
the paths page, you'll need to set the root directories and add the
Enhydra XMLC library. The Source directory is where the compiler
will look for Java files and packages to compile. Packages names
start in this directory. If you prefix your packages with com, then
the com folder will be located directly under the Source directory.
When using package names, all the source files will be in
subdirectories under the Source directory.
The
Output directory specifies where you want class files to be created.
You should keep the Output separate from the Source to make it the
Output directory match what the contents of a production jar
file.
The
only required library for Enhydra applications is the Enhydra XMLC
library created by the Enhydra Tools for JBuilder setup program. The
first time you add this to a project, JBuilder will create dependency
files for it. The dependency files help speedup the build process.
The Enhydra 2.3 library consists of enhydra.jar. If
you are using JDBC in your application, you will also need to add
the JDBC driver as a library.
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 check this option you may
get warnings that the compiler cannot locate the source files for
your presentation objects. Since the XMLC Compiler Wizard already
compiled the presentation objects for you, it is safe to ignore
these warnings. You can uncheck the Show warnings option to suppress
the warnings.
On
the Run/Debug tab, select the Execution Log option under Console
I/O. This sends output from your applications to a scrollable
window. Before you run something such as a multiserver startup
program, you can select View | Execution Log to open the output
window.
Debugging
Enhydra Applications
The
only requirement to debug Enhydra applications from JBuilder is that
you start the multiserver from your JBuilder project. The Enhydra
Sample Project contains a StartMultiSever class that will lunch
Multiserver with the sample application. While it defaults to using
configuration files specific to the sample project, you can pass it
the location of any mutliserver.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.
Before
you try debugging an application, make sure you can run the Ennydra
Sample successfully. If that is working correctly, try stepping
through the following procedure to see how easy it is to debug an
Enhydra application.
- Make
sure multiserver is not running.
- Open
the EnhydraSample project
- Select
the Table.java file in the
com.lutris.jbuilder.sample.presentation package.
- 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.
- Select
StartMultiServer.java.
- From
the menu, select Run | Debug. This will start the debugger. Note
that the debugger will open an command window even if you have
selected Execution Log for console I/O.
- Open
the table page in your browser. This will trigger the breakpoint
as shown below.
- 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
XMLC Compiler Wizard consists of the jb-kelpa.jar, winotter.dll
and bcjhide.exe. Setup installs the jar file in the jb-kelp/lib
folder within your JBuilder directory. The dll is placed in
the JBuilder bin directory and the exe is copied to the Windows
directory. If you used the Custom setup option to install the open
source, you will have three project files you can use to modify the
three components that make up the JBuilder wizard.
The
jb-kelp.jpr file contains all the source files required to build
the jb-kelp.jar. These classes use Swing and JBuilder's Add-in
framework to implement the wizard. To use this file, you will need
to create a library called JBuilder classes containing the
jbuilder.zip file from the JBuilder lib directory. Documentation for
the OpenTools SDK that was used to create the wizard is available
with the Professional and Enterprise version of JBuilder.
The
bcjhide.bpr is a C++ Builder project for compiling the bcjhide.exe.
The wizard uses this file to hide the command window when calling
the Borland Java Compiler from XMLC. It works with a bcjhide.ini
file that is located in the same directory as the exe.
The
winotter.bpr is a C++ Builder project for compiling the java native
interface winotter.dll. The wizard calls functions within this dll
to navigate through directories and to create bcjhide.ini. A
makehead.bat file is included to generate the Native.h header from
the Native.java source file.
Copyright 2000 Lutris Technologies, Inc.
All rights reserved.
JBuilder is a trademark of Inprise Corporation.
InstallShield is a registered trademark of InstallShield Corporation.
|