Contents

Before You Begin
Mounting the APPS and docs directories as Forte For Java filesystems
Creating a kjs StartEngine Class
Invoking the Application Server within Forte for Java
Attaching the Forte Debugger to the Application Server
Stopping the Debug Session

Before You Begin

You must have the following programs installed on your machine:

• The iPlanet Application Server version 6.0 and iAB 6.0.
• The iPlanet Web Server (Enterprise Edition)  4.1.
• Forte for Java Community Edition 1.0.1. You can freely download a copy at http://www.sun.com/forte/ffj/ce/download.html. You have to use the jdk 1.2.2 version with Forte for Java Community Edition in order to run or debug IAS applications (this is found in <IAS-INSTALL-DIRECTORY>\ias\usr\java\bin)
• The Java Platform Debugger Architecture Software addon correctly installed on top of the jdk1.2.2 version. To achieve that, unzip the jpda zip file and copy all the 5 files (*.dll and *.exe) from the bin directory to the jdk1.2.2\bin directory, and the jpda.jar file from the lib directory to the jdk1.2.2\jre\lib\ext directory. Overriding the jdb.exe file in the bin directory is OK.
• An IAS application developed and deployed using iAB that you want to debug. As an example, you can use the iAS 6.0 HelloWorld sample application instructions at http://developer.iplanet.com/appserver/samples/index.html, and create the application/
• Optionally, you can download the HelloWorld application (zip file) .
• Create a HelloWorld folder in the <WEBSERVER-INSTALL-DIRECTORY>\docs directory. (be careful with the capital H and capital W)
• Copy the HTML, GIF, and validate.js files from the above zip file into the HelloWorld folder.
• Create another HelloWorld folder in the <IAS-INSTALL-DIRECTORY>\ias\APPS directory.
• Copy all the other files from the above zip file into this HelloWorld folder.

Summary

Here is a summary of the steps involved in order to run/debug an IAS application with Forte for Java.

1. First of all, you have to add (or mount) the <IAS-INSTALL-DIRECTORY>\ias\APPS and <WEBSERVER-INSTALL-DIRECTORY>\docs directories as Forte for Java filesystems. A Filesystem can be seen as a CLASSPATH and SOURCEPATH entry in Forte for Java. Once they are mounted, you can see the content of these directories in the FFJ explorer window.
2. Then, You'll have to add  a few JAR files into Forte for Java in order to make them available for the IAS applications.
3. Then, we'll create a Java class in charge of starting from the IDE a kjs process.
4. We'll have to configure a special executor to set up the runtime parameters correctly for the kjs process.
5. Using the JPDA debugger, we can now attach the Forte for Java debugger to this running kjs instance and the debugger will stop on any breakpoints set on servlets or EJBs registered.

Remember that you will have to compile and deploy the servlets and EJBs with IAB before you can debug them into Forte For Java. Also, it is necessary to do the steps 1 to 4 only once if you want to debug more than one IAS application.

Mounting the APPS and docs directories as a Forte for Java filesystem

To mount the APPS and docs directories as a Forte for Java filesystem

1. Open Forte for Java Community Edition.
2. Select the Filesystems icon in the Explorer. Right click to display a pop-up menu and select Add Directory...(note: with FFJCE v2.0, the menu item has been renamed as Mount Directory...)


 
3. Select the <IAS-INSTALL-DIRECTORY>\ias\APPS directory:


 
4. For the docs directory, select the Filesystems icon in the Explorer. Right click to display a pop-up menu and select Add Directory... (or Mount directory...) and navigate to the <WEBSERVER-INSTALL-DIRECTORY>\docs directory and click the Add button


 

To add the neccessary JAR files into FFJ:

1. Select the Filesystems tab from the Explorer window.
2. Click to select the Filesystems icon. Right-click to display the pop-up menu and select Add JAR... (or Mount JAR...)

The Add JAR Archive window appears.
3. Add the following JAR files:

<IAS-INSTALL-DIRECTORY>\ias\lib\java\kfcjdk11.jar
<IAS-INSTALL-DIRECTORY>\ias\lib\java\jdbc20.jar
<IAS-INSTALL-DIRECTORY>\ias\lib\java\javax.jar
<IAS-INSTALL-DIRECTORY>\ias\usr\java\jre\lib\ext\iioprt.jar
<IAS-INSTALL-DIRECTORY>\ias\classes\java\servlet.jar


Once you have added each file, it should appear in the Filesystems tab for your project.

Creating a kjs StartEngine Class

To create a StartEngine.java:

Now we need to create a Java class that when executed will start a kjs process from the Forte for Java IDE itself. This is this process that we'll use to connect the FFJ debugger, allowing us to debug IAS applications.

Note: If you used the Helloworld.zip file, it contains the StartEngine.java file and you can skip the creation step.

1. From the Explorer window Filesystems tab, select a java package where you want to create the Java class. In this example, we'll use the HelloWorld package. Right-click to display the pop-up menu and select "New From Template...", "Classes", "Empty" meu item as follow:

 

 
 
 
 
 



The New From Template - Target Location window appears.
 

2. In the Name field, enter StartEngine as the name, and click the finish button.


3. The StartEngine.java file is opened in the Forte For Java editor.
4. Add the following code in the editor for the StartEngine file.


5. Right-click on the StartEngine file in the Explorer window to display the pop-up menu.
6. Select Compile...
7. Save your work by selecting Save All from the File menu.

This code, when executed will start a kjs process. But we are not done yet. We must also configure a special executor for this java class:

To create a special executor for the kjs class

1. Select the Project Menu and The "Settings" menu item.
2. Expand the Execution Types node to display the External and Internal Execution.
3. Right-click on the External Execution node to display a pop-up menu.


(Note: with Forte for Java CE V2.0, the way to create a new executor is by using the popup menu on the Execution Types node and selecting the New then External Execution Service menu item.)
4. select New External Execution Service.

A new sub-node appears labeled External Execution.


 

5. Double-click on the External Execution sub-node to display the properties window.


6. Select the Identifying Name field to edit it.
7. Enter the name iPlanet and click elsewhere.
8. Select the External Process field to display the  icon.
9. Select the  to open External Process Property Editor.
10. In the Arguments field type the following arguments (as one single line) and click OK:

-classic -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n

-Djava.compiler=NONE -Djava.library.path=D:\iPlanet\iAS6\ias\bin

-cp {filesystems} {classname} {arguments}


Where D:\iPlanet\iAS6\ias\bin is the location where you have the iPlanet Application Server installed.
Be careful: the Arguments entry field must be a single line. Remove any extra carriage return chars.



11. You've just created an iPlanet executor. Now we need to tell the StartEngine class to use this executor. In the Explorer, select the StartEngine java class. Activate the popup menu on it and select the "Properties" Menu item. In the Properties Window, select the "Execution" tab. In the Executor property, select the newly created iplanet executor:


Congratulations: you've just modified the Executor property for the StartEngine Class. Now on, whenever you execute the StartEngine class, you will launch a kjs java process with the correct execution flags.

Invoking the iPlanet Application Server within Forte For Java

To invoke iAS from the Forte for Java IDE

1. From the DOS command prompt, launch KXS by typing:

start kxs

A DOS window appears identifying the server initialization process and launches the server.

You are now ready to execute the StartEngine java class from the IDE.

2. In the Explorer Filesystems  Tab, select the StartEngine java class.
3. Activate the popup menu on the StartEngine java class ans select the 'Execute' menu item. An output message appears identifying that the server has been started. When you see the message that the engine is ready, then you are ready to test your application.

4. Open a browser and type the following URL in the location field:

http://<yourmachinename base URL>/yourprojectname>/Hello

In this example, the machine name base url is pc541437/NASApp, and the project name is HelloWorld.



5. Test the application to ensure proper functionality.

Attaching the Forte debugger to the Application Server

To attach the Forte debugger to the Application Server:

1. Set breakpoints in the Servlets and EJB's.
2. Make sure that a kxs process is already running from a DOS session outside the IDE.
3. Select the StartEngine class in the Forte For Java Explorer window.
4. Select the Execute button or the execute popup menu item
5. Review the Output window to verify the KJS has been started.

 

 
 






The Port Number is the first line in the Output window. Take note of this number so you can enter the right number in the following steps. In the example above, this number is 2022.
6. Review the messages window to verify that the Engine is ready.
7. Select  "Connect..." from the Debug menu in the Forte for Java menu bar. (Note: with FFJCE V2.0, the menu item has changed to "Attach to VM...".)
8. From the Connector pop-up menu, select the "socketAttach (Attaches by socket to other VMs)" to connect to the running kjs virtual machine.
9. Enter the Port Number in the Port entry field and click OK.





10. Note: I you don't see the dialog as it is in this tutorial, it means that you did not installed  the Java Platform Debugger Architecture Software addon correctly on top of the jdk1.2.2 version used by Forte For Java.
11. Run your application in a browser.
12. When the debugger stops at the specified breakpoints, select Continue.

Stopping the Debugging Session

To stop the debug session:

1. When the debugger has gone through all the breakpoints, stop the debugger by selecting Finish Debugging from the Debug menu.
2. Open the View Execution window and terminate th process for the StartEngine class.

Copyright © 2000, Sun Microsystems Inc. All rights reserved.
Copyright © 2000, Netscape Communications Corporation. All rights reserved.

Sun, Sun Microsystems, the Sun logo, Java, iPlanet, and the Sun, Java, and iPlanet-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the U.S. and other countries. Other Netscape logos, product names, and service names are also trademarks of Netscape Communications Corporation, which may be registered to other countries.