Sun Microsystems 820682310 User Manual

Sun GlassFish Enterprise Server v3 PreludeTroubleshooting Guide

Sun Microsystems, Inc.
4150 Network Circle
Santa Clara, CA 95054
U.S.A.

Part No: 820–6823–10
November 2008

Copyright 2008 SunMicrosystems, Inc. 4150 NetworkCircle, Santa Clara, CA 95054 U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without
limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries.

U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions
of the FAR and its supplements.

This distribution may include materials developed by third parties.

Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other
countries, exclusively licensed through X/Open Company, Ltd.

Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coee Cup logo, docs.sun.com, Enterprise JavaBeans, EJB, GlassFish, J2EE, J2SE, Java Naming and
Directory Interface, JavaBeans, Javadoc, JDBC, JDK, JavaScript, JavaServer, JavaServer Pages, JMX, JSP,JVM, MySQL, NetBeans, OpenSolaris, SunSolve, Sun
GlassFish, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. or its subsidiaries in the U.S. and other countries. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARCInternational, Inc. in the U.S. and other countries. Products bearing
SPARCtrademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK and Sun
of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to
the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license
agreements.

Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in
other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export
or reexport to countries subject to U.S. embargo or to entities identied on U.S. export exclusion lists, including, but not limited to, the denied persons and specially
designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDINGANY
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO
THE EXTENT THATSUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

TM

Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering eorts

Copyright 2008 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés.

Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier,
et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis
et dans d'autres pays.

Cette distribution peut comprendre des composants développés par des tierces personnes.

Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD,licenciés par l'Université de Californie. UNIX est une marque déposée aux
Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd.

Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coee Cup, docs.sun.com, Enterprise JavaBeans, EJB, GlassFish, J2EE, J2SE, Java Naming and
Directory Interface, JavaBeans, Javadoc, JDBC, JDK, JavaScript, JavaServer, JavaServer Pages, JMX, JSP,JVM, MySQL, NetBeans, OpenSolaris, SunSolve, Sun
GlassFish, Java et Solaris sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc., ou ses liales, aux Etats-Unis et dans d'autres pays.
Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans
d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.

L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les eorts de
pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient
une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface
d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.

Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et
peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations nales, ou utilisateurs naux, pour des armes nucléaires,
des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou
réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités gurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière
non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui
sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spéciquement designés, sont rigoureusement interdites.

LA DOCUMENTATIONEST FOURNIE "EN L'ETAT"ET TOUTES AUTRESCONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES
SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE
IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATIONPARTICULIERE OU A L'ABSENCE DE CONTREFACON.

081201@21288

Contents

Preface .....................................................................................................................................................7

1 Overview of Enterprise Server Troubleshooting ........................................................................... 13

Identifying the Problem ...................................................................................................................... 13

First Steps ...................................................................................................................................... 13

Gathering Information ................................................................................................................ 15

Examining Log Files .................................................................................................................... 16

Monitoring the System ................................................................................................................ 17

Troubleshooting Tools ....................................................................................................................... 17

Operating System Utilities .......................................................................................................... 17

Stack Traces and Thread Dumps ............................................................................................... 18

VisualVM ...................................................................................................................................... 18

Where to Go for More Information .................................................................................................. 19

2 Specic Issues .......................................................................................................................................21

Cannot Access Local Server (http://localhost:8080) ............................................................... 21

Did the Server Start? .................................................................................................................... 22

Was the Server Started at the Expected Port? ........................................................................... 22

Cannot Access Remote Server ........................................................................................................... 23

Is the Server Available Locally? ................................................................................................... 23

Is the Proxy Setting Causing a Problem? ................................................................................... 23

Cannot Access the Administration Console .................................................................................... 24

Is the Application Server Running? ........................................................................................... 24

Is the Administration Console Running on the Expected Port? ............................................ 25

Is the Security Manager Disabled? ............................................................................................. 25

Cannot Access a Server Application ..................................................................................................25

Is the Application Server Running? ........................................................................................... 25

3

Contents

Was Application Deployment Successful? ................................................................................ 26

Administrator User Name or Password Not Known ............................................................... 26

Server Will Not Start on Windows (Port Conict) .......................................................................... 27

Is Another Application Running on the Server's Port? ............................................................ 28

Has an Ungraceful Shutdown Occurred on a Previously Running Server? .......................... 28

Two Server Instances Bind to Same Port on Windows ................................................................... 28

Description ................................................................................................................................... 28

Solution ......................................................................................................................................... 28

Cannot Produce a JVM Thread Dump After Server Crash ............................................................ 29

Description ................................................................................................................................... 29

Solution ......................................................................................................................................... 29

Issues Related to Applications ............................................................................................................ 29

Error When Deploying EAR ...................................................................................................... 29

Cannot Find SunDeploymentManager ....................................................................................... 30

Cannot Undeploy or Redeploy Application With Open Streams to jar Files (Windows

Only) .............................................................................................................................................. 30

Issues Related to asadmin ................................................................................................................... 31

asadmin start-domain Command Fails .................................................................................. 31

Cannot Stop Domain Using asadmin stop-domain ................................................................ 32

Using asadmin set Command Might Produce Unexpected Results .....................................33

Issues Related to Eclipse ...................................................................................................................... 33

Eclipse GlassFish Server Adapter – Port Conict When Starting GlassFish ......................... 33

Issues Related to Installation and Upgrade ...................................................................................... 34

General Installation ..................................................................................................................... 34

Cannot Upgrade ........................................................................................................................... 34

Issues Related to JavaMail ................................................................................................................... 35

Cannot Congure JavaMail Resources ...................................................................................... 35

Issues Related to JNDI ......................................................................................................................... 35

Cannot Deploy a Mail Session as a JNDI Resource .................................................................. 35

Issues Related to MySQL .................................................................................................................... 36

Exception When Creating MySQL Connection Pool .............................................................. 36

Issues Related to Security .................................................................................................................... 36

java.security.AccessControlException: Access Denied Error ...................................... 36

Mutual Authentication Not Working With the Application Client ...................................... 37

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 20084

Contents

3 Frequently Asked Questions .............................................................................................................39

Administration FAQs .......................................................................................................................... 39

Which asadmin Commands are Supported? ............................................................................ 39

Application FAQs ................................................................................................................................ 40

How Do I Debug Applications? .................................................................................................. 40

How Do I Change Application Permissions? ........................................................................... 40

What Are the Restrictions and Optimizations for Session Beans? ........................................ 40

How Do I Move Tomcat Toplink Applications to Enterprise Server v3 Prelude? ............... 40

Eclipse FAQs ........................................................................................................................................ 40

Where Can I Find More Information About Eclipse and Enterprise Server Integration? .. 40

Extensibility FAQs ............................................................................................................................... 41

How Do I Develop Add-On Components? .............................................................................. 41

How Do I Add Containers? ......................................................................................................... 41

How Do I Extend the Administration Console? ...................................................................... 41

Java Persistence FAQs ......................................................................................................................... 42

What Are the Restrictions and Optimizations for the Java Persistence API? ....................... 42

What Java Persistence Support Is Available? ............................................................................ 42

JDBC FAQs ........................................................................................................................................... 42

Is JDBC Support Provided? ......................................................................................................... 42

Jersey FAQs ........................................................................................................................................... 42

How Do I Use Jersey? ................................................................................................................... 42

OpenESB FAQs .................................................................................................................................... 43

Does Enterprise Server v3 Prelude Support OpenESB? .......................................................... 43

Rails and JRuby FAQs ......................................................................................................................... 43

Should I Start an Enterprise Server Domain and Deploy My Application Into It, or Should I

Use the glassfish_rails Gem? ............................................................................................... 43

If I Deploy an Application Using the glassfish_rails Gem, Can I Still Access the

Administration Console? ............................................................................................................ 43

Where in a Rails Application Structure Does Enterprise Server Look for jar Files to Add to

the Classpath for That Application? .......................................................................................... 43

Where Can I Find More Information About Rails Applications and Enterprise Server? .... 44

What Options Are Available for Running JRuby With Enterprise Server? .......................... 44

Security FAQs ....................................................................................................................................... 45

What Happens When No Server Side Realm Is Congured? ................................................. 45

Can I See the TLS/SSL Handshake Information for an SSL Client? ....................................... 45

Can I Change the Keystore Password? ...................................................................................... 45

5

Contents

Update Tool FAQs ............................................................................................................................... 45

How Do I Use Update Tool to Extend My Enterprise Server Installation? ........................... 45

Index ......................................................................................................................................................47

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 20086

Preface

This guide describes common problems that you might encounter when using Sun GlassFish
Enterprise Server v3 Prelude and how to solve them.

This preface contains information about and conventions for the entire Sun GlassFish
Enterprise Server documentation set.

The following topics are addressed here:

■

“Enterprise Server Documentation Set” on page 7

■

“Related Documentation” on page 9

■

“Typographic Conventions” on page 9

■

“Symbol Conventions” on page 10

■

“Default Paths and File Names” on page 10

■

“Documentation, Support, and Training” on page 11

■

“Searching Sun Product Documentation” on page 11

■

“Third-Party Web Site References” on page 11

■

“Sun Welcomes Your Comments” on page 12

Enterprise Server Documentation Set

The Enterprise Server documentation set describes deployment planning and system
installation. The Uniform Resource Locator (URL) for Enterprise Server documentation is

http://docs.sun.com/coll/1343.7. For an introduction to Enterprise Server, refer to the

books in the order in which they are listed in the following table.

TM

TABLE P–1 Books in the Enterprise Server Documentation Set

Book Title Description

Release Notes Provides late-breaking information about the software and the

documentation. Includes a comprehensive, table-based summary of the
supported hardware, operating system, Java
and database drivers.

Quick Start Guide Explains how to get started with the Enterprise Server product.

TM

Development Kit (JDKTM),

7

Preface

TABLE P–1 Books in the Enterprise Server Documentation Set (Continued)

Book Title Description

Installation Guide Explains how to install the software and its components.

Application Deployment Guide Explains how to assemble and deploy applications to the Enterprise Server

and provides information about deployment descriptors.

Developer’s Guide Explains how to create and implement Java Platform, Enterprise Edition

(Java EE platform) applications that are intended to run on the Enterprise
Server. These applications follow the open Java standards model for Java EE
components and APIs. This guide provides information about developer
tools, security, and debugging.

Add-On Component
Development Guide

Explains how to use published interfaces of Enterprise Server to develop
add-on components for Enterprise Server. This document explains how to
perform only those tasks that ensure that the add-on component is suitable
for Enterprise Server.

RESTful Web Services
Developer’s Guide

Getting Started With JRuby on
Rails for Sun GlassFish

Explains how to develop Representational State Transfer (RESTful) web
services for Enterprise Server.

Explains how to develop Ruby on Rails applications for deployment to
Enterprise Server.

Enterprise Server

Getting Started With Project
jMaki for Sun GlassFish
Enterprise Server

Roadmap to the Java EE 5
Tutorial

Explains how to use the jMaki framework to develop Ajax-enabled web
applications that are centered on JavaScript

TM

technology for deployment to

Enterprise Server.

Explains which information in the Java EE 5 Tutorial is relevant to users of
the v3 Prelude release of the Enterprise Server.

Java EE 5 Tutorial Explains how to use Java EE 5 platform technologies and APIs to develop

Java EE applications.

Java WSIT Tutorial Explains how to develop web applications by using the Web Service

Interoperability Technologies (WSIT). The tutorial focuses on developing
web service endpoints and clients that can interoperate with Windows
Communication Foundation (WCF) endpoints and clients.

Administration Guide Explains how to congure, monitor, and manage Enterprise Server

subsystems and components from the command line by using the

asadmin(1M) utility. Instructions for performing these tasks from the

Administration Console are provided in the Administration Console online
help.

Administration Reference Describes the format of the Enterprise Server conguration le, domain.xml.

Troubleshooting Guide Describes common problems that you might encounter when using

Enterprise Server and how to solve them.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 20088

TABLE P–1 Books in the Enterprise Server Documentation Set (Continued)

Book Title Description

Reference Manual Provides reference information in man page format for Enterprise Server

Related Documentation

A JavadocTMtool reference for packages that are provided with the Enterprise Server is located at

https://glassfish.dev.java.net/nonav/api/v3-prelude/index.html. Additionally, the

following resources might be useful:

■

The Java EE 5 Specications (http://java.sun.com/javaee/5/javatech.html)

■

The Java EE Blueprints (http://java.sun.com/reference/blueprints/index.html)

For information about creating enterprise applications in the NetBeansTMIntegrated
Development Environment (IDE), see http://www.netbeans.org/kb/60/index.html.

For information about the Java DB for use with the Enterprise Server, see

http://developers.sun.com/javadb/.

Preface

administration commands, utility commands, and related concepts.

Typographic Conventions

The following table describes the typographic changes that are used in this book.

TABLE P–2 TypographicConventions

Typeface Meaning Example

AaBbCc123 The names of commands, les, and

directories, and onscreen computer
output

AaBbCc123 What you type, contrasted with onscreen

computer output

AaBbCc123 A placeholder to be replaced with a real

name or value

AaBbCc123 Book titles, new terms, and terms to be

emphasized (note that some emphasized
items appear bold online)

Edit your .login le.

Use ls -a to list all les.

machine_name% you have mail.

machine_name% su

Password:

The command to remove a le is rm lename.

Read Chapter 6 in the User's Guide.

A cache is a copy that is stored locally.

Do not save the le.

9

Preface

Symbol Conventions

The following table explains symbols that might be used in this book.

TABLE P–3 SymbolConventions

Symbol Description Example Meaning

[] Contains optional arguments

and command options.

{|} Contains a set of choices for a

required command option.

${ } Indicates a variable

reference.

- Joins simultaneous multiple
keystrokes.

+ Joins consecutive multiple

keystrokes.

→ Indicates menu item

selection in a graphical user
interface.

ls [-l] The -l option is not required.

-d {y|n} The -d option requires that you use

${com.sun.javaRoot} References the value of the

Control-A Press the Control key while you press

Ctrl+A+N Press the Control key, release it, and

File → New → Templates From the File menu, choose New.

Default Paths and File Names

The following table describes the default paths and le names that are used in this book.

TABLE P–4 Default Pathsand File Names

Placeholder Description Default Value

as-install Represents the base installation directory for

Enterprise Server.

In conguration les, as-install is represented
as follows:

${com.sun.aas.installRoot}

Installations on the Solaris
system, and Mac operating system:

user’s-home-directory/glassfishv3-prelude/glassfish

Windows, all installations:

SystemDrive:\glassfishv3-prelude\glassfish

either the y argument or the n
argument.

com.sun.javaRoot variable.

the A key.

then press the subsequent keys.

From the New submenu, choose
Templates.

TM

operating system, Linux operating

domain-root-dir Represents the directory in which a domain is

created by default.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200810

as-install/domains/

TABLE P–4 Default Paths and File Names (Continued)

Placeholder Description Default Value

Preface

domain-dir Represents the directory in which a domain's

conguration is stored.

In conguration les, domain-dir is
represented as follows:

${com.sun.aas.instanceRoot}

domain-root-dir/domain-name

Documentation, Support, andTraining

The Sun web site provides information about the following additional resources:

■

Documentation (http://www.sun.com/documentation/)

■

Support (http://www.sun.com/support/)

■

Training (http://www.sun.com/training/)

Searching Sun Product Documentation

Besides searching Sun product documentation from the docs.sun.comSMweb site, you can use a
search engine by typing the following syntax in the search eld:

search-term site:docs.sun.com

For example, to search for “broker,” type the following:

broker site:docs.sun.com

To include other Sun web sites in your search (for example, java.sun.com, www.sun.com, and

developers.sun.com), use sun.com in place of docs.sun.com in the search eld.

Third-PartyWeb Site References

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

11

Preface

Note – 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 or alleged to be caused by
or in connection with use of or reliance on any such content, goods, or services that are available
on or through such sites or resources.

Sun WelcomesYour Comments

Sun is interested in improving its documentation and welcomes your comments and
suggestions. To share your comments, go to http://docs.sun.com and click Send Comments.
In the online form, provide the full document title and part number. The part number is a
7-digit or 9-digit number that can be found on the book's title page or in the document's URL.
For example, the part number of this book is 820-6823.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200812

CHAPTER 1

1

Overview of Enterprise Server Troubleshooting

This chapter describes the tools, methods, and information sources available for
troubleshooting Sun GlassFish Enterprise Server v3 Prelude. Guidelines for evaluating and
investigating a problem are included.

This chapter contains the following sections:

■

“Identifying the Problem” on page 13

■

“Troubleshooting Tools” on page 17

■

“Where to Go for More Information” on page 19

Identifying the Problem

Application servers are typically deployed in complex and sophisticated operating
environments and involve many technologies, products, and tools. Understanding and
diagnosing problems in a large piece of software with so many components performing so
many tasks can be challenging. This section gets you started, and includes the following topics:

■

“First Steps” on page 13

■

“Gathering Information” on page 15

■

“Examining Log Files” on page 16

■

“Monitoring the System” on page 17

First Steps

Sometimes the most obvious solutions are overlooked. As you begin your investigation, try the
following steps rst.

13

Identifying the Problem

VerifySystemRequirements and Conguration

Problems are often caused by conguration issues (system, JVMTM, server, or application-level)
and by resource issues (such as when a system runs out of memory). Refer to the

Sun GlassFish

Enterprise Server v3 Prelude Release Notes for the latest information regarding system

requirements dependencies.

Review Known Issues

Your problem might be related to a known issue for the release. Refer to the Sun GlassFish

Enterprise Server v3 Prelude Release Notes for the latest information regarding known issues and

possible workarounds. Also search the GlassFish issue tracker at

https://glassfish.dev.java.net/servlets/ProjectIssues.

Search the Product Documentation

Enterprise Server includes complete documentation. Search the documentation to see if your
problem is addressed. The documentation set is available at

http://docs.sun.com/coll/1343.7. See “Enterprise Server Documentation Set” on page 7 for

a list of books in the documentation set and a description of their contents.

Search the GlassFish Mailing Lists and Forums

Lists and forums are extremely helpful resources, and are accessed as follows:

■

GlassFish mailing lists (start with users@glasssh.dev.java.net):

http://glassfish.dev.java.net/servlets/ProjectMailingListList

■

GlassFish user forum: http://forums.java.net/jive/forum.jspa?forumID=56

■

Other GlassFish forums: http://forums.java.net/jive/category.jspa?categoryID=58

Learn More About Enterprise Server v3 Prelude

As the name suggests, the release is a prelude to Sun GlassFish Enterprise Server v3. It is not a
full Java EE 5 application server, and not everything that was implemented in Sun Java System
Application Server 9.1 (GlassFish v2) is implemented and functional in Enterprise Server v3
Prelude. You might be trying to do something that is not possible with the existing feature set.
For more information about Enterprise Server v3 Prelude and the features it contains, consult
the following resources:

■

Feature list and comparison:

https://glassfish.dev.java.net/public/comparing_v2_and_v3.html

■

Download page: https://glassfish.dev.java.net/downloads/v3-prelude.html

■

Resources page:

http://wiki.glassfish.java.net/Wiki.jsp?page=GlassFishV3PreludeResources

■

Documentation: http://docs.sun.com/coll/1343.7

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200814

Identifying the Problem

Note – Some resources refer to GlassFish v3 Prelude. GlassFish v3 Prelude is the community

version of the commercially supported oering, Sun GlassFish Enterprise Server v3 Prelude.
The software is the same; the dierence is in support.

Search the SunSolve Knowledgebase

SunSolveSMis Sun's informational and patch database service with a browseable directory of all
publicly available Sun Microsystems support documents. SunSolve is available at

http://sunsolve.sun.com. Additional resources are also available for customers with support

contracts.

Gathering Information

Troubleshooting and analysis require information. The more information that you have, the
easier it is to classify a problem and search for its solution. Detailed information will also be
necessary should you need to contact others for support, either through a community mailing
list or through more formal Sun support channels.

For general information about gathering data, also refer to

Java System Application Server

. The document pertains to previous versions but much of the

Sun Gathering Debug Data for Sun

information is generic enough that it might be helpful for Enterprise Server v3 Prelude.

As you continue your investigation, consider the following questions.

When Does the Problem Occur?

■

What do the logs show? What kind of error message are you getting? For more information
about logs, see

■

What are you trying to do when the problem occurs, and how are you doing it? What is the

“Examining Log Files” on page 16.

sequence of events?

■

Does the problem occur every time you perform the same type of operation, or does it seem
random? Can you reproduce the issue?

■

Have other events or problems occurred that could possibly be related, such as web sessions
closing early, exceptions being thrown in your own application logic, components not being
correctly deployed or undeployed?

What Is Your Environment?

■

What version of Enterprise Server are you using? What operating system and version? What
JDK version?

■

What resources does your system have, such as memory, disk, and swap space? If system
memory is an issue, look for ways to optimize your conguration and consider taking other
actions such as adding memory or decreasing system load.

Chapter 1 • Overview of Enterprise Server Troubleshooting 15

Identifying the Problem

■

Have any patches been applied? If so, what are the product and operating system patch
numbers?

■

What other products and technologies are installed and being used in the installation?

■

How many application servers, web servers, and directory servers are installed? What are
the products and versions?

■

How is the web server connected to Enterprise Server? On the same system?

■

How is Enterprise Server connected to the directory server?

■

What JDBC driver is being used to access the database?

What Is Your System Conguration?

■

What are your settings?

■

On which port is Enterprise Server v3 Prelude congured? The default or something else?

■

What defaults were changed during installation and what are the values?

■

What other settings were changed from the defaults and what are their values?

■

What are the JVM heap, stack, and garbage collection-related parameters set to?

■

What are the JVM options?

■

What is the permgen size? OutOfMemoryError:PermGen space errors are common and
indicate that you need to increase the permanent generation space available.

■

Is SSL enabled?

■

What are your network settings (proxy, rewall, and so on)? What happens if you disable
your rewall and attempt the task?

What Is Dierent?

■

What is dierent that could have provoked the problem or triggered the event? Was
something new added or changed? Have any new applications been deployed? If changes
have been made recently, consider backing them out and seeing what happens — does the
problem still occur?

■

Was the feature or functionality working correctly at one time? If so, what changed or
happened between then and now?

■

Is this working on another system? If so, what is dierent about that environment?

Examining Log Files

Logging is one of your most important troubleshooting tools. It is the process by which
Enterprise Server captures data about events that occur during server operation. This data is
recorded in a log le, and is usually the rst source of information when Enterprise Server
problems occur. The primary purpose of log les is to provide troubleshooting information.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200816

TroubleshootingTools

By default, all Enterprise Server log information is captured in the server.log le, typically
located in domain-dir/logs. Log Viewer is not available in Enterprise Server v3 Prelude. You
cannot view the server's log le or congure logging using the Administration Console. To view
log information, open the server.log le in a text editor. You can also use command-line le
viewing commands such as tail, grep,ormore. Logging is congured by editing the
logging.properties le, located by default in the same directory as the domain.xml le,
typically domain-dir/config.

Log levels such as SEVERE, WARNING, INFO, CONFIG, and others can be set to provide dierent
types and amounts of information. Each Enterprise Server module has its own logger, and each
logger has its own namespace. Log levels can be set globally for all loggers, or individually for
module-specic loggers.

Chapter 9, “Administering Logging,” in Sun GlassFish Enterprise Server v3 Prelude

See

Administration Guide
Server v3 Prelude Release Notes

for complete details about logging. Also see the Sun GlassFish Enterprise

for any known issues related to logging.

Monitoring the System

Monitoring is another helpful tool. It is the process of reviewing the statistics of a system to
improve performance or solve problems. By monitoring the state of various components and
services deployed in Enterprise Server, you can identify performance bottlenecks, predict
failures, perform root cause analysis, and ensure that everything is functioning as expected. For
more information about monitoring, see

Sun GlassFish Enterprise Server v3 Prelude Administration Guide

Chapter 10, “Monitoring the Enterprise Server,” in

.

Troubleshooting Tools

Several tools are available that can be used to collect information for troubleshooting purposes.
This section provides basic information about the following:

■

“Operating System Utilities” on page 17

■

“Stack Traces and Thread Dumps” on page 18

■

“VisualVM” on page 18

Operating System Utilities

Operating system utilities, such as pkginfo and showrev on Solaris and rpm on Linux, are
helpful in gathering system information.

The ps -ef command provides helpful information about processes that are running,
including their process identication numbers (PIDs).

Chapter 1 • Overview of Enterprise Server Troubleshooting 17

TroubleshootingTools

▼

●

Stack Tracesand Thread Dumps

A stack trace is a user-friendly snapshot of the threads and monitors in a Virtual Machine for
the Java platform (Java Virtual Machine or JVM machine). A thread dump shows what every
thread in a JVM is doing at a given time and is useful in debugging. When the application server
freezes, hangs, or becomes sluggish for no apparent reason, you should generate and analyze a
thread dump.

This section explains how to obtain a thread dump for Enterprise Server. More information
about analyzing the information contained in a thread dump can be found in “An Introduction
to Java Stack Traces”

http://java.sun.com/developer/technicalArticles/Programming/Stacktrace). By

(
default, the server dumps a core le and restarts with the -Xrs java-option ag in the
server.xml le.

To Obtain a ServerThread Dump

Typethe following command:

asadmin generate-jvm-report --type=thread

See Also

generate-jvm-report(1)

VisualVM

VisualVM is a Java troubleshooting tool that uses various technologies such as jvmstat, JMXTM,
and Attach API to access monitored applications. VisualVM is a tool for visualizing data
sources and by default visualizes the following types: applications, hosts, snapshots, core
dumps, heap dumps, and thread dumps. These data sources are visualized in VisualVM so that
they can be monitored for the purposes of analysis, management, and troubleshooting.
VisualVM is commonly used to detect memory leaks.

VisualVM has a GlassFish plugin that enhances monitoring of hosted applications by adding
specialized overview, a tab for monitoring the HTTP Service, and the ability to visually select
and monitor any of the deployed web applications. You can experiment with VisualVM
troubleshooting capabilities, but note that various features depend on the Java versions used in
the client and server. Depending on your conguration, you might only get parts of the
VisualVM features. For more information about VisualVM, see

https://visualvm.dev.java.net.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200818

Where to Go for More Information

■

Product page:

http://www.sun.com/software/products/glassfishv3_prelude/index.xml

■

Comparison between Sun Java System Application Server 9.1 (GlassFish v2) and Enterprise
Server v3 Prelude:

https://glassfish.dev.java.net/public/comparing_v2_and_v3.html

■

Support and services:

http://www.sun.com/software/products/glassfishv3_prelude/support.xml

■

SunSolve knowledgebase: http://sunsolve.sun.com

■

Resources page (points to articles, blogs, videos, screencasts, FAQs, and many other
resources related to Enterprise Server v3 Prelude):

http://wiki.glassfish.java.net/Wiki.jsp?page=GlassFishV3PreludeResources

■

Documentation: http://docs.sun.com/coll/1343.7

■

Mailing lists and forums: See “Search the GlassFish Mailing Lists and Forums” on page 14
for details about accessing lists and forums.

■

Technical Note: Sun Gathering Debug Data for Sun Java System Application Server

■

GlassFish community site: http://glassfish.org

■

GlassFish wiki:

http://wiki.glassfish.java.net/Wiki.jsp?page=PlanForGlassFishV3

Where to Go for More Information

Chapter 1 • Overview of Enterprise Server Troubleshooting 19

20

CHAPTER 2

2

Specic Issues

This chapter lists problems that you might encounter when using Sun GlassFish Enterprise
Server v3 Prelude. The following issues are addressed.

General Issues

■

“Cannot Access Local Server (http://localhost:8080)” on page 21

■

“Cannot Access Remote Server” on page 23

■

“Cannot Access the Administration Console” on page 24

■

“Cannot Access a Server Application” on page 25

■

“Server Will Not Start on Windows (Port Conict)” on page 27

■

“Two Server Instances Bind to Same Port on Windows” on page 28

■

“Cannot Produce a JVM Thread Dump After Server Crash” on page 29

Specic Issues

■

“Issues Related to Applications” on page 29

■

“Issues Related to asadmin” on page 31

■

“Issues Related to Eclipse” on page 33

■

“Issues Related to Installation and Upgrade” on page 34

■

“Issues Related to JavaMail” on page 35

■

“Issues Related to JNDI” on page 35

■

“Issues Related to MySQL” on page 36

■

“Issues Related to Security” on page 36

Cannot Access Local Server (http://localhost:8080)

When this error occurs, check the following:

■

“Did the Server Start?” on page 22

■

“Was the Server Started at the Expected Port?” on page 22

21

Cannot Access Local Server (http://localhost:8080)

Did the Server Start?

Description

If the console window is still open, the expected message is:

Domain domain Started

where domain is the name of the default domain. This indicates that the default domain was
started successfully.

If the console window is already closed, check for messages in the log le:

as-install/domains/domain1/logs/server.log

If startup was successful, the expected message is similar to that on the console, and appears at
the end of the log le.

Wasthe Server Started at the Expected Port?

Description

The server might be running at a dierent port number than expected, either because it was
intentionally installed there, or because another server was already running on the default port
when the server was installed.

▼

To Determine Which Port Number the Server Is Actually Using

Examine the server's congurationle:

1

as-install/domains/domain1/config/domain.xml

Find the http-listener element.

2

Inspect the value of the port attribute.

3

Be sure to enter the correct port number when invoking the server.

Note – The server's default port number is 8080, however, there are a number of ways in which

the expected value can change:

■

A dierent port number was specied during installation.

■

A previous installation exists.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200822

Cannot Access Remote Server

When attempting to open the start page of Enterprise Server, the initial screen does not appear.

When this error occurs, check the following:

■

“Is the Server Available Locally?” on page 23

■

“Is the Proxy Setting Causing a Problem?” on page 23

Is the Server Available Locally?

Description

If the server cannot be accessed from the web, but it is running locally, then the server is actually
running.

Solution

Verify that the server is running locally.

▼

To VerifyThat the Server Is Running Locally

Cannot Access Remote Server

Log on to the host where the server is running.

1

Go to the local web page. For example, if 8080 is the default port, go to:

2

http://localhost:8080/

If the start page does appear, the web connection is encountering a problem that prevents
accessing the server remotely. If the start page does not appear, see “Did the Server Start?” on

.

page 22

Is the Proxy Setting Causing a Problem?

Description

The server should be accessible directly from the host on which it is running (localhost); for
example, using the default port 8080:

http://localhost:8080/

Solution

A server instance running on localhost might not be accessible if the server host machine is
connected to the web through a proxy. To solve this problem, do one of the following:

Chapter 2 • Specic Issues 23

Cannot Access the Administration Console

■

Set the browser to bypass the proxy server when accessing localhost. Refer to the browser's
help system for information about how to do this.

■

Use the fully-qualied host name or IP address of your system; for example:

http://myhost.mydomain.com:8080/

■

Create an entry in the system's hosts le (for example, pointing 127.0.0.1 to localhost;

127.0.0.1 is not proxied).

Note – To nd the host name and domain for the localhost machine:

■

On Microsoft Windows — On the desktop, right-click My Computer and select Properties
from the pop-up menu. A System Properties dialog is displayed. Click Network
Identication to see the computer name.

■

On Solaris or Linux — Type hostname at the command prompt.

Cannot Access the Administration Console

The Administration Console provides an interface for administrative functions. If the
Administration Console is not accessible, check the following:

■

“Is the Application Server Running?” on page 24

■

“Is the Administration Console Running on the Expected Port?” on page 25

■

“Is the Security Manager Disabled?” on page 25

Is the Application Server Running?

Description

The server must be running before the Administration Console can be accessed.

Solution

Review the information in “Did the Server Start?” on page 22 to determine if the server is
running.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200824

Cannot Access a Server Application

Is the Administration Console Running on the Expected Port?

Description

The default port number for the Administration Console is 4848. However, it could be running
on a dierent port number than expected, either because it was intentionally installed there, or
because that port was in use when the server was started.

Solution

Refer to “Was the Server Started at the Expected Port?” on page 22 for guidelines on verifying
the port on which the Administration Console is running. Be sure to enter the correct port
number and HTTP protocol when invoking the Administration Console.

Is the Security Manager Disabled?

Description

The Security Manager is not optional; it must be enabled in Enterprise Server. Because there is
no conguration interface in Enterprise Server for disabling the Security Manager, it can only
be disabled when you directly modify the domain.xml conguration le in such a way that the
following line is removed or commented out:

<jvm-option\>-Djava.security.policy=yourPolicy</jvm-option\>

Solution

Verify that the -Djava.security.policy=yourPolicy option is present in the domain.xml le.

Cannot Access a Server Application

If a particular application cannot be accessed through Enterprise Server, check the following:

■

“Is the Application Server Running?” on page 25

■

“Was Application Deployment Successful?” on page 26

■

“Administrator User Name or Password Not Known” on page 26

Is the Application Server Running?

Description

If Enterprise Server is not running, applications are not accessible.

Chapter 2 • Specic Issues 25

Cannot Access a Server Application

Solution

Review the information in “Did the Server Start?” on page 22 to determine if the server is
running. The server must be running before a server application can be accessed.

Was Application Deployment Successful?

Description

An application must be successfully deployed before it can be accessed.

Solution

Check the server's log le:

as-install/domains/domain1/server.log

Administrator User Name or Password Not Known

If you have forgotten the administrator user name, you can nd it by inspecting the
as-install/domains/domain-name/config/keyfile le, where domain-name is the name of
the domain. In the default domain, domain1, the le to inspect is
as-install/domains/domain1/config/keyfile. For a dierent domain, substitute its name in
the path.

If you have forgotten the administrator password, you must create a new user name-password
pair by removing the user name and password, creating new ones, and restarting the server.
(You will not be able to read the password, because it is encrypted in the keyle.)

▼

To Remove the User Name and Password Completely

Stop the server,if it is currently running.

1

Change to the appropriate WEB-INF directory; for example:

2

as-install/lib/install/applications/adminapp/adminapp_war/WEB-INF

Comment out the entire <security-constraint> element in the web.xml le.

3

Do not delete the element, as you will be reenabling it later. This action disables security for
command-line operations.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200826

Server Will Not Start on Windows (Port Conict)

Note – The commands will still expect a value for --username (or -u) and --password (or -w).

But these can be dummy values, since the server side does not impose any security.

Start the server.

4

At this point, the server does not have command-line security.

Create a plain text le that denes the AS_ADMIN_USERPASSWORD variable as follows:

5

AS_ADMIN_USERPASSWORD=adminpassword

adminpassword Your choice of password for the administration user's password.

Create an administration user whose password is the password that you dened in the

6

preceding step.

asadmin create-file-user --groups asadmin --passwordfile=password-le adminuser

passwordle The full path to the le that you created in the previous step.

adminuser The name of the user that you are creating.

This command adds an entry to the as-install/domains/domain-name/config/keyfile le.

Uncomment the <security-constraint> element in the web.xml le.

7

Restart the server for the new user name-password to take eect.

8

Note – After the server is restarted, remote commands must specify adminuser as the

administration user and adminpassword as the administration password.

Server Will Not Start on Windows (Port Conict)

If a message similar to the following is displayed when starting Enterprise Server on Microsoft
Windows, a server port conict has occurred:

Address already in use

This error occurs when another application is running on the Enterprise Server port (default

8080), or because a previous instance of Enterprise Server did not shut down cleanly.

You might also check the following:

■

“Is Another Application Running on the Server's Port?” on page 28

■

“Has an Ungraceful Shutdown Occurred on a Previously Running Server?” on page 28

Chapter 2 • Specic Issues 27

TwoServer Instances Bind to Same Port on Windows

Is Another Application Running on the Server's Port?

If another application is using the server's port, stop the other application, then restart
Enterprise Server.

Has an Ungraceful Shutdown Occurred on a Previously Running Server?

Use the asadmin stop-domain command to stop the server, or explicitly kill the Java process
and then restart Enterprise Server.

Two Server Instances Bind to Same Port on Windows

Description

This problem only occurs on Windows 2000/XP systems with Enterprise Server software, and is
due to a known Windows security aw rather than a problem with Enterprise Server itself.

The problem occurs when two or more instances of Enterprise Server are created using the
same port number for the instanceport option; for example:

asadmin create-domain -adminport 5001 options -instanceport 6001 domain
asadmin create-domain -adminport 5002 options -instanceport 6001 domain

When the two domains are started on a UNIX or Linux system, a port conict error is thrown
and the second instance fails to start. However, when the two domains are started on Windows
2000/XP, no error is thrown, both server instances start, but only the rst instance is accessible
at the specied port. When that rst server instance is subsequently shut down, the second
instance then becomes accessible. Moreover, when both instances are running, the Windows
netstat command only reports the rst instance.

Solution

Be sure to use unique port numbers for all server instances on Windows systems.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200828

Issues Related to Applications

Cannot Produce a JVM Thread Dump After Server Crash

Description

If Enterprise Server crashes, the server dumps a core le and, by default, restarts with the -Xrs
ag, which prevents the dump of a JVM thread dump.

Solution

▼

To Obtain a ServerThread Dump

Typethe following command:

●

asadmin generate-jvm-report --type=thread

See Also

generate-jvm-report(1)

Issues Related to Applications

ErrorWhen Deploying EAR

Description

You tried to deploy a traditional EAR type of application in Enterprise Server but received an
error message instead.

Solution

Enterprise Server v3 Prelude does not include a full EJB 3.0 implementation and does not
support traditional EJB modules. Applications can be packaged for deployment in web archive
(WAR) format only. You can download a partial implementation of a few EJB 3.1 features using
Update Tool, but the bulk of EJB 3.0 (ejb-jar and .ear support) is not available . If you need a
full Java EE 5 implementation, Sun Java System Application Server 9.1 (GlassFish v2) is a better
choice for now. Web applications are the only Java EE application type supported by Enterprise
Server v3 Prelude.

For related information, see the following:

Chapter 2 • Specic Issues 29

Issues Related to Applications

■

■

■

■

Cannot Find SunDeploymentManager

Description

You cannot nd SunDeploymentFactory.java .

Solution

Enterprise Server v3 Prelude does not include the JSR-88 API (SunDeploymentManager is the
implementation of the JSR 88 API). The JSR 88 specication provides a complete description of
the APIs required by the Java EE platform to enable development of platform-independent
deployment tools.

Forum threads: http://forums.java.net/jive/thread.jspa?messageID=301326 and

http://forums.java.net/jive/thread.jspa?messageID=318879

Blog post: “EJB 3.1 in GlassFish v3 Prelude”
(http://blogs.sun.com/kensaks/entry/ejb_3_1_in_glassfish)

Blog post: “Deployment in GlassFish v3 Prelude”

http://blogs.sun.com/quinn/entry/deployment_in_glassfish_v3_prelude)

(

Documentation: Chapter 3, “Extending Enterprise Server,” in Sun GlassFish Enterprise

Server v3 Prelude Administration Guide

Cannot Undeploy or Redeploy Application With Open Streams to jar Files (WindowsOnly)

Description

On Windows systems, after running an application, subsequent attempts to undeploy it or
redeploy it throw exceptions about the server being unable to delete a le or rename a directory.

On Windows systems, an application may use getClass().getResource or
getResourceAsStream methods to locate a resource inside the application, particularly in jar
les that are in the application or accessible to it. If the streams remain open, subsequent
attempts to redeploy or undeploy the application can fail. In addition, the Java runtime by
default caches streams to jar les for performance reasons.

Solution

Be sure to close streams opened by your applications. Also, if an application needs to be
redeployed or undeployed repeatedly, and also needs to obtain a resource from a jar le using

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200830

getResource or getResourceAsStream, consider using getClass().getResource, which
returns a URL object, then invoke the url.setUseCaches method to turn o caching for that
jar le, and use url.getInputStream() to obtain the stream.

Although turning o caching for access to the jar le can slow performance, this approach does
allow the application to be undeployed or redeployed. Note also that if the
getClass().getResourceAsStream method is used instead, then the jar le in which the
resource is located is cached (this is the default Java runtime setting) and remains open until the
server is stopped.

Issues Related to asadmin

asadmin start-domain Command Fails

The command asadmin start-domain fails with one of the following errors:

■

Error: CLI143 There is more than one domain...

■

Error: Could Not Start Domain

Issues Related to asadmin

Error: CLI143 There is more than one domain...

Description

When issued with no arguments, the command asadmin start-domain fails with the error:

CLI143 There is more than one domain in C:\\Sun\\AppServer\\domains.
Please use operand to specify the domain.
CLI156 Could not start the domain null.

This error occurs when there is more than one domain in the domains directory, none of them
is named domain1, and no domain is specied with the start-domain command.

Solution

Specify the domain when issuing the start-domain command:

asadmin start-domain domain-name

For example:

asadmin start-domain mycustomdomain

Chapter 2 • Specic Issues 31

Issues Related to asadmin

Error: Could Not Start Domain

Description

This message comes from Sun Java System Application Server 8. The full message looks like
either:

Could not start the domain.
There are no domains.

or

Could not start the domain.
No default domain. Need to enter a domain.

This error occurs when Sun Java System Application Server 8 is installed on the same system,
and its asadmin command (at /usr/sbin) is found on the PATH before the asadmin command
for Sun Java System Application Server 8 at as-install/bin. The situation is especially likely to
occur on Solaris and Linux systems when . is not specied as part of the PATH variable. Without
. in the PATH, the asadmin command in /usr/sbin is found rst, even when the current
directory is as-install/bin.

Solution

Make sure as-install/bin is in the PATH ahead of /usr/sbin, or that . is in the PATH ahead of
/usr/sbin if you access asadmin by changing directories to as-install/bin. Alternatively, if you

do change to as-install/bin to run asadmin, be sure to include./ in the command name; for
example:

cd as-install/bin
./asadmin

Cannot Stop Domain Using asadmin stop-domain

Description

You cannot stop the domain using the asadmin stop-domain command.

Solution

Search the server.log le for error messages related to your inability to stop the domain. To
kill a process when stop-domain is not working, try $JAVA_HOME/bin/jps and look for the
process with ASMain.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200832

Using asadmin set Command Might Produce Unexpected Results

Description

Unexpected results are returned when setting variables in a command, such as:

asadmin set name={$a-b}

In this case, name is set to b, not {$a-b} because the shell syntax ${a=b} is interpreted as “if the
variable a is unset, substitute the value b, otherwise substitute the value of a.” This is standard
shell behavior. For example, consider the following:

asadmin set default-config.http-service.http-listener.http-listener-1.port=
${http-listener-1-port}

In this case, default-config.http-service.http-listener.http-listener-1.port is set to
listener-1-port, which is invalid.

Issues Related to Eclipse

Issues Related to Eclipse

Eclipse GlassFish Server Adapter – Port Conict When
Starting GlassFish

Description

On Windows, the following error message is displayed when you start Enterprise Server v3
Prelude using the server adapter within Eclipse:

Please stop the server process using the same port as the one used
by the Application Server. A server process is already running on this port
but we cannot determine if it’s a GlassFish
process (lack of info or credentials)

The message does not list which port is blocked by a server process, making it dicult to locate
the blocking process. Obvious candidates such 4848 or 8080 are not blocked, according to TCP
View.

Chapter 2 • Specic Issues 33

Issues Related to Installation and Upgrade

Solution

This problem only occurs on Windows platforms and is related to an HTTP connection socket
error. For more information, see the following:

■

Forum threads: http://forums.java.net/jive/thread.jspa?messageID=316148 and

http://forums.java.net/jive/thread.jspa?messageID=316905

■

Issue report: http://glassfishplugins.dev.java.net/issues/show_bug.cgi?id=72

Note – The netstat -ab command shows the PID and might prove useful.

Issues Related to Installation and Upgrade

General Installation

Description

You encounter problems when installing.

Solution

The Enterprise Server installation requires JDK 5 or JDK 6, so check your system for that
dependency. Make sure that the JDK 5 or JDK 6 release bin directory is in your PATH so that the
java binary used with Enterprise Server comes from the JDK release rather than a JRE
implementation. For more information about system requirements and dependencies, see the

Sun GlassFish Enterprise Server v3 Prelude Release Notes. For complete installation information

and guidelines, see the

Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

Cannot Upgrade

Description

You cannot upgrade from Sun Java System Application Server 9.1 (GlassFish v2) to Enterprise
Server v3 Prelude. No upgrade option is available.

Solution

Upgrade support is not provided in Enterprise Server v3 Prelude. You cannot upgrade from
Sun Java System Application Server 9.1 (GlassFish v2) to Enterprise Server v3 Prelude.

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200834

For information about updating an existing Enterprise Server v3 Prelude installation, see

Chapter 2, “Updating an Existing Enterprise Server v3 Prelude Installation,” in Sun GlassFish

Enterprise Server v3 Prelude Installation Guide.

Issues Related to JavaMail

Cannot Congure JavaMail Resources

Description

You cannot congure JavaMail resources using the Administration Console.

Solution

JavaMail resources are not supported by Enterprise Server v3 Prelude. The mail.jar and
activation.jar les are bundled so that you can create and use mail sessions. However, you

cannot obtain mail sessions from a predened XML resource.

Issues Related to JNDI

Issues Related to JNDI

Cannot Deploy a Mail Session as a JNDI Resource

Description

You cannot deploy a mail session as a Java Naming and Directory InterfaceTM(JNDI) resource.

Solution

This functionality is not available in Enterprise Server v3 Prelude. You must use the mail
session directly. You cannot perform this task in the Administration Console or by using the
asadmin utility.

Chapter 2 • Specic Issues 35

Issues Related to MySQL

Issues Related to MySQL

ExceptionWhen Creating MySQL Connection Pool

Description

On Windows, you get an exception when creating a MySQL connection pool using the
Administration Console.

Solution

See “Attempt to Use Administration Console to Create a Connection Pool Fails Even if the

Driver Is Present (Issue 6671)” in Sun GlassFish Enterprise Server v3 Prelude Release Notes.

Issues Related to Security

java.security.AccessControlException: Access Denied Error

Description

The following error occurs from an application client, or appears in the server.log le:

java.security.AccessControlException: access denied
(java.util.PropertyPermission name write...)

There is a permissions issue in the policy les. Either the client.policy le for the application
client or the server.policy le for server side components does not have permission to set the
property.

Solution

Add the permission in client.policy (for the application client), or in server.policy (for
web modules) for the application that needs to set the property. By default, applications only
have “read” permission for properties.

For example, to grant read/write permission for all les in the codebase directory, add or
append the following to client.policy or server.policy:

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200836

Issues Related to Security

grant codeBase "file:/.../build/sparc_SunOS/sec/-" {

permission java.util.PropertyPermission "*", "read,write";

};

Mutual Authentication Not WorkingWith the Application Client

Description

This failure can occur when the keystore and truststore properties are not set properly.

Solution

Set the following properties on the JVM:

javax.net.ssl.keyStore=
<keystore-file-path>;javax.net.ssl.trustStore=<truststore-file-path>

To use the application client, set the environment variable VMARGS to the following value:

-Djavax.net.ssl.keyStore=${admin.domain.dir}/${admin.domain}/config/keystore.jks

-Djavax.net.ssl.trustStore=${admin.domain.dir}/${admin.domain}/config/cacerts.jks

Chapter 2 • Specic Issues 37

38

CHAPTER 3

3

Frequently Asked Questions

This chapter lists Frequently Asked Questions (FAQs) related to Sun GlassFish Enterprise
Server v3 Prelude. This list is certain to grow. For the latest FAQs,also see the GlassFish wiki at

http://wiki.glassfish.java.net/Wiki.jsp?page=GlassFishFAQIndex.

This chapter contains the following:

■

“Administration FAQs” on page 39

■

“Application FAQs” on page 40

■

“Eclipse FAQs” on page 40

■

“Extensibility FAQs” on page 41

■

“Java Persistence FAQs” on page 42

■

“JDBC FAQs” on page 42

■

“Jersey FAQs” on page 42

■

“OpenESB FAQs” on page 43

■

“Rails and JRuby FAQs” on page 43

■

“Security FAQs” on page 45

■

“Update Tool FAQs” on page 45

Administration FAQs

Which asadmin Commands are Supported?

Use asadmin list-commands to determine which commands are supported and available for
use. For related information, see

GlassFish Enterprise Server v3 Prelude Administration Guide

Appendix A, “The asadmin Utility Commands,” in Sun

.

39

Application FAQs

Application FAQs

How Do I Debug Applications?

See Chapter 3, “Debugging Applications,” in Sun GlassFish Enterprise Server v3 Prelude

Developer’s Guide

How Do I Change Application Permissions?

See “Changing Permissions for an Application” in Sun GlassFish Enterprise Server v3 Prelude

Developer’s Guide

What Are the Restrictions and Optimizations for Session Beans?

See “Session Bean Restrictions and Optimizations” in Sun GlassFish Enterprise Server v3

Prelude Developer’sGuide

.

.

.

How Do I Move TomcatToplink Applications to Enterprise Server v3 Prelude?

Enterprise Server v3 Prelude and NetBeans 6.5 enable you to move applications that run on
Tomcat using TopLink/EclipseLink to Enterprise Server. As a start, see “Moving Tomcat
Toplink Apps to GlassFish v3 Prelude”

http://blogs.sun.com/Lance/entry/moving_tomcat_toplink_apps_to).

(

Eclipse FAQs

Where Can I Find More Information About Eclipse and Enterprise Server Integration?

Eclipse is a development environment that provides a framework, tools, and runtime for
deploying and managing software. The GlassFish plugin for Eclipse provides important
changes to better support Enterprise Server v3 Prelude and to provide optimal redeployment of
web applications. For more information, see the following:

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200840

■

Download: Download the plugin from within Eclipse using the Download Additional
Server Adapters link on the New Server Wizard. See the Downloads page for additional
information (https://glassfishplugins.dev.java.net/download/index.html). If you
have diculty downloading the plugin from within Eclipse, you could be experiencing an
Eclipse update center network problem. Try again at another time.

■

Release Notes: https://ajax.dev.java.net/eclipse/releasenotes.html

■

Documentation: https://glassfishplugins.dev.java.net/eclipse34

Extensibility FAQs

How Do I Develop Add-On Components?

See the Sun GlassFish Enterprise Server v3 Prelude Add-On Component Development Guide for
complete details.

How Do I Add Containers?

Extensibility FAQs

Enterprise Server has a highly modular architecture that enables you to add new types of
containers that handle many application types, not just Java EE. Enterprise Server denes a
service provider interface (SPI), which container developers implement. The Enterprise Server
framework then invokes the container's implementation of the SPI to detect, deploy, and
manage applications of the new type.

For more information, see

Enterprise Server v3 Prelude Add-On Component Development Guide

Note – Web applications are the only Java EE application type supported by Enterprise Server v3

Prelude.

Chapter 6, “Adding Container Capabilities,” in Sun GlassFish

.

How Do I Extend the Administration Console?

See Chapter 3, “Extending the Administration Console,” in Sun GlassFish Enterprise Server v3

Prelude Add-On Component Development Guide.

Chapter 3 • FrequentlyAsked Questions 41

Java Persistence FAQs

Java Persistence FAQs

What Are the Restrictions and Optimizations for the Java Persistence API?

See “Restrictions and Optimizations” in Sun GlassFish Enterprise Server v3 Prelude Developer’s

Guide.

What Java Persistence Support Is Available?

Java Persistence 1.0 support in Enterprise Server v3 Prelude is available as follows:

■

EclipseLink 1.0

■

Hibernate EntityManager

■

OpenJPA

JDBC FAQs

Is JDBC Support Provided?

Yes, Enterprise Server v3 Prelude includes JDBC support. The JDBC connection pooling
infrastructure is the same as that of Sun Java System Application Server 9.1 (GlassFish v2). See
“JDBC support in v3 Prelude” (

Jersey FAQs

How Do I Use Jersey?

Jersey 1.0 is the production-quality Reference Implementation of JAX-RS. It is part of
Enterprise Server v3 Prelude and is available from Update Tool. For additional details,
including installation instructions, see the

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200842

http://blogs.sun.com/technical) for more information.

RESTful Web Services Developer’s Guide.

OpenESB FAQs

Does Enterprise Server v3 Prelude Support OpenESB?

No, OpenESB v2 runs on Sun Java System Application Server 9.1 (GlassFish v2). For more
information about OpenESB, see

Rails and JRuby FAQs

Should I Start an Enterprise Server Domain and Deploy My Application Into It, or Should I Use the glassfish_rails Gem?

To continue the question: I'm not sure what the second option does, or why I might choose one
over the other.

Response: In a nutshell, a gem is an application runner. It can run your Rails application but
nothing else. If you use the Enterprise Server v3 Prelude installation, start the domain and
deploy. You can deploy several Rails applications (or Java EE applications even) concurrently
with a dierent context root. This gives you access to dierent containers such as web and EJB
and also to the Update Tool. Enterprise Server enables you to host not only multiple Rails
applications, but also any other Java EE application.

Rails and JRuby FAQs

https://open-esb.dev.java.net.

If I Deploy an Application Using the glassfish_rails Gem, Can I Still Access the Administration Console?

No, the gem only runs Rails applications with no extensions or extra features. You must have
Enterprise Server v3 Prelude with a web container to access the Administration Console.

Where in a Rails Application Structure Does Enterprise Server Look for jar Files to Add to the Classpath for That Application?

To continue the question: WAR les and exploded Java webapp directories have a WEB-INF/lib
directory. Rails applications also have a lib directory, but this is for Ruby libraries. Where in a
Rails application can I put application-specic jar les? Is there such a place, or must I place
them in the domain/lib directory?

Chapter 3 • FrequentlyAsked Questions 43

Rails and JRuby FAQs

Response: Place them in the domain/lib directory, or in glassfish/lib. If those bundles are
OSGi bundles, you should place them in the glassfish/modules directory. If you want to
package your own set of jar les with the Rails application, instead of copying the jars in the
glassfish/lib or glassfish/modules directory, you might want to use Warbler. The Warbler
gem lets you package your own jars and creates a WAR le from your Rails applications.

Where Can I Find More Information About Rails Applications and Enterprise Server?

See the following:

■

Related documentation: Getting Started With JRuby on Rails for Sun GlassFish Enterprise

Server v3 Prelude

■

Blog post: “New and Improved GlassFish Gem”
(

http://weblogs.java.net/blog/vivekp/archive/2008/11/new_and_improve_1.html)

■

Getting Started Guide:

http://wiki.glassfish.java.net/Wiki.jsp?page=GettingStartedGuide

■

Gem documentation: http://glassfishgem.rubyforge.org

■

Warbler information: http://caldersphere.rubyforge.org/warbler/

■

Related screencasts: http://wiki.glassfish.java.net/Wiki.jsp?page=Screencasts

What Options Are Available for Running JRuby With Enterprise Server?

JRuby applications can be deployed natively, without the use of the servlet container. Enterprise
Server v3 Prelude can run JRuby applications directly on top of the servlet container. Warbler
can also be used to deploy JRuby applications to the servlet container.

For screencasts related to JRuby and Enterprise Server, see the GlassFish screencasts page at

http://wiki.glassfish.java.net/Wiki.jsp?page=Screencasts. Also see Getting Started
With JRuby on Rails for Sun GlassFish Enterprise Server v3 Prelude

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200844

.

Security FAQs

What Happens When No Server Side Realm Is
Congured?

When the application is congured (within XML les), but no server side realm is congured,
the application is authenticated in the default realm. No error is thrown that indicates “No such
realm.”

Can I See the TLS/SSL Handshake Information for an SSL Client?

Yes. Set the Java debugging property on the JVM. To see the handshake information from the
application client, append the following to the VMARGS variable:

-Djavax.net.debug=ssl,handshake

UpdateToolFAQs

Can I Change the Keystore Password?

Yes. Use the following Java 2 Platform, Standard Edition (J2SETM) properties to change the
keystore password:

-Djavax.net.ssl.keyStorePassword=password

-Djavax.net.ssl.trustStorePassword=password

Note that the keystore password must match the individual key passwords to perform
operations on the keys, so you must change the keystore password with the property mentioned
above, and then change the password to each key to match that password.

UpdateTool FAQs

How Do I Use Update Tool to Extend My Enterprise Server Installation?

Update Tool enables you to extend your Enterprise Server v3 Prelude installation by adding
add-on components such as JRuby and Groovy, Jersey, and Metro web services. Update Tool
can be accessed from within the Administration Console or on the command line.

Chapter 3 • FrequentlyAsked Questions 45

UpdateToolFAQs

After you start your Enterprise Server instance, the default location for the Administration
Console is http://localhost:4848/ (at least one Enterprise Server domain must be started
before you can launch the Administration Console). Unless you declined to check for updates
during installation, you will be notied of available updates in the message area. Update Tool
can also be accessed on the command line by running the updatetool command in the
as-install/bin directory. Extensive online help is provided for both versions.

For more information about Update Tool, see

Chapter 3, “Extending Enterprise Server,” in Sun

GlassFish Enterprise Server v3 Prelude Administration Guide

Console online help.

. Also see the Administration

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200846

Index

A

add-on components, developing, 41
admin password, not known, 26-27
admin username, not known, 26-27
Administration Console, cannot access, 24-25
Administration Console, extending, 41
administration FAQs, 39
application, cannot access, 25-27
application FAQs, 40
application issues, 29-31
asadmin issues, 31-33

C

cannot access Administration Console, 24-25
cannot access local server, 21-23
cannot access remote server, 23-24
cannot access server application, 25-27
cannot recall admin user name or password, 26-27
connection pool, cannot create, 36
containers, adding, 41

E

EAR, cannot deploy, 29-30
Eclipse FAQs, 40-41
Eclipse issues, 33-34
EJB support, 29-30
extensibility FAQs, 41

F

forums, 14
Frequently Asked Questions (FAQs), 39-46

G

gathering information, 15-16

H

hostname, nding, 24

D

debug data, gathering, 19
documentation, 14
domain, nding, 24
domain, cannot stop, 32

I

information, gathering, 15-16
installation issues, 34-35
issue tracker, 14

47

Index

J

Java Persistence FAQs, 42
JavaMail issues, 35
JDBC FAQs, 42
Jersey FAQs, 42
JNDI issues, 35
JRuby FAQs, 43-44
JSR 88, 30

K

kill processes, 17, 32
known issues, 14

L

local server, access fails, 21-23
log les, 16-17

M

mailing lists, 14
monitoring, 17

N

netstat -ab, 34

R

Rails FAQs, 43-44
release contents, 14-15
release resources, 19
remote server, access fails, 23-24
rpm, 17

S

security FAQs, 45
security issues, 36-37
server

how default port number can change, 22

will not start on windows, 27-28
showrev, 17
stack traces, 18
SunSolve, 15
system requirements, 14

T

thread dump, obtaining, 18

U

Update Tool FAQs, 45-46
upgrade issues, 34-35

O

OpenESB FAQs, 43

P

pkginfo, 17
port conict, Windows, 27-28
port number, how the default value can change, 22
ps -ef, 17

Sun GlassFish Enterprise Server v3 PreludeTroubleshootingGuide • November 200848

V

VisualVM, 18

W

Warbler, 44
Windows, server will not start, 27-28