Integration Guide for iPlanet Application Server 6.5 in JBuilder 8 Enterprise

Abstract: Integration Guide for iPlanet Application Server 6.5 in JBuilder 8 Enterprise

[Note: JBuilder 8 officially supports only iAS 6.5 SP0, but supplementary instructions are provided for also integrating with iAS 6.5 SP1 (in blue)]

A. Preliminary requirements:

The following products must be installed on a single machine before beginning:

1. iAS 6.5 SP0 (& SP1) (Please refer to the official documentation for iAS for help regarding installation)

* Officially supported under NT 4 SP5

* Installation requires that the machine is a part of a network domain

* Installation to Windows 2000 requires a loopback network device, if using DHCP. This is because iAS requires a static IP number to communicate between processes. You can get around this problem by installing the `loopback' network device that is supplied with Windows 2000. This can be assigned an arbitrary IP number-- iAS will accept this as a valid IP number.

    1. Installing the Microsoft Loopback Adapter on Windows 2000 (If your computer already uses a static IP, these steps are not necessary)::

    a) Start | Settings | Control Panel | Add-Remove Hardware | Next

    b) "Add/Troubleshoot a new device" | Next.

    c) "Add a new device" | Next.

    d) "No, I want to select the hardware from a list" | Next

    e) Select "Network adapters" | Next

    f) Select "Microsoft" from Manufacturers and then select "Microsoft Loopback Adapter" | Next.

    g) Next | Finish

    2. Configuring TCP/IP settings for the Loopback Adapter:

    a) Start | Settings | "Network and Dial-up Connections"

    b) Rename "Local Area Connection2" to "Local Area loopback"

    c) Right click on it and choose Properties.

    d) Select "Internet Protocol (TCP/IP)" and click on the Properties button

    e) Choose the radio button "Use the following IP address:"

    Example:

    IP address: 69.254.0.2.
    Subnet mask: 255.255.0.0

    f) Choose: "Use the following DNS server addresses"

    127.0.0.1

    g) OK

2. iWS 6.0 (integrated with iAS)

Note:. Install iWS prior to installing iAS. During the iAS installer, it will ask to integrate with the existing installation of iWS.

3. JBuilder 8 Enterprise Edition

B. Integrating JBuilder 8 Enterprise Edition with iAS 6.5:

1. In JBuilder, choose Tools | Configure Servers... | iPlanet Application Server 6.x+ | under the General tab, check "Enable Server."

For iAS 6.5 SP1:

1. In JBuilder, choose Tools | Configure Servers... | iPlanet Application Server 6.x+ | under the General tab, check "Enable Server." Next, under the Class sub-tab, click the Add... button and multi-select all of the following JARs:

../ias/classes/java/buzz_properties.jar

../ias/classes/java/jts_properties.jar

../ias/classes/java/kadmin_properties.jar

../ias/classes/java/kfcjdk11_properties.jar

../ias/classes/java/tomcat/jasper_properties.jar

2. Then under the Custom tab, verify that "Add iPlanet Tools to Tools menu," and the iAS JDK installation directory is filled out (e.g. ../ias/usr/java).

C. Creating a new project

1. Choose: File | New Project | type a new name for the project | Finish

2. Choose Project | Project Properties | Server, and choose "iPlanet Application Server 6.x+" from the combo box. Notice that JBuilder automatically added the client library (iPlanet 6.x+ Client) to the Paths | Required Libraries.

3. In the Project Properties, choose | Paths | JDK | and choose the JDK that is defined with iAS (e.g. the JDK in ../ias/usr/java)

D. Create a new Web Application

1. Choose: File | New | Web | Web Application | OK | type in a name | OK

E. Create a new JSP

1. Choose: File | New | Web | JavaServer Page | OK | Finish

F. Create a new Servlet

1. Choose: File | New | Web | Servlet | OK | Finish

2. Use the iAS tool, "../ias/bin/kguidgen.exe" to generate a GUID for your servlet (not necessary for JSPs). (e.g. {bd498e61-3c98-11d4-a006-0010a4e78553} )

3. Edit the "ias-web.xml" (under the "Deployment descriptor" WebApp subnode), and add the GUID:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ias-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD iAS Web Application 1.0//EN" "http://developer.iplanet.com/appserver/dtds/IASWebApp_1_0.dtd">
<ias-web-app>
<servlet>
<servlet-name>servlet1</servlet-name>
<guid>{bd498e61-3c98-11d4-a006-0010a4e78553}</guid>
<servlet-info>
<sticky>false</sticky>
<encrypt>false</encrypt>
<number-of-singles>10</number-of-singles>
<disable-reload>false</disable-reload>
</servlet-info>
</servlet>
</ias-web-app>

G. Compiling the project

1. Project | Rebuild Project.

H: Configuring the Run Configuration for the Server

1. Run | Configurations... | and in the Run tab of the Project Properties, select the run configuration listed (for the JSP) and click the Edit... button.

2. In the "Runtime Configuration Properties" dialog, rename this runtime configuration to "Server"

3. In the same dialog, choose: Run | Category | Server | Archives | & uncheck the WAR from the "Project archives to deploy at runtime"

4. In the same dialog, choose:: Run | Category | Services | JSP/Servlet | & change the Port Number to the port of the web server (iWS default is 80).

[Note: this Run configuration will be used to merely start iAS from within JBuilder. It will not automatically deploy any archives when the server is launched--they will be deploy manually later in this document]

I: Stopping iWS using the Control Panel's services tool

1. Due to an issue with iAS, use the Windows Control Panel to manually STOP the iPlanet Web Server (iWS). This step may be ignored with iAS 6.5 SP1.

J. Starting iAS from within JBuilder

1. Right-click on the WebApp node and choose Web Run using 'Server'. iAS should startup normally.

[Note: If you instead want to debug, choose: Web Debug using 'Server'. Also, verify that the server is starting up in debug mode using the dt_socket transport mechanism. If it is using dt_shmem, and you experience intermittent crashing when debugging on Windows, you may force the use of dt_socket.dll by renaming the dt_shmem.dll in the iAS JDK itself (rename to dt_shmen.dll.bad). This is a known issue with certain versions of Sun's JDK.]

For iAS 6.5 SP1:

The following error may appear in the message pane when launching iAS within JBuilder, but can be ignored.

*** Couldn't load resource for "tools". ***
Localize.loadStringTable - 2: java.util.MissingResourceException: Can't find bundle for base name com.iplanet.ias.tools.buzz.resources.properties.deploy, locale en_US

2. Look for the following output in the message pane to verify that the server started up successfully:

[date time] info ENGINE-ready: ready: 10819

If the server failed to launch correctly, and you received an error message that the KJS service could not be started/stopped, complete the following step and then try starting the server again (this should only need to be done once):

Tools | iPlanet Administration Tool | & when it loads, expand the "Registered Servers", select kjs, and then click on the "Stop Process" button | close the "iPlanet Administration Tool"

K: Starting iWS using the Control Panel's services tool

1. Now that the iAS is started within JBuilder, use Windows Control Panel to manually START the iPlanet Web Server (iWS). This step may be ignored with iAS 6.5 SP1.

L: Deploying the WAR to iAS within JBuilder

1. Right-click on the WebApp node and choose: Deploy Options of "<WebApp name>.war" | Deploy

[Note: The WAR should deploy successfully. If the JSP attempts to load in the Ice Browser, close it.]

M: Running the JSP within JBuilder

1. Now, right-click on the JSP itself and choose Web Run using 'Server'. The JSP should load in the Ice Browser.

[Note: If you started up iAS in debug mode (in step J), set a breakpoint on a tag within the JSP source, right-click on the JSP and choose: Web Debug using 'Server'. This may take a while, just be patient. After a time, execution will stop at the breakpoint in the JSP source.]

An example URI for a JSP (replace: <host name> with the name of your machine; <web node name> with the name of your WebApp module; <jsp name> with the file name of your JSP) :

http://<host name>:80/NASApp/<web node name>/<jsp name>.jsp

N: Running the servlet within JBuilder

1. Now, right-click on the servlet itself and choose Web Run using 'Server'. The servlet should load in the Ice Browser.

[Note: If you started up iAS in debug mode (in step J), set a breakpoint within the doGet method in the servlet source, right-click on the servlet and choose: Web Debug using 'Server'. This may take a while, just be patient. After a time, execution will stop at the breakpoint in the servlet source.]

An example URI for a servlet (replace: <host name> with the name of your machine; <web node name> with the name of your WebApp module; <servlet name> with the file name of your servlet) :

http://<host name>:80/NASApp/<web node name>/<servlet name>