test

Sun Java System Application Server 7 Update 11 Release Notes

Documentation

This section describes the known documentation issues and associated solutions.

ID  

Summary  

6629470

Documentation does not warn the user about the implications of using the -Xms or -Xmx options in conjunction with -XX:+AggressiveHeap in the server.xml file.

Solution: 

The following information needs to be included: 

Do not use the -Xms or -Xmx options in conjunction with -XX:+AggressiveHeap, because -XX:+AggressiveHeap sets the heap size. Using-Xms or -Xmx options in conjunction with -XX:+AggressiveHeap causes the options to override each other’s settings for heap size. 

The -Xss option can help reduce stack requirements. 

6610764

Need to have clear documentation on the auto-commit feature for conection validation in the Application Server 7 Administration Guide. 

The topic on Configuring JDBC connection pools in Chapter 9 does not provide detailed information about auto-commit. 

Solution 

The following information needs to be included: 

The auto-commit feature uses the getAutoCommit and the setAutoCommit methods for validating a connection.

The getAutoCommit method retrieves the current state of auto-commit.

The setAutoCommit method can be used to change the state of auto-commit, so that actual contact with the database can take place.The getAutoCommit method may or may not contact the DB, based on the implementation.

NOTE: Some databases, such as Oracle, perform caching for the setAutoCommit method and do not actually validate the connection. Use table-based validation instead of the auto-commit feature.

6412668

The following statement in the Configuring the File Cache section of the Application Server 7 Performance Tuning Guide is incorrect:

By default, Transmit File is enabled on NT, and not enabled on Unix. On Unix, enable Transmit File for platforms that have native OS support for PR_TransmitFile, which currently includes HP-UX and AIX. It is not recommended for other Unix/Linux platforms. 

Solution

The statement must read as follows: 

By default, Transmit File is enabled on NT, and not enabled on Unix. On Unix, Transmit File is enabled for platforms that have native OS support for PR_TransmitFile, which currently includes Solaris, HP-UX and AIX. It is not recommended for other Unix/Linux platforms. 

6333096

The following example for "redirect" directive in Sun Java System Application Server 7, Enterprise Edition Developer’s Guide to NSAPI is incorrect:

In the second example, any request for http://hostname/toopopular/whatever is translated to a request for http://bigger/better/stronger/morepopular/whatever.

Solution 

The example must read as follows: 

In the second example, any request for http://hostname/toopopular/whatever is translated to a request for http://bigger/better/stronger/morepopular.

4839719

Developer’s Guide to Web Applications: Description of cookieName property misleading.

In the Developer’s Guide to Web Applications, the documentation of the sun-web.xml file lists the cookieName property of the cookie-properties subelement and implies that the value of the cookieName property can be changed from the default value. However, the value cannot be changed; it must always be JSESSIONID.

Solution

None. 

4720171

There is no documentation explaining the use of indexed deployment directories.

The numbering scheme part of a deployed application’s directory name has been implemented as an indexing mechanism to allow a developer to modify a JAR and/or class file associated with the deployed application. This is significant to the Windows platform due to a sharing violation error that occurs during an attempt to overwrite a loaded file; Windows places a file lock on the loaded file. The file is loaded into the server instance or the IDE during session startup. With the sharing violation error, two options are possible: 

  • Compile the updated class file (originally part of that JAR file) and place it first in the classpath in order to be loaded before the older classes, then allow for the Sun Java System Application Server to reload this application (as long as reload is active), OR

  • Update the JAR file, create a new EAR file, and redeploy the application.

    NOTE: Redeployment of the application on the Solaris platform is not necessary since there are no file locking constraints.

Solution

When making changes to an already deployed application on the Windows platform for IDE setup, ANT file copy, or compile or other operations, note that a new directory will be created with an incremented index number as the workaround for the file locking constraint. For example: On the Solaris platform the J2EE application, helloworld, is deployed to the Sun Java System Application Server with the following directory structure: 

appserv/domains/domain1/server1/applications/j2ee-apps/helloworld_1

A change is then to be made to a servlet that’s part of this deployed application (for example, HelloServlet.java). The Sun Java Studio IDE is started, the source file for this servlet is changed and compiled with the javac target set to the above directory. With the source compiled to the proper location, a reload file exists for this application, the reload flag in server.xml is set to true, and, with the server instance running, the changes take effect without having to reassemble the application and redeploy it.

For the Windows platform, the JAR or class file cannot be altered and updated due to the file locking issue. Therefore, there are two methods of dealing with this issue on Windows: 

  • Compile the changed source file and prepend the class file or JAR in the classpath in order to have the source changes picked up, OR

  • Make the changes to the helloworld source, assemble it, and redeploy it without undeploying the previous deployment of helloworld.

    The second option is the preferred method since this option results in the use of the incremented index number appended to the deployed application’s directory name. Therefore, after a second deployment of helloworld, the directory structures would be:

    appserv/domains/domain1/server1/applications/j2ee-apps/helloworld_1appserv/domains/domain1/server1/applications/j2ee-apps/helloworld_2

    The second deployment of helloworld would be deployed under helloworld_2.

4851218

You cannot use keytool to generate certificates with Sun Java System Application Server.

Certificates generated with keytool are not compatible with Sun Java System Application Server. 

Solution

You can use certutil to generate self-signed certificates. It is available as an add-on to the Sun Java System Application Server at:

http://wwws.sun.com/software/download/app_servers.html 

For information on using certutil, see:

http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html 

4870888

Getting Started Guide built into the product is incorrect.

The Getting Started Guide that is built into the product contains incorrect information regarding platforms and sizing. It also is not fully 508-compliant.

Solution

For correct platform and sizing information, refer to the Installation Guide or the Platform Summary. For a 508-compliant version of the Getting Started Guide, see the version posted here:

http://docs.sun.com

4875280

Online help has some incorrect descriptions.

Solution

  • In the asprfhls.html file:

    Determines whether SSL3 is enabled. For administrative purposes, deselecting SSL2 and using TLS only is recommended. (file name asprfhls.html)

    If your browser does not support TLS, then select SSL3.

    Instead, this should be:

    Determines whether SSL3 is enabled. For administrative purposes, deselecting SSL3 and using TLS only is recommended.

    If your browser does not support TLS, then select SSL3.

  • In the asprflo.html file:

    Create Console

    (Window only). When checked, a console window is created for stderr output.

    Instead, this should be:

    Create Console

    (Windows only). When checked, a console window is created for stderr output.

4884043

Configuration File Reference: Transmit File parameter default is stated incorrectly.

Solution

The document description for the TransmitFile parameter in the nsfc.conf file specifies the following default:

(for Unix) i.e. 

TransmitFile=off

This is incorrect. The Transmit File check box by default is "enabled". As described in the document, it should have been disabled. 

4890285

Some documents are not updated for the Solaris x86 platform.

In documents that list supported platforms for Sun Java System Application Server, the Solaris x86 platform might not be included. For the latest platform information, see the Platform Summary.

Developer’s Guide to NSAPI: Where the manual refers to SPARC, the references should be to Solaris (Solaris includes SPARC and x86). On Page 158 and 159, SPARC should not be specified.

Solution

Refer to Solaris x86 Limitations for a list of Solaris x86 limitations in this release. The documentation does not always specify these limitations.

4893954

Administrator’s Guide doesn’t include the information that log rotation using the Solaris cron script restarts the Sun Java System Application Server.

Solution

Two types of log rotation are available: 

Internal-daemon log rotation happens within the HTTP daemon, and can only be configured at startup time. Internal daemon log rotation allows the server to rotate logs internally without requiring a server restart. 

Scheduler-based (cron-based) log rotation is initialized at server startup. If rotation is turned on, the server creates a time-stamped access log file and rotation starts at server startup. This type log rotation internally calls the rotatelog script, which restarts the application server process.

4896094

Administrator’s Guide: Need instructions for setting ACC_CONFIG variable at installation.

Solution

There are no instructions in the documentation for setting the ACC_CONFIG variable after creating domain and server instances. After the “Deploying Applications” section in the Sun Java System Application Server Administration Guide, the following text needs to be added:

In addition to the above steps, you need to modify the asenv.conf file. After creating the domains, set the value of the AS_ACC_CONFIG variable to the sun-acc.xml file located in the server_instance_config directory. If this value is not set properly, you might get errors while running the applications related to the Application Client Container (ACC). For example:

AS_ACC_CONFIG=/var/appserver/domains/domain1/server1/config/sun-acc.xml

where server1 is the application server instance you have created. 

4913290

Form Based Authentication does not provide the same functionality as in 6.5 

Applications developed on iPlanet Application Server 6.5 that use form-based authentication can pass the request parameters to the Authentication Form or the Login page. The Login page could be customized to display the authentication parameters based on the input parameters. 

Solution

Sun Java System Application Server 7 does not support the passing of request parameters while displaying the Login page. The applications that uses form-based authentication, which passes the request parameters can not be migrated to Sun Java System Application Server 7. Porting such applications to Application Server 7 requires significant changes in the code. Instead, you can store the input parameters in the session which can be retrieved during the display of Login page. 

The following code example demonstrates the workaround: 

Before changing the code in 6.5: 

---------index-65.jsp -----------
<%@page contentType="text/html"%>
<html>
<head><title>JSP Page</title></head>
<body>
go to the <a href="secured/page.jsp?arg1=test&arg2=me">secured area</a>
</body>
</html>
----------login-65.jsp--------------
<%@page contentType="text/html"%>
<html>
<head> </head>
<body>
<!-- Print login form -->
<h3>Parameters</h3><br>
<%out.println("arg1 is " + request.getParameter("arg1")); %>
<%out.println("arg2 is " + request.getParameter("arg2")); %>;
</body>
</html>

4913290 (Continued)

After changing the code in 7.0: 

---------index-7.jsp -----------
<%@page contentType="text/html"%>
<html>
<head><title>JSP Page</title></head>
<body>
<%session.setAttribute("arg1","test"); %>
<%session.setAttribute("arg2","me"); %>
go to the <a href="secured/page.jsp">secured area</a>
</body>
</html>

The index-7.jsp shows how you can store the request parameters in a session. 

----------login-7.jsp--------------
<%@page contentType="text/html"%>
<html>
<head> </head>
<body>
<!-- Print login form -->
<h3>Parameters</h3><br>
<!--retrieving the parameters from the session -->
<%out.println("arg1 is " + (String)session.getAttribute("arg1")); %>
<%<>out.println("arg2 is " + (String)session.getAttribute("arg2")); %>
</body>
</html>

4913611

J2EE spec incompatibilities are not documented.

Solution

Developer’s Guide to Web Applications: The following note applies to the description of the delegate attribute:

"If the delegate flag is set to its default value of false, the classloader delegation behavior complies with the Servlet 2.3 specification, section 9.7.2. If set to true, classes and resources residing in container-wide library JAR files are loaded in preference to classes and resources packaged within the WAR file, contrary to what this specification recommends. 

Portable programs that use this flag should not be packaged with any classes or interfaces that are a part of the J2EE specification. The behavior of a program that includes such classes or interfaces in its WAR file is undefined." 

Developer’s Guide and the Developer’s Guide to Enterprise JavaBeans Technology: The following note applies to the descriptions of the pass-by-reference element:

"If the pass-by-reference flag is set to its default value of false, the passing semantics for calls to remote interfaces comply with the EJB 2.0 specification, section 5.4. If set to true, remote calls involve pass-by-reference semantics instead of pass-by-value semantics, contrary to this specification. 

Portable programs should not assume that a copy of the object is made during such a call, and thus that it’s safe to modify the original. Nor should they assume that a copy is not made, and thus that changes to the object are visible to both caller and callee. When this flag is set, parameters and return values should be considered read-only. The behavior of a program that modifies such parameters or return values is undefined." 

4915451

The definition of idle-timeout-in-seconds in the Administrator’s Guide is incorrect.

Solution

In Sun Java System Application Server Administration Guide, Chapter 6, Monitoring the Sun Java System Application Server, the definition of idle-timeout-in-seconds includes the following sentence:

If the current size is less than steady-pool-size, it is increased by pool-resize-quantity, with a ceiling of min (current-pool-size+pool + resize-quantity, max-pool-size).

This should be changed to: 

If the current size is less than steady-pool-size, it is increased by pool-resize-quantity, with a ceiling of min (current-pool-size + pool-resize-quantity, max-pool-size).

4950035, 4976502, 5024804

The information on enabling statistics with stats-xml in the Performance Tuning Guide is incorrect.

Solution

In the Sun Java System Application Server Performance Tuning Guide in the “Tuning Sun Java System Application Server” chapter, the description of enabling statistics with stats-xml contains the following errors:

  • You must make the change to the instance_name-obj.conf file, not the obj.conf file as stated.

  • The example is incorrect. The entries for:

    NameTrans fn="assign-name" from="/stats-xml/*" name="stats-xml" and
NameTrans fn=assign-name from="/.perf" name="perf"

    must appear before the line:

    NameTrans fn=document-root root="$docroot"

    otherwise they’ll be ignored. The current example does not have the lines in the correct order.

  • The introductions to Figure 4.1 and Figure 4.2 are incorrect.

    Figure 4.1 should say that it shows a sample instance_name-obj.conf file which has stats-xml enabled.

    Figure 4.2 should say that is shows a sample init.conf file which has stats-xml enabled.

4983280, 4992520, 6078104

Web server plug-in installation instructions are incorrect

In the Administration Guide, the instructions for installing the web server plug-in are incorrect. 

Solution

The procedure should be as follows: 

Changes to Sun Java System Web Server 

Take backups of critical configuration files, such as magnus.conf and obj.conf, before making changes to these files.

  1. Create a directory in the web server installation area that will contain the web server (passthrough) plug-in. For example:

    cd /webserver_install_dir/plugins
mkdir -p passthrough/bin

  2. Copy the passthrough plug-in from Sun Java System Application Server installation to this new, web server directory. For example:

    cd appserver_install_dir/lib
cp libpassthrough.so webserver_install_dir/plugins/passthrough/bin

    For Windows, copy the passthrough.dll file.

  3. Edit the magnus.conf file, found under webserver_install_dir/https-host.domain/config, and append the following lines. These lines need to be entered as 2 lines, each starting with Init.

    Init fn=load-modules shlib="your_app_server_install/lib/libpassthrough.so
    "funcs="init-passthrough,auth-passthrough,check-passthrough,
    service-passthrough"NativeThread="no"
Init fn="init-passthrough"

  4. Edit the web server’s obj.conf file, found under webserver_install_dir/https-host.domain/config, and add the NameTrans directive. It must be entered on a single line. The NameTrans directives are executed in the order they appear, so make sure your addition is in proper position. If in doubt, put it above all other NameTrans directives Be careful with whitespace (spaces/tabs) in this file.The way obj.conf gets parsed causes lines that start with whitespace to be ignored, since they are considered to be part of the previous line’s directive. The example below only redirects for a context root named “webapp-context”. Add more context root names for multiple applications, or use a catch-all directive: from="/*"

    <Object name="default">
NameTrans fn="assign-name" from="(/webapp-context|/webapp-context/*)
    "name="passthrough"
...
</Object>

4983280, 4992520, 6078104(Continued)

  1. For Sun Java System Web Server 6.0, add the following lines in the web server’s obj.conf file. Replace app_server.domain:port with the server name and port number of your Sun Java System Application Server. Note that you need to enter the Service line as one line.

    Object name="passthrough">
ObjectType fn="force-type" type="magnus-internal/passthrough"
PathCheck fn="deny-existence" path="*/WEB-INF/*"
Service type="magnus-internal/passthrough" fn="service-passthrough"
    servers="http://app_server.domain:port"
Error reason="Bad Gateway" fn="send-error" uri="/badgateway.html"
</Object>

  2. For Sun Java System Web Server 6.1, add the following lines in the web server’s obj.conf file. Replace app_server.domain:port with the server name and port number of your Sun Java System Application Server. Note that you need to enter the Service line as one line.

    Object name="passthrough">
PathCheck fn="deny-existence" path="*/WEB-INF/*"
Service type="magnus-internal/passthrough" fn="service-passthrough"
    servers="http://app_server.domain:port"
Error reason="Bad Gateway" fn="send-error" uri="/badgateway.html"
</Object>

  3. Restart the Sun Java System Web Server instance.

    If required for authentication reasons, on the Sun Java System Application Server you may need to change init.conf and server_name-obj.conf. These steps are required if you have a web server running in SSL mode while the Sun Java System Application Server is non-SSL. In this case any redirects fail unless you add the lines below to the proper Sun Java System Application Server files. If you don’t need this information, skip these steps:

  4. In app_server_instance/config/init.conf, add the following lines as two lines, each starting with Init:

    Init fn="load-modules" shlib="/app_server_install/lib/libpassthrough.so"
    funcs="init-passthrough,auth-passthrough,check-passthrough,
    service-passthrough"shlib_flags="(global|now)"
Init fn="init-passthrough"

  5. In /domain/server_instance/config/server_instance-obj.conf, enter the following lines:

    <Object name="default">
AuthTrans fn="match-browser" browser="*MSIE*" ssl-unclean-shutdown="true"
AuthTrans fn="auth-passthrough"
....
</Object>

4986222

Clarify documentation relating to JMS.

The documentation refers to an incorrect version of the Sun Java System Message Queue documentation. 

The description of the server.xml jms-service property instance-name is incorrect in the Administrator’s Configuration File Reference and in the Developer’s Guide to J2EE Features and Services is incorrect.

Solution

For the correct version of the Sun Java System Message Queue documentation, refer to: http://docs.sun.com/app/docs/prod/s1.s1msgqu 

The documentation for the jms-service property instance-name says that the Sun Java System Message Queue broker instance name is always the concatenation of the domain and server instance name. That is not true. You can use any name.

N/A

J2EE CA SPI Administrator’s Guide refers to wrong book title.

The Sun Java System Application Server J2EE CA SPI Administrator’s Guide refers to Sun Java System Application Server J2EE CA SPI Developer’s Guide. This title is incorrect.

Solution

These references should be to the Sun Java System Application Server Developer’s Guide.

N/A

Sun Java System Application Server Administrator’s Guide doesn’t document using escape characters for the asadmin utility properly for Linux.

Solution

When using the asadmin command in multimode on Linux, use a single backslash character to escape reserved characters such as colons. For example:create-jdbc-connection-pool --datasourceclassname oracle.jdbc.pool.OracleDataSource --propertyurl=jdbc\:oracle\:thin\:@1asperf\:1521\:ntdb01":user=testprod:password=testprod rekla-pool

The value of the URL property will then be stored with the proper syntax for a JDBC connection string 

5015994

Additional recommended configurations to improve performance.

Solution

If you change the default Sun Java System Application Server configuration by using the settings described below, you may see improved performance. These settings are found in your server instance’s server.xml file.

Add or change the following settings: 

<jvm-options>-server -Xss128k</jvm-options>

<jvm-options>-Xms256m -Xmx256m</jvm-options>

<jvm-options>-XX:+AggressiveHeap</jvm-options>

<jvm-options>-XX:+DisableExplicitGC</jvm-options>

<jvm-options>-Djavax.rmi.CORBA.UtilClass=com.iplanet.ias.util.orbutil.IasUtilDelegate</jvm-options>

<orb message-fragment-size="1024" steady-thread-pool-size="40" max-thread-pool-size="70"idle-thread-timeout-in-seconds="300" max-connections="1024" monitoring-enabled="false"/>

<mdb-container steady-pool-size="32" pool-resize-quantity="16" max-pool-size="1024"idle-timeout-in-seconds="600" monitoring-enabled="false">

Remove the following setting: 

<jvm-options>-Dsun.rmi.dgc.server.gcInterval=3600000</jvm-options>

In addition, if the machine has enough memory, you should increase the initial heap size to 1024M (3500M on Solaris systems). 

5031531

The Performance Tuning Guide does not include information on maximum heap space.

Solution

The maximum heap space depends of various factors: 

  • Maximum address space for a process (maxPAS)

  • Space that the process needs for stack space (stack)

  • Space that the process needs for libraries (libs)

The following equation shows the value for the maximum heap space: 

MaxHeapSpace =  maxPAS - stack - libs

The maximum address space per process varies by platform: 

x86 / Redhat Linux 32 bit                2 GB
x86 / Redhat Linux 64 bit                3 GB
x86 / Win98/2000/NT/Me/XP                2 GB
x86 / Solaris x86 (32 bit)                4 GB
Sparc / Solaris 32 bit                4 GB
Sparc / Solaris 64 bit                terabytes

Stack space and library space vary by individual application. 

6156869

No documentation on migrating from Sun Java System Message Queue 3.0.1 to Sun Java System Message Queue 3.5

Sun Java System Application Server 7 is shipped with Sun Java System Message Queue 3.01. However, Sun Java System Message Queue 3.5 is also supported. To migrate from Sun Java System Message Queue 3.01 to Sun Java System Message Queue 3.5, follow the instructions in the Sun Java System Message Queue Installation Guide on the docs.sun.com web site.

N/A

Version of Xerces not documented.

Sun Java System Application Server 7 supports LibXerces version 1.2 and Xerces2 Java Parser 2.6.2.