user-home-directory/glassfish3
Copyright © 2019, Oracle and/or its affiliates. All rights reserved.
|
GlassFish Server Upgrade Compatibility Issues DRAFT |
| Previous | Next | Contents |
This section describes some compatibility issues between GlassFish Server 4.0 and earlier product releases. This section also describes some compatibility issues that affect Java applications that run on earlier product releases with which Oracle GlassFish Server 4.0 is binary-compatible. When you upgrade to GlassFish Server 4.0, you must address these issues.
The following topics are addressed here:
GlassFish Server Open Source Edition 4.0 is binary-compatible with the following earlier releases of the software:
Sun GlassFish Enterprise Server v2.1.1 (Enterprise and Developer Profiles)
Sun GlassFish Enterprise Server v3
GlassFish Server Open Source Edition 3.0.1
GlassFish Server Open Source Edition 3.1
GlassFish Server Open Source Edition 3.1.1
Java applications that run on these releases also work on GlassFish Server Open Source Edition 4.0 except for the compatibility issues that are listed in the remainder of this chapter.
Note: The compatibility issues that are listed in the remainder of this chapter do not affect Java applications that run on Sun GlassFish Enterprise Server v3 and GlassFish Server 3.0.1. The differences between GlassFish Server 4.0 and the Enterprise Server v3 releases do not affect applications and data. |
The default GlassFish Server 4.0 installation directories are as follows:
user-home-directory/glassfish3SystemDrive\glassfish3In GlassFish Server 3.0.1 and Enterprise Server v3, the default
installation root directory was glassfishv3.
The functionality of the Group Management Service (GMS) has not changed since Sun GlassFish Enterprise Server v2.1.1, but the names of GMS settings have been changed in the Administration Console to make them more understandable. These changes are made automatically during the upgrade process.
Changes to settings on the Edit Group Management Service page in the Administration Console are summarized in the following table.
Table 1-1 GMS Administration Console Settings Changes from 2.1.1 to 4.0
| Old Setting Name | New Setting Name |
|---|---|
Protocol Maximum Trial |
Maximum Missed Heartbeats |
Protocol Timeout |
Heartbeat Frequency |
Ping Timeout |
Group Discovery Timeout |
Verified Timeout |
Failure Verification Wait Time |
The Merge Protocol settings from Sun GlassFish Enterprise Server v2.1.1 are not supported and have been removed.
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 GlassFish Server 4.0 will have the compatibility
property set to v2 and will run without change on GlassFish Server
4.0. 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 GlassFish
Server 4.0 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-nameIf 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 GlassFish
Server 4.0 to upgrade the GlassFish 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. GlassFish Server 4.0 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.
GlassFish Server 4.0 does not support node agents. When updating from installations of earlier product versions in which node agents were configured, the cluster definitions will be migrated, but the clustered instances themselves must be manually re-created. See Upgrading Clusters and Node Agent Configurations for more information.
hadbm Command SupportGlassFish Server 4.0 does not support HADB or the hadbm management
command.
Instead of HADB, GlassFish Server 4.0 supports high availability clustering by means of in-memory session state replication and ActiveCache for GlassFish. See "High Availability in GlassFish Server" in GlassFish Server Open Source Edition High Availability Administration Guide for more information.
asadmin CommandThe following sections describe changes to the command line utility
asadmin:
For more information about asadmin and its subcommands, see the
GlassFish Server Open Source Edition Reference Manual.
asadmin SubcommandsIn GlassFish Server 4.0, 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
Options in Table 1-2 are deprecated or no longer supported, or are obsolete and are ignored.
Table 1-2 Deprecated, Unsupported, and Obsolete Options for asadmin
and Subcommands
| Option | Affected Subcommands |
|---|---|
|
Unsupported for the |
|
Unsupported for the |
|
Unsupported for all relevant subcommands. Use
|
|
Obsolete for the |
|
Obsolete for the |
|
Obsolete for the |
|
Unsupported for the |
|
Unsupported for the |
|
Unsupported for the |
|
Deprecated for the |
|
Obsolete for the |
|
Obsolete for the |
|
Obsolete for the |
|
Obsolete for the |
|
Obsolete for the |
|
Obsolete for the |
|
Deprecated for the |
|
Deprecated for the |
|
Obsolete for the |
|
Replaced by the all lowercase option
|
|
Unsupported for the |
|
Unsupported for all remote subcommands. Use
|
|
Unsupported for the |
|
Obsolete only for the |
|
Unsupported for all relevant subcommands. Use
|
|
Obsolete for the |
|
Obsolete for the |
|
Obsolete only for the following subcommands:
Replaced by an operand in the |
The directory location of Java DB in GlassFish Server 4.0 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 GlassFish
Server 4.0. 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:
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
After upgrade, start GlassFish Server 4.0.
GlassFish Server 4.0 and 3.0.1, and Sun GlassFish Enterprise Server v3 use the persistence provider EclipseLink, while earlier versions used TopLink Essentials.
An application that uses the container to create an EntityManager or
EntityManagerFactory and that used Toplink Essentials as its provider
will work in GlassFish Server 4.0. The container creates an
EntityManager if the application uses the @PersistenceContext
annotation to inject an EntityManager, as in the following example:
@PersistenceContext
EntityManager em;The container creates an EntityManagerFactory if the application uses
the @PersistenceUnit annotation to inject an EntityManagerFactory,
as in the following example:
@PersistenceUnit
EntityManagerFactory emf;
EntityManager em = emf.createEntityManager();When the application is loaded, GlassFish Server 4.0 will translate the
provider to EclipseLink and will also translate toplink.* properties
in the persistence.xml to corresponding EclipseLink properties. (The
actual persistence.xml file remains unchanged.)
Under certain circumstances, however, you may have to modify the
persistence.xml file or your code:
If your application uses Java SE code to create the
EntityManagerFactory, you will need to change your persistence.xml
file for both the provider element and for any toplink.* properties
to use the EclipseLink equivalents. An application uses Java SE code if
it uses the javax.persistence.Persistence class to create the
EntityManagerFactory, as in the following example:
EntityManagerFactory emf =
javax.persistence.Persistence.createEntityManagerFactory("Order");
EntityManager em = emf.createEntityManager();
In this case, change the provider element to specify the following:
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>If the application itself contains any TopLink Essentials-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
(http://wiki.eclipse.org/EclipseLink/Examples/MigratingFromOracleTopLink#Rename_Packages)
to do this. This tool is not provided with GlassFish Server 4.0,
however, so you must obtain it from the EclipseLink project download
site.
In GlassFish Server 4.0, most HTTP Service settings are defined in the Network Service configuration that was introduced in Sun GlassFish Enterprise Server v3.
The changes are described in the following sections.
The dotted name hierarchy for the HTTP Service configuration in
GlassFish Server 4.0 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-poolThe dotted name hierarchy for the GlassFish Server 4.0 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-poolThe following example compares the commands for setting a listener port for Sun GlassFish Enterprise Server v3 and GlassFish Server 4.0. Note that the configuration for Enterprise Server v3 also applies to all earlier Enterprise Server 2.x releases.
Command for Sun GlassFish Enterprise Server v3 and earlier:
asadmin set server-config.http-service.http-listener.http-1.listenerport=4321
Command for GlassFish Server 4.0:
asadmin set server-config.network-config.network-listeners.network-\ listener.http-1.listenerport=4321
asadmin SubcommandsTo accommodate the move of HTTP Service into the new Network Service
configuration, asadmin subcommands are changed as
follows:
The create-ssl subcommand has a new --type
parameter value, network-listener.
The create-virtual-server SUBcommand has a new
parameter, --networklisteners.
The create-http-listener subcommand adds a
network-listener element to the domain configuration. The syntax and
options of this commands are unchanged.
The following tables describe how attributes and properties in the HTTP Service configuration for GlassFish Server 4.0 are remapped to attributes in the Network Service configuration for older product releases. If you use a configuration from a Sun GlassFish Enterprise Server v2 or v3 release, this remapping happens automatically and then discontinued elements are deleted.
Table 1-3 com.sun.grizzly Property Remapping
com.sun.grizzly Property |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 1-4 connection-pool Attribute Remapping
connection-pool Attribute |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Table 1-5 http-file-cache Attribute Remapping
http-file-cache Attribute |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
Table 1-6 http-listener Attribute Remapping
http-listener Attribute |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
Table 1-7 http-listener Property Remapping
http-listener Property |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
|
none |
not supported |
Table 1-8 http-protocol Attribute Remapping
http-protocol Attribute |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
none |
not supported |
|
none |
not supported |
Table 1-9 http-service Property Remapping
http-service Property |
New Owning Element | New Attribute or Property Name |
|---|---|---|
|
|
|
|
|
unchanged property |
|
|
unchanged property |
|
|
unchanged property |
|
|
unchanged property |
|
|
unchanged property |
all other properties |
none |
not supported |
Table 1-10 keep-alive Attribute Remapping
keep-alive Attribute |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
none |
not supported |
Table 1-11 request-processing Attribute Remapping
request-processing Attribute |
New Owning Element | New Attribute Name |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
none |
not supported |
Table 1-12 ssl Attribute Changes
| Previous Attribute or Property | Previous Owning Element | New ssl
Attribute |
|---|---|---|
none |
none |
|
none |
none |
|
|
|
|
|
|
|
|
|
|
all other |
|
unchanged |
Table 1-13 thread-pool Attribute Changes
| Previous Attribute | Previous Owning Element | New thread-pool
Attribute |
|---|---|---|
none |
none |
|
none |
none |
|
|
|
|
|
|
|
|
|
not supported |
all other |
|
unchanged |
Table 1-14 virtual-server Attribute Changes
| Previous Attribute or Property | Previous Owning Element | New
virtual-server Attribute |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
all other |
|
unchanged |
all other |
|
unchanged, still properties |
The following tables describe the Network Service elements and attributes that were introduced in Sun GlassFish Enterprise Server v3. 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-5.
Table 1-15 New http Attributes
| Attribute | Default | Description |
|---|---|---|
|
|
(Optional) Specifies the class name of the static resources adapter. |
|
|
(Optional) Specifies the maximum size
of |
For remapped http attributes, see Table 1-4,
Table 1-6, Table 1-7, Table 1-8,
Table 1-10, and Table 1-11.
Table 1-16 New network-listener Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies the |
|
none |
(Optional) Specifies the |
|
none |
Specifies the |
For remapped network-listener attributes, see Table 1-6.
Table 1-17 New port-unification Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the |
|
none |
Specifies the class name of the |
Table 1-18 New protocol Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the |
For remapped protocol attributes, see Table 1-6.
Table 1-19 New protocol-chain Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the |
|
none |
Specifies the class name of the |
|
|
Specifies the type of protocol chain. |
Table 1-20 New protocol-chain-instance-handler Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the
|
|
none |
Specifies the class name of the
|
Table 1-21 New protocol-filter Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the |
|
none |
Specifies the class name of the |
Table 1-22 New protocol-finder Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the |
|
none |
Specifies the class name of the |
|
none |
Specifies the |
Table 1-23 New selection-key-handler Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the |
|
none |
Specifies the class name of the
|
Table 1-24 New ssl Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
(Optional) Specifies a key store. |
|
none |
(Optional) Specifies a trust store. |
For remapped ssl attributes, see Table 1-12.
Table 1-25 New thread-pool Attributes
| Attribute | Default | Description |
|---|---|---|
|
|
(Optional)
Specifies the class name of the |
|
|
(Optional) Specifies the maximum number of
messages that can be queued until threads are available to process them.
A value of |
For remapped thread-pool attributes, see Table 1-4,
Table 1-11, and Table 1-13.
Table 1-26 New transport Attributes
| Attribute | Default | Description |
|---|---|---|
|
none |
Specifies a unique name for the |
|
|
(Optional)
Specifies the class name of the |
|
none |
(Optional) Specifies the |
|
|
(Optional) Specifies the idle key timeout. |
GlassFish Server 4.0 does not support Network Security Services (NSS) cryptographic tokens. When upgrading to GlassFish Server 4.0 from Enterprise Server v2.x, additional manual configuration steps must be performed. These steps are explained later in this guide, in Upgrading Installations That Use NSS Cryptographic Tokens.
| Previous | Next | Contents |
Copyright © 2019, Oracle and/or its affiliates. All rights reserved.
DRAFT