Chapter 1 Sun GlassFish Enterprise Server v3 Prelude Release Notes

The Sun GlassFish^TM Enterprise Server v3 Prelude Release Notes contain important information for the Enterprise Server v3 Prelude release, including new Enterprise Server features and known issues with workarounds, if available.

Check this document prior to installing and setting up your software, and read this document before you begin using Sun GlassFish Enterprise Server v3 Prelude. Consult this document periodically to view the most up-to-date documentation.

• Revision History

• What’s New in the Sun GlassFish Enterprise Server v3 Prelude Release?

• Hardware and Software Requirements

• Known Issues

• Restrictions

• Enterprise Server Documentation Set

• How to Report Problems and Provide Feedback

• Additional Resources

• Third-Party Web Site References

• Accessibility Features

Revision History

This section provides a record of changes inSun GlassFish Enterprise Server v3 Prelude Release Notes.

What’s New in the Sun GlassFish Enterprise Server v3 Prelude Release?

Sun GlassFish Enterprise Server v3 Prelude provides a server for the development and deployment of Java Platform, Enterprise Edition (Java^TM EE platform) applications and web technologies based on Java technology.

Web applications that are developed by using Enterprise Server v3 Prelude can be deployed in earlier versions of the Enterprise Server, for example, GlassFish v2 Application Server.

The following new features of Enterprise Serverare described here:

• Modular Design

• Support for Extending Enterprise Server

• Support for Embedding Enterprise Server

• Update Tool Integration

• Support for Scripting Languages

• Web Tier Extensions

Modular Design

Sun GlassFish Enterprise Server v3 Prelude has split the GlassFish code into modules to provide flexibility and improved runtime performance. The modular architecture is implemented on top of OSGi Alliance standards and enables reusability of Enterprise Server v3 Prelude modules as well as other modules.

This design change allows you to download and install only the modules that you require for the applications that you are deploying. Runtime is used only for applications that use it, and upgrades can be implemented without a complete system reinstallation. This change minimizes startup times, memory consumption, and disk space requirements.

The modular design provides the ability to do the following:

• Import OSGi bundles

• Import library Java archive (JAR) files

• Embed Enterprise Server in other self-contained applications

• Replace the Enterprise Server web container with another web container

Support for Extending Enterprise Server

A new Sun GlassFish Enterprise Server v3 Prelude container system provider interface (SPI) defines interfaces that the container developer must implement so that Enterprise Server can call into it at appropriate times. This change enables Enterprise Server users to create custom application servers by adding administrative commands and graphical add-on components.

Enterprise Server also provides streamlined support of new module types, such as Ruby on Rails.

Support for Embedding Enterprise Server

Because Sun GlassFish Enterprise Server v3 Prelude is based on OSGi Alliance standards, OSGi modules can easily be embedded in any runtime based on OSGi. Enterprise Server itself can be embedded in other compatible modules or applications.

A non-modular version of Enterprise Server v3 Prelude with a reduced set of dynamic features can be embedded in a Java or native runtime.

Update Tool Integration

Update Tool is now embedded in the Sun GlassFish Enterprise Server v3 Prelude Administration Console. This tool provides automated updates, and facilitates managing add-on components and related applications that are available for extending Enterprise Server v3 Prelude functions.

The Administration Console provides access to the Update Tool page through the navigation tree. The Update Tool page provides tabs to display the following:

• Components that are installed

• Updates that are available for installed components

• Add-on components that are available and can be installed

Integration of Update Tool in Administration Console enables administrators to extend and update Enterprise Server without the need to launch a standalone version of Update Tool by using the updatetool command.

The Update Tool is developed through the Update Center project. The Administration Console uses the Update Center 2.0 API to display a list of available components, versions and dates. For information about Update Center 2.0, see the Release Notes for Update Center 2.0 .

Support for Scripting Languages

To facilitate rapid application development and deployment, Sun GlassFish Enterprise Server v3 Prelude supports a variety of scripting languages. The use of scripting languages enables Enterprise Server to be applied beyond developments that are centered on Java technology. Supported scripting languages include the following:

• JRuby and Rails: A scripting language and a framework for developing web applications

• Grails: A web application framework that leverages the Groovy programming language and complements Java web development

• Phobos: A lightweight, scripting-friendly web application environment that supports JavaScript programming language so that developers can use the same language on the client and server tier of a web application

• jMaki: A framework for creating Ajax web applications

Support for these scripting languages is provided by components that are available through Update Tool.

Web Tier Extensions

Sun GlassFish Enterprise Server v3 Prelude supports the web tier of the Java EE specification to enable the deployment of web applications. Enterprise Server implements the following Java EE technology standards:

• Java Persistence API 1.0

• Java Servlet 2.5

• JavaServer^TM Faces 1.2

• Java Server Pages^TM 2.1 (JSP^TM 2.1)

• Java Server Pages Standard Tag Library (JSTL) 1.2

• Streaming API for XML (StAX)

Building on these standards, Enterprise Server v3 Prelude provides a number of extensions, including the following:

• Comet and Representation State Transfer (REST): Reduce latency when a server uses hypertext transmission protocol (HTTP) to transmit domain-specific data and eliminate an additional messaging layer such as simple object access protocol (SOAP).

• Ajax (asynchronous JavaScript and XML): Retrieves and displays new data for a portion of a web page without affecting the rest of the page.

• Metro: A web services stack that implements Java Architecture for XML Binding (JAXB) and Java APIs for XML Web Services 2.1 (JAX-WS 2.1).

• Roller: A blog server that runs on any Java EE server using any relational database.

• Grizzly: A framework for building scalable and robust servers using New I/O (NIO) APIs, which make scaling to thousands of users possible. The ability to embed components that support HTTP, Bayeux Protocol, Java Servlet API, and Comet is provided.

Hardware and Software Requirements

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

• Supported Platforms

• System Virtualization Support

• Required Disk Space

• Required Free Ports

• Important Patch Information

• Required JDK Version

• Supported JDBC Drivers and Databases

• Supported Browsers

Supported Platforms

Sun GlassFish Enterprise Server v3 Prelude requires a minimum of 200 Mbytes of free disk space to install, and 100 Mbytes of free memory to run.

This following table lists supported operating systems and provides minimum memory, recommended memory, minimum disk space, recommended disk space, and Java virtual machine for each.

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

Use the NTFS file system rather than FAT or FAT32 when running the Enterprise Server on any Microsoft Windows platform.

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.

Required Disk Space

Your temporary directory must have a minimum of 35 MB of free space for the installation of Enterprise Server v3 Prelude.

Required Free Ports

You must have seven unused ports available.

The installation program automatically detects ports that are in use and suggests currently unused ports for the default settings.

The initial default port assignments are listed in the following table. If these default port numbers are in use, the installation program assigns a randomly selected port number from the dynamic port range. The selected port number might not be the next available port number.

Important Patch Information

Solaris Patch Requirements

If you are using the Solaris 10 operating system, you must apply the appropriate patch for your platform as listed in the following table.

These patches are available from the SunSolve^SM program web site. In the Patch Finder section, type the patch number in the text box, and click the Find Patch button.

If you are using the Solaris 10 OS (x86, SPARC platforms), ensure that the Sun recommended patch cluster is applied. This patch cluster is available from the SunSolve program web site. In the Downloads section, click the Recommended and Security Patches link. When the license agreements is displayed, click the Agree button.

Required JDK Version

Installation of Sun GlassFish v3 Prelude Enterprise Server requires JDK^TM release 5 or JDK release 6.

The following binary files that are used with Enterprise Server must come from the JDK software, not the Java Runtime Environment (JRE^TM) software:

• java

• keytool

To meet this requirement, ensure that the bin directory of the JDK software is at the start of your path.

Supported JDBC Drivers and Databases

The following table lists databases and drivers that meet the Java EE compatibility requirements. All supported configurations of the Sun GlassFish Enterprise Server v3 Prelude must contain at least one combination of database and driver from this table, such as the Java DB and driver. In addition, the Enterprise Server is designed to support connectivity through Java DataBase Connectivity (JDBC^TM) technology to any additional database management system (DBMS) with a corresponding driver that supports the JDBC API (JDBC driver).

In general, the Sun GlassFish Enterprise Server v3 Prelude supports all JDBC drivers that meet the Java EE specification.

Supported Browsers

The following table lists supported browsers and versions.

Known Issues

This section lists the following known issues with Enterprise Server:

• Registration Not Available During Red Hat Linux Installations (Issue 6058)

• Start and Stop Menu Items Launch the Administration Console in Minimized State (Issue 5100)

• Start Menu Items Do Not Display on Windows Vista Installations (Issue 5087)

• The delete-domain Command Does Not Check That Domain is not Running (Issue 6196)

• Windows Installation Directory Cannot be Removed When Update Tool Notifier is Running (Issue 5789)

• The uninstall.sh Command Does Not Delete All Files (Issue 6032)

• The uninstall.exe Command to Does Not Remove the Desktop Shortcut (Issue 5856)

• File Permissions on Domain /applications Directory Can Cause NullProcessException (Issue 6545)

• The Windows Installation Log File is not Readable (Issue 4881)

• Running updatetool Command to Start Update Center Produces a Segmentation Violation (Issue 5514)

• Client VM Is Not Supported on Windows AMD64 (Issue 6395)

• Anonymous User Has Administrator Privileges After a User Is Created (Issue 6481)

• Access to Statistics For New Virtual Servers Requires Server Restart (Issues 6238 and 6422)

• No Support for Logging Configuration is Provided in the Administration Console or at the Command Line (Issue 6630)

• Attempt to Use Administration Console to Create a Connection Pool Fails Even if the Driver Is Present (Issue 6671)

• Option Missing From Help Information for create jbdc-connection-pool (Issue 5766)

• In Bourne shell, all DAS, node agent, and instance processes exit when console window is closed. (6879701)

• Operand is missing from the man page example for ping-connection-pool. (6881540)

Registration Not Available During Red Hat Linux Installations (Issue 6058)

Description

Product Registration through installation is not supported when Open JDK is used in Red Hat Linux operating system.

For more information, see Issue report.

Workaround

To register your installation:

1. During installation on this environment, select the Skip Registration option.

2. Use the Administration Console or Update Center to register your installation.

Start and Stop Menu Items Launch the Administration Console in Minimized State (Issue 5100)

Description

The property Run field for the Start and Stop Application Server menu items is specified as Normal to open the Administration Console in a maximized state, but these menu items launch the Administration Console as though the property were set to Minimized.

For more information, see Issue report.

Workaround

You must maximize the Administration Console manually.

Start Menu Items Do Not Display on Windows Vista Installations (Issue 5087)

Description

After a Windows Vista installation is completed, the Start menu program group has these problems:

• The Start menu group is not shown.

• The Start menu group is empty. Start domain, stop domain, and start Update Center are not shown.

For more information, see Issue report.

Workaround

You must log out and log back in to display the Start menu item program group.

The delete-domain Command Does Not Check That Domain is not Running (Issue 6196)

Description

The delete-domain command does not verify whether the domain to be removed is running. If the domain to be removed is running when the delete-domain command runs, the command should fail and should notify the user to stop the domain.

For more information, see Issue report.

Workaround

Before the delete-domain command is executed, run the stop-domain command.

Windows Installation Directory Cannot be Removed When Update Tool Notifier is Running (Issue 5789)

Description

If you try to delete the glassfishv3-prelude directory from c:\Program files when Update Tool Notifier is running, you receive this error message: Error deleting File or Folder: Cannot delete msvcp71: Access is denied.

For more information, see Issue report.

Workaround

Before you delete the installation directory, stop Update Center Notifier by closing the window for this utility.

The uninstall.sh Command Does Not Delete All Files (Issue 6032)

Description

The message WARNING: Cannot delete file filename filename is generated following execution of uninstall.sh command.

For more information, see Issue report.

Workaround

Examine the contents of your directories to verify that the files are removed. If files remain, remove them manually. If you are removing a UNIX installation, check for and delete hidden directories.

The uninstall.exe Command to Does Not Remove the Desktop Shortcut (Issue 5856)

Description

The Desktop shortcut for Enterprise Server v3 Prelude remains in the Programs menu, and an error message is written to the log file after as-install/uninstall.exe, where as-install is the Enterprise Server installation directory.

For more information, see Issue report.

Workaround

Overwrite the entry by installing Enterprise Server v3 Prelude again, or manually remove the shortcut from the list.

File Permissions on Domain /applications Directory Can Cause NullProcessException (Issue 6545)

Description

If a domain's /applications directory restricts access, or if you use directory deployment from a restricted directory, the server cannot read the files in the expanded directory. A NullProcessException error occurs during deployment.

For more information, see Issue report.

Workaround

Change the file access settings for such directories yo grant the server permission to read the directory contents.

The Windows Installation Log File is not Readable (Issue 4881)

Description

The time-stamp-install.log file cannot be read, because all lines written to the file are concatenated into a single long string.

For more information, see Issue report.

Workaround

Use a different editor, and manually open the installation log file created under the %TEMP% directory.

Running updatetool Command to Start Update Center Produces a Segmentation Violation (Issue 5514)

Description

After Update Center is installed on a Solaris 10 x86 system, using the updatetool to start Update Center fails due to a segv error.

For more information, see Issue report.

Workaround

Use the Enterprise Server Administration Console to access Update Center.

For Solaris 10 x86 operating system installations, install patch 119964-08 and patch 125212-01.

Client VM Is Not Supported on Windows AMD64 (Issue 6395)

Description

By default Enterprise Server uses client VM to achieve best startup and deployment performance. If you use a JDK that includes only server VM, you must edit the domain.xml configuration file and remove the client line.

For more information, see Issue report.

Workaround

Ensure that Client JVM is supported on your platform/operating system. If it is not supported, edit the domain.xmlfile to remove the line <jvm-options>–client<jvm-options>. In this case, JVM ergonomics will choose the appropriate kind of VM for given platform.

For more information about platform support, see Ergonomics in the 5.0 Java Virtual Machine.

Anonymous User Has Administrator Privileges After a User Is Created (Issue 6481)

Description

Anonymous user is the default user created for the default domain. If another administrative user is added to the default domain, the anonymous user definition remains available for use. Any user can use the privileges of the anonymous user to perform Enterprise Server management tasks. This access can create a security problem for some development and production deployments.

For more information, see Issue report.

Workaround

Delete the anonymous user manually.

Access to Statistics For New Virtual Servers Requires Server Restart (Issues 6238 and 6422)

Description

Monitoring statistics about newly added virtual servers are available only after the server is restarted.

For more information, see the reports for Issue 6238 and Issue 6422.

Workaround

After adding a virtual server, restart the server to view monitoring data for the virtual server.

No Support for Logging Configuration is Provided in the Administration Console or at the Command Line (Issue 6630)

Description

No Support for logging configuration is provided in the Administration Console or at the command line.

For more information, see Issue report.

Workaround

Use a plain text editor to edit the as-install/domains/domain1/config/logging.properties file. For more information, see Configuring Logging in Sun GlassFish Enterprise Server v3 Prelude Administration Guide.

Attempt to Use Administration Console to Create a Connection Pool Fails Even if the Driver Is Present (Issue 6671)

Description

In some circumstances, an attempt to use the Administration Console to create a JDBC connection pool fails even if the driver is present. When this failure occurs, the Administration Console returns a server error such as HTTP Status 500.

For more information, see Issue report.

Workaround

Repeat the attempt to create the JDBC connection pool, specifying the data-source class name explicitly. You can use either the Administration Console or the asadmin utility for this task.

• If you use the Administration Console, see To Specify the Data-Source Class Name Explicitly When Using Administration Console.

• If you use the asadmin utility, see To Create a JDBC Connection Pool in Sun GlassFish Enterprise Server v3 Prelude Administration Guide. In the create-jdbc-connection-pool(1) command, specify the --restype option and the --datasourceclassname option as follows:

  --restype

  The interface that the data-source class implements.

  --datasourceclassname

  The name of the vendor-supplied JDBC data-source class.

  For an example that shows how to set these options, see Example 1–1.

The required class name depends on the resource type. For example, for the MySQL database, the required class name for each resource type is as shown in Table 1–6.

For other database drivers, consult the documentation from the database driver vendor.

Example 1–1 Creating a JDBC Connection Pool by Using the asadmin Utility

This example shows how to create a JDBC connection pool that is named mysql-pool for the MySQL database. The vendor-supplied JDBC data-source class is com.mysql.jdbc.jdbc2.optional.MysqlDataSource. This class implements the javax.sql.DataSource interface.

asadmin create-jdbc-connection-pool 
--datasourceclassname=com.mysql.jdbc.jdbc2.optional.MysqlDataSource
--restype=javax.sql.DataSource
--property="user=DBUSER:password=DBPASSWORD:url=jdbc\\:mysql\\://DB_HOSTNAME\\:3306/DATABASE_NAME"
mysql-pool

To Specify the Data-Source Class Name Explicitly When Using Administration Console

Perform this workaround only if an attempt to use the Administration Console to create a JDBC connection pool returns a server error such as HTTP Status 500. Use this workaround with the instructions for creating a JDBC connection pool in the Administration Console online help.

1. In the step for selecting a database vendor, do not select a vendor from the Database Vendor drop-down list.

   You perform this step on the New JDBC Connection Pool (Step 1 of 2) page.

   As a result of not selecting a vendor, the data source class name in the New JDBC Connection Pool (Step 2 of 2) page will not be filled in for you.

2. In the step for specifying the data-source class name, type the required class name in the Datasource Classname field.

   You perform this step on the New JDBC Connection Pool (Step 2 of 2) page.

   The required class name depends on the resource type that is selected from the Resource Type drop-down list. For example, for the MySQL database, the required class name for each resource type is as shown in Table 1–6.

   For other database drivers, consult the documentation from the database driver vendor.

3. In the step for specifying additional properties, fill in the property table with the required property names and values.

   You perform this step on the New JDBC Connection Pool (Step 2 of 2) page.

   The required property names and values depend on the data-source class.

Option Missing From Help Information for create jbdc-connection-pool (Issue 5766)

Description

The option --validateatmostonceperiod=interval is missing from the Synopsis section and the Options section of the help information for the create jbdc-connection-pool command.

The description of this option is as follows:

--validateatmostonceperiod

Specifies the time interval in seconds between successive request to validate a connection at most once. Setting this attribute to an appropriate value minimizes the number of validation requests by a connection.

The default value is 0, which specifies that the connection is never validated.

For more information, see Issue report.

Workaround

For complete information about the create jbdc-connection-pool, see the create-jdbc-connection-pool(1) man page.

In Bourne shell, all DAS, node agent, and instance processes exit when console window is closed. (6879701)

Description

If you log in as root with the Bourne shell (/bin/sh) and run asadmin commands, then log out of the console window, all the domain administration server (DAS), node agent, and instance processes are killed. This is because in the Bourne shell all child terminals inherit the TTY by default, so when the terminal is logged out, all child processes are killed too.

Workaround

Before running any asadmin commands, do the following:

1. Log in to the server.

2. Log in to the server.

   # exec /bin/ksh

3. In K shell, run all the asadmin commands to bring up the DAS, node agents, and instances.

Operand is missing from the man page example for ping-connection-pool. (6881540)

The example in the man page is missing the operand at the end of the command. An error occurs if the command is entered as shown in the example. Correct example is:

asadmin> ping-connection-pool --user admin1
--passwordfile pwordfile sampleConnectionPool

Restrictions

This section describes the following Sun GlassFish v3 Prelude Enterprise Server restrictions:

• Upgrades

• application-root Attribute in the domain.xml File

• Unsupported Options in asadmin Commands

• Multi-Mode Operation

• Security

Upgrades

An upgrade scenario from an earlier installation into Enterprise Server v3 Prelude is not supported. The command-line interface and configuration are compatible.

application-root Attribute in the domain.xml File

You should not modify the default setting in the domain.xml file for the application-root attribute.

The domain element's application-root attribute In the domain.xml file is intended to specify where the server will expand application archives when the user deploys them.

Currently, not all places in Enterprise Server v3 Prelude that should use this attribute do so. Some uses of the attribute assume that applications are to be expanded in ${com.sun.aas.instanceRoot}/applications.

Unsupported Options in asadmin Commands

The help for asadmin commands describes some options that are not supported by Sun GlassFish Enterprise Server v3 Prelude. For example:

• Options that relate to clusters and multiple server instances, for example, the --target option

• Options that relate to profiles, for example, the --profile option

If you specify an unsupported option, a syntax error does not occur. Instead, the command runs successfully, and the unsupported option is silently ignored.

Multi-Mode Operation

Examples in the help for asadmin commands show the commands in multi-mode operation. Multi-mode operation is not supported by Sun GlassFish Enterprise Server v3 Prelude. All asadmin commands must be typed separately on the operating system command line.

Security

Secure mode (with a security manager) is not supported.

Enterprise Server Documentation Set

The following table provides titles and short descriptions of books in the Enterprise Server documentation set.

How to Report Problems and Provide Feedback

If you have problems with Sun GlassFish Enterprise Server v3 Prelude, provide feedback through one of the following mechanisms:

• GlassFish mailing lists – A variety of GlassFish community mailing lists for various interests and feedback

• GlassFish forum – A forum for discussing the GlassFish project

Additional Resources

Useful information can be found at the following locations:

• GlassFish Community

• Glassfish Wiki: GlassFish v3

• Sun Developer Information

• Sun Developer Support Services

• Sun Microsystems product documentation

Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Sun is not responsible for the availability of third-party Web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused by or in connection with the use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Accessibility Features

To obtain accessibility features that have been released since the publication of these media, consult Section 508 product assessments available from Sun upon request to determine which versions are best suited for deploying accessible solutions. Updated versions of applications can be found at http://sun.com/software/javaenterprisesystem/get.html.

For information on Sun's commitment to accessibility, visit http://sun.com/access.