Chapter 1 Application Server Compatibility Issues

Application Server 9 is upward binary compatible with Application Server 8.x and with Application Server 7/6.x except for the incompatibilities noted below. Java EE applications that run on versions 6.x, 7.x, and 8.x also work on version 9 except for the incompatibilities listed in this chapter.

The topics discussed in this chapter include incompatibilities in the following areas:

• HTTP File Caching

• Classpath Changes

• Web Server Features

• Security Realms

• Sun Deployment Descriptor: sun-web.xml

• The encodeCookies Property

• CORBA Performance Option

• File Formats

• Tools Interoperability

• System Properties

• Java SE 5 Changes

• Implicit URL Rewriting

• Primary Key Attribute Values

• Command Line Interface: start-appserv and stop-appserv

• Command Line Interface: asadmin

HTTP File Caching

HTTP file caching has been re-introduced in Application Server 9. This feature was present in Application Server 8.1 Enterprise Edition but was discontinued in Application Server 8.2.

Classpath Changes

In Application Server 7.x and 8.x, most of the Application Server core classes were loaded by the by the System Classloader, which also loaded Java Virtual Machine (JVM) classes. In Application Server 9, the System Classloader loads JVM classes but most of the Application Server core classes have been moved to the new Shared Chain Classloader.

In the Migration Tool, on the JVM Settings page, under the Configuration component, there is a new field called System Classpath. This contains the JVM classes. Classes cannot be deleted from this field, but they can be added. The Server Classpath field no longer shows the Application Server core classes, and its use is discouraged. Use Classpath suffix instead.

Web Server Features

As a result, the following web server-specific features are no longer supported in Application Server 9:

• cgi-bin, shtml

• Simple Network Management Protocol (SNMP) support

• Netscape API (NSAPI) plug-in APIs

• Native-content-handling features

• Web server tools (flexanlg, htpasswd)

• HTTP QoS

• Web server configuration files (*.conf, *.acl, mime.types)

• Web server-specific log rotation facility

• Watch dog process (appserv-wdog)

Security Realms

The package names of the security realm implementations have been renamed from com.iplanet.ias.security.auth.realm in Application Server 7 to com.sun.enterprise.security.auth.realm in Application Server 9. Custom realms written using the com.iplanet.* classes must be modified.

The com.sun.enterprise.security.AuthenticationStatus class has been removed.

The com.sun.enterprise.security.auth.login.PasswordLoginModule authenticate method implementation has changed as follows:

/**
    * Perform authentication decision.
    * <P> Note: AuthenticationStatus and AuthenticationStatusImpl
    * classes have been removed.
    * Method returns silently on success and returns a LoginException
    * on failure.
    *
    * @return void authenticate returns silently on 
    *               successful authentication.
    * @throws LoginException on authentication failure.
    *
    */
abstract protected void authenticate()
    throws LoginException;

For more information, see:

http://developers.sun.com/prodtech/appserver/reference/techart/as8_authentication/index.html

Sun Deployment Descriptor: sun-web.xml

In Application Server 7, the default value for the optional attribute delegate was false. In Application Server 9, this attribute defaults to true. This change means that by default the Web application classloader first delegates to the parent classloader before attempting to load a class by itself. For details, see Application Server 9 Options Contrary to Java EE 5 Specification Recommendations.

The encodeCookies Property

URL encoding of cookies is performed, if the encodeCookies property of the sun-web-app element in the sun-web.xml file is set to true. In Application Server 7, the default value of the encodeCookies property was true. This property was not present in Application Server 8. In Application Server 9, the default value is false.

URL encoding of cookies is unnecessary. Setting this property to true is strongly discouraged. This property is provided only for those rare applications that depended on this behavior in Application Server 7.

CORBA Performance Option

In Application Server 7, users were able to specify the following system property to optionally turn on some Object Request Broker (ORB) performance optimization:

-Djavax.rmi.CORBA.UtilClass=com.iplanet.ias.util.orbutil.IasUtilDelegate

The ORB performance optimization is turned on by default in Application Server 9. If you are using the preceding system property reference, you must remove it to avoid interfering with the default optimization.

File Formats

In Application Server 9, domain.xml is the main server configuration file. In Application Server 7, the main server configuration file was server.xml. The DTD file of domain.xml is found in lib/dtds/sun-domain_1_1.dtd. The upgrade tool included in Application Server 9 can be used to migrate the server.xml from Application Server 7 to domain.xml for Application Server 9.

The lib/dtds/sun-domain_1_1.dtd file for Application Server 9 is fully backward compatible with the corresponding file for Application Server 8, sun-domain_1_0.dtd.

In general, the configuration file formats are not backward compatible. The following configuration files are not supported:

• *.conf

• *.acl

• mime.types

• server.xml (replaced with domain.xml)

In Application Server 9, the use of ZIP files in the following directories is deprecated.

• Common class loader directory: domain-dir/lib

• Extension directory: domain-dir/lib/ext

• Endorsed directory:domain-dir/lib/endorsed

Tools Interoperability

As a general rule, tools are not interoperable between Application Server 7 and Application Server 9. Users must upgrade their Application Server 7 tools to work with Application Server 9.

System Properties

The default security policy of Application Server 9 does not allow you to change some system properties. For example, in Application Server 7, the read/write permission for java.util.PropertyPermission was "*", "read,write";. In Application Server 9the read/write permission for java.util.PropertyPermission is "*", "read";. The administrator can change the security policy to grant write access to specific system properties.

Implicit URL Rewriting

Application Server 6.x supported implicit URL rewriting, in which the web connector plug-in parsed the HTML stream being sent to the browser and appended session IDs to attributes such as href= and frame=. In Application Server 7.x/ 8.x and Application Server 9, this feature is not available. You need to review your applications and use encodeURL and encodeRedirectURL on every URL that the applications present to clients (such as mobile phones) that do not support cookies.

Java SE 5 Changes

Application Server 9 no longer bundles JAXP classes. In an Application Server 8.2 installation, JAXP jar files resided in the <install-directory>/lib/endorsed directory. These classes are now part of Java SE 5 and if you have a standalone application, you need to ensure you are using Java SE 5

Primary Key Attribute Values

In Application Server 7, it was possible to change any field (in the Administration Console) or attribute (in the Command Line Interface (CLI)). In Application Server 9, a field or attribute that is the primary key of an item cannot be changed. However, an item can be deleted and then recreated with a new primary key value. In most cases, the primary key is a name, ID, reference, or JNDI name. The following table lists the primary keys that cannot be changed.

---

Note –

In the domain.xml file, a field or attribute is called an attribute, and an item is called an element. For more information about domain.xml, see the Chapter 1, The domain.xml File, in Sun Java System Application Server Platform Edition 9 Administration Reference.

---

Table 1–1 Primary Key Attributes

Item	Primary Key Field or Attribute
admin-object-resource	jndi-name
alert-subscription	name
appclient-module	name
application-ref	ref
audit-module	name
auth-realm	name
cluster-ref	ref
cluster	name
config	name
connector-connection-pool	name
connector-module	name
connector-resource	jndi-name
custom-resource	jndi-name
ejb-module	name
external-jndi-resource	jndi-name
http-listener	id
iiop-listener	id
j2ee-application	name
jacc-provider	name
jdbc-connection-pool	name
jdbc-resource	jndi-name
jms-host	name
jmx-connector	name
lb-config	name
lifecycle-module	name
mail-resource	jndi-name
message-security-config	auth-layer
node-agent	name
profiler	name
element-property	name
provider-config	provider-id
resource-adapter-config	resource-adapter-name
resource-ref	ref
security-map	name
server	name
server-ref	ref
system-property	name
thread-pool	thread-pool-id
virtual-server	id
web-module	name
persistence-manager-factory-resource	jndi-name

Command Line Interface: start-appserv and stop-appserv

The start-appserv and stop-appserv commands are deprecated. Use of these commands results in a warning. Useasadmin start-domain and asadmin stop-domain instead.

In Application Server 9, the Log Messages to Standard Error field has been removed from the Administration Console. The log-to-console attribute in the domain.xml file is deprecated and ignored. The asadmin set command has no effect on the log-to-console attribute. Use the ---verbose option of the asadmin start-domain command to print messages to the window in which you executed the asadmin start-domain command. This option works only if you execute the asadmin start-domain command on the machine that has the domain you are starting.

Command Line Interface: asadmin

The following sections describe changes to the command line utility asadmin:

• Subcommands

• Error Codes for Start and Stop Subcommands

• Options

• Dotted Names

• Tokens in Attribute Values

• Nulls in Attribute Values

For more information about the asadmin commands, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Subcommands

Subcommands are backward compatible except as noted below.

The reconfigsubcommand is deprecated and ignored.

The following subcommands are no longer supported in Application Server 9. The software license key and web core were removed, and Application Server 9 no longer supports controlled functions from web server features.

• install-license

• display-license

• create-http-qos

• delete-http-qos

• create-mime

• delete-mime

• list-mime

• create-authdb

• delete-authdb

• list-authdbs

Error Codes for Start and Stop Subcommands

For Application Server 7, the error codes for the start and stop subcommands of the asadmin command were based on the desired end state. For example, for asadmin start-domain, if the domain was already running, the exit code was 0 (success). If domain startup failed, the exit code was 1 (error).

For Application Server 9, the exit codes are based on whether the commands execute as expected. For example, the asadmin start-domain command returns exit code 1 if the domain is already running or if domain startup fails. Similarly, asadmin stop-domain returns exit code 1 if the domain is already not running or cannot be stopped.

Options

Options in the following table are deprecated or no longer supported.

Table 1–2 Deprecated and Unsupported asadmin Options

Option	Deprecated or Unsupported in Subcommands
--acceptlang	Deprecated for the create-virtual-server subcommand.
--acls	Deprecated for the create-virtual-server subcommand.
--adminpassword	Deprecated for all relevant subcommands. Use --passwordfile instead.
--blockingenabled	Deprecated for the create-http-listener subcommand.
--configfile	Deprecated for the create-virtual-server subcommand.
--defaultobj	Deprecated for the create-virtual-server subcommand.
--domain	Deprecated for the stop-domain subcommand.
--family	Deprecated for the create-http-listener subcommand.
--instance	Deprecated for all remote subcommands. Use --target instead.
--mime	Deprecated for the create-virtual-server subcommand.
--optionsfile	No longer supported for any commands.
--password	Deprecated for all remote subcommands. Use --passwordfile instead.
--path	Deprecated for the create-domain subcommand. Use --domaindir instead.
--resourcetype	Deprecated for all relevant subcommands. Use --restype instead.
--storeurl	No longer supported for any commands.
--target	Deprecated for all jdbc-connection-pool, connector-connection-pool, connector-security-map, and resource-adapter-config subcommands.
--type	Deprecated for all relevant subcommands.

Dotted Names

All dotted names used in versions 8.1 or 8.2 are supported in Application Server 9. The following use of dotted names in asadmin get and set subcommands are not backward compatible:

• The default server name is server instead of server1

• .resource becomes domain.resources.resource

• .app-module becomes domain.applications.app-module

• Attributes names format is different. For example,poolResizeQuantity is now pool-resize-quantity.

• Some aliases supported in Application Server 7 are not supported in Application Server 9

In Application Server 9, the ---passwordfile option of the asadmin command does not read the password.conf file, and the upgrade tool does not upgrade this file. For information about creating a password file in Application Server 9, see the Sun Java System Application Server Platform Edition 9 Administration Guide.

This table displays a one-to-one mapping of the incompatibilities in dotted names between Application Server 7 and 9. The compatible dotted names are not listed in this table.

Table 1–3 Incompatible Dotted Names Between Versions

Application Server 7 Dotted Names	Application Server 9 Dotted Names
server_instance.http-listener.listener_idserver_instance.http-service.http-listener.listener_id	.http-service.http-listener.listener_id.http-service.http-listener.listener_id
server_instance.orbserver_instance.iiop-service	.iiop-service.iiop-service
server_instance.orblistenerserver_instance.iiop-listener	.iiop-service.iiop-listener.listener_id.iiop-service.iiop-listener.listener_id
server_instance.jdbc-resource.jndi_name	.resources.jdbc-resource.jndi_namedomain.resources.jdbc-resource.jndi_name
server_instance.jdbc-connection-pool.pool_id	.resources.jdbc-connection-pool.pool_iddomain.resources.jdbc-connection-pool.pool_id
server_instance.external-jndi-resource.jndi_nameserver_instance.jndi-resource.jndi_name	.resources.external-jndi-resource.jndi_namedomain.resources.external.jndi-resource.jndi_name
server_instance.custom-resource.jndi_name	.resources.custom-resource.jndi_namedomain.resources.custom-resource.jndi_name
server_instance.web-container.logLevel (see note below)	.log-service.module-log-levels.web-container.log-service.module-log-levels.web-container
server_instance.web-container.monitoringEnabled (see note below)	.monitoring-service.module-monitoring-levels.web-container.monitoring-service.module-monitoring-levels.web-container
server_instance.j2ee-application.application_nameserver_instance.application.application_name	.applications.j2ee-application.application_namedomain.applications.j2ee-application.application_name
server_instance.ejb-module.ejb-module_name	.applications.ejb-module.ejb-module_namedomain.applications.ejb-module.ejb-module_name
server_instance.web-module.web-module_name	.applications.web-module.web-module_namedomain.applications.web-module.web-module_name
server_instance.connector-module.connector_module_name	.applications.connector-module.connector_module_namedomain.applications.connector-module.connector_module_name
server_instance.lifecycle-module.lifecycle_module_name	.applications.lifecycle-module.lifecycle_module_namedomain.application.lifecycle-module.lifecycle_module_name
server_instance.virtual-server-class	N/A*
server_instance.virtual-server.virtual-server_id	.http-service.virtual-server.virtual-server_id.http-service.virtual-server.virtual-server_id
server_instance.mime.mime_id	N/A*
server_instance.acl.acl_id	N/A*
server_instance.virtual-server.virtual-server_id.auth-db.auth-db_id	N/A*
server_instance.authrealm.realm_idserver_instance.security-service.authrealm.realm_id	.security-service.auth-realm.realm_id.security-service-auth-realm.realm_id
server_instance.persistence-manager-factory-resource.jndi_nameserver_instance.resources.persistence-manager-factory-resource.jndi_name	.resources.persistence-manager-factory-resource.jndi_namedomain.resources.persistence-manager-factory-resource.jndi_name
server_instance.http-service.acl.acl_id	N/A*
server_instance.mail-resource.jndi_name	.resources.mail-resource.jndi_namedomain.resources.mail-resource.jndi_name
server_instance.profiler	.java-config.profiler.java-config.profiler

* — These attribute names in Application Server 7 do not correspond directly with Application Server 9 dotted names.

Tokens in Attribute Values

The asadmin get command shows raw values in Application Server 9 instead of resolved values as in Application Server 8. These raw values may be tokens. For example, executing the following command:

asadmin get domain.log-root

The preceding command displays the following value:

${com.sun.aas.instanceRoot}/logs

Nulls in Attribute Values

In Application Server 8, attributes with no values contained null. This caused problems in attributes that specified paths. In Application Server 9, attributes with no values contain empty strings, as they did in Application Server 7.