Sun GlassFish Enterprise Server v3 Upgrade Guide

Chapter 1 Application Server Compatibility Issues

Sun GlassFish^TM Enterprise Server v3 (Enterprise Server v3) is binary compatible with Sun Java^TM System Application Server 9.1 Update 2 (Developer Profile) and with Sun GlassFish Enterprise Server v2 Update 2 (Developer Profile), v2.1 (Developer Profile), and v3 Prelude. Java applications that run on Sun Java System Application Server 9.1 Update 2 (Developer Profile) or on Sun GlassFish Enterprise Server v2 Update 2 (Developer Profile), v2.1 (Developer Profile), or v3 Prelude, also work on Sun GlassFish Enterprise Server v3 except for the compatibility issues listed in this chapter.

The following topics are addressed here:

Application Client Interoperability

The Java EE 6 platform specification imposes stricter requirements than Java EE 5 did on which JAR files can be visible to various modules within an EAR file. In particular, application clients must not have access to EJB JAR files or other JAR files in the EAR file unless they use a Class-Path header in the manifest file, or unless references use the standard Java SE mechanisms (extensions, for example), or use the Java EE library-directory mechanism. Deployed Java EE 5 applications that are upgraded to Enterprise Server v3 will have the compatibility property set to v2 and will run without change on Enterprise Server v3. You may, however, want to consider modifying the applications to conform to Java EE 6 requirements.

If your upgrade includes a deployed application with an application client, you will need to retrieve the client stubs using Enterprise Server v3 in order to run the client. Use the asadmin get-client-stubs command.

If you try to run the application client before retrieving the client stubs, you will see the following error message:

Invalid or corrupt jarfile jar-file-name

If you commonly distribute application clients to remote systems from which users will run them, you must not only retrieve the client stubs, but you must also run the package-appclient utility for Enterprise Server v3 to upgrade the Enterprise Server system files. This utility creates a JAR file, which you can then expand on the remote systems.

Application clients use EJBs, web services, or other enterprise components that are in the application server (on the server side). The application client and the application server must use the same version and implementation of the RMI-IIOP protocol. Enterprise Server v3 does not support communication between different versions of the protocol implementation. You cannot run application clients with one version of the application server runtime with a server that has a different version. Most often, this would happen if you upgraded the server but had not upgraded all the application client installations. If you run the package-appclient utility, this issue will not arise.

You can use the Java Web Start support to distribute and launch the application client. If the runtime on the server has changed since the end-user last used the application client, Java Web Start automatically retrieves the updated runtime. Java Web Start enables you to keep the clients and servers synchronized and using the same runtime.

Command Line Interface: The `asadmin` Command

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

For more information about asadmin and its subcommands, see the Sun GlassFish Enterprise Server v3 Reference Manual.

`asadmin` Subcommands

Subcommands are backward compatible except as noted below.

The following subcommand is deprecated.

deploydir (use deploy instead)

In Enterprise Server v3, it is recommended that utility options of the asadmin command precede the subcommand. Utility options are options that control the behavior of the asadmin utility, as distinguished from subcommand options. Use of the following options after the subcommand is deprecated.

--host
--port
--user
--passwordfile
--terse
--secure
--echo
--interactive

Deprecated and Unsupported Options

Options in Table 1–1 are deprecated or no longer supported.

Table 1–1 Deprecated and Unsupported asadmin Options


Option	Deprecated or Unsupported in Subcommands
`--defaultvs`	Deprecated for the `create-http-listener` subcommand.
`--httplisteners`	Deprecated for the `create-virtual-server` subcommand. Use `--networklisteners` instead.
`--acceptlang`	Unsupported for the `create-virtual-server` subcommand.
`--acls`	Unsupported for the `create-virtual-server` subcommand.
`--adminpassword`	Unsupported for all relevant subcommands. Use `--passwordfile` instead.
`--blockingenabled`	Unsupported for the `create-http-listener` subcommand.
`--configfile`	Unsupported for the `create-virtual-server` subcommand.
`--defaultobj`	Unsupported for the `create-virtual-server` subcommand.
`--domain`	Unsupported for the `stop-domain` subcommand.
`--instance`	Unsupported for all remote subcommands.
`--mime`	Unsupported for the `create-virtual-server` subcommand.
`--password`	Unsupported for all remote subcommands. Use `--passwordfile` instead.
`--path`	Unsupported for the `create-domain` subcommand. Use `--domaindir` instead.
`--resourcetype`	Unsupported for all relevant subcommands. Use `--restype` instead.
`--target`	Unsupported at this release for all subcommands.

Applications That Use Java DB

The directory location of Java DB in Enterprise Server v3 has changed from its location in previous installations. Suppose that you have deployed applications that use Java DB databases in your previous server installation, and you upgrade your existing installation to Enterprise Server v3. If you run the asadmin start-database command and successfully start Java DB, you could run into problems while trying to run applications that were deployed on your previous server installation.

To solve this problem, you can copy the databases directory from your previous installation to as-install/databases. Make sure the database is not running when you do this.

Alternatively, you can perform these steps:

After upgrade, start Enterprise Server v3.
Use the asadmin start-database command with the --dbhome option pointing to the databases directory in the older version of Java DB. For example:
asadmin start-database --dbhome c:\glassfish\databases
Deploy the migrated applications.

Applications That Use Persistence

Enterprise Server v3 uses the persistence provider EclipseLink, while earlier versions used TopLink. If your application uses persistence, you may have to modify the persistence.xml file or your code as follows:

The upgrade process modifies the ddl-generation property of the persistence.xml file to specify the new provider. However, it does not modify the provider element. If your application's persistence.xml file contains this element, change it to specify the following:
```
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
```
The provider element is required if the application creates an EntityManagerFactory by calling the method Persistence.createEntityManagerFactory.
If the application contains any TopLink-specific code and therefore contains casts to oracle.toplink.*, you must change the code to cast to org.eclipse.persistence.*. You can use the package renamer tool described on the Eclipse wiki to do this. This tool is not provided with Enterprise Server v3, however, so you must obtain it from the EclipseLink project download site.

Signed Applications

During the upgrade process, archives for previously deployed applications are recreated from the application repository bits and then redeployed. This approach does not work for signed applications. After archive recreation, the signature becomes invalid. Therefore, you must redeploy the signed applications manually after upgrade.

HTTP Service to Network Service Changes

In Enterprise Server v3, most HTTP Service settings have been moved into the new Network Service configuration.

The changes are described in the following sections.

Changes to Dotted Names

The dotted name hierarchy for the HTTP Service configuration in the v3 Prelude release is shown below. Elements that are no longer supported are request-processing, keep-alive, connection-pool, http-protocol, http-file-cache, and http-listener. During the upgrade process, these discontinued elements are remapped to the new configuration automatically and then deleted.

config
    http-service
        access-log
        request-processing
        keep-alive
        connection-pool
        http-protocol
        http-file-cache
        http-listener
            ssl 
            property
        virtual-server
            http-access-log
            property
        property
    thread-pools
        thread-pool

The dotted name hierarchy for the new Network Service and HTTP Service configurations is shown below. The network-config element and all its children are new except for ssl.

config
    network-config
        transports
            selection-key-handler
            transport
        protocols
            protocol
                http
                    file-cache
                port-unification
                    protocol-finder
                protocol-chain-instance-handler
                    protocol-chain
                protocol-filter
                ssl
        network-listeners
            network-listener
    http-service
        access-log
        virtual-server
            http-access-log
            property
        property
    thread-pools
        thread-pool

The following examples compare the commands for setting a listener port for Enterprise Server v3 Prelude and Enterprise Server v3.

Command for Enterprise Server v3 Prelude:

asadmin set server-config.http-service.http-listener.http-1.listenerport=4321

Command for Enterprise Server v3:

asadmin set server-config.network-config.network-listeners.network-listener.http-1.listenerport=4321

Changes to `asadmin` Commands

To accommodate the move of HTTP Service into the new Network Service configuration, asadmin(1M) commands are changed as follows:

The create-ssl(1) command has a new --type parameter value, network-listener.
The create-virtual-server(1) command has a new parameter, --networklisteners.
The create-http-listener(1) command adds a network-listener element to the domain configuration. The syntax and options of this commands are unchanged.

Remapping of HTTP Service Attributes and Properties

The following tables describe how attributes and properties in the HTTP Service configuration for v3 Prelude are remapped to attributes in the Network Service configuration for Enterprise Server v3. If you use a configuration from an Enterprise Server v2 or v3 release, this remapping happens automatically and then discontinued elements are deleted.

Table 1–2 com.sun.grizzly Property Remapping


`com.sun.grizzly` Property	New Owning Element	New Attribute Name
`selector.timeout`	`transport`	`selector-poll-timeout-millis`
`displayConfiguration`	`transport`	`display-configuration`
`enableSnoop`	`transport`	`snoop-enabled`
`readTimeout`	`transport`	`read-timeout-millis`
`writeTimeout`	`transport`	`write-timeout-millis`

Table 1–3 connection-pool Attribute Remapping


`connection-pool` Attribute	New Owning Element	New Attribute Name
`queue-size-in-bytes`	`thread-pool`	`max-queue-size`
`max-pending-count`	`transport`	`max-connections-count`
`receive-buffer-size-in-bytes`	`http`	`request-body-buffer-size-bytes`
`send-buffer-size-in-bytes`	`http`	`send-buffer-size-bytes`

Table 1–4 http-file-cache Attribute Remapping


`http-file-cache` Attribute	New Owning Element	New Attribute Name
`file-caching-enabled`	`file-cache`	`enabled`
`max-age-in-seconds`	`file-cache`	`max-age-seconds`
`medium-file-space-in-bytes`	`file-cache`	`max-cache-size-bytes`
`max-files-count`	`file-cache`	`max-files-count`
`globally-enabled`	none	not supported
`medium-file-size-limit-in-bytes`	none	not supported
`small-file-size-limit-in-bytes`	none	not supported
`small-file-space-in-bytes`	none	not supported
`file-transmission-enabled`	none	not supported
`hash-init-size`	none	not supported

Table 1–5 http-listener Attribute Remapping


`http-listener` Attribute	New Owning Element	New Attribute Name
`id`	`network-listener`	`name`
`address`	`network-listener`	`address`
`port`	`network-listener`	`port`
`enabled`	`network-listener`	`enabled`
`acceptor-threads`	`transport`	`acceptor-threads`
`security-enabled`	`protocol`	`security-enabled`
`default-virtual-server`	`http`	`default-virtual-server`
`server-name`	`http`	`server-name`
`redirect-port`	`http`	`redirect-port`
`xpowered-by`	`http`	`xpowered-by`
`external-port`	none	not supported
`family`	none	not supported
`blocking-enabled`	none	not supported

Table 1–6 http-listener Property Remapping


`http-listener` Property	New Owning Element	New Attribute Name
`maxKeepAliveRequests`	`http`	`max-connections`
`authPassthroughEnabled`	`http`	`auth-pass-through-enabled`
`compression`	`http`	`compression`
`compressableMimeType`	`http`	`compressable-mime-type`
`noCompressionUserAgents`	`http`	`no-compression-user-agents`
`compressionMinSize`	`http`	`compression-min-size-bytes`
`restrictedUserAgents`	`http`	`restricted-user-agents`
`cometSupport`	`http`	`comet-support-enabled`
`connectionUploadTimeout`	`http`	`connection-upload-timeout-millis`
`disableUploadTimeout`	`http`	`upload-timeout-enabled`
`chunkingDisabled`	`http`	`chunking-enabled`
`uriEncoding`	`http`	`uri-encoding`
`traceEnabled`	`http`	`trace-enabled`
`rcmSupport`	`http`	`rcm-support-enabled`
`jkEnabled`	`network-listener`	`jk-enabled`
`crlFile`	`ssl`	`crl-file`
`trustAlgorithm`	`ssl`	`trust-algorithm`
`trustMaxCertLength`	`ssl`	`trust-max-cert-length-bytes`
`tcpNoDelay`	`transport`	`tcp-no-delay`
`bufferSize`	`transport`	`buffer-size-bytes`
`use-nio-direct-bytebuffer`	`transport`	`byte-buffer-type`
`proxyHandler`	none	not supported
`proxiedProtocols`	none	not supported
`recycle-objects`	none	not supported
`reader-threads`	none	not supported
`acceptor-queue-length`	none	not supported
`reader-queue-length`	none	not supported
`connectionTimeout`	none	not supported
`monitoring-cache-enabled`	none	not supported
`monitoring-cache-refresh-in-millis`	none	not supported
`ssl-cache-entries`	none	not supported
`ssl3-session-timeout`	none	not supported
`ssl-session-timeout`	none	not supported

Table 1–7 http-protocol Attribute Remapping


`http-protocol` Attribute	New Owning Element	New Attribute Name
`version`	`http`	`version`
`forced-response-type`	`http`	`forced-response-type`
`default-response-type`	`http`	`default-response-type`
`dns-lookup-enabled`	none	not supported
`ssl-enabled`	none	not supported

Table 1–8 http-service Property Remapping


`http-service` Property	New Owning Element	New Attribute or Property Name
`accessLoggingEnabled`	`http-service`, `virtual-server`	`access-logging-enabled` attribute
`ssl-cache-entries`	`http-service`	unchanged property
`ssl3-session-timeout`	`http-service`	unchanged property
`ssl-session-timeout`	`http-service`	unchanged property
`proxyHandler`	`http-service`	unchanged property
`connectionTimeout`	`http-service`	unchanged property
all other properties	none	not supported

Table 1–9 keep-alive Attribute Remapping


`keep-alive` Attribute	New Owning Element	New Attribute Name
`max-connections`	`http`	`max-connections`
`timeout-in-seconds`	`http`	`timeout-seconds`
`thread-count`	none	not supported

Table 1–10 request-processing Attribute Remapping


`request-processing` Attribute	New Owning Element	New Attribute Name
`thread-count`	`thread-pool`	`max-thread-pool-size`
`initial-thread-count`	`thread-pool`	`min-thread-pool-size`
`header-buffer-length-in-bytes`	`http`	`header-buffer-length-bytes`
`request-timeout-in-seconds`	`http`	`request-timeout-seconds`
`thread-increment`	none	not supported

Table 1–11 ssl Attribute Changes


Previous Attribute or Property	Previous Owning Element	New `ssl` Attribute
none	none	`key-store`
none	none	`trust-store`
`crlFile` property	`http-listener`	`crl-file`
`trustAlgorithm` property	`http-listener`	`trust-algorithm`
`trustMaxCertLength` property	`http-listener`	`trust-max-cert-length-bytes`
all other `ssl` attributes	`ssl`	unchanged

Table 1–12 thread-pool Attribute Changes


Previous Attribute	Previous Owning Element	New `thread-pool` Attribute
none	none	`classname`
none	none	`max-queue-size`
`thread-pool-id`	`thread-pool`	`name`
`idle-thread-timeout-in-seconds`	`thread-pool`	`idle-thread-timeout-seconds`
`num-work-queues`	`thread-pool`	not supported
all other `thread-pool` attributes	`thread-pool`	unchanged

Table 1–13 virtual-server Attribute Changes


Previous Attribute or Property	Previous Owning Element	New `virtual-server` Attribute
`http-listeners` attribute	`virtual-server`	`network-listeners`
`accessLoggingEnabled` property	`http-service`	`access-logging-enabled`
`sso-enabled` property	`virtual-server`	`sso-enabled`
`ssoCookieSecure` property	`virtual-server`	`sso-cookie-secure`
all other `virtual-server` attributes	`virtual-server`	unchanged
all other `virtual-server` properties	`virtual-server`	unchanged, still properties

New Network Service Elements and Attributes

The following tables describe new Network Service elements and attributes. For attributes and properties remapped from discontinued elements to new elements, see Remapping of HTTP Service Attributes and Properties.

The new file-cache element has no new attributes. All of its attributes are remapped from the http-file-cache element. For details, see Table 1–4.

Table 1–14 New http Attributes


Attribute	Default	Description
`adapter`	`com.sun.grizzly.tcp.StaticResourcesAdapter`	(Optional) Specifies the class name of the static resources adapter.
`max-post-size-bytes`	`2097152`	(Optional) Specifies the maximum size of `POST` actions.

For remapped http attributes, see Table 1–3, Table 1–5, Table 1–6, Table 1–7, Table 1–9, and Table 1–10.

Table 1–15 New network-listener Attributes


Attribute	Default	Description
`protocol`	none	Specifies the `name` of the `protocol` associated with this `network-listener`. Although this attribute is required, a `protocol` is automatically created with the same `name` as the `network-listener` when you use `asadmin create-http-listener` to create a `network-listener`.
`thread-pool`	none	(Optional) Specifies the `name` of the `thread-pool` associated with this `network-listener`.
`transport`	none	Specifies the `name` of the `transport` associated with this `network-listener`. Although this attribute is required, the default `transport` is used when you use `asadmin create-http-listener` to create a `network-listener`.

For remapped network-listener attributes, see Table 1–5.

Table 1–16 New port-unification Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `port-unification`.
`classname`	none	Specifies the class name of the `port-unification` implementation.

Table 1–17 New protocol Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `protocol`.

For remapped protocol attributes, see Table 1–5.

Table 1–18 New protocol-chain Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `protocol-chain`.
`classname`	none	Specifies the class name of the `protocol-chain` implementation.
`type`	`STATELESS`	Specifies the type of protocol chain.

Table 1–19 New protocol-chain-instance-handler Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `protocol-chain-instance-handler`.
`classname`	none	Specifies the class name of the `protocol-chain-instance-handler` implementation.

Table 1–20 New protocol-filter Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `protocol-filter`.
`classname`	none	Specifies the class name of the `protocol-filter` implementation.

Table 1–21 New protocol-finder Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `protocol-finder`.
`classname`	none	Specifies the class name of the `protocol-finder` implementation.
`protocol`	none	Specifies the `name` of the `protocol` associated with this `protocol-finder`.

Table 1–22 New selection-key-handler Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `selection-key-handler`.
`classname`	none	Specifies the class name of the `selection-key-handler` implementation.

Table 1–23 New ssl Attributes


Attribute	Default	Description
`key-store`	none	(Optional) Specifies a key store.
`trust-store`	none	(Optional) Specifies a trust store.

For remapped ssl attributes, see Table 1–11.

Table 1–24 New thread-pool Attributes


Attribute	Default	Description
`classname`	`com.sun.grizzly.http.StatsThreadPool`	(Optional) Specifies the class name of the `thread-pool` implementation.
`max-queue-size`	`-1`	(optional) Specifies the maximum number of messages that can be queued until threads are available to process them. A value of `-1` specifies no limit.

For remapped thread-pool attributes, see Table 1–3, Table 1–10, and Table 1–12.

Table 1–25 New transport Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the `transport`.
`classname`	`com.sun.grizzly.TCPSelectorHandler`	(Optional) Specifies the class name of the `transport` implementation.
`selection-key-handler`	none	(Optional) Specifies the `name` of the `selection-key-handler` associated with this `transport`.
`idle-key-timeout-seconds`	`30`	(Optional) Specifies the idle key timeout.

For remapped transport attributes, see Table 1–2, Table 1–3, Table 1–5, and Table 1–6.