The iPlanet Application Server 6.0, is a fully J2EE-compliant server, and follows the Netscape Application Server 4.0 (NAS 4.0) and NetDynamics 5.0 release. This document includes a summary of new features, bug fixes, and workarounds, in the following sections:
For background information on iPlanet Application Server 6.0 see: http://docs.iplanet.com.
This section summarizes the features added with this release:
The iPlanet Application Server 6.0 is fully compliant with J2EE 1.2 standards. J2EE contains the following components:
For installation on a machine with an earlier release already installed on it, even an earlier release of iPlanet Application Server 6.0, the earlier release must be uninstalled first. Make sure to follow the uninstall instructions of the earlier release carefully so that the uninstall will be complete. Only one instance of iPlanet Application Server should be running per machine on Windows NT. Do not install multiple iPlanet Application Servers on the same machine. On Solaris only, instances of both NetDynamics and iPlanet Application Server 6.0 can be installed on the same machine.
Prepare for iPlanet Application Server installation by:
Before beginning installation of the iPlanet Application Server, be sure the system meets the following requirements:
Device |
Requirement |
Computer/Operating system |
Sun UltraSPARC running Solaris 2.6 or Solaris 8 |
Memory |
Per CPU: 128 MB minimum; 256 MB recommended |
Available disk space |
Total disk space: 200 MB NT, 400 MB Solaris, 800 MB Solaris if
installing both NetDynamics and iPlanet Application Server 6.0 |
Other software |
One of the following web servers: iPlanet Directory Server 4.0 (bundled) or 4.11 One of the following web browsers: Database connectivity software (see the following table) |
DB Client |
DB Server |
Oracle 8.1.5 |
Oracle 8.0.5, 8i, 7.3.4 |
Sybase 11.1.1 |
Sybase 11.9.2, 12 |
DB2 5.2 |
DB2 5.2, 6.1 |
ODBC 3.51 |
Microsoft SQL Server 7 |
Informix 2.1 |
Informix Server 7.3 |
iPlanet Application Server 6.0 bundles Solaris Production JDK 1.2.2_05a for SPARC. For proper operation of the Application Server, the following Solaris patches need to be applied to the system:
Patch Id |
Description |
105490-07 |
Linker Patch |
105568-14 |
Libthread Patch |
105210-25 |
LibC Patch |
106040-13 |
X Input & Output Method Patch |
105633-30 |
OpenWindows 3.6: Xsun Patch |
106409-01 |
Fixes the Chinese TrueType fonts |
108091-01 |
SunOS 5.6: ssJDK1.2.1_03 fails with fatal error in ISO8859-01 Locales |
105181-17 |
Kernel Update (socket close/hang) |
105669-09 |
CDE 1.2: libDTSvc Patch (dtmail) |
105284-31 |
Motif 1.2.7: Runtime library patch |
These patches are NOT bundled with iPlanet Application Server 6.0 distribution. They can be downloaded from: http://www.sun.com/software/solaris/java/download.html.
Click on the Solaris SPARC Platform Edition link, under J2SE: Java 2 Standard Edition (1.2.2_05a). Registration or login is needed to access the download page.
It is safe to apply a higher revision patch (the trailing two digits). For the latest patches, check:
Download the README, Developers Guide, and Release Notes for more information on how to tune and use the JDK 1.2.2_05a.
Although Solaris 8 does not need any patches, to work around a Solaris libthread bug (4326537), use libthread.so from /usr/lib/lwp. This has the effect of using Bound Solaris threads instead of user level threads; enhancing stability without impacting performance.
Arguments can be supplied to the Solaris JDK can be set via the JAVA_ARGS shell variable in kjs shell script.
Settings with JVM flags, particularly -Xms and -Xmx flags, specify the starting and maximum heap size that is used by each kjs engine. This decision will be based on how much memory is available on the system, and how much can be set aside for Java Object heaps. Set these as large as possible without starving other applications running on the same server. The default starting heap size is 8mb, and grows automatically if the dataset is large. Starting with a large heap size will avoid frequent garbage collection during growth; use -Xmx flag to cap the size. The JDK documentation provides more information on these and other flags.
To turn off the Just In Time Compiler ( for example, to get line numbers in Exception Stack traces during debugging) add -Djava.compiler=none to the JAVA_ARGS variable in kjs script (See above).
No patches are needed to run JDK 1.2 on the Solaris 2.8 platform
Currently Java HotSpot Version 2.0 RC2 is bundled with iAS6.0. When a final version of Java HotSpot 2.0 is released, it will be bundled with a subsequent release of iPlanet Application Server.
Java runtime related properties specific to the Application Server operation are under: My Computer \HKEY_LOCAL_MACHINE\SOFTWARE\iPlanet\Application Server\6.0\Java in the Windows NT registry.
Apply arguments to the Java runtime by setting the flags in the Registry variable JavaArgs. The ClassPath is preset to include all necessary classes and .jar files, including deployed applications. Due to a bug in HotSpot 2.0 RC2, the first entry in ClassPath (before the first ;) is ignored. As a workaround, a dummy entry hotspotbug.jar has been added. Applications needing to extend this ClassPath setting can append to this entry.
LibPath is set to point to all native dlls needed by the application server. Applications that use native code dlls, can append to it, if necessary.
To turn off the Just In Time Compiler, (for example to get line numbers in Exception Stack traces during debugging), add -Xint to JavaArgs variable in registry (See above).
The documentation for iPlanet Application Server 6.0 is available both on the iAS CD-ROM disk at the top level under the iasdocs directory and online in pdf format. Ignore the documentation currently installed with the product in the <install-dir>/ias/docs directory and use the documentation either in the iasdocs directory of the CD-ROM or download the most recent versions at the iPlanet site: http://docs.iplanet.com.
Installation instructions are included on the iPlanet Application Server 6.0 product CD-ROM disk, at the same level as the Release Notes file.
Contains instruction for migrating 2.1 or 4.0 NAS applications /extensions to iPlanet Application Server 6.0 specifications. Chapter 6 discusses migration for NetDynamics 5.0. Refer to: http://iplanet.com/support/technical resources for further information.
This manual contains updated material on the administration and deployment tools. Appendix B has examples of the deployment tool with sample applications.
Refer to the iPlanet Application Server sample applications documentation, including release notes for each sample, at the following locations.
For iPlanet Application Server installations with web server plugin:
http://<hostname>:<port>/ias-samples/index.html
In the iPlanet Application Server installation directory structure:
<iAS install path>/nas/ias-samples/index.html
Configuring the Bank sample application is strongly recommended for a better understanding the new J2EE features in iPlanet Application Server. For Rich Client access to EJBs, follow the configuration instructions for the Currency Converter sample application.
Programmer's Guides for C++ and Java describe how to create applications intended to run on iPlanet Application Server 6.0. The Programmer's Guide for Java provides Java application developers with a summary of public classes and their interfaces, including methods, syntax, usage, and examples. Both guides describe the major issues developers face in migrating NAS 2.1, NAS 4.0, and possibly Net Dynamics applications to iPlanet Application Server 6.0.
Appendix A, "Using the Java Message Service," in the Programmer's Guide (Java) provides information on the JMS feature.
Java clients for RMI-IIOP are not currently supported on Windows 98. See System Requirements above for details on platform support.
The ORB bundled with iPlanet Application Server 6.0 must be used for both clients and the iPlanet Application Server. Other ORBs have not been tested and are not supported.
A prepackaged file named iasclient.tar (Solaris) or iasclient.zip (NT) is available in the iPlanet Application Server CD image. This file contains JDK 1.2 and iPlanet Application Server client .jar files required by Java clients on Solaris /NT.
When deploying a rich client to a remote system, the JDK packaged in the iasclient.tar or iasclient.zip files are required to support the remote client application. The JDK used by iPlanet Application Server and packaged in the iasclient.jar file has been modified per the standard Java Extension mechanism to change the default ORB selected by the JVM. Other than the use of the Java Extension mechanism, the Jimsonweed are identical to the production Sun JVMs for Solaris and NT.
When running the Java rich client on the same system as iPlanet Application Server, the client's PATH can reference the JDK in the iPlanet Application Server installation (<iAS install path>/ias/usr/java/bin).
EJB classes must be extracted from the EJB-JAR module for those EJBs that are to be accessed via RMI/IIOP. The extracted classes must be placed in a location that is included in the CLASSPATH used by iPlanet Application Server. The iAS/APPS/ directory, although in the iAS CLASSPATH, is NOT a valid location for these extracted EJB classes. Create a new directory under apps names, for example APPS/rmi/, and set the CLASSPATH to include this directory, prior to starting the iPlanet Application Server. On UNIX, set the CLASSPATH, stop the server, and then run KIVAes.sh to restart the server with the CLASSPATH modification. On Windows NT, set the system CLASSPATH in the Control Panel to include the directory, and then restart the iAS NT Service. Refer to the Currency Converter sample application setup documentation for an example of this workaround.
In order to run a specific EJB-JAR module using RMI/IIOP rich client, first make the EJBs accessible by running the fixejb4rmi script using the name of the EJB module. For example, for the module estoreEjb.jar needing rich client access invoke : fixejb4rmi estoreEjb. This script will be obsolete when the problem is resolved in a subsequent release.
This section addresses known problems and their workarounds in the following areas:
Applying Changes in a Panel
When making changes in a panel click "Apply Changes" before switching to another panel, or the changes will be discarded.
Cluster Panel May Not Properly Display Instance Names and Status
This occurs when iPlanet Application Server instance names are too long: choose names with less than eight characters.
Duplicate Instance Entries in Cluster Panel
The Cluster Panel may show duplicate entries for the same iPlanet Application Server instance: one for the name used when creating the instance, and one for the numeric IP address. Though confusing, the list functions properly.
JVM Crash
JVM sporadically crashes when running the administration tool (AT) on Windows NT. This has occurred when configuring two iPlanet Application Servers (one local and one remote) in AT, and during the Refresh operation, due to a Java virtual machine issue. Quit and then relaunch if this happens.
Refresh List Command Causes AT to Hang
Using this command when no servers have been registered causes the iPlanet Application Server to hang and require restarting.
Server Cannot Be Administered When Stopped
When an iPlanet Application Server instance is stopped, attempting to administer to it will result in error messages. Ensure that the instance is running before attempting to administer it.
Text Fields May Be Uneditable
Some text fields may be uneditable when running the iPlanet Application Server AT using an X-windows server on a host other than the local host. However, almost all functionality is available.
Divide-by-zero Code Segment Crashes KJS in Servlet
For example:
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.IOException;
import com.netscape.server.servlet.platformhttp.PlatformHttpServletResponse;
public class HelloHTMLServlet extends HttpServlet {
public void service(HttpServletRequest
req, HttpServletResponse res)
throws ServletException, IOException
{
int i = 0;
try
{
i
= 10/i;
}
catch (java.lang.ArithmeticException
e)
{
System.err.println("Exception:
"+ e );
}
public String getServletInfo()
{
return "Create an HTML
page that gets invoked from the servlet";
dsync Config Parameters
Only one type of sync server is supported; sync local is not supported. The installer provides this option, but it should not be selected.
KIVAes.sh Script Doesn't Shut Down Gracefully
This script kills all server processes, including the iPlanet Application Server AT and the administration server (kas). No graceful shutdown is performed. Use it only to shut down all server processes immediately. Use the AT to stop an iPlanet Application Server instance gracefully, while still leaving the administration server running.
BLOB and CLOB Support
iPlanet Application Server 6.0 fully supports BLOB and CLOB through Binary Stream and AsciiStream, but not through JDBC interfaces. They belong to the SQL3 part of the spec.
Connection to Database Client Fails
When Sybase, Oracle, or Informix clients are installed as a user not having Admin privileges, the connection with any of these servers will fail. Give Admin privileges to the user installing database client.
DatabaseMetaData.getCatalogs( ) Fails Against DB2
Causes an error in the kjs logs.
DatabaseMetaData.getExportedKeys( ) Throws Exception
Throws an exception in kjs on Solaris platform for DB2.
DatabaseMetaData.getImportedKeys( ) Throws Exception
Throws an exception in kjs on Solaris platform for DB2.
DatabaseMetaData.getVersionColumns( ) Doesn't Work on Sybase.
Enabling Global Transactions May Cause kjs Crash
After a typical or express install, enabling global transactions without also using dbsetup may cause kjs to crash on startup. To enable global transactions, install iPlanet Application Server via the custom install option, or run dbsetup after a typical /express installation.
Escape Syntax Processing for Oracle
Escape syntax processing of statements is only turned on for Oracle by default. To enable escape syntax processing for other databases, use the method stmt.setEscapeProcessing(true).
Exception Not Thrown When Failing to Insert Duplicate Row Key
When attempting to insert a duplicate row key in a table using JDBC API through iPlanet Application Server, the SQLException is not thrown, and the SQL statement appears to have executed, but the record does not get inserted in the database. The Sybase 1.1.1. server generates error 2601 when tried from the isql.
KJS dumps core when the following syntax is used to get CallableStatement from prepareCall:
conn.prepareCall ("{ ? = call sp_name (?,?,?) } " );
kjs Crashes at GXODBC2DatabaseMetaData::GetProcedureColumns
kjs crashes on Solaris platforms for DB2 when calling this function.
Lightweight CMP Tab Not Saving
Changes will not be saved when they are made to the upper half of the Lightweight CMP tab of the EJB descriptor editor, without specifying database columns in the table in the lower half of the tab.
Prepared Statement Functions Not Previously Implemented
Status of the following three methods not previously implemented on Prepared Statement:
SetCharacterStream - is now implemeted
setUnicodeStream - is deprecated
getMetaData - not required for J2EE.
Will be evaluated again later.
pstmt.setObject( ) Throws Unsupported Network Datatype Exception
This exception occurs with Oracle database on Solaris platform. . Same is true for both:
setObject(int paramindex, Object x, int targetjdbctype)
setObject(int paramindex, Object x, int targetjdbctype, int scale)
No exception occurs with Sybase, but iPlanet Application Server fails to insert row in table.
RowSet Support
RowSet can be implemented as Standard, cached, and Web. iPlanet Application Server 6.0 does not support cached or web implementations.
setAutoCommit( ) Doesn't Throw Exception
setAutoCommit("true") should throw exception, as autocommit mode is not supported, but setAutoCommit("false") does not throw an exception.
setNull Not Supported for BIGINT and BIGDECIMAL
The setNull method called from prepared and callable statements is not supported for BIGINT and BIGDECIMAL datatypes. When setNull is used for these datatypes the tables are not updated. No exceptions are thrown.
Building Stubs in an Application
When using the Edit Descriptor button to edit descriptor information for an EJB-JAR, avoid building iAS-specific stubs for the EJBs. These are created from the Build Stubs menu, or by answering "Yes" to the dialog asking whether to build stubs. It is usually not necessary to rebuild stubs after a module has been added to an application. If required, extract the module from the application, open the resulting .jar file, rebuild stubs as needed, save the module, then add the updated .jar file to the application. See "Updating Modules in an Application".
Class None
A dialog saying that class "None" could not be found may be encountered when creating or editing an EJB descriptor. Ignore this dialog; no action is required.
Class Not Found When Linking EJB References in an .ear File
When linking EJB references in an .ear file, messages may be encountered that a class cannot be found, and asking for a path to be added to the classpath. If the class is in an EJB-JAR module of the .ear file, supply the path to the .jar file for that module. If that module is not present on the file system, extract it from the .ear file using the "Extract Module" button on the Modules tab. Note that deploying an .ear file automatically causes an attempt to link EJB references.
Collection Names in webApp Security Panel
This panel contains two tables: in the upper table the user can define resource collections (with names), and in the lower table, security constraints can be defined for these resource collections, identifying them by name. Error checking for correct use of these names only happens when the entire descriptor is saved. By then, the user may be looking at a different tab. Spelling errors are not corrected. Error checking merely warns that a name is invalid, or that a constraint has been created that does not mention any valid collection names. After correcting the resource collection names, the user will discover the menu item for saving the descriptor is disabled, because editing within a single cell of a table is not detected as a change that needs to be saved. The workaround is to add a new row to one of the tables with the "Add" button; then select the same row and "Remove" it. This will lead to the "Save WebApp Descriptor" menu item being enabled.
Context Descriptions Not Written to XML
Descriptions are not saved in Web App Descriptor under the Context pane. Descriptions for webApp Descriptors and EJB Descriptors are not getting saved.
Crashing During Startup
Write access is required to both the ias/registry/reg.dat file and the ias/APPS directory to run iPlanet Application Server deployment tool under a UNIX system. This can be arranged by always running deployment tool as a user having privileges equal to the user who installed iPlanet Application Server, or by changing the protections after installation.
Current Selection Wiped Out by Cluster Tab Refresh
An automatic refresh occurs every 15 seconds in the Cluster Tab, wiping out the current selection. Workaround: perform the desired operation quickly and click "Apply Changes" before the refresh occurs.
Destination Paths for Unrecognized File Types
When inserting a file type unrecognized by the Deployment Tool (DT) into a module, DT will not compute a destination for it, but will use its source path. Edit the destination path using View Properties. Types recognized by the tool include: .gxm, .iab, .gxr, .java, .html, .htm, .html, .htm, .gxq, .kdm, .pdm, .gif,.jpg, .jpeg, .class, .js, .ebx, .ntv, .properties, .props, .jsp, .so, .sl, .dll, .o, .obj
EJB-JAR Files Requiring Additional Work
EJB-JAR modules containing .properties files may result in the error message "this file may require additional work." Ignore this message; nothing else is required.
Editing An .ear File
The Insert submenu of the Edit menu is enabled when editing an .ear file, but should not be used. Use the Add Module button on the Modules tab.
Existing Stubs Not Removed
When employing Build [All] Stubs or Convert to iAS, the tool does not always remove existing stub files, so that error messages about duplicate files will be seen when the module is saved, and the save will fail. After converting an EJB-JAR file or building stubs in it, use the menu commands View > By Destination. The Files tab will then show the paths where stub files will end up in the archive, so that duplicates can be easily found. Before converting an application (.ear file), make sure that none of the EJB-JAR modules in it contain any iAS-specific stubs. To achieve this, some modules may need to be removed before doing the conversion, and then added back after completion.
Expanding .jar Files for Rich Client
Rich client is supported by the deployment tool; follow configuration instructions for the Currency Converter sample application to expand the .jar files.
No Visible Indication of Stub Generation
While generating stubs there is no visible indication of progress. At completion, a message indicates the number of stubs created, for example "15 EJB stubs created." This message indicates that the generation process is complete.
Save Application Before Editing Descriptors
After using the Add Module button to add a module to an application, saved the application before editing the descriptor information with the Edit Descriptor button. Changes made before saving the application may be lost.
Spurious Class Not Found
When inserting the contents of a directory subtree into a module, if the first .class file depends on other class files in the same subtree, the class will not be loaded correctly and an error will be displayed. This will probably continue until a class file is encountered that does not have such dependencies, after which everything will be fine. Workaround: OK all the error dialogs, wait until the inserted files display, and click on any highlighted in red for explanation. Or add the user's class path to the deployGUI script.
Surplus Files in Application
Changing the Location In EAR of a module in an application, or removing the module altogether, may leave XML files still visible in the Files tab of the application editor relating to the module's previous name. These can be safely removed. Make sure that the files being removed do not relate to a module still existing in the application, or that application may become unusable.
Unable to Define Roles for Manual Deployment
j2eeappreg should be able to deploy an .ear file without using the deployment tool, however, iPlanet Application Server deployment tool cannot insert role bindings, such as definitions of security roles in terms of users and groups, into an .ear file. For new applications, or ones acquiring new security roles, use the deployment tool to add roles to the servers. For all other applications use j2eeappreg. Once the application has been deployed, the iPlanet Application Server AT can correctly administer roles across different LDAPs.
Unpack Archive Disabled
The unpack archive command under the file menu has been disabled; unjar the archive file using jar xvf <archivename>.
Updating Modules in an Application
After updating a module added to an application, for example recompiling a bug in the Java code and rebuilding the .jar file, insert the updated module into the application in place of the original version. If the Edit Descriptor button was used to change the module's descriptor, these changes have been saved as an alt-dd file in the application, and are not present in any version of the module's .jar or .war file. To discard these changes, simply remove the module from the application by using the Remove Module button of the application editor. Then use the Add Module button to add the updated .jar or .war file back into the application. To keep these changes, add the updated file to the application, and do not use the Remove Module button. The updated file will replace the previous version of the same module, and will inherit the changed descriptor information.
User-Specified Error Handler Not Supported
The servlet DD editor cannot specify the error-handler. The server has a default error handler.
Web Server Needs to be Restarted
When a new application is deployed, the web server that sends the requests to iPlanet Application Server must be restarted.
iPlanet Application Server DTDs
All iPlanet Application Server specific DTDs (those found under the ias\APPS directory after an install, starting with an ias- prefix) need to be installed under the http://developer.iplanet.com/appserver/dtds/.
JMS Bits Required for Windows NT
The following bits required to run the Java Message Service on Windows NT were not included in the iPlanet Application Server 6.0 build, but are included in the package. Instructions to install them are on the CD. These bits include JNDI classes and some Java wrappers for the provider's administered objects. To install JMS on NT:
This will create a jms directory under the main iAS directory. To enable the JMS provider on NT:
Note: setjmscp.bat can not handle path names containing spaces. For example :
c:\Program Files\JavaMessageQueue1.1.
The iAS classpath must be set up for the selected JMS provider. This requires knowing the installation location of that provider. The values for the iAS ClassPath and LibPath are copied to the file jmscp.txt in the setup directory. To add these values to the settings in the iAS registry:
javax.transaction Problem
Situation: rich client, RMI-IIOP, entity bean with BMP, and container managed transactions. No transaction manager defined in application server. The bean can be initialized correctly, including writing an insert into the database, but error occurs at the first container managed transaction. May be an XML problem.
JSP Caching Requires Custom Library Tag
The functionality of JSP caching depends on the custom library tag CacheLib.tld. Copy this file from $YOUR_INSTALL_PATH/APPS/jsp_extensions/GX.tld into the same directory as the JSP using caching.
JSP Compiler Incorrectly Determines Classname from URL
When iPlanet Application Server gets a request for a .jsp file, it tries to locate the compiled class file. If it does not find the compiled class, it fires the jsp compiler to create it from the .jsp file. However, the class file (and classname) it creates uses the URL name, not the filename of the .jsp file. The resulting case misspelling creates an incorrect class file, and causes all correct references to the .jsp file to fail.
JSP Conversion Tool
After converting with the conversion tool, if the 0.92 JSP has the old GX style tags, copy $YOUR_INSTALL_PATH/APPS/jsp_extensions/GX.tld into the directory of the converted JSP before running it.
No Support for Serving Static Pages from Web Server If Request Includes NASApp
There is no support in the plugin /servlet engine for serving static pages from the web server's doc root, if the request includes the prefix NASApp. The plugin forwards all such requests to the StaticServlet on the application server. If the access is for /NASApp/Foo/Bar.html, and bar.html has a relative link to Boo.js, then both Bar.html and Boo.js need to be on the application server's doc root. Static content can only be served off the web server's doc root, is if the URL does not include /NASApp. Docs on the web server's doc root, can only be supported by changing all relative links to absolute links without NASApp. Users are encouraged to use WebServer doc root for static serving, and to code the JSPs accordingly. Currently,the iPlanet Application Server deployment tool only deploys the application on the Application server. To have static content served by the Web server, the static file must be manually moved to the web server doc root, and the links replaced so that the don't have the prefix NASApp. On a UNIX system, write access is required to both the ias/registry/reg.dat file and the ias/APPS directory to run iPlanet Application Server deployment tool. Arrange this by always running the deployment tool as a user having privileges equal to the user who installed iPlanet Application Server, or by changing the protections after installation.
PagePath Feature Not Working with .html and .htm
Page forwarding to .html, .htm, and .css files under PagePath and errorpage does not work.
Uninstall on IIS Machine Causes inetinfo.exe to Error
An incorrect error message stating "inetinfo.exe caused an application error" occurs while uninstalling iPlanet Application Server or iPlanet Application Builder on a machine with an IIS web server. Close this dialog box and the uninstall process continues.