Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Upgrade and Migration Guide

- Previous: Preface
- Next: Chapter 2 J2EE 1.4 Compatibility Issues

# Chapter 1 Application Server Compatibility Issues

The Sun Java System Application Server 8.12005Q2 (Application Server 8.1) is upward binary-compatible with Sun Java System Application Server 8 2004Q2 (Application Server 8) and with Sun Java System Application Server 7 2004Q2 (Application Server 7) except for the incompatibilities noted below. J2EE applications that run on versions 7 and 8 also work on version 8.1 except for the incompatibilities noted below.

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

- Web Server Features

- Security Realms

- Sun Deployment Descriptor: sun-web.xml

- encodeCookies Property

- CORBA Performance Option

- File Formats

- Tools Interoperability

- Cluster Scripts

- Primary Key Attribute Values

- Command Line Interface: hadbm

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

- Command Line Interface: asadmin

# Web Server Features

Application Server 8.1 replaces the Web server shipped with Application Server 7 with a faster native web server component. As a result, the following web server-specific features are no longer supported in version 8.1:

- `cgi-bin`, `shtml`

- SNMP support

- NSAPI plugin 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 8.1. 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:

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 8.1, 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 8.1 Options Contrary to J2EE 1.4 Specification Recommendations.

# encodeCookies Property

The encodeCookies property of the `sun-web-app` element in the `sun-web.xml` file performs URL encoding of cookies if set to true. If set to false, no encoding of cookies is performed. 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 8.1, the default value is false.

In general, 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. This property might be removed in a future release.

# CORBA Performance Option

In Application Server 7, users were able to specify the following system property to optionally turn on some 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 8.1. If you are using the system property reference above, you must remove it to avoid interfering with the default optimization.

# File Formats

In Application Server 8.1, `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 8.1 can be used to migrate the `server.xml` from Application Server 7 to `domain.xml` for Application Server 8.1.

The `lib/dtds/sun-domain_1_1.dtd` file for Application Server 8.1 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`)

# Tools Interoperability

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

# Cluster Scripts

The `clsetup` and `cladmin` scripts in Application Server 7 are not supported in Application Server 8.1. In Application Server 8.1, the `asadmin configure-ha-cluster` command replaces the `clsetup` script, and `asadmin` commands that operate on clusters replace the commands supported by the `cladmin` script. For more information about the `asadmin` commands, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

# 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). In Application Server 8.1, 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 Sun Java System Application Server Enterprise Edition 8.1 2005Q2 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: hadbm

The following table lists options for the command line utility `hadbm` that are no longer supported. For more information about the `hadbm` commands, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

Table 1–2 Unsupported `hadbm` Options

Option | Unsupported in Subcommands
--- | ---
`--inetdsetup` | Not supported for the `addnodes` subcommand.
`--inetd` | Not supported for the `create` subcommand.
`--inetdsetupdir` | Not supported for the `create` subcommand.
`--configpath` | Not supported for the `create` subcommand.
`--set managementProtocol` | Not supported for the `create` subcommand.
`--set DataDeviceSize` `--set TotalDatadeviceSizePerNode` | Not supported for the `create` or `set` subcommand.

# 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. Use`asadmin start-domain` and `asadmin stop-domain` instead.

In Application Server 8.1, 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 only works if you execute the `asadmin start-domain` command on the machine on which the domain you are starting is installed.

# 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 Enterprise Edition 8.1 2005Q2 Reference Manual.

## Subcommands

Subcommands are backward compatible except as noted below.

The following subcommand is deprecated and ignored:

- `reconfig`

The following subcommands are not supported in Application Server 8.1:

- `show-instance-status` (use `list-instances`)

- `restart-instance` (use `stop-instance` followed by `start-instance`)

- `configure-session-persistence` (renamed to `configure-ha-persistence`)

- `create-session-store` (renamed to `create-ha-store`)

- `clear-session-store` (renamed to `clear-ha-store`)

The following subcommands are no longer supported in Application Server 8.1, because the software license key and web core were removed, and because controlled functions from web server features are no longer supported:

- `install-license`

- `display-license`

- `create-http-qos`

- `delete-http-qos`

- `create-mime`

- `delete-mime`

- `list-mime`

- `create-authdb`

- `delete-authdb`

- `list-authdbs`

- `create-acl`

- `delete-acl`

- `list-acls`

## Error Codes for Start and Stop Subcommands

For Application Server 7, the exit codes returned by 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 8.1, 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–3 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

The following use of dotted names in `asadmin get` and `set` subcommands are not backward compatible:

- Default server name is `server` instead of `server1`

- server_instance.resource becomes domain.resources.resource

- server_instance.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 8.1

In Application Server 8.1, 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 8.1, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

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

Table 1–4 Incompatible Dotted Names Between Versions

Application Server 7 Dotted Names | Application Server 8 Dotted Names
--- | ---
server_instance`.http-listener.`listener_idserver_instance`.http-service.http-listener.`listener_id | server_instance`.http-service.http-listener.`listener_idconfig_name`.http-service.http-listener.`listener_id
server_instance`.orb` server_instance`.iiop-service` | server_instance`.iiop-service` config_name`.iiop-service`
server_instance`.orblistener` server_instance`.iiop-listener` | server_instance`.iiop-service.iiop-listener.`listener_idconfig_name`.iiop-service.iiop-listener.`listener_id
server_instance`.jdbc-resource.`jndi_name | server_instance`.resources.jdbc-resource.`jndi_name `domain.resources.jdbc-resource.`jndi_name
server_instance`.jdbc-connection-pool.`pool_id | server_instance`.resources.jdbc-connection-pool.`pool_id `domain.resources.jdbc-connection-pool.`pool_id
server_instance`.external-jndi-resource.`jndi_nameserver_instance`.jndi-resource.`jndi_name | server_instance`.resources.external-jndi-resource.`jndi_name `domain.resources.external.jndi-resource.`jndi_name
server_instance`.custom-resource.`jndi_name | server_instance`.resources.custom-resource.`jndi_name `domain.resources.custom-resource.`jndi_name
server_instance`.web-container.logLevel` (see note below) | server_instance`.log-service.module-log-levels.web-container` config_name`.log-service.module-log-levels.web-container`
server_instance`.web-container.monitoringEnabled` (see note below) | server_instance`.monitoring-service.module-monitoring-levels.web-container` config_name`.monitoring-service.module-monitoring-levels.web-container`
server_instance`.j2ee-application.`application_nameserver_instance`.application.`application_name | server_instance`.applications.j2ee-application.`application_name `domain.applications.j2ee-application.`application_name
server_instance`.ejb-module.`ejb-module_name | server_instance`.applications.ejb-module.`ejb-module_name `domain.applications.ejb-module.`ejb-module_name
server_instance`.web-module.`web-module_name | server_instance`.applications.web-module.`web-module_name `domain.applications.web-module.`web-module_name
server_instance`.connector-module.`connector_module_name | server_instance`.applications.connector-module.`connector_module_name `domain.applications.connector-module.`connector_module_name
server_instance`.lifecycle-module.`lifecycle_module_name | server_instance`.applications.lifecycle-module.`lifecycle_module_name `domain.application.lifecycle-module.`lifecycle_module_name
server_instance`.virtual-server-class` | N/A
server_instance.`virtual-server`.virtual-server_id | server_instance`.`http-service.virtual-server.virtual-server_idconfig_name.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 | server_instance`.security-service.auth-realm.`realm_idconfig_name`.security-service-auth-realm.`realm_id
server_instance`.persistence-manager-factory-resource.`jndi_nameserver_instance`.resources.persistence-manager-factory-resource.`jndi_name | server_instance`.resources.persistence-manager-factory-resource.`jndi_name `domain.resources.persistence-manager-factory-resource.`jndi_name
server_instance`.http-service.acl.`acl_id | N/A
server_instance`.mail-resource.`jndi_name | server_instance`.resources.mail-resource.`jndi_name `domain.resources.mail-resource.`jndi_name
server_instance`.profiler` | server_instance`.java-config.profiler` config_name`.java-config.profiler`

Note –

Rows with note in previous table describe attribute names. In these instances, there is not a one-to-one relationship with the dotted names between Application Server 7 and 8.1.

## Tokens in Attribute Values

The asadmin `get` command shows raw values in Application Server 8.1 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

displays the following value:

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

## Nulls in Attribute Values

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

- Previous: Preface
- Next: Chapter 2 J2EE 1.4 Compatibility Issues

- © 2010, Oracle Corporation and/or its affiliates