Sun Java System Application Server 7 Update 11 Release Notes

- Previous: Internationalization (i18n)
- Next: Redistributable Files

## 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-siz`e + `pool-resize-quantity`, `max-pool-siz`e).
- 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.
1. 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. 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
3. For Windows, copy the `passthrough.dll` file. 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>
1. 4983280, 4992520, 6078104(Continued) | 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>
4. 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: 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\:@1`asperf`\: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.

- Previous: Internationalization (i18n)
- Next: Redistributable Files

- © 2010, Oracle Corporation and/or its affiliates