Some compatibility issues affect Java applications that run on earlier releases with which Oracle GlassFish Server 3.0.1 (GlassFish Server 3.0.1) is binary compatible. When you upgrade to GlassFish Server 3.0.1, you must address these issues.
The following topics are addressed here:
Oracle GlassFish Server 3.0.1 (GlassFish Server 3.0.1) is binary compatible with the following earlier releases of the software:
Sun JavaTM System Application Server 9.1 Update 2 (Developer Profile)
Sun GlassFishTM Enterprise Server v2 Update 2 (Developer Profile)
Sun GlassFish Enterprise Server v2.1 (Developer Profile)
Sun GlassFish Enterprise Server v2.1.1 (Developer Profile)
Sun GlassFish Enterprise Server v3 Prelude
Sun GlassFish Enterprise Server v3
Java applications that run on these releases also work on GlassFish Server 3.0.1 except for the compatibility issues that are listed in the remainder of this chapter.
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. The differences between GlassFish Server 3.0.1 and Sun GlassFish Enterprise Server v3 do not affect applications and data.
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 3.0.1 will have the compatibility property set to v2 and will run without change on GlassFish Server 3.0.1. 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 3.0.1 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 GlassFish Server 3.0.1 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 3.0.1 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.
The following sections describe changes to the command line utility asadmin:
For more information about asadmin and its subcommands, see Oracle GlassFish Server 3.0.1 Reference Manual.
Subcommands are backward compatible except as noted below.
The following subcommand is deprecated.
deploydir (use deploy instead)
In GlassFish Server 3.0.1, 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–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. |
The directory location of Java DB in GlassFish Server 3.0.1 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 3.0.1. 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 GlassFish Server 3.0.1.
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.
GlassFish Server 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 3.0.1. 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 3.0.1 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 to do this. This tool is not provided with GlassFish Server 3.0.1, however, so you must obtain it from the EclipseLink project download site.
During the upgrade process, archives for previously deployed applications are re-created 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.
In GlassFish Server 3.0.1 and Sun GlassFish Enterprise Server v3, most HTTP Service settings are 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 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 Sun GlassFish Enterprise Server v3 Prelude and GlassFish Server 3.0.1 or Sun GlassFish Enterprise Server v3.
Command for Sun GlassFish Enterprise Server v3 Prelude:
asadmin set server-config.http-service.http-listener.http-1.listenerport=4321 |
Command for GlassFish Server 3.0.1 or Sun GlassFish Enterprise Server v3:
asadmin set server-config.network-config.network-listeners.network-listener.http-1.listenerport=4321 |
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.
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 GlassFish Server 3.0.1 and Sun GlassFish Enterprise Server v3. 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–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 |
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–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.