Chapter 2 About Sun GlassFish Enterprise Server

Enterprise Server is a Java EE 5 platform-compatible server for the development and deployment of Java EE applications and Java technology-based web services in large-scale production environments.

This chapter includes:

• What's New in Sun GlassFish Enterprise Server 2.1

• Sun GlassFish Enterprise Server Features

• Hardware and Software Requirements

• Using the Update Center

What's New in Sun GlassFish Enterprise Server 2.1

Bug fixes and enhancements – To view the complete list of bugs fixed in the release, see the GlassFish IssueTracker and bugs.sun.com. The following table lists some of the bugs fixed in this release.

Sun GlassFish Enterprise Server Features

These features were introduced in Sun Java System Application Server 9.1. Sun GlassFish Enterprise Server includes the following features:

• Registration with Sun Connection — You can use the installer, the Admin Console GUI, or the Update Center to register the product with Sun Connection. By registering the Enterprise Server with Sun Connection you receive benefits such as:

  • Patch information and bug updates

  • Screencasts and tutorials

  • News and events

  • Support and training offerings

• AIX operating system support — Enterprise Server is supported on the AIX operating system for domains that are created with the developer profile or the cluster profile.

  ---

  Note –

  The enterprise profile is not supported on the AIX operating system because HADB and NSS are not supported on the AIX operating system.

  ---

• Ubuntu operating system support — Enterprise Server is bundled with the Ubuntu Linux operating system.

  ---

  Note –

  Installation information in the Enterprise Server documentation set is not relevant to this operating system. The enterprise profile is not supported on the Ubuntu Linux operating system because HADB and NSS are not supported on the Ubuntu Linux operating system.

  ---

• SUSE Linux 64–bit support

• Multilevel relationship prefetching support— Multilevel relationship prefetching for container-managed persistence (CMP) 2.1 entity beans is now supported. For more information, see Enabling Multilevel Relationship Prefetching.

• Enhanced JBI support — You can update a JBI component through the Admin Console GUI or from the command line without the need to redeploy any service assemblies that are already deployed.

• Java EE 5 platform support — Sun GlassFish Enterprise Server implements the Java EE 5 specification to deliver one of the best application runtimes for next-generation enterprise applications and web services. Enterprise Server implements the following Java EE standards:

  • Enterprise Java Beans 3.0

  • JAXB 2.0

  • Java Persistence

  • Java Server Faces 1.2

  • Java Server Pages 2.1 (JSP 2.1)

  • Java Server Pages Standard Tag Library (JSTL) 1.2

  • Streaming API for XML (StAX)

  • Web Services Metadata

  • Java API for XML based Web Services 2.0 (JAX-WS 2.0)

  • Common Annotations for the Java Platform 1.0 (CAJ 1.0)

  • Java Servlet 2.5

  The complete list of Java EE 5 platform technologies is provided later in these notes.

• Web Services Interoperability Technologies (WSIT) support – Sun is working closely with Microsoft to ensure interoperability of Web services enterprise technologies such as message optimization, reliable messaging, and security. The initial release of WSIT is a product of this joint effort. WSIT is an implementation of a number of open web services specifications to support enterprise features. In addition to message optimization, reliable messaging, and security, WSIT includes a bootstrapping and configuration technology. Starting with the core XML support currently built into the Java platform, WSIT uses or extends existing features and adds new support for interoperable web services, including:

  • Bootstrapping and Configuration

  • Message Optimization Technology

  • Reliable Messaging Technology

  • Security Technology

  See More About WSIT Integration later in this chapter for more information about WSIT integration in Enterprise Server.

• JBI support – JBI extends Java EE with business integration Service Provider Interfaces (SPI). These SPI enable developers to create or implement a Java business integration environment for specifications such as WSCI, BPEL4WS and the W3C Choreography Working Group. A JBI implementation is installed directly by the Enterprise Server installer, mostly in the as-install/jbi directory. This directory contains all common JAR files and system components for the JBI including a lifecycle module that starts the JBI framework in the Enterprise Server JVM.

• In-memory replication support – In-memory replication on other servers provides lightweight storage of session state data without the need to obtain a separate database, such as HADB. This type of replication uses memory on other servers for high availability storage of HTTP session and stateful session bean data. Clustered server instances replicate session state in a ring topology. Each backup instance stores the replicated data in memory. Replication of session state data in memory on other servers enables sessions to be distributed. The use of in-memory replication requires the Group Management Service (GMS) to be enabled (which is true by default).

• Usage profiles – Every administrative domain is associated with a usage profile, which identifies the capabilities of that domain. Enterprise Server provides the following profiles:

  • Developer – Use this profile if you are running your domain in a development environment and if your applications do not need clustering features, such as load balancing, high availability, and session replication. Note that the actual name of the profile is “developer” (case sensitive).

  • Cluster – Use this profile if you want to create clusters of application server instances imparting scalability and high availability to the deployed Java EE applications. The state of the applications is persisted in-memory. Note that the actual name of the profile is “cluster” (case sensitive).

  • Enterprise – Use this profile if you need HADB and NSS. This profile is not usable unless you install HADB and NSS separately or install the Enterprise Server as part of the Java Enterprise System (Java ES).

• Load balancing enhancements – Several enhancements have been added to the load balancing plugin. Briefly, these include

  • Weighted Round Robin – An optional attribute called weight has been added to the instance Loadbalancer.xml file. This option enables the load balancer plugin to route requests according to the weight. For example, for every 500 requests, 100 will go to instance1 and 400 would go to instance2. The default weight is 100. The weight is assigned to each instance from the admin console or command line, and the server domain.xml has an attribute for every instance indicating the weight.

  • User-Defined Load Balancer Decision – Enables users to define custom logic for load balancing; for example, user identity-based redirects and mime-based load balancing. This feature is implemented by means of a user-defined shared library that gets loaded by the load balancer. This custom shared library implements the interface as defined in loadbalancer.h, which is placed in as-install/lib/install/templates/.

  • Administration Enhancements – Previous versions of Enterprise Server required that the loadbalancer.xml file be manually copied to the particular server's config directory. Enterprise Server includes push automations for performing such copies between the Web server and Enterprise Server. The load balancer itself is configured in the server's domain.xml file.

• Open Source and GlassFish Community — In June 2005, Sun launched the GlassFish community with the goal of developing a free, open source, commerical-grade application server that implements the newest features of the Java EE 5 platform and related enterprise technologies. Enterprise Server is based on the source code developed by Sun engineers and the GlassFish community.

• Update Center Support – The Enterprise Server Update Center provides automated Enterprise Server updates and easy access to additional components. See Using the Update Center for more information.

Hardware and Software Requirements

This section lists the requirements that must be met before installing Sun GlassFish Enterprise Server.

• Supported Platforms

• Important Patch Information

• JDK Version

• To Switch to the Supported Java SE Version

• Apache Ant Version

• JDBC Drivers and Databases

• Using the Bundled Java DB Database

• Message Queue Versions

• Web Servers

• Browsers

• HADB Requirements and Supported Platforms

• Upgrading the Enterprise Server

• Other Requirements

Supported Platforms

All supported operating systems are 32-bit unless indicated otherwise. The 64-bit JDK is supported only on 64-bit supported operating systems.

The following table lists the operating systems with which the Sun GlassFish Enterprise Server 2.1 is compatible.

The table lists the minimum required version of each supported operating system.

Its recommended that you use the NTFS file system rather than FAT or FAT32 when running the Enterprise Server on any Microsoft Windows platform.

On UNIX^TM, you can check your operating system version using the uname command. Disk space can be checked using the df command.

Although Mac OS is not supported for production deployments, it is supported for development purposes. You can get information on downloading the Macintosh operating system from the GlassFish downloads page , or through the SDK page where Mac is listed. For example, on the Java EE 5 SDK Update 5 download page https://cds.sun.com/is-bin/INTERSHOP.enfinity/WFS/CDS-CDS_Developer-Site/en_US/-/USD/ViewProductDetail-Start?ProductRef=java_ee_sdk-5_05-nojdk-oth-JPR@CDS-CDS_Developer.

System Virtualization Support

System virtualization is a technology that enables multiple operating system (OS) instances to execute independently on shared hardware. Functionally, software deployed to an OS hosted in a virtualized environment is generally unaware that the underlying platform has been virtualized. Sun performs testing of its Sun Java System products on select system virtualization and OS combinations to help validate that the Sun Java System products continue to function on properly sized and configured virtualized environments as they do on non-virtualized systems. For information about Sun support for Sun Java System products in virtualized environments, see System Virtualization Support in Sun Java System Products.

Important Patch Information

Solaris Patch Requirements

It is recommended that Solaris 10 (x86, SPARC) users have the “Sun recommended patch cluster” installed. This patch cluster is available under “Recommended and Security Patches” on the SunSolve Web site.

JDK Version

The minimum (and certified) version of JDK required for Enterprise Server is 1.5.0_14.

To Switch to the Supported Java SE Version

You can switch to a supported Java SE version by editing the asenv file as described here.

1. If you have not already done so, install the new Java SE version on your system.

   The Java SE SDK can be downloaded from http://java.sun.com/javase

2. Stop the Enterprise Server.

   • From the command line:

     install_dir/bin/asadmin stop-domain

   • From the Administration Console:

     1. Click the Application Server node.

     2. Click Stop Instance.

3. Edit the install_dir/config/asenv.conf file (asenv.bat on Windows), changing the value for AS_JAVA to point to the new Java home directory:

4. Edit the as-install/samples/common.properties file, changing the line beginning com.sun.aas.javaRoot... to reference the new Java home directory.

5. Restart the Application Server.

   • From the command line:

     as-install/bin/asadmin start-domain

   • From the Administration Console:

     1. Click the Application Server node.

     2. Click Start Instance.

Apache Ant Version

Version 1.6.5 of Apache Ant is bundled with Enterprise Server on all operating systems except Ubuntu Linux. Version 1.7.0 of Apache Ant is bundled with Ubuntu Linux and used with Enterprise Server .

JDBC Drivers and Databases

Table 2–2 lists databases and drivers that meet the Java EE compatibility requirements. All supported configurations of the Sun GlassFish Enterprise Server must contain at least one database/driver combination from this table, such as the bundled Java DB database and driver. In addition, the Enterprise Server is designed to support JDBC connectivity to any additional DBMS with a corresponding JDBC driver.

Table 2–3 lists all the additional databases and drivers scheduled to be supported in the Enterprise Server FCS release.

In general, the Enterprise Server 2.1 supports all JDBC drivers that meet the Java EE specification.

Using the Bundled Java DB Database

This section provides instructions for using the Java DB database implementation bundled with Enterprise Server 2.1. Java DB is based on the Apache Derby database.

• Starting and Stopping the Java DB Database

• Java DB Utility Scripts

Starting and Stopping the Java DB Database

Sun GlassFish Enterprise Server has the following asadmin commands for starting and stopping the Java DB Network Server.

• Use the asadmin start-database command to start an instance of the Java DB network server:

  asadmin start-database [--dbhost 0.0.0.0] [--dbport 1527] [--dbhome path]

  The default value for the host is 0.0.0.0, which enables Java DB to listen on localhost as well as the IP/hostname interfaces. The value for the dbhome property is the location of where the Java DB databases reside. The default path is as-install/javadb.

• Use the asadmin stop-database command to shut down a running instance of the Java DB network server:

  asadmin stop-database [--dbhost 0.0.0.0] [--dbport 1527]

Java DB Utility Scripts

The Java DB configuration that is supplied with Enterprise Server 2.1 includes scripts that can help you use Java DB. The following scripts are available for use in the as-install/javadb/bin directory:

• startNetworkServer, startNetworkServer.bat— Script to start the network server

• stopNetworkServer, stopNetworkServer.bat— Script to stop the network server

• ij, ij.bat— Interactive JDBC scripting tool

• dblook, dblook.bat — Script to view all or part of the DDL for a database

• sysinfo, sysinfo.bat — Script to display versioning information about the Java DB environment

• NetworkServerControl, NetworkServerControl.bat — Script which provides a means of executing commands on the NetworkServerControl API

To Configure Your Environment to Run the Java DB Utility Scripts

1. Ensure that the JAVA_HOME environment variable specifies the directory where the JDK is installed.

2. Set the DERBY_HOME environment variable to point to the as-install/javadb directory.

See Also

For more information about these utilities, see the following Derby documentation:

• Derby Tools and Utilities Guide

• Derby Server and Administration Guide

Message Queue Versions

For file-based installations, Message Queue 4.3 is co-packaged with Enterprise Server. For UNIX package-based installations, Message Queue 4.1.1, which is functionally equivalent to 4.3, is provided. Despite the version numbering, Message Queue 4.1.1 is actually backward-compatible with Message Queue 4.2.

The embedded Sun GlassFish Message Queue code that is supplied as part of Enterprise Server is only tested and certified (typically) against the equivalent version of the Message Queue broker. This means that using the supplied embedded Message Queue code to connect to a remote (not managed by Enterprise Server) Message Queue broker running a different version of the Message Queue code is not supported.

Web Servers

This section lists the web servers that are supported for the Sun GlassFish Enterprise Server .

Only 32–bit platforms are supported.

Browsers

This section lists the browsers that are supported with the Sun GlassFish Enterprise Server 2.1.

HADB Requirements and Supported Platforms

In addition to the requirements listed in Hardware and Software Requirements, verify that your system meets the requirements listed below for running HADB.

• Supported Platforms

• HADB Server Host Requirements

• HADB Management Host Requirements

• HADB Client Host Requirements

HADB is only bundled with the Enterprise Server 2.1 Enterprise profile. Also note that the Java components of the system have been built with JDK 5 and has been tested on JDK 1.5.

Supported Platforms

• Solaris (SPARC). – Solaris 8 MU7, Solaris 9 MU7, Solaris 10 RR.

• Solaris (x86). – Solaris 9 MU7, Solaris 10 RR.

• Red Hat Enterprise Linux. 2.1 U5 (only ext2 file system is supported, not ext3). 3.0 U4 (both ext2 and ext3 are supported. Updates before U4 are not recommended due to excessive swapping.) Note that HADB is tested on these operating system versions in 32–bit mode only. Also, note that HADB does not support Red Hat Enterprise Linux 3.0 running in 64–bit mode due to a bug in the operating system (see known bug 6249685 in the High Availability section for details about impact on HADB). Versions 4 and 5 are also supported.

• Microsoft Windows. – Microsoft Windows 2000 Advanced Server Service Pack 4 and Microsoft Windows 2003 Enterprise Edition. Note that HADB does not support any of the forthcoming Microsoft Windows operating system versions in 64–bit mode.

HADB Server Host Requirements

• Minimum memory - 320 MB per node.

• Minimum free disk space - 70 MB for HADB binaries per host. In addition, disk space is needed for the data devices, 512 MB for a test installation per node.

• Recommended memory - 512 MB per node.

• Recommended free disk space - 70 MB for HADB binaries per host. In addition, disk space is needed for the data devices, 1200 MB for a test installation per node.

Make sure write caching is disabled on devices storing HADB data and log files. Write caching is enabled by default on some Solaris platforms; for example, Solaris x86.

HADB Management Host Requirements

• Minimum memory - 128 MB

• Minimum free disk space - 70 MB for HADB binaries per node

HADB Client Host Requirements

• Minimum memory - 120 MB

• Minimum free disk space - 20 MB

Upgrading the Enterprise Server

Refer to the Sun GlassFish Enterprise Server 2.1 Upgrade guide for complete instructions for upgrading from a previous version of the Enterprise Server to the current version.

Other Requirements

The following additional requirements should be met before installing the Sun GlassFish Enterprise Server software.

• Free space: your temporary directory must have a minimum of 35MB free for Sun GlassFish Enterprise Server installation, and 250 MB of free space for the SDK installation.

• Using the uninstall program: If you need to remove the Enterprise Server from your system, it is important to use the uninstall program that is included with the software. If you attempt to use another method, problems will arise when you try to reinstall the same version, or when you install a new version.

• Free ports: You must have seven unused ports available. The installation program automatically detects ports in use and suggests currently unused ports for the default domain. By default, the initial default ports are:

  • 8080 for HTTP, 8181 for HTTPS

  • 3700 for IIOP, 3820 for IIOP/SSL and 3920 for IIOP/SSL with Mutual Authentication

  • 4848 (HTTP) for the Administration Server

  • 8686 (RMI) port for pure JMX Clients

  Starting previously-installed servers (UNIX) — unless you are replacing the previously installed server, you should start it before you begin the Sun GlassFish Enterprise Server 2.1 installation process. This allows the installation program to detect ports that are in use and avoid assigning them for other uses.

• Replacing previously-installed servers (UNIX) — Refer to the Sun GlassFish Enterprise Server 2.1 Upgrade guide for complete instructions for upgrading from a previous version of the Enterprise Server.

• Shutting down firewall (Microsoft Windows) — You must stop any firewall software before installing the Sun GlassFish Enterprise Server software, because some of this software disables all ports by default. The installation program must be able to accurately determine which ports are available.

  For further compatibility information, see theSun GlassFish Enterprise Server 2.1 Upgrade guide.

Java EE 5 Platform APIs

The Sun GlassFish Enterprise Server 2.1 supports the Java EE 5 platform. The following table lists the enhanced APIs available on the Java EE 5 platform.

Java EE 5 SDK

Sun GlassFish Enterprise Server 2.1 is available as part of the Java EE 5 SDK.

There are two Java EE 5 SDK versions:

• Java Application Platform SDK

• Java EE 5 SDK

In addition, you can download these SDK distributions with the JDK or with the NetBeans 5.5.1 tools. For more information, access the download page at http://java.sun.com/javaee/downloads/index.jsp.

GlassFish v2.1 and Enterprise Server 2.1 does not work with NetBeans 5.5 for developing Java EE applications. You must use NetBeans 5.5.1.

Switching to Another Supported Java Version

Sun GlassFish Enterprise Server 2.1 requires Java SE 5.0 or greater as the underlying JVM. If you want to switch from one Java version to another, perform the following general steps. (Windows and Unix)

Downgrading to an earlier Java version is not recommended after a domain has been created with a newer Java VM. If you must downgrade your JVM, it is recommended that you do it on a per-domain basis. The following procedure describes how to do this.

To Switch to Another Supported Java Version

1. Download the desired Java SDK (not the JRE) and install it on your system, if you have not already done so.

   The Java SDK can be downloaded from http://java.sun.com/j2se.

2. Start the domain for which you want to change the JDK:

   as-install/bin/asadmin start-domain domain-name

3. Log in to the Admin console and change the JVM attributes for the domain.

   In particular, you may want to change the JAVA_HOME variable on the JVM Settings page for the domain.

   Alternatively, you can use the asadmin command:

   as-install/bin/asadmin set "server.java-config.java-home=Path-To-Java-Home"

Known Java ES 5 Compatibility Issues

There are two known compatibility issues between Enterprise Server 2.1 and Java ES 5 (JES5).

1. The JES5 Service Registry is not compatible with Enterprise Server 2.1 because of the JSF 1.2 version provided by Enterprise Server 2.1. The Service Registry needs to be upgraded to JES5u1 prior the Enterprise Server upgrade to 2.1. This limitation is also documented in the Service Registry documentation.

2. The JES5 Portal Server is not compatible with Enterprise Server 2.1 because of the JSF 1.2 version provided by Enterprise Server 2.1. Portal Server needs to be upgraded to JES5u1 prior the 2.1 upgrade to 2.1.

   On a Java ES 5 setup that has Portal Server on Enterprise Server 8.2, upgrading Enterprise Server 8.2 to 2.1 makes the Portal Server unusable. Enterprise Server 2.1 uses JSF 1.2, but the JSF-Portlet bridge in Release 5 Portal Server does not support JSF 1.2. On Solaris/Linux the Portal Server needs to be upgraded to JavaES5 Update 1. On Windows do not upgrade Enterprise Server to 2.1 if you want to continue using the Release 5 Portal Server, as Portal Server is not supported in Java ES 5 Update 1 on Windows.

Features Not Supported on All Operating Systems

Some features of the Enterprise Server are not supported on all operating systems. Details about these features are provided in the subsections that follow.

Features Not Supported on the AIX Operating System

If you are using the AIX operating system, the following limitations apply:

• Enterprise Server 2.1 is supported on the AIX operating system only for domains that are created with the developer profile or the cluster profile. The enterprise profile is not supported on the AIX operating system because HADB and NSS are not supported on the AIX operating system.

• For the AIX operating system, the native launcher is not available.

Features Not Supported on the Linux Operating System

If you are using the Linux operating system, the following limitations apply:

• For the SUSE Linux 64–bit operating system and RHEL 64–bit operating system on 64–bit JVM, the native application server launcher is not available. Use 32–bit JVM instead.

• For the SUSE Linux 64–bit operating system and RHEL 64–bit operating system on 64–bit JVM, the installer is not available. Use 32–bit JVM instead.

• The enterprise profile is not supported on the following platforms:

  ---

  Note –

  For a description of the supported profiles, see Usage Profiles in Sun GlassFish Enterprise Server 2.1 Administration Guide.

  ---

  • Red Hat Enterprise Linux 64–bit operating system and 64–bit JVM

  • SUSE Linux 64–bit operating system and 64–bit JVM

Features Not Supported on the Ubuntu Operating System

If you are using the Ubuntu Linux operating system, the following limitations apply:

• Because Enterprise Server 2.1 is bundled with the Ubuntu Linux operating system, installation information in the Enterprise Server 2.1 documentation set is not relevant to this operating system.

• The enterprise profile is not supported on the Ubuntu Linux operating system because HADB and NSS are not supported on the Ubuntu Linux operating system.

Using the Update Center

The Update Center provides automated Enterprise Server updates and easy access to additional components.

When the Update Center is enabled, it performs an automated software update. During this automated update process, the Update Center collects and transmits the following data to Sun Microsystems (or its service provider):

• Unique installation ID (GUID)

• IP address

• Operating system information (name, version, architecture, locale)

• JDK version

• Module download information (module name, date, time, status, download time, number of bytes downloaded)

No personally identifiable information is tracked. No personally identifiable information is associated with any other data or used for reporting purposes.

To Use the Update Center

To ensure explicit agreement of the automated update, the Update Center is disabled by default. To enable the Update Center to perform periodic checks and automated updates:

1. Start the Update Center.

   • On Unix: <installdir>/updatecenter/bin/updatetool

   • On Windows: <installdir>\updatecenter\bin\updatetool.bat

2. Select the Preferences tab.

3. In the Update Scheduling window, change the Check for Updates drop-down box value from Never (Manual) to a desired value. For example, daily or weekly.

4. Specify the desired day of the week and time of the day for the update.

5. Select the Save button to save your changes.

   The Update Center will now automatically check for Enterprise Server component updates according to the schedule specified. When an update is available, the Update Center will launch and notify you of the component available to update.

Upgrading the Enterprise Server on the Ubuntu Operating System

On the Ubuntu Linux operating system, installing GlassFish v2 does not override an existing installation of GlassFish v1. The asadmin script in /usr/bin administers GlassFish v2. To administer GlassFish v1, use its local asadmin utility in /usr/share/sunappserver/bin. To upgrade the v1 domain to v2, use the asupgrade tool located in /usr/share/glassfishv2/bin.

Using the global asadmin script to start a v1 domain results in the upgrade tool being invoked automatically. However, this causes an error due to a bug that uses the default domain location of the server for other (non-Ubuntu) platforms. To avoid this error, use the asupgrade tool instead.

Enabling Multilevel Relationship Prefetching

Multilevel relationship prefetching is supported for CMP 2.1 entity beans.

To enable multilevel relationship prefetching, set the following property:

-Dcom.sun.jdo.spi.persistence.support.sqlstore.MULTILEVEL_PREFETCH=true

For more information about relationship prefetching, see Relationship Prefetching in Sun GlassFish Enterprise Server 2.1 Developer’s Guide.

More About WSIT Integration

For detailed information about WSIT status, refer to the WSIT Status Notes page. Also refer to the The WSIT Tutorial for information about using WSIT with Enterprise Server.