821 2418

Oracle GlassFishServer 3.
1Application
Development Guide
Part No: 821241812
July 2011
Copyright 2010, 2011, Oracle and/or its afliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual
property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software,
unless required by lawfor interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you fnd any errors, please report themto us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is
applicable:
U.S. GOVERNMENTRIGHTS
Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or
"commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specifc supplemental regulations. As such, the use, duplication,
disclosure, modifcation, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent
applicable by the terms of the Government contract, the additional rights set forth in FAR52.227-19, Commercial Computer Software License (December 2007).
Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA94065.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently
dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall
be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its afliates disclaimany
liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its afliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARCtrademarks are used under license and are trademarks or registered
trademarks of SPARCInternational, Inc. AMD, Opteron, the AMDlogo, and the AMDOpteron logo are trademarks or registered trademarks of Advanced Micro
Devices. UNIXis a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and services fromthird parties. Oracle Corporation and
its afliates are not responsible for and expressly disclaimall warranties of any kind with respect to third-party content, products, and services. Oracle Corporation
and its afliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
111130@25097
Contents
Preface ...................................................................................................................................................15
Part I Development Tasks andTools ........................................................................................................... 23
1 SettingUpa Development Environment ........................................................................................ 25
Installing and Preparing the Server for Development .................................................................... 25
High Availability Features .................................................................................................................. 26
Development Tools ............................................................................................................................. 26
The asadmin Command .............................................................................................................. 27
The Administration Console ...................................................................................................... 27
The Migration Tool ..................................................................................................................... 27
The NetBeans IDE ........................................................................................................................ 27
The Eclipse IDE ............................................................................................................................ 28
Debugging Tools .......................................................................................................................... 28
Profling Tools .............................................................................................................................. 28
Sample Applications ............................................................................................................................ 28
2 Class Loaders ........................................................................................................................................29
The Class Loader Hierarchy ............................................................................................................... 30
Delegation ............................................................................................................................................ 31
Using the Java Optional Package Mechanism .................................................................................. 31
Using the Endorsed Standards Override Mechanism ..................................................................... 32
Class Loader Universes ....................................................................................................................... 32
Application-Specifc Class Loading .................................................................................................. 32
Circumventing Class Loader Isolation ............................................................................................. 34
Using the Common Class Loader .............................................................................................. 34
Sharing Libraries Across a Cluster ............................................................................................. 34
3
Packaging the Client JARfor One Application in Another Application ............................... 35
To Package the Client JARfor One Application in Another Application ............................. 35
3 DebuggingApplications ....................................................................................................................37
Enabling Debugging ........................................................................................................................... 37
To Set the Server to Automatically Start Up in Debug Mode ................................................. 38
JPDAOptions ...................................................................................................................................... 38
Generating a Stack Trace for Debugging .......................................................................................... 39
Application Client Debugging ........................................................................................................... 39
GlassFish Server Message Queue Debugging ................................................................................... 40
Enabling Verbose Mode ..................................................................................................................... 40
Class Loader Debugging ..................................................................................................................... 40
GlassFish Server Logging .................................................................................................................... 41
Profling Tools ..................................................................................................................................... 41
The NetBeans Profler ................................................................................................................. 41
The HPROF Profler .................................................................................................................... 42
The JProbe Profler ...................................................................................................................... 43
Part II DevelopingApplications andApplicationComponents .............................................................. 45
4 SecuringApplications .........................................................................................................................47
Security Goals ...................................................................................................................................... 48
GlassFish Server Specifc Security Features ...................................................................................... 48
Container Security .............................................................................................................................. 49
Declarative Security ..................................................................................................................... 49
Programmatic Security ................................................................................................................ 50
Roles, Principals, and Principal to Role Mapping ........................................................................... 50
RealmConfguration .......................................................................................................................... 52
Supported Realms ........................................................................................................................ 52
Howto Confgure a Realm .......................................................................................................... 52
Howto Set a Realmfor an Application or Module ................................................................... 53
Creating a CustomRealm ........................................................................................................... 53
JACCSupport ...................................................................................................................................... 56
Pluggable Audit Module Support ...................................................................................................... 56
Contents
Oracle GlassFish Server 3.1 Application Development Guide July 2011 4
Confguring an Audit Module .................................................................................................... 56
The AuditModule Class ............................................................................................................... 57
The server.policy File ..................................................................................................................... 58
Default Permissions ..................................................................................................................... 58
SystemProperties ......................................................................................................................... 59
Changing Permissions for an Application ................................................................................ 59
Enabling and Disabling the Security Manager ......................................................................... 61
Confguring Message Security for Web Services ............................................................................. 62
Message Security Providers ........................................................................................................ 63
Message Security Responsibilities .............................................................................................. 65
Application-Specifc Message Protection ................................................................................. 66
Understanding and Running the Sample Application ............................................................ 69
Programmatic Login ........................................................................................................................... 72
Programmatic Login Precautions .............................................................................................. 72
Granting Programmatic Login Permission .............................................................................. 73
The ProgrammaticLogin Class .................................................................................................. 73
User Authentication for Single Sign-on ............................................................................................ 74
Adding Authentication Mechanisms to the Servlet Container ...................................................... 76
The GlassFish Server and JSR196 .............................................................................................. 76
Writing a Server Authentication Module .................................................................................. 77
Sample Server Authentication Module ..................................................................................... 78
Compiling and Installing a Server Authentication Module .................................................... 82
Confguring a Server Authentication Module .......................................................................... 82
Binding a Server Authentication Module to Your Application .............................................. 83
5 DevelopingWebServices ................................................................................................................... 85
Creating Portable Web Service Artifacts .......................................................................................... 86
Deploying a Web Service .................................................................................................................... 86
The Web Service URI, WSDL File, and Test Page ........................................................................... 87
GlassFish Java EE Service Engine ...................................................................................................... 88
Using the jbi.xml File ................................................................................................................ 88
6 Usingthe Java Persistence API .......................................................................................................... 91
Specifying the Database ...................................................................................................................... 92
Additional Database Properties ......................................................................................................... 94
Contents
5
Confguring the Cache ........................................................................................................................ 94
Setting the Logging Level .................................................................................................................... 94
Using Lazy Loading ............................................................................................................................. 94
Primary Key Generation Defaults ..................................................................................................... 95
Automatic Schema Generation .......................................................................................................... 95
Annotations .................................................................................................................................. 96
Generation Options ..................................................................................................................... 96
Query Hints .......................................................................................................................................... 98
Changing the Persistence Provider ................................................................................................... 98
Restrictions and Optimizations ......................................................................................................... 99
Oracle Database Enhancements ................................................................................................. 99
Extended Persistence Context .................................................................................................... 99
Using @OrderBy with a Shared Session Cache ...................................................................... 100
Using BLOB or CLOB Types with the Inet Oraxo JDBCDriver .......................................... 100
Database Case Sensitivity .......................................................................................................... 100
Sybase Finder Limitation .......................................................................................................... 101
MySQL Database Restrictions .................................................................................................. 102
7 DevelopingWebApplications .........................................................................................................105
Using Servlets ..................................................................................................................................... 105
Caching Servlet Results ............................................................................................................. 106
About the Servlet Engine ........................................................................................................... 109
Using JavaServer Pages ..................................................................................................................... 110
JSP Tag Libraries and Standard Portable Tags ....................................................................... 110
JSP Caching ................................................................................................................................. 111
Options for Compiling JSP Files .............................................................................................. 114
Creating and Managing Sessions ..................................................................................................... 114
Confguring Sessions ................................................................................................................. 115
Session Managers ....................................................................................................................... 118
Using Comet ...................................................................................................................................... 122
Introduction to Comet .............................................................................................................. 122
Grizzly Comet ............................................................................................................................ 124
Bayeux Protocol ......................................................................................................................... 133
Advanced Web Application Features .............................................................................................. 135
Internationalization Issues ........................................................................................................ 136
Contents
Virtual Server Properties ........................................................................................................... 137
Class Loader Delegation ............................................................................................................ 137
Using the default-web.xml File .............................................................................................. 138
Confguring Logging and Monitoring in the Web Container .............................................. 139
Confguring Idempotent URL Requests ................................................................................. 139
Header Management ................................................................................................................. 140
Confguring Valves and Catalina Listeners ............................................................................ 140
Alternate Document Roots ....................................................................................................... 140
Using a context.xml File ............................................................................................................ 142
Enabling WebDav ...................................................................................................................... 143
Using SSI ..................................................................................................................................... 144
Using CGI ................................................................................................................................... 145
8 UsingEnterprise JavaBeans Technology ....................................................................................... 149
Value Added Features ....................................................................................................................... 149
Read-Only Beans ........................................................................................................................ 150
The pass-by-reference Element ........................................................................................... 150
Pooling and Caching .................................................................................................................. 151
Priority Based Scheduling of Remote Bean Invocations ....................................................... 152
Immediate Flushing ................................................................................................................... 152
EJB Timer Service .............................................................................................................................. 153
To Deploy an EJB Timer to a Cluster ....................................................................................... 154
Using Session Beans .......................................................................................................................... 156
About the Session Bean Containers ......................................................................................... 156
Stateful Session Bean Failover .................................................................................................. 157
Session Bean Restrictions and Optimizations ........................................................................ 162
Using Read-Only Beans .................................................................................................................... 163
Read-Only Bean Characteristics and Life Cycle ..................................................................... 164
Read-Only Bean Good Practices .............................................................................................. 165
Refreshing Read-Only Beans .................................................................................................... 165
Deploying Read-Only Beans .................................................................................................... 166
Using Message-Driven Beans .......................................................................................................... 167
Message-Driven Bean Confguration ...................................................................................... 167
Message-Driven Bean Restrictions and Optimizations ........................................................ 168
Contents
7
9 UsingContainer-ManagedPersistence .........................................................................................171
GlassFish Server Support for CMP .................................................................................................. 171
CMP Mapping ................................................................................................................................... 172
Mapping Capabilities ................................................................................................................ 172
The Mapping Deployment Descriptor File ............................................................................. 173
Mapping Considerations .......................................................................................................... 174
Automatic Schema Generation for CMP ....................................................................................... 177
Supported Data Types for CMP ............................................................................................... 177
Generation Options for CMP ................................................................................................... 179
Schema Capture ................................................................................................................................. 182
Automatic Database Schema Capture ..................................................................................... 183
Using the capture-schema Utility ........................................................................................... 183
Confguring the CMP Resource ....................................................................................................... 184
Performance-Related Features ......................................................................................................... 184
Version Column Consistency Checking ................................................................................. 184
Relationship Prefetching ........................................................................................................... 185
Read-Only Beans ........................................................................................................................ 186
Default Fetch Group Flags ................................................................................................................ 186
Confguring Queries for 1.1 Finders ............................................................................................... 187
About JDOQL Queries .............................................................................................................. 187
Query Filter Expression ............................................................................................................. 188
Query Parameters ...................................................................................................................... 189
Query Variables .......................................................................................................................... 189
JDOQL Examples ....................................................................................................................... 189
CMP Restrictions and Optimizations ............................................................................................. 191
Disabling ORDERBYValidation ............................................................................................ 191
Setting the Heap Size on DB2 ................................................................................................... 191
Eager Loading of Field State ..................................................................................................... 192
Restrictions on Remote Interfaces ........................................................................................... 192
PostgreSQL Case Insensitivity .................................................................................................. 192
No Support for lock-when-loaded on Sybase ....................................................................... 192
Sybase Finder Limitation .......................................................................................................... 193
Date and Time Fields ................................................................................................................. 193
Set RECURSIVE_TRIGGERS to false on MSSQL ...................................................................... 193
MySQL Database Restrictions .................................................................................................. 194
Contents
10 DevelopingJava Clients ...................................................................................................................197
Introducing the Application Client Container .............................................................................. 197
ACCSecurity .............................................................................................................................. 198
ACCNaming .............................................................................................................................. 198
Application Client Annotation ................................................................................................ 198
Java Web Start ............................................................................................................................. 199
Application Client JARFile ....................................................................................................... 199
Developing Clients Using the ACC ................................................................................................. 199
To Access an EJB Component Froman Application Client ................................................. 199
To Access a JMS Resource Froman Application Client ........................................................ 201
Using Java Web Start ................................................................................................................. 202
Using the Embeddable ACC ..................................................................................................... 212
Running an Application Client Using the appclient Script ................................................ 213
Using the package-appclient Script ..................................................................................... 214
The client.policy File ............................................................................................................ 214
Using RMI/IIOP Over SSL ........................................................................................................ 214
Connecting to a Remote EJB Module Through a Firewall .................................................... 216
Specifying a Splash Screen ........................................................................................................ 216
Setting Login Retries .................................................................................................................. 217
Using Libraries with Application Clients ................................................................................ 217
Developing Clients Without the ACC ............................................................................................ 217
To access an EJB component froma stand-alone client ........................................................ 218
To access an EJB component froma server-side module ...................................................... 219
To access a JMS resource froma stand-alone client .............................................................. 221
11 DevelopingConnectors ....................................................................................................................223
Connector Support in the GlassFish Server ................................................................................... 224
Connector Architecture for JMS and JDBC ........................................................................... 225
Connector Confguration ......................................................................................................... 225
Advanced Connector Confguration Options ............................................................................... 225
Thread Associations .................................................................................................................. 226
Security Maps ............................................................................................................................. 226
Work Security Maps .................................................................................................................. 227
Overriding Confguration Properties ...................................................................................... 227
Testing a Connector Connection Pool .................................................................................... 228
Contents
9
Flushing a Connector Connection Pool .................................................................................. 228
Handling Invalid Connections ................................................................................................. 229
Setting the Shutdown Timeout ................................................................................................. 229
Specifying the Class Loading Policy ......................................................................................... 230
Using Last Agent Optimization of Transactions ................................................................... 230
Disabling Pooling for a Connection ........................................................................................ 231
Using Application-Scoped Connectors .................................................................................. 231
Inbound Communication Support ................................................................................................. 231
Outbound Communication Support .............................................................................................. 232
Confguring a Message Driven Bean to Use a Resource Adapter ................................................ 232
12 DevelopingLifecycle Listeners ........................................................................................................235
Server Life Cycle Events .................................................................................................................... 236
The LifecycleListener Interface ........................................................................................................ 236
The LifecycleEvent Class .............................................................................................................. 236
The Server Lifecycle Event Context ................................................................................................. 237
Deploying a Lifecycle Module .......................................................................................................... 237
Considerations for Lifecycle Modules ............................................................................................ 238
13 DevelopingOSGi-enabledJava EE Applications .......................................................................... 239
Overviewof OSGi Application and GlassFish Server ................................................................... 239
Benefts of Using OSGi in Enterprise Java Applications ....................................................... 240
Developing OSGi Application Bundles for GlassFish Server ....................................................... 240
Developing Plain OSGi Bundles .............................................................................................. 241
Developing Web Application Bundles .................................................................................... 244
Developing EJB Application Bundles ...................................................................................... 246
Deploying OSGi Bundles in GlassFish Server ................................................................................ 247
Part III UsingServices andAPIs ................................................................................................................... 249
14 Usingthe JDBCAPI for Database Access ....................................................................................... 251
Statements .......................................................................................................................................... 252
Using an Initialization Statement ............................................................................................ 252
Setting a Statement Timeout .................................................................................................... 252
Contents
Statement Leak Detection and Leaked Statement Reclamation ........................................... 253
Statement Caching ..................................................................................................................... 253
Statement Tracing ...................................................................................................................... 254
Connections ....................................................................................................................................... 255
Transparent Pool Reconfguration .......................................................................................... 256
Disabling Pooling ....................................................................................................................... 256
Associating Connections with Threads ................................................................................... 257
CustomConnection Validation ............................................................................................... 258
Sharing Connections ................................................................................................................. 258
Marking Bad Connections ........................................................................................................ 259
Handling Invalid Connections ................................................................................................. 259
Connection Wrapping ...................................................................................................................... 260
Wrapping Connections ............................................................................................................. 260
Obtaining a Physical Connection Froma Wrapped Connection ........................................ 261
Using the Connection.unwrap() Method .............................................................................. 261
Allowing Non-Component Callers ................................................................................................. 262
Using Application-Scoped Resources ............................................................................................. 262
Restrictions and Optimizations ....................................................................................................... 263
Disabling Stored Procedure Creation on Sybase .................................................................... 263
15 UsingtheTransactionService ......................................................................................................... 265
Handling Transactions with Databases .......................................................................................... 265
Using JDBCTransaction Isolation Levels ............................................................................... 266
Using Non-Transactional Connections .................................................................................. 267
Handling Transactions with Enterprise Beans .............................................................................. 268
Flat Transactions ........................................................................................................................ 269
Global and Local Transactions ................................................................................................. 269
Commit Options ........................................................................................................................ 269
Bean-Level Container-Managed Transaction Timeouts ...................................................... 270
Handling Transactions with the Java Message Service ................................................................. 270
Transactions and Non-Persistent Messages ........................................................................... 270
Using the ConfgurableTransactionSupport Interface ......................................................... 270
The Transaction Manager, the Transaction Synchronization Registry, and
UserTransaction .............................................................................................................................. 271
Contents
11
16 Usingthe Java NamingandDirectory Interface .......................................................................... 273
Accessing the Naming Context ........................................................................................................ 273
Global JNDI Names ................................................................................................................... 274
Accessing EJB Components Using the CosNaming Naming Context .................................. 275
Accessing EJB Components in a Remote GlassFish Server ................................................... 275
Naming Environment for Lifecycle Modules ......................................................................... 276
Confguring Resources ..................................................................................................................... 276
External JNDI Resources .......................................................................................................... 277
CustomResources ...................................................................................................................... 277
Built-in Factories for CustomResources ................................................................................ 277
Disabling GlassFish Server V2 Vendor-Specifc JNDI Names ............................................. 279
Using Application-Scoped Resources ..................................................................................... 280
Using a Customjndi.properties File .......................................................................................... 280
Mapping References .......................................................................................................................... 280
17 Usingthe Java Message Service ...................................................................................................... 283
Using Application-Scoped JMS Resources ..................................................................................... 283
Load-Balanced Message Infow ....................................................................................................... 284
Authentication With ConnectionFactory .................................................................................... 284
Delivering SOAP Messages Using the JMS API ............................................................................. 285
To Send SOAP Messages Using the JMS API ......................................................................... 285
To Receive SOAP Messages Using the JMS API ..................................................................... 286
18 Usingthe JavaMail API ..................................................................................................................... 289
Introducing JavaMail ........................................................................................................................ 289
Creating a JavaMail Session .............................................................................................................. 290
JavaMail Session Properties .............................................................................................................. 290
Looking Up a JavaMail Session ........................................................................................................ 290
Sending and Reading Messages Using JavaMail ............................................................................ 291
To Send a Message Using JavaMail .......................................................................................... 291
To Read a Message Using JavaMail .......................................................................................... 292
Using Application-Scoped JavaMail Resources ............................................................................. 292
Index ................................................................................................................................................... 293
Contents
Tables
TABLE 21 Oracle GlassFish Server Class Loaders .................................................................... 30
TABLE 41 PredefnedSystemProperties .................................................................................. 59
TABLE 42 Message Security Provider Properties ..................................................................... 65
TABLE 61 The asadmin deploy and asadmin deploydir Generation Options ................. 97
TABLE 62 The asadmin undeploy Generation Options ........................................................ 97
TABLE 71 The cache Attributes ............................................................................................... 112
TABLE 72 The flush Attributes ............................................................................................... 114
TABLE 73 Object Types Supported for Java EEWeb Application Session State Failover . 117
TABLE 74 SSIServlet init-param Values ............................................................................ 145
TABLE 75 CGIServlet init-param Values ............................................................................ 146
TABLE 81 Object Types Supported for Java EEStateful Session Bean State Failover ........ 158
TABLE 91 Java Type to JDBCType Mappings for CMP ....................................................... 177
TABLE 92 Mappings of JDBCTypes to Database Vendor Specifc Types for CMP .......... 179
TABLE 93 The glassfish-ejb-jar.xml GenerationElements .......................................... 180
TABLE 94 The asadmin deploy and asadmin deploydir Generation Options for CMP
.................................................................................................................................... 181
TABLE 95 The asadmin undeploy Generation Options for CMP ...................................... 182
TABLE 101 OwnedJNLPFile Content ...................................................................................... 211
TABLE 102 DefaultedJNLPFile Content ................................................................................. 211
TABLE 103 MergedJNLPFile Content ..................................................................................... 211
TABLE 151 TransactionIsolationLevels .................................................................................. 266
13
14
Preface
This Application Development Guide describes howto create and run Java Platform, Enterprise
Edition (Java EE platform) applications that followthe open Java standards model for Java EE
components and APIs in the Oracle GlassFish Server environment. Topics include developer
tools, security, and debugging. This book is intended for use by software developers who create,
assemble, and deploy Java EE applications using Oracle servers and software.
This preface contains information about and conventions for the entire Oracle GlassFish Server
(GlassFish Server) documentation set.
GlassFish Server 3.1 is developed through the GlassFish project open-source community at
http://glassfish.java.net/. The GlassFish project provides a structured process for
developing the GlassFish Server platformthat makes the newfeatures of the Java EE platform
available faster, while maintaining the most important feature of Java EE: compatibility. It
enables Java developers to access the GlassFish Server source code and to contribute to the
development of the GlassFish Server. The GlassFish project is designed to encourage
communication between Oracle engineers and the community.
The following topics are addressed here:
GlassFish Server Documentation Set on page 15
Related Documentation on page 17
Typographic Conventions on page 18
Symbol Conventions on page 19
Default Paths and File Names on page 19
Documentation, Support, and Training on page 20
Searching Oracle Product Documentation on page 20
Third-Party Web Site References on page 21

GlassFishServer DocumentationSet
The GlassFish Server documentation set describes deployment planning and system
installation. For an introduction to GlassFish Server, refer to the books in the order in which
they are listed in the following table.
15
TABLE P1 Books in the GlassFish Server Documentation Set
BookTitle Description
Release Notes Provides late-breaking information about the software and the
documentation and includes a comprehensive, table-based summary of the
supported hardware, operating system, Java Development Kit (JDK), and
database drivers.
Quick Start Guide Explains howto get started with the GlassFish Server product.
Installation Guide Explains howto install the software and its components.
Upgrade Guide Explains howto upgrade to the latest version of GlassFish Server. This guide
also describes diferences between adjacent product releases and
confguration options that can result in incompatibility with the product
specifcations.
Deployment Planning Guide Explains howto build a production deployment of GlassFish Server that
meets the requirements of your systemand enterprise.
Administration Guide Explains howto confgure, monitor, and manage GlassFish Server
subsystems and components fromthe command line by using the
asadmin(1M) utility. Instructions for performing these tasks fromthe
Administration Console are provided in the Administration Console online
help.
Security Guide Provides instructions for confguring and administering GlassFish Server
security.
Application Deployment Guide Explains howto assemble and deploy applications to the GlassFish Server
and provides information about deployment descriptors.
Application Development Guide Explains howto create and implement Java Platform, Enterprise Edition
(Java EE platform) applications that are intended to run on the GlassFish
Server. These applications followthe open Java standards model for Java EE
components and application programmer interfaces (APIs). This guide
provides information about developer tools, security, and debugging.
Add-On Component
Development Guide
Explains howto use published interfaces of GlassFish Server to develop
add-on components for GlassFish Server. This document explains howto
performonly those tasks that ensure that the add-on component is suitable
for GlassFish Server.
Embedded Server Guide Explains howto run applications in embedded GlassFish Server and to
develop applications in which GlassFish Server is embedded.
High Availability
Administration Guide
Explains howto confgure GlassFish Server to provide higher availability and
scalability through failover and load balancing.
Performance Tuning Guide Explains howto optimize the performance of GlassFish Server.
Preface
TABLE P1 Books in the GlassFish Server Documentation Set (Continued)
BookTitle Description
Troubleshooting Guide Describes common problems that you might encounter when using
GlassFish Server and explains howto solve them.
Error Message Reference Describes error messages that you might encounter when using GlassFish
Server.
Reference Manual Provides reference information in man page format for GlassFish Server
administration commands, utility commands, and related concepts.
Message Queue Release Notes Describes newfeatures, compatibility issues, and existing bugs for GlassFish
Server Message Queue.
Message Queue Technical
Overview
Provides an introduction to the technology, concepts, architecture,
capabilities, and features of the Message Queue messaging service.
Message Queue Administration
Guide
Explains howto set up and manage a Message Queue messaging system.
Message Queue Developers
Guide for JMXClients
Describes the application programming interface in Message Queue for
programmatically confguring and monitoring Message Queue resources in
conformance with the Java Management Extensions (JMX).
Guide for Java Clients
Provides information about concepts and procedures for developing Java
messaging applications (Java clients) that work with GlassFish Server.
Guide for CClients
Provides programming and reference information for developers working
with Message Queue who want to use the Clanguage binding to the Message
Queue messaging service to send, receive, and process Message Queue
messages.
RelatedDocumentation
The following tutorials explain howto develop Java EE applications:
Your First Cup: An Introduction to the Java EE Platform(http://download.oracle.com/

javaee/6/firstcup/doc/). For beginning Java EE programmers, this short tutorial
explains the entire process for developing a simple enterprise application. The sample
application is a web application that consists of a component that is based on the Enterprise
JavaBeans specifcation, a JAX-RS web service, and a JavaServer Faces component for the
web front end.
The Java EE 6 Tutorial (http://download.oracle.com/javaee/6/tutorial/doc/). This

comprehensive tutorial explains howto use Java EE 6 platformtechnologies and APIs to
develop Java EE applications.
Preface
17
Javadoc tool reference documentation for packages that are provided with GlassFish Server is
available as follows.
The API specifcation for version 6 of Java EE is located at http://download.oracle.com/

javaee/6/api/.
The API specifcation for GlassFish Server 3.1, including Java EE 6 platformpackages and
nonplatformpackages that are specifc to the GlassFish Server product, is located at
http://glassfish.java.net/nonav/docs/v3/api/.
Additionally, the Java EE Specifcations (http://www.oracle.com/technetwork/java/
javaee/tech/index.html) might be useful.
For information about creating enterprise applications in the NetBeans Integrated
Development Environment (IDE), see the NetBeans Documentation, Training &Support page
(http://www.netbeans.org/kb/).
For information about the Java DB database for use with the GlassFish Server, see the Java DB
product page (http://www.oracle.com/technetwork/java/javadb/overview/index.html).
The Java EE Samples project is a collection of sample applications that demonstrate a broad
range of Java EE technologies. The Java EE Samples are bundled with the Java EE Software
Development Kit (SDK) and are also available fromthe Java EE Samples project page
(http://java.net/projects/glassfish-samples).
Typographic Conventions
The following table describes the typographic changes that are used in this book.
TABLE P2 Typographic Conventions
Typeface Meaning Example
AaBbCc123 The names of commands, fles, and
directories, and onscreen computer
output
Edit your .login fle.
Use ls -a to list all fles.
machine_name% you have mail.
AaBbCc123 What you type, contrasted with onscreen
computer output
machine_name% su
Password:
AaBbCc123 Aplaceholder to be replaced with a real
name or value
The command to remove a fle is rm flename.
AaBbCc123 Book titles, newterms, and terms to be
emphasized (note that some emphasized
items appear bold online)
Read Chapter 6 in the Users Guide.
Acache is a copy that is stored locally.
Do not save the fle.
Preface
Symbol Conventions
The following table explains symbols that might be used in this book.
TABLE P3 Symbol Conventions
Symbol Description Example Meaning
[ ] Contains optional arguments
and command options.
ls [-l] The -l option is not required.
{ | } Contains a set of choices for a
required command option.
-d {y|n} The -d option requires that you use
either the y argument or the n
argument.
${ } Indicates a variable
reference.
${com.sun.javaRoot} References the value of the
com.sun.javaRoot variable.
- Joins simultaneous multiple
keystrokes.
Control-A Press the Control key while you press
the Akey.
+ Joins consecutive multiple
keystrokes.
Ctrl+A+N Press the Control key, release it, and
then press the subsequent keys.
Indicates menu item
selection in a graphical user
interface.
File NewTemplates Fromthe File menu, choose New.
Fromthe Newsubmenu, choose
Templates.
Default Paths andFile Names
The following table describes the default paths and fle names that are used in this book.
TABLE P4 Default Paths and File Names
Placeholder Description Default Value
as-install Represents the base installation directory for
GlassFish Server.
In confguration fles, as-install is represented
as follows:
${com.sun.aas.installRoot}
Installations on the Oracle Solaris operating system, Linux
operating system, and Mac OS operating system:
users-home-directory/glassfish3/glassfish
Windows, all installations:
SystemDrive:\glassfish3\glassfish
Preface
19
TABLE P4 Default Paths and File Names (Continued)
Placeholder Description Default Value
as-install-parent Represents the parent of the base installation
directory for GlassFish Server.
Installations on the Oracle Solaris operating system, Linux
operating system, and Mac operating system:
users-home-directory/glassfish3
Windows, all installations:
SystemDrive:\glassfish3
domain-root-dir Represents the directory in which a domain is
created by default.
as-install/domains/
domain-dir Represents the directory in which a domain's
confguration is stored.
In confguration fles, domain-dir is
represented as follows:
${com.sun.aas.instanceRoot}
domain-root-dir/domain-name
Documentation, Support, andTraining
The Oracle web site provides information about the following additional resources:
Documentation (http://www.oracle.com/technetwork/indexes/documentation/
index.html)
Support (http://www.oracle.com/us/support/index.html)
Training (http://education.oracle.com/)
SearchingOracle Product Documentation
Besides searching Oracle product documentation fromthe Oracle Documentation
(http://www.oracle.com/technetwork/indexes/documentation/index.html) web site, you
can use a search engine by typing the following syntax in the search feld:
search-term site:oracle.com
For example, to search for broker, type the following:
broker site:oracle.com
Preface
Third-PartyWebSite References
Third-party URLs are referenced in this document and provide additional, related information.
Note Oracle is not responsible for the availability of third-party web sites mentioned in this
document. Oracle 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. Oracle 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.
Preface
21
22
Development Tasks andTools
P A R T I
23
24
Setting Up a Development Environment
This chapter gives guidelines for setting up an application development environment in the
Oracle GlassFish Server. Setting up an environment for creating, assembling, deploying, and
debugging your code involves installing the mainstreamversion of the GlassFish Server and
making use of development tools. In addition, sample applications are available.
Installing and Preparing the Server for Development on page 25
High Availability Features on page 26
Development Tools on page 26
Sample Applications on page 28

InstallingandPreparingthe Server for Development
For more information about GlassFish Server installation, see the Oracle GlassFish Server 3.1
Installation Guide.
The following components are included in the full installation.
JDK
GlassFish Server core
Java Platform, Standard Edition (Java SE) 6
Java EE 6 compliant application server
Administration Console
asadmin utility
Other development and deployment tools
GlassFish Server Message Queue software
Java DB database, based on the Derby database fromApache (http://db.apache.org/

derby/manuals)
Load balancer plug-ins for web servers

1
C H A P T E R 1
25
The NetBeans Integrated Development Environment (IDE) bundles the GlassFish edition of
the GlassFish Server, so information about this IDE is provided as well.
After you have installed GlassFish Server, you can further optimize the server for development
in these ways:
Locate utility classes and libraries so they can be accessed by the proper class loaders. For
more information, see Using the Common Class Loader on page 34.
Set up debugging. For more information, see Chapter 3, Debugging Applications.
Confgure the Virtual Machine for the Java platform(JVMsoftware). For more information,
see Chapter 4, Administering the Virtual Machine for the Java Platform, in Oracle
GlassFish Server 3.1 Administration Guide.
HighAvailability Features
High availability features such as load balancing and session failover are discussed in detail in
the Oracle GlassFish Server 3.1-3.1.1 High Availability Administration Guide. This book
describes the following features in the following sections:
For information about HTTP session persistence, see Distributed Sessions and Persistence
on page 116.
For information about checkpointing of the stateful session bean state, see Stateful Session
Bean Failover on page 157.
For information about failover and load balancing for Java clients, see Chapter 10,
Developing Java Clients.
For information about load balancing for message-driven beans, see Load-Balanced
Message Infow on page 284.
Development Tools
The following general tools are provided with the GlassFish Server:
The asadmin Command on page 27
The Administration Console on page 27

The following development tools are provided with the GlassFish Server or downloadable from
Oracle:
The Migration Tool on page 27
The NetBeans IDE on page 27

The following third-party tools might also be useful:
The Eclipse IDE on page 28

High Availability Features
Debugging Tools on page 28
Profling Tools on page 28

The asadmin Command
The asadmin command allows you to confgure a local or remote server and performboth
administrative and development tasks at the command line. For general information about
asadmin, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
The asadmin command is located in the as-install/bin directory. Type asadmin help for a list
of subcommands.
The AdministrationConsole
The Administration Console lets you confgure the server and performboth administrative and
development tasks using a web browser. For general information about the Administration
Console, click the Help button in the Administration Console. This displays the GlassFish
Server online help.
To access the Administration Console, type http://host:4848 in your browser. The host is the
name of the machine on which the GlassFish Server is running. By default, the host is
localhost. For example:
http://localhost:4848
The MigrationTool
The Migration Tool converts and reassembles Java EE applications and modules developed on
other application servers. This tool also generates a report listing howmany fles are
successfully and unsuccessfully migrated, with reasons for migration failure. For more
information and to download the Migration Tool, see http://java.sun.com/j2ee/tools/
migration/index.html.
The NetBeans IDE
The NetBeans IDE allows you to create, assemble, and debug code froma single, easy-to-use
interface. The GlassFish edition of the GlassFish Server is bundled with the NetBeans 6.1 IDE.
To download the NetBeans IDE, see http://www.netbeans.org. This site also provides
documentation on howto use the NetBeans IDE with the bundled GlassFish edition of the
GlassFish Server.
You can also use the GlassFish Server with the Java Studio Enterprise software, which is built on
the NetBeans IDE. For more information, see http://developers.sun.com/jsenterprise/.
Development Tools
Chapter 1 Setting Up a Development Environment 27
The Eclipse IDE
Aplug-in for the Eclipse IDE is available at https://glassfishplugins.dev.java.net/. This
site also provides documentation on howto register the GlassFish Server and use GlassFish
Server deployment descriptors.
DebuggingTools
You can use several debugging tools with the GlassFish Server. For more information, see
Chapter 3, Debugging Applications.
ProflingTools
You can use several proflers with the GlassFish Server. For more information, see Profling
Tools on page 41.
Sample Applications
Sample applications that you can examine and deploy to the GlassFish Server are available. If
you installed the GlassFish Server as part of installing the Java EE 6 SDKbundle fromJava EE 6
Downloads (http://www.oracle.com/technetwork/java/javaee/downloads/index.html),
the samples may already be installed. You can download these samples separately fromthe
Code Samples (http://www.oracle.com/technetwork/java/javaee/documentation/
index.html) page if you installed the GlassFish Server without theminitially.
Most GlassFish Server samples have the following directory structure:
The docs directory contains instructions for howto use the sample.
The build.xml fle defnes Ant targets for the sample.
The src/java directory under each component contains source code for the sample.
The src/conf directory under each component contains the deployment descriptors.
With a fewexceptions, sample applications followthe standard directory structure described
here: http://java.sun.com/blueprints/code/projectconventions.html.
The samples-install-dir/bp-project/main.xml fle defnes properties common to all sample
applications and implements targets needed to compile, assemble, deploy, and undeploy
sample applications. In most sample applications, the build.xml fle imports main.xml.
In addition to the Java EE 6 sample applications, samples are also available at GlassFish Samples
(https://glassfish-samples.dev.java.net/) and at as-install/glassfish/samples/.
Sample Applications
Class Loaders
Understanding Oracle GlassFish Server class loaders can help you determine where to place
supporting JARand resource fles for your modules and applications. For general information
about J2SE class loaders, see Understanding Network Class Loaders (http://java.sun.com/
developer/technicalArticles/Networking/classloaders/).
In a JVMimplementation, the class loaders dynamically load a specifc Java class fle needed for
resolving a dependency. For example, when an instance of java.util.Enumeration needs to be
created, one of the class loaders loads the relevant class into the environment.
The Class Loader Hierarchy on page 30
Delegation on page 31
Using the Java Optional Package Mechanism on page 31
Using the Endorsed Standards Override Mechanism on page 32
Class Loader Universes on page 32
Application-Specifc Class Loading on page 32
Circumventing Class Loader Isolation on page 34

Note The Web Profle of the GlassFish Server supports the EJB3.1 Lite specifcation, which
allows enterprise beans within web applications, among other features. The full GlassFish
Server supports the entire EJB 3.1 specifcation. For details, see JSR318 (http://jcp.org/en/
jsr/detail?id=318).
For information about class loader debugging, see Class Loader Debugging on page 40.
2
C H A P T E R 2
29
The Class Loader Hierarchy
Class loaders in the GlassFish Server runtime followa delegation hierarchy that is fully
described in Table 21.
The following table describes the class loaders in the GlassFish Server.
TABLE 21 Oracle GlassFish Server Class Loaders
Class Loader Description
Bootstrap The Bootstrap class loader loads the basic runtime classes provided by the JVM
software.
Extension The Extension class loader loads classes fromJARfles present in the systemextensions
directory, domain-dir/lib/ext. It is parent to the Public API class loader. See Using
the Java Optional Package Mechanism on page 31.
Public API The Public API class loader makes available all classes specifcally exported by the
GlassFish Server runtime for use by deployed applications. This includes, but is not
limited to, Java EE APIs and other Oracle APIs. It is parent to the Common class loader.
Common The Common class loader loads JARfles in the as-install/lib directory, then classes in
the domain-dir/lib/classes directory, followed by JARfles in the domain-dir/lib
directory. Using domain-dir/lib/classes or domain-dir/lib is recommended
whenever possible, and required for customlogin modules and realms. It is parent to the
Connector class loader. See Using the Common Class Loader on page 34.
Connector The Connector class loader is a single class loader instance that loads individually
deployed connector modules, which are shared across all applications. It is parent to the
Applib class loader and the LifeCycleModule class loader.
LifeCycleModule The LifeCycleModule class loader is created once per lifecycle module. Each lifecycle
modules classpath is used to construct its own class loader. For more information on
lifecycle modules, see Chapter 12, Developing Lifecycle Listeners.
Applib The Applib class loader loads the library classes, specifed during deployment, for a
specifc enabled module or Java EE application; see Application-Specifc Class
Loading on page 32. One instance of this class loader is present in each class loader
universe; see Class Loader Universes on page 32. It is parent to the Archive class
loader.
When multiple deployed applications use the same library, they share the same instance
of the library. One library cannot reference classes fromanother library.
Archive The Archive class loader loads classes fromthe WAR, EAR, and JARfles or directories
(for directory deployment) of applications or modules deployed to the GlassFish Server.
This class loader also loads any application-specifc classes generated by the GlassFish
Server runtime, such as stub classes or servlets generated by JSP pages.
The Class Loader Hierarchy
Delegation
Note that the class loader hierarchy is not a Java inheritance hierarchy, but a delegation
hierarchy. In the delegation design, a class loader delegates class loading to its parent before
attempting to load a class itself. If the parent class loader cannot load a class, the class loader
attempts to load the class itself. In efect, a class loader is responsible for loading only the classes
not available to the parent. Classes loaded by a class loader higher in the hierarchy cannot refer
to classes available lower in the hierarchy.
The Java Servlet specifcation recommends that a web module's class loader look in the local
class loader before delegating to its parent. You can make this class loader followthe delegation
inversion model in the Servlet specifcation by setting delegate="false" in the class-loader
element of the glassfish-web.xml fle. It is safe to do this only for a web module that does not
interact with any other modules. For details, see class-loader in Oracle GlassFish Server 3.1
Application Deployment Guide.
The default value is delegate="true", which causes a web module's class loader to delegate in
the same manner as the other class loaders. You must use delegate="true" for a web
application that accesses EJB components or that acts as a web service client or endpoint. For
details about glassfish-web.xml, see Oracle GlassFish Server 3.1 Application Deployment
Guide.
For a number of packages, including java.* and javax.*, symbol resolution is always
delegated to the parent class loader regardless of the delegate setting. This prevents
applications fromoverriding core Java runtime classes or changing the API versions of
specifcations that are part of the Java EE platform.
Usingthe Java Optional Package Mechanism
Optional packages are packages of Java classes and associated native code that application
developers can use to extend the functionality of the core platform.
To use the Java optional package mechanism, copy the JARfles into the domain-dir/lib/ext
directory, then restart the server.
For more information, see Optional Packages - An Overview(http://download.oracle.com/
javase/6/docs/technotes/guides/extensions/extensions.html) and Understanding
Extension Class Loading (http://download.oracle.com/javase/tutorial/ext/basics/
load.html).
Using the Java Optional Package Mechanism
Chapter 2 Class Loaders 31
Usingthe EndorsedStandards Override Mechanism
Endorsed standards handle changes to classes and APIs that are bundled in the JDKbut are
subject to change by external bodies.
To use the endorsed standards override mechanism, copy the JARfles into the
domain-dir/lib/endorsed directory, then restart the server.
For more information and the list of packages that can be overridden, see Endorsed Standards
Override Mechanism(http://download.oracle.com/javase/6/docs/technotes/guides/
standards/).
Class Loader Universes
Access to components within applications and modules installed on the server occurs within
the context of isolated class loader universes, each of which has its own Applib and Archive class
loaders.
Application Universe Each Java EE application has its own class loader universe, which
loads the classes in all the modules in the application.
Individually Deployed Module Universe Each individually deployed EJB JARor web
WARhas its own class loader universe, which loads the classes in the module.
Aresource such as a fle that is accessed by a servlet, JSP, or EJB component must be in one of
the following locations:
Adirectory pointed to by the Libraries feld or ----libraries option used during

deployment
Adirectory pointed to by the library-directory element in the application.xml

deployment descriptor
Adirectory pointed to by the application or modules classpath; for example, a web modules
classpath includes these directories:
module-name/WEB-INF/classes
module-name/WEB-INF/lib
Application-Specifc Class Loading
You can specify module- or application-specifc library classes during deployment in one of the
following ways:
Use the Administration Console. Open the Applications component, then go to the page for
the type of application or module. Select the Deploy button. Type the comma-separated
paths in the Libraries feld. For details, click the Help button in the Administration Console.
Using the Endorsed Standards Override Mechanism
Use the asadmin deploy command with the ----libraries option and specify
comma-separated paths. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference
Manual.
Note The Libraries feld in the Administration Console's deployment page and the
----libraries option of the asadmin deploy command do not apply to application clients.
For more information, see Using Libraries with Application Clients on page 217.
You can only specify module- or application-specifc library classes during deployment. You
can update a library JARfle using dynamic reloading or by restarting (disabling and
re-enabling) a module or application. To add or remove library JARfles, you must redeploy the
module or application.
Application libraries are included in the Applib class loader. Paths to libraries can be relative or
absolute. Arelative path is relative to domain-dir/lib/applibs. If the path is absolute, the path
must be accessible to the domain administration server (DAS). The GlassFish Server
automatically synchronizes these libraries to all remote cluster instances when the cluster is
restarted. However, libraries specifed by absolute paths are not guaranteed to be synchronized.
Tip You can use application-specifc class loading to specify a diferent XML parser than the
default GlassFish Server XML parser.
You can also use application-specifc class loading to access diferent versions of a library from
diferent applications.
If multiple applications or modules refer to the same libraries, classes in those libraries are
automatically shared. This can reduce the memory footprint and allowsharing of static
information. However, applications or modules using application-specifc libraries are not
portable. Other ways to make libraries available are described in Circumventing Class Loader
Isolation on page 34.
One library cannot reference classes fromanother library.
For general information about deployment, including dynamic reloading, see the Oracle
GlassFish Server 3.1 Application Deployment Guide.
Note If you see an access control error message when you try to use a library, you may need to
grant permission to the library in the server.policy fle. For more information, see Changing
Permissions for an Application on page 59.
Application-Specifc Class Loading
CircumventingClass Loader Isolation
Since each application or individually deployed module class loader universe is isolated, an
application or module cannot load classes fromanother application or module. This prevents
two similarly named classes in diferent applications or modules frominterfering with each
other.
To circumvent this limitation for libraries, utility classes, or individually deployed modules
accessed by more than one application, you can include the relevant path to the required classes
in one of these ways:
Using the Common Class Loader on page 34
Sharing Libraries Across a Cluster on page 34
Packaging the Client JARfor One Application in Another Application on page 35

Usingthe CommonClass Loader
To use the Common class loader, copy the JARfles into the domain-dir/lib or as-install/lib
directory or copy the .class fles (and other needed fles, such as .properties fles) into the
domain-dir/lib/classes directory, then restart the server.
Using the Common class loader makes an application or module accessible to all applications
or modules deployed on servers that share the same confguration. However, this accessibility
does not extend to application clients. For more information, see Using Libraries with
Application Clients on page 217.
For example, using the Common class loader is the recommended way of adding JDBCdrivers
to the GlassFish Server. For a list of the JDBCdrivers currently supported by the GlassFish
Server, see the Oracle GlassFish Server 3.1-3.1.1 Release Notes. For confgurations of supported
and other drivers, see Confguration Specifcs for JDBCDrivers in Oracle GlassFish Server 3.1
Administration Guide.
To activate customlogin modules and realms, place the JARfles in the domain-dir/lib
directory or the class fles in the domain-dir/lib/classes directory, then restart the server.
SharingLibraries Across a Cluster
To share libraries across a specifc cluster, copy the JARfles to the
domain-dir/config/cluster-confg-name/lib/classes directory.
Circumventing Class Loader Isolation
Packagingthe Client JARfor One Applicationin
Another Application
By packaging the client JARfor one application in a second application, you allowan EJB or
web component in the second application to call an EJB component in the frst (dependent)
application, without making either of themaccessible to any other application or module.
As an alternative for a production environment, you can have the Common class loader load
the client JARof the dependent application as described in Using the Common Class Loader
on page 34. Restart the server to make the dependent application accessible to all applications or
modules deployed on servers that share the same confguration.
ToPackage the Client JARfor One Applicationin

Another Application
Deploy the dependent application.
Addthe dependent applications client JARfle tothe callingapplication.
For a calling EJB component, add the client JARfle at the same level as the EJB component.
Then add a Class-Path entry to the MANIFEST.MF fle of the calling EJB component. The
Class-Path entry has this syntax:
Class-Path: flepath1.jar flepath2.jar ...
Each flepath is relative to the directory or JARfle containing the MANIFEST.MF fle. For
details, see the Java EE specifcation.
For a calling web component, add the client JARfle under the WEB-INF/lib directory.
If youneedtopackage the client JARwithboththe EJBandwebcomponents, set
delegate="true" inthe class-loader element of the glassfish-web.xml fle.
This changes the Web class loader so that it follows the standard class loader delegation model
and delegates to its parent before attempting to load a class itself.
For most applications, packaging the client JARfle with the calling EJB component is sufcient.
You do not need to package the client JARfle with both the EJB and web components unless
the web component is directly calling the EJB component in the dependent application.
Deploy the callingapplication.
The calling EJB or web component must specify in its glassfish-ejb-jar.xml or
glassfish-web.xml fle the JNDI name of the EJB component in the dependent application.
Using an ejb-link mapping does not work when the EJB component being called resides in
another application.
1
2
3
4
You do not need to restart the server.
Debugging Applications
This chapter gives guidelines for debugging applications in the Oracle GlassFish Server.
Enabling Debugging on page 37
JPDAOptions on page 38
Generating a Stack Trace for Debugging on page 39
Application Client Debugging on page 39
GlassFish Server Message Queue Debugging on page 40
Enabling Verbose Mode on page 40
Class Loader Debugging on page 40
GlassFish Server Logging on page 41
Profling Tools on page 41

EnablingDebugging
When you enable debugging, you enable both local and remote debugging. To start the server in
debug mode, use the ----debug option as follows:
asadmin start-domain --debug [domain-name]
You can then attach to the server fromthe Java Debugger (jdb) at its default Java Platform
Debugger Architecture (JPDA) port, which is 9009. For example, for UNIXsystems:
jdb -attach 9009
For Windows:
jdb -connect com.sun.jdi.SocketAttach:port=9009
For more information about the jdb debugger, see the following links:
3
C H A P T E R 3
37
Java PlatformDebugger Architecture - The Java Debugger: http://java.sun.com/javase/

technologies/core/toolsapis/jpda/
Java PlatformDebugger Architecture - Connecting with JDB: http://java.sun.com/

javase/technologies/core/toolsapis/jpda/
GlassFish Server debugging is based on the JPDA. For more information, see JPDAOptions
on page 38.
You can attach to the GlassFish Server using any JPDAcompliant debugger, including that of
NetBeans (http://www.netbeans.org), Java Studio Enterprise, JBuilder, Eclipse, and so on.
You can enable debugging even when the GlassFish Server is started without the ----debug
option. This is useful if you start the GlassFish Server fromthe Windows Start Menu, or if you
want to make sure that debugging is always turned on.
ToSet the Server toAutomatically Start UpinDebug

Mode
Use the AdministrationConsole. Select the JVMSettings component under the relevant
confguration.
Check the DebugEnabledbox.
Tospecify a diferent port (from9009, the default) touse whenattachingthe JVMsoftware toa
debugger, specify address= port-number inthe DebugOptions feld.
ToaddJPDAoptions, addany desiredJPDAdebuggingoptions inDebugOptions. See JPDA
Optionsonpage 38.
For details, click the Help button in the Administration Console fromthe JVMSettings page.
JPDAOptions
The default JPDAoptions in GlassFish Server are as follows:
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=9009
For Windows, you can change dt_socket to dt_shmem.
If you substitute suspend=y, the JVMsoftware starts in suspended mode and stays suspended
until a debugger attaches to it. This is helpful if you want to start debugging as soon as the JVM
software starts.
1
2
3
4
See Also
JPDAOptions
To specify a diferent port (from9009, the default) to use when attaching the JVMsoftware to a
debugger, specify address=port-number.
You can include additional options. Alist of JPDAdebugging options is available at
http://java.sun.com/javase/technologies/core/toolsapis/jpda/.
Generatinga StackTrace for Debugging
To generate a Java stack trace for debugging, use the asadmin generate-jvm-report
--type=thread command. The stack trace goes to the domain-dir/logs/server.log fle and
also appears on the command prompt screen. For more information about the asadmin
generate-jvm-report command, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
ApplicationClient Debugging
When the appclient script executes the java command to run the Application Client
Container (ACC), which in turn runs the client, it includes on the command line the value of
the VMARGS environment variable. You can set this variable to any suitable value. For example:
VMARGS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8118
The following example also works:
set VMARGS=-Xdebug -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8118
For debugging an application client, you should set suspend to y so you can connect the
debugger to the client before any code has actually executed. Otherwise, the client may start
running and execute past the point you want to examine.
You should use diferent ports for the server and client if you are debugging both concurrently.
For details about setting the port, see JPDAOptions on page 38.
You can also include JVMoptions such as -Xdebug and -Xrunjwdp in the appclient script
directly. For information about the appclient script, see Oracle GlassFish Server 3.1-3.1.1
Reference Manual.
Note The Application Client Container is supported only in the full GlassFish Server, not in the
Web Profle. See Chapter 10, Developing Java Clients.
Application Client Debugging
Chapter 3 Debugging Applications 39
GlassFishServer Message Queue Debugging
GlassFish Server Message Queue has a broker logger, which can be useful for debugging Java
Message Service (JMS) applications, including message-driven bean applications. You can
adjust the loggers verbosity, and you can send the logger output to the brokers console using
the brokers -tty option. For more information, see the Oracle GlassFish Server Message
Queue 4.5 Administration Guide.
Note JMS resources are supported only in the full GlassFish Server, not in the Web Profle. See
Chapter 17, Using the Java Message Service.
EnablingVerbose Mode
To have the server logs and messages printed to System.out on your command prompt screen,
you can start the server in verbose mode. This makes it easy to do simple debugging using print
statements, without having to viewthe server.log fle every time.
To start the server in verbose mode, use the ----verbose option as follows:
asadmin start-domain --verbose [domain-name]
When the server is in verbose mode, messages are logged to the console or terminal windowin
addition to the log fle. In addition, pressing Ctrl-Cstops the server and pressing Ctrl-\ (on
UNIXplatforms) or Ctrl-Break (on Windows platforms) prints a thread dump. On UNIX
platforms, you can also print a thread dump using the jstack command (see
http://download.oracle.com/javase/6/docs/technotes/tools/share/jstack.html) or
the command kill -QUIT process_id.
Class Loader Debugging
To generate class loading messages, use the following asadmin create-jvm-options
command:
asadmin create-jvm-options -verbose\:class
To send the JVMmessages to a special JVMlog fle instead of stdout, use the following asadmin
create-jvm-options commands:
asadmin create-jvm-options -XX\:+LogVMOutput
asadmin create-jvm-options -XX\:LogFile=${com.sun.aas.instanceRoot}/logs/jvm.log
GlassFish Server Message Queue Debugging
Note These -XX options are specifc to the OpenJDK(or Hotspot) JVMand do not work with
the JRockit JVM.
To send the GlassFish Server messages to the Administration Console instead of stderr, start
the domain in verbose mode as described in Enabling Verbose Mode on page 40.
GlassFishServer Logging
You can use the GlassFish Servers log fles to help debug your applications. Use the
Administration Console. Select the Stand-Alone Instances component, select the instance from
the table, then click the ViewLog Files button in the General Information page. Or select the
Cluster component, select the cluster fromthe table, select the Instances tab, select the instance
fromthe table, then click the ViewLog Files button in the General Information page.
To change logging settings, select Logger Settings under the relevant confguration.
For details about logging, click the Help button in the Administration Console.
ProflingTools
You can use a profler to performremote profling on the GlassFish Server to discover
bottlenecks in server-side performance. This section describes howto confgure proflers for
use with GlassFish Server.
The NetBeans Profler on page 41
The HPROF Profler on page 42
The JProbe Profler on page 43

Information about comprehensive monitoring and management support in the Java 2 Platform,
Standard Edition (J2SE platform) is available at http://download.oracle.com/
javase/6/docs/technotes/guides/management/index.html.
The NetBeans Profler
For information on howto use the NetBeans profler, see http://profiler.netbeans.org/
index.html.
ProflingTools
The HPROF Profler
The Heap and CPUProfling Agent (HPROF) is a simple profler agent shipped with the Java 2
SDK. It is a dynamically linked library that interacts with the Java Virtual Machine Profler
Interface (JVMPI) and writes out profling information either to a fle or to a socket in ASCII or
binary format.
HPROF can monitor CPUusage, heap allocation statistics, and contention profles. In addition,
it can also report complete heap dumps and states of all the monitors and threads in the Java
virtual machine. For more details on the HPROF profler, see the technical article at
http://java.sun.com/developer/technicalArticles/Programming/HPROF.html.
After HPROF is enabled using the following instructions, its libraries are loaded into the server
process.
ToUse HPROF ProflingonUNIX

Use the AdministrationConsole. Select the JVMSettings component under the relevant
confguration. Thenselect the Profler tab.
Edit the followingfelds:
Profler Name hprof
Profler Enabled true
Classpath (leave blank)
Native Library Path (leave blank)
JVMOption Select Add, type the HPROF JVMoption in the Value feld, then check its
box. The syntax of the HPROF JVMoption is as follows:
-Xrunhprof[:help]|[:param=value,param2=value2, ...]
Here is an example of params you can use:
-Xrunhprof:file=log.txt,thread=y,depth=3
The fle parameter determines where the stack dump is written.
Using help lists parameters that can be passed to HPROF. The output is as follows:
Hprof usage: -Xrunhprof[:help]|[:<option>=<value>, ...]
Option Name and Value Description Default
--------------------- ----------- -------
heap=dump|sites|all heap profiling all
cpu=samples|old CPU usage off
format=a|b ascii or binary output a
file=<file> write data to file java.hprof
(.txt for ascii)
1
2
ProflingTools
net=<host>:<port> send data over a socket write to file
depth=<size> stack trace depth 4
cutoff=<value> output cutoff point 0.0001
lineno=y|n line number in traces? y
thread=y|n thread in traces? n
doe=y|n dump on exit? y
Note Do not use help in the JVMOption feld. This parameter prints text to the standard
output and then exits.
The help output refers to the parameters as options, but they are not the same thing as JVM
options.
Restart the GlassFishServer.
This writes an HPROF stack dump to the fle you specifed using the fle HPROF parameter.
The JProbe Profler
Information about JProbe fromSitraka is available at http://www.quest.com/jprobe/.
After JProbe is installed using the following instructions, its libraries are loaded into the server
process.
ToEnable Remote ProflingWithJProbe

Install JProbe 3.0.1.1.
For details, see the JProbe documentation.
Confgure GlassFishServer usingthe AdministrationConsole:
a. Select the JVMSettings component under the relevant confguration. Thenselect the
Profler tab.
b. Edit the followingfelds before selectingSave andrestartingthe server:
Profler Name jprobe
Profler Enabled true
Classpath (leave blank)
Native Library Path JProbe-dir/profiler
JVMOption For each of these options, select Add, type the option in the Value feld,
then check its box
-Xbootclasspath/p:JProbe-dir/profiler/jpagent.jar
3
1
2
ProflingTools
-Xrunjprobeagent
-Xnoclassgc
Note If any of the confguration options are missing or incorrect, the profler might
experience problems that afect the performance of the GlassFish Server.
When the server starts up with this confguration, you can attach the profler.
Set the followingenvironment variable:
JPROBE_ARGS_0=-jp_input=JPL-fle-path
See Step 6 for instructions on howto create the JPL fle.
Start the server instance.
Launchthe jpprofiler andattachtoRemote Session. The default port is 4444.
Create the JPL fle usingthe JProbe LaunchPad. Here are the requiredsettings:
a. Select Server Side for the type of application.
b. Onthe Programtab, provide the followingdetails:
Target Server other-server
Server home Directory as-install
Server class File com.sun.enterprise.server.J2EERunner
Working Directory as-install
Classpath as-install/lib/appserv-rt.jar
Source File Path source-code-dir (in case you want to get the line level details)
Server class arguments (optional)
Main Package com.sun.enterprise.server

You must also set VM, Attach, and Coverage tabs appropriately. For further details, see the
JProbe documentation. After you have created the JPL fle, use this an input to
JPROBE_ARGS_0.
3
4
5
6
ProflingTools
Developing Applications and Application
Components
P A R T I I
45
46
Securing Applications
This chapter describes howto write secure Java EE applications, which contain components
that performuser authentication and access authorization for the business logic of Java EE
components.
For information about administrative security for the Oracle GlassFish Server, see the Oracle
GlassFish Server 3.1 Security Guide.
For general information about Java EE security, see Part VII, Security, in The Java EE 6
Tutorial.
Security Goals on page 48
GlassFish Server Specifc Security Features on page 48
Container Security on page 49
Roles, Principals, and Principal to Role Mapping on page 50
RealmConfguration on page 52
JACCSupport on page 56
Pluggable Audit Module Support on page 56
The server.policy File on page 58
Confguring Message Security for Web Services on page 62
Programmatic Login on page 72
User Authentication for Single Sign-on on page 74
Adding Authentication Mechanisms to the Servlet Container on page 76

jsr/detail?id=318).
4
C H A P T E R 4
47
Security Goals
In an enterprise computing environment, there are many security risks. The goal of the
GlassFish Server is to provide highly secure, interoperable, and distributed component
computing based on the Java EE security model. Security goals include:
Full compliance with the Java EE security model. This includes EJB and servlet role-based
authorization.
Support for single sign-on across all GlassFish Server applications within a single security
domain.
Support for web services message security.
Security support for application clients.
Support for several underlying authentication realms, such as simple fle and Lightweight
Directory Access Protocol (LDAP). Certifcate authentication is also supported for Secure
Socket Layer (SSL) client authentication. For Solaris, OS platformauthentication is
supported in addition to these.
Support for declarative security through GlassFish Server specifc XML-based role mapping.
Support for Java Authorization Contract for Containers (JACC) pluggable authorization as
included in the Java EE specifcation and defned by Java Specifcation Request (JSR) 115
(http://www.jcp.org/en/jsr/detail?id=115).
Support for Java Authentication Service Provider Interface for Containers as included in the
Java EE specifcation and defned by JSR196 (http://www.jcp.org/en/jsr/
detail?id=196).
Support for Web Services Interoperability Technologies (WSIT) as described in Metro

Users Guide (https://metro.dev.java.net/guide/).
GlassFishServer Specifc Security Features
The GlassFish Server supports the Java EE security model, as well as the following features
which are specifc to the GlassFish Server:
Message security; see Confguring Message Security for Web Services on page 62
Single sign-on across all GlassFish Server applications within a single security domain; see
User Authentication for Single Sign-on on page 74
Programmatic login; see Programmatic Login on page 72

Security Goals
Container Security
The component containers are responsible for providing Java EE application security. The
container provides two security forms:
Declarative Security on page 49
Programmatic Security on page 50

Annotations (also called metadata) enable a declarative style of programming, and so
encompass both the declarative and programmatic security concepts. Users can specify
information about security within a class fle using annotations. When the application is
deployed, this information can either be used by or overridden by the application or module
deployment descriptor.
Declarative Security
Declarative security means that the security mechanismfor an application is declared and
handled externally to the application. Deployment descriptors describe the Java EE
applications security structure, including security roles, access control, and authentication
requirements.
The GlassFish Server supports the deployment descriptors specifed by Java EE and has
additional security elements included in its own deployment descriptors. Declarative security is
the application deployers responsibility. For more information about GlassFish Server
deployment descriptors, see the Oracle GlassFish Server 3.1 Application Deployment Guide.
There are two levels of declarative security, as follows:
Application Level Security on page 49
Component Level Security on page 50

ApplicationLevel Security
For an application, roles used by any application must be defned in @DeclareRoles
annotations in the code or role-name elements in the application deployment descriptor
(application.xml). Those role names are scoped to the EJB XML deployment descriptors
(ejb-jar.xml and glassfish-ejb-jar.xml fles) and to the servlet XML deployment
descriptors (web.xml and glassfish-web.xml fles). For an individually deployed web or EJB
module, you defne roles using @DeclareRoles annotations or role-name elements in the Java
EE deployment descriptor fles web.xml or ejb-jar.xml.
To map roles to principals and groups, defne matching security-role-mapping elements in
the glassfish-application.xml, glassfish-ejb-jar.xml, or glassfish-web.xml fle for
each role-name used by the application. For more information, see Roles, Principals, and
Principal to Role Mapping on page 50.
Container Security
Chapter 4 Securing Applications 49
Component Level Security
Component level security encompasses web components and EJB components.
Asecure web container authenticates users and authorizes access to a servlet or JSP by using the
security policy laid out in the servlet XML deployment descriptors (web.xml and
glassfish-web.xml fles).
The EJB container is responsible for authorizing access to a bean method by using the security
policy laid out in the EJB XML deployment descriptors (ejb-jar.xml and
glassfish-ejb-jar.xml fles).
Programmatic Security
Programmatic security involves an EJB component or servlet using method calls to the security
API, as specifed by the Java EE security model, to make business logic decisions based on the
caller or remote users security role. Programmatic security should only be used when
declarative security alone is insufcient to meet the applications security model.
The Java EE specifcation defnes programmatic security as consisting of two methods of the
EJB EJBContext interface and two methods of the servlet HttpServletRequest interface. The
GlassFish Server supports these interfaces as specifed in the specifcation.
For more information on programmatic security, see the following:
The Java EE Specifcation
Programmatic Login on page 72

Roles, Principals, andPrincipal toRole Mapping
For applications, you defne roles in @DeclareRoles annotations or the Java EE deployment
descriptor fle application.xml. You defne the corresponding role mappings in the GlassFish
Server deployment descriptor fle glassfish-application.xml. For individually deployed web
or EJB modules, you defne roles in @DeclareRoles annotations or the Java EE deployment
descriptor fles web.xml or ejb-jar.xml. You defne the corresponding role mappings in the
GlassFish Server deployment descriptor fles glassfish-web.xml or glassfish-ejb-jar.xml.
For more information regarding Java EE deployment descriptors, see the Java EE Specifcation.
For more information regarding GlassFish Server deployment descriptors, see Appendix C,
Elements of the GlassFish Server Deployment Descriptors, in Oracle GlassFish Server 3.1
Each security-role-mapping element in the glassfish-application.xml,
glassfish-web.xml, or glassfish-ejb-jar.xml fle maps a role name permitted by the
application or module to principals and groups. For example, a glassfish-web.xml fle for an
individually deployed web module might contain the following:
Roles, Principals, and Principal to Role Mapping
<glassfish-web-app>
<security-role-mapping>
<role-name>manager</role-name>
<principal-name>jgarcia</principal-name>
<principal-name>mwebster</principal-name>
<group-name>team-leads</group-name>
</security-role-mapping>
<role-name>administrator</role-name>
<principal-name>dsmith</principal-name>
</glassfish-web-app>
Arole can be mapped to either specifc principals or to groups (or both). The principal or group
names used must be valid principals or groups in the realmfor the application or module. Note
that the role-name in this example must match the @DeclareRoles annotations or the
role-name in the security-role element of the corresponding web.xml fle.
You can also specify a customprincipal implementation class. This provides more fexibility in
howprincipals can be assigned to roles. Auser's JAAS login module nowcan authenticate its
customprincipal, and the authenticated customprincipal can further participate in the
GlassFish Server authorization process. For example:
<role-name>administrator</role-name>
<principal-name class-name="CustomPrincipalImplClass">
dsmith
</principal-name>
You can specify a default principal and a default principal to role mapping, each of which
applies to the entire GlassFish Server instance. The default principal to role mapping maps
group principals to the same named roles. Web modules that omit the run-as element in
web.xml use the default principal. Applications and modules that omit the
security-role-mapping element use the default principal to role mapping. These defaults are
part of the Security Service, which you can access in the following ways:
In the Administration Console, select the Security component under the relevant
confguration. For details, click the Help button in the Administration Console.
Use the asadmin set command. For details, see the Oracle GlassFish Server 3.1-3.1.1
Reference Manual. For example, you can set the default principal as follows.
asadmin set server-config.security-service.default-principal=dsmith
asadmin set server-config.security-service.default-principal-password=secret
You can set the default principal to role mapping as follows.
asadmin set server-config.security-service.activate-default-principal-to-role-mapping=true
asadmin set server-config.security-service.mapped-principal-class=CustomPrincipalImplClass
Roles, Principals, and Principal to Role Mapping
RealmConfguration
Supported Realms on page 52
Howto Confgure a Realm on page 52
Howto Set a Realmfor an Application or Module on page 53
Creating a CustomRealm on page 53

SupportedRealms
The following realms are supported in the current release of the GlassFish Server:
file Stores user information in a fle. This is the default realmwhen you frst install the
GlassFish Server.
ldap Stores user information in an LDAP directory.
jdbc Stores user information in a database.

In the JDBCrealm, the server gets user credentials froma database. The GlassFish Server
uses the database information and the enabled JDBCrealmoption in the confguration fle.
For digest authentication, a JDBCrealmshould be created with jdbcDigestRealm as the
JAAS context.
certificate Sets up the user identity in the GlassFish Server security context, and
populates it with user data obtained fromcryptographically verifed client certifcates.
solaris Allows authentication using Solaris username+password data. This realmis only
supported on the Solaris operating system, version 9 and above.
For information about confguring realms, see Howto Confgure a Realm on page 52.
HowtoConfgure a Realm
You can confgure a realmin one of these ways:
In the Administration Console, open the Security component under the relevant
confguration and go to the Realms page. For details, click the Help button in the
Administration Console.
Use the asadmin create-auth-realm command to confgure realms on local servers. For
details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
RealmConfguration
HowtoSet a Realmfor anApplicationor Module
The following deployment descriptor elements have optional realm or realm-name data
subelements or attributes that override the domains default realm:
glassfish-application element in glassfish-application.xml
web-app element in web.xml
as-context element in glassfish-ejb-jar.xml
client-container element in sun-acc.xml
client-credential element in sun-acc.xml

If modules within an application specify realms, these are ignored. If present, the realmdefned
in glassfish-application.xml is used, otherwise the domains default realmis used.
For example, a realmis specifed in glassfish-application.xml as follows:
<glassfish-application>
...
<realm>ldap</realm>
</glassfish-application>
For more information about the deployment descriptor fles and elements, see Appendix C,
Elements of the GlassFish Server Deployment Descriptors, in Oracle GlassFish Server 3.1
Creatinga CustomRealm
You can create a customrealmby providing a customJava Authentication and Authorization
Service (JAAS) login module class and a customrealmclass. Note that client-side JAAS login
modules are not suitable for use with the GlassFish Server.
To activate the customlogin modules and realms, place the JARfles in the domain-dir/lib
directory or the class fles in the domain-dir/lib/classes directory. For more information
about class loading in the GlassFish Server, see Chapter 2, Class Loaders.
JAAS is a set of APIs that enable services to authenticate and enforce access controls upon users.
JAAS provides a pluggable and extensible framework for programmatic user authentication
and authorization. JAAS is a core API and an underlying technology for Java EE security
mechanisms. For more information about JAAS, refer to the JAAS specifcation for Java SDK,
available at http://www.oracle.com/technetwork/java/javase/tech/
index-jsp-136007.html.
For general information about realms and login modules, see Working with Realms, Users,
Groups, and Roles in The Java EE 6 Tutorial.
For Javadoc tool pages relevant to customrealms, go to http://glassfish.java.net/nonav/
docs/v3/api/ and click on the com.sun.appserv.security package.
RealmConfguration
Customlogin modules must extend the
com.sun.appserv.security.AppservPasswordLoginModule class. This class implements
javax.security.auth.spi.LoginModule. Customlogin modules must not implement
LoginModule directly.
Customlogin modules must provide an implementation for one abstract method defned in
AppservPasswordLoginModule:
abstract protected void authenticateUser() throws LoginException
This method performs the actual authentication. The customlogin module must not
implement any of the other methods, such as login, logout, abort, commit, or initialize.
Default implementations are provided in AppservPasswordLoginModule which hook into the
GlassFish Server infrastructure.
The customlogin module can access the following protected object felds, which it inherits from
AppservPasswordLoginModule. These contain the user name and password of the user to be
authenticated:
protected String _username;
protected String _password;
The authenticateUser method must end with the following sequence:
String[] grpList;
// populate grpList with the set of groups to which
// _username belongs in this realm, if any
commitUserAuthentication(_username, _password,
_currentRealm, grpList);
Customrealms must extend the com.sun.appserv.security.AppservRealm class and
implement the following methods:
public void init(Properties props) throws BadRealmException,
NoSuchRealmException
This method is invoked during server startup when the realmis initially loaded. The props
argument contains the properties defned for this realm. The realmcan do any initialization it
needs in this method. If the method returns without throwing an exception, the GlassFish
Server assumes that the realmis ready to service authentication requests. If an exception is
thrown, the realmis disabled.
public String getAuthType()
This method returns a descriptive string representing the type of authentication done by this
realm.
public abstract Enumeration getGroupNames(String username) throws
InvalidOperationException, NoSuchUserException
RealmConfguration
This method returns an Enumeration (of String objects) enumerating the groups (if any) to
which the given username belongs in this realm.
Customrealms that manage users must implement the following additional methods:
public abstract boolean supportsUserManagement();
This method returns true if the realmsupports user management.
public abstract Enumeration getGroupNames() throws BadRealmException;
This method returns an Enumeration of all group names.
public abstract Enumeration getUserNames() throws BadRealmException;
This method returns an Enumeration of all user names.
public abstract void refresh() throws BadRealmException;
This method refreshes the realmdata so that newusers and groups are visible.
public abstract void persist() throws BadRealmException;
This method persists the realmdata to permanent storage.
public abstract User getUser(String name) throws NoSuchUserException,
BadRealmException;
This method returns the information recorded about a particular named user.
public abstract void addUser(String name, String password, String[] groupList) throws
BadRealmException, IASSecurityException;
This method adds a newuser, who cannot already exist.
public abstract void removeUser(String name) throws NoSuchUserException,
BadRealmException;
This method removes a user, who must exist.
public abstract void updateUser(String name, String newName, String password,
String[] groups) throws NoSuchUserException, BadRealmException, IASSecurityException;
This method updates data for a user, who must exist.
RealmConfguration
Note The array passed to the commitUseAuthentication method should be newly created and
otherwise unreferenced. This is because the group name array elements are set to null after
authentication as part of cleanup. So the second time your customrealmexecutes it returns an
array with null elements.
Ideally, your customrealmshould not return member variables fromthe authenticate
method. It should return local variables as the default JDBCRealm does. Your customrealmcan
create a local String array in its authenticate method, copy the values fromthe member
variables, and return the String array. Or it can use clone on the member variables.
JACCSupport
JACC(Java Authorization Contract for Containers) is part of the Java EE specifcation and
defned by JSR115 (http://www.jcp.org/en/jsr/detail?id=115). JACCdefnes an interface
for pluggable authorization providers. Specifcally, JACCis used to plug in the Java policy
provider used by the container to performJava EE caller access decisions. The Java policy
provider performs Java policy decisions during application execution. This provides third
parties with a mechanismto develop and plug in modules that are responsible for answering
authorization decisions during Java EE application execution. The interfaces and rules used for
developing JACCproviders are defned in the JACC1.0 specifcation.
The GlassFish Server provides a simple fle-based JACC-compliant authorization engine as a
default JACCprovider, named default. An alternate provider named simple is also provided.
To confgure an alternate provider using the Administration Console, open the Security
component under the relevant confguration, and select the JACCProviders component. For
details, click the Help button in the Administration Console.
Pluggable Audit Module Support
Audit modules collect and store information on incoming requests (servlets, EJB components)
and outgoing responses. You can create a customaudit module.
Confguring an Audit Module on page 56
The AuditModule Class on page 57

For additional information about audit modules, see Audit Callbacks (http://
developers.sun.com/appserver/reference/techart/ws_mgmt3.html).
ConfguringanAudit Module
To confgure an audit module, you can performone of the following tasks:
JACC Support
To specify an audit module using the Administration Console, open the Security
component under the relevant confguration, and select the Audit Modules component. For
You can use the asadmin create-audit-module command to confgure an audit module.
For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
The AuditModule Class
You can create a customaudit module by implementing a class that extends
com.sun.enterprise.security.audit.AuditModule.
For Javadoc tool pages relevant to audit modules, go to http://glassfish.java.net/nonav/
docs/v3/api/ and click on the com.sun.enterprise.security.audit package.
The AuditModule class provides default no-op implementations for each of the following
methods, which your customclass can override.
public void init(Properties props)
The preceding method is invoked during server startup when the audit module is initially
loaded. The props argument contains the properties defned for this module. The module can
do any initialization it needs in this method. If the method returns without throwing an
exception, the GlassFish Server assumes the module realmis ready to service audit requests. If
an exception is thrown, the module is disabled.
public void authentication(String user, String realm, boolean success)
This method is invoked when an authentication request has been processed by a realmfor the
given user. The success fag indicates whether the authorization was granted or denied.
public void webInvocation(String user, HttpServletRequest req, String type, boolean success)
This method is invoked when a web container call has been processed by authorization. The
success fag indicates whether the authorization was granted or denied. The req object is the
standard HttpServletRequest object for this request. The type string is one of
hasUserDataPermission or hasResourcePermission (see JSR115 (http://www.jcp.org/en/
jsr/detail?id=115)).
public void ejbInvocation(String user, String ejb, String method, boolean success)
This method is invoked when an EJB container call has been processed by authorization. The
success fag indicates whether the authorization was granted or denied. The ejb and method
strings describe the EJB component and its method that is being invoked.
public void webServiceInvocation(String uri, String endpoint, boolean success)
Pluggable Audit Module Support
This method is invoked during validation of a web service request in which the endpoint is a
servlet. The uri is the URL representation of the web service endpoint. The endpoint is the
name of the endpoint representation. The success fag indicates whether the authorization was
granted or denied.
public void ejbAsWebServiceInvocation(String endpoint, boolean success)
This method is invoked during validation of a web service request in which the endpoint is a
stateless session bean. The endpoint is the name of the endpoint representation. The success
fag indicates whether the authorization was granted or denied.
The server.policy File
Each GlassFish Server domain has its own global J2SE policy fle, located in
domain-dir/config. The fle is named server.policy.
The GlassFish Server is a Java EE compliant application server. As such, it follows the
requirements of the Java EE specifcation, including the presence of the security manager (the
Java component that enforces the policy) and a limited permission set for Java EE application
code.
Default Permissions on page 58
SystemProperties on page 59
Changing Permissions for an Application on page 59
Enabling and Disabling the Security Manager on page 61

Default Permissions
Internal server code is granted all permissions. These are covered by the AllPermission grant
blocks to various parts of the server infrastructure code. Do not modify these entries.
Application permissions are granted in the default grant block. These permissions apply to all
code not part of the internal server code listed previously. The GlassFish Server does not
distinguish between EJB and web module permissions. All code is granted the minimal set of
web component permissions (which is a superset of the EJB minimal set). Do not modify these
entries.
Afewpermissions above the minimal set are also granted in the default server.policy fle.
These are necessary due to various internal dependencies of the server implementation. Java EE
application developers must not rely on these additional permissions. In some cases, deleting
these permissions might be appropriate. For example, one additional permission is granted
specifcally for using connectors. If connectors are not used in a particular domain, you should
remove this permission, because it is not otherwise necessary.
SystemProperties
The following predefned systemproperties, also called variables, are available for use in the
server.policy fle. The systemproperty most frequently used in server.policy is
${com.sun.aas.instanceRoot}. For more information about systemproperties, see the
asadmin create-system-properties command in the Oracle GlassFish Server 3.1-3.1.1
Reference Manual.
TABLE 41 PredefnedSystemProperties
Property Default Description
com.sun.aas.installRoot depends on
operating system
Specifes the directory where the GlassFish Server is installed.
com.sun.aas.instanceRoot depends on
operating system
Specifes the top level directory for a server instance.
com.sun.aas.hostName none Specifes the name of the host (machine).
com.sun.aas.javaRoot depends on
operating system
Specifes the installation directory for the Java runtime.
com.sun.aas.imqLib depends on
operating system
Specifes the library directory for the GlassFish Server Message Queue
software.
com.sun.aas.configName server-config Specifes the name of the confguration used by a server instance.
com.sun.aas.instanceName server1 Specifes the name of the server instance. This property is not used in the
default confguration, but can be used to customize confguration.
com.sun.aas.clusterName cluster1 Specifes the name of the cluster. This property is only set on clustered server
instances. This property is not used in the default confguration, but can be
used to customize confguration.
com.sun.aas.domainName domain1 Specifes the name of the domain. This property is not used in the default
confguration, but can be used to customize confguration.
ChangingPermissions for anApplication
The default policy for each domain limits the permissions of Java EE deployed applications to
the minimal set of permissions required for these applications to operate correctly. Do not add
extra permissions to the default set (the grant block with no codebase, which applies to all code).
Instead, add a newgrant block with a codebase specifc to the applications requiring the extra
permissions, and only add the minimally necessary permissions in that block.
If you develop multiple applications that require more than this default set of permissions, you
can add the custompermissions that your applications need. The com.sun.aas.instanceRoot
variable refers to the domain-dir. For example:
grant codeBase "file:${com.sun.aas.instanceRoot}/applications/-" {
...
}
You can add permissions to stub code with the following grant block:
grant codeBase "file:${com.sun.aas.instanceRoot}/generated/-" {
...
}
In general, you should add extra permissions only to the applications or modules that require
them, not to all applications deployed to a domain. For example:
grant codeBase "file:${com.sun.aas.instanceRoot}/applications/MyApp/-" {
...
}
For a module:
grant codeBase "file:${com.sun.aas.instanceRoot}/applications/MyModule/-" {
...
}
Note Deployment directories may change between GlassFish Server releases.
An alternative way to add permissions to a specifc application or module is to edit the
granted.policy fle for that application or module. The granted.policy fle is located in the
domain-dir/generated/policy/app-or-module-name directory. In this case, you add
permissions to the default grant block. Do not delete permissions fromthis fle.
When the GlassFish Server policy subsystemdetermines that a permission should not be
granted, it logs a server.policy message specifying the permission that was not granted and
the protection domains, with indicated code source and principals that failed the protection
check. For example, here is the frst part of a typical message:
[#|2005-12-17T16:16:32.671-0200|INFO|sun-appserver-pe9.1|
javax.enterprise.system.core.security|_ThreadID=14;_ThreadName=Thread-31;|
JACC Policy Provider: PolicyWrapper.implies, context(null)-
permission((java.util.PropertyPermission java.security.manager write))
domain that failed(ProtectionDomain
(file:/E:/glassfish/domains/domain1/applications/cejug-clfds/ ... )
...
Granting the following permission eliminates the message:
grant codeBase "file:${com.sun.aas.instanceRoot}/applications/cejug-clfds/-" {
permission java.util.PropertyPermission "java.security.manager", "write";
}
Note Do not add java.security.AllPermission to the server.policy fle for application
code. Doing so completely defeats the purpose of the security manager, yet you still get the
performance overhead associated with it.
As noted in the Java EE specifcation, an application should provide documentation of the
additional permissions it needs. If an application requires extra permissions but does not
document the set it needs, contact the application author for details.
As a last resort, you can iteratively determine the permission set an application needs by
observing AccessControlException occurrences in the server log.
If this is not sufcient, you can add the -Djava.security.debug=failure JVMoption to the
domain. Use the following asadmin create-jvm-options command, then restart the server:
asadmin create-jvm-options -Djava.security.debug=failure
For more information about the asadmin create-jvm-options command, see the Oracle
GlassFish Server 3.1-3.1.1 Reference Manual.
You can use the J2SE standard policytool or any text editor to edit the server.policy fle. For
more information, see http://download.oracle.com/javase/tutorial/security/tour2/
index.html.
For detailed information about policy fle syntax, see http://download.oracle.com/
javase/6/docs/technotes/guides/security/PolicyFiles.html.
For information about using systemproperties in the server.policy fle, see
http://download.oracle.com/
javase/6/docs/technotes/guides/security/PolicyFiles.html.
For detailed information about the permissions you can set in the server.policy fle, see
javase/6/docs/technotes/guides/security/permissions.html.
The Javadoc for the Permission class is at http://download.oracle.com/javase/6/docs/
api/java/security/Permission.html.
EnablingandDisablingthe Security Manager
The security manager is disabled by default.
In a production environment, you may be able to safely disable the security manager if all of the
following are true:
Performance is critical
Deployment to the production server is carefully controlled
Only trusted applications are deployed
Applications don't need policy enforcement

Disabling the security manager may improve performance signifcantly for some types of
applications.
To enable the security manager, do one of the following:
To use the Administration Console, open the Security component under the relevant
confguration, and check the Security Manager Enabled box. Then restart the server. For
Use the following asadmin create-jvm-options command, then restart the server:
asadmin create-jvm-options -Djava.security.manager
To disable the security manager, use the corresponding delete-jvm-options command.
For more information about the create-jvm-options and asadmin delete-jvm-options
commands, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
ConfguringMessage Security for WebServices
In message security, security information is applied at the message layer and travels along with
the web services message. Web Services Security (WSS) is the use of XML Encryption and XML
Digital Signatures to secure messages. WSS profles the use of various security tokens including
X.509 certifcates, Security Assertion Markup Language (SAML) assertions, and
username/password tokens to achieve this.
Message layer security difers fromtransport layer security in that it can be used to decouple
message protection frommessage transport so that messages remain protected after
transmission, regardless of howmany hops they travel.
Note Message security (JSR196) is supported only in the full GlassFish Server, not in the Web
Profle.
Note In this release of the GlassFish Server, message layer annotations are not supported.
For more information about web services, see Chapter 5, Developing Web Services.
For more information about message security, see the following:
Chapter 39, Introduction to Security in the Java EE Platform, in The Java EE 6 Tutorial
Oracle GlassFish Server 3.1 Security Guide

Confguring Message Security for Web Services
JSR196 (http://www.jcp.org/en/jsr/detail?id=196), Java Authentication Service

Provider Interface for Containers
The Liberty Alliance Project specifcations at http://www.projectliberty.org/

resources/specifications.php/?f=resources/specifications.php
The Oasis Web Services Security (WSS) specifcation at http://docs.oasis-open.org/

wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf
The Web Services Interoperability Organization (WS-I) Basic Security Profle (BSP)
specifcation at http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html
The XML and Web Services Security page at https://xwss.dev.java.net/
The WSITpage at https://wsit.dev.java.net/

Message Security Providers on page 63
Message Security Responsibilities on page 65
Application-Specifc Message Protection on page 66
Understanding and Running the Sample Application on page 69

Message Security Providers
When you frst install the GlassFish Server, the providers XWS_ClientProvider and
XWS_ServerProvider are confgured but disabled. You can enable themin one of the following
ways:
To enable the message security providers using the Administration Console, open the
Security component under the relevant confguration, select the Message Security
component, and select SOAP. Then select XWS_ServerProvider fromthe Default Provider
list and XWS_ClientProvider fromthe Default Client Provider list. For details, click the
Help button in the Administration Console.
You can enable the message security providers using the following commands.
asadmin set
server-config.security-service.message-security-config.SOAP.default_provider=XWS_ServerProvider
asadmin set
server-config.security-service.message-security-config.SOAP.default_client_provider=XWS_ClientProvider
For more information about the asadmin set command, see the Oracle GlassFish
Server 3.1-3.1.1 Reference Manual.
The example described in Understanding and Running the Sample Application on page 69
uses the ClientProvider and ServerProvider providers, which are enabled when the Ant
targets are run. You dont need to enable these on the GlassFish Server prior to running the
example.
If you install the OpenSSO, you have these additional provider choices:
AMClientProvider and AMServerProvider These providers secure web services and

Simple Object Access Protocol (SOAP) messages using either WS-I BSP or Liberty ID-WSF
tokens. These providers are used automatically if they are confgured as the default
providers. If you wish to override any provider settings, you can confgure these providers in
message-security-binding elements in the glassfish-web.xml,
glassfish-ejb-jar.xml, and glassfish-application-client.xml deployment
descriptor fles.
AMHttpProvider This provider handles the initial end user authentication for securing
web services using Liberty ID-WSF tokens and redirects requests to the OpenSSOfor single
sign-on. To use this provider, specify it in the httpservlet-security-provider attribute
of the glassfish-web-app element in the glassfish-web.xml fle.
Liberty specifcations can be viewed at http://www.projectliberty.org/
resources/specifications.php/?f=resources/specifications.php. The WS-I BSP
specifcation can be viewed at http://www.ws-i.org/Profiles/
BasicSecurityProfile-1.0.html.
For more information about the GlassFish Server deployment descriptor fles, see the Oracle
For information about confguring these providers in the GlassFish Server, see the Oracle
GlassFish Server 3.1 Security Guide. For additional information about overriding provider
settings, see Application-Specifc Message Protection on page 66.
You can create newmessage security providers in one of the following ways:
To create a message security provider using the Administration Console, open the Security
component under the relevant confguration, and select the Message Security component.
For details, click the Help button in the Administration Console.
You can use the asadmin create-message-security-provider command to create a

message security provider. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference
Manual.
In addition, you can set a fewoptional provider properties using the asadmin set command.
For example:
asadmin set server-config.security-service.message-security-config.provider-config.property.debug=true
The following table describes these message security provider properties.
TABLE 42 Message Security Provider Properties
Property Default Description
security.config domain-dir/
config/
wss-server-
config-1.0.xml
Specifes the location of the message security confguration fle. To point to a confguration
fle in the domain-dir/config directory, use the systemproperty
${com.sun.aas.instanceRoot}/config/, for example:
${com.sun.aas.instanceRoot}/config/wss-server-config-1.0.xml
See SystemProperties on page 59.
debug false If true, enables dumping of server provider debug messages to the server log.
dynamic.username.
password
false If true, signals the provider runtime to collect the user name and password fromthe
CallbackHandler for each request. If false, the user name and password for
wsse:UsernameToken(s) is collected once, during module initialization. This property is
only applicable for a ClientAuthModule.
encryption.key.
alias
s1as Specifes the encryption key used by the provider. The key is identifed by its keystore alias.
signature.key.
alias
s1as Specifes the signature key used by the provider. The key is identifed by its keystore alias.
Message Security Responsibilities
In the GlassFish Server, the systemadministrator and application deployer roles are expected to
take primary responsibility for confguring message security. In some situations, the application
developer may also contribute, although in the typical case either of the other roles may secure
an existing application without changing its implementation and without involving the
developer.
Application Developer Responsibilities on page 65
Application Deployer Responsibilities on page 66
SystemAdministrator Responsibilities on page 66

ApplicationDeveloper Responsibilities
The application developer can turn on message security, but is not responsible for doing so.
Message security can be set up by the systemadministrator so that all web services are secured,
or set up by the application deployer when the provider or protection policy bound to the
application must be diferent fromthat bound to the container.
The application developer is responsible for the following:
Determining if an application-specifc message protection policy is required by the

application. If so, ensuring that the required policy is specifed at application assembly
which may be accomplished by communicating with the application deployer.
Determining if message security is necessary at the GlassFish Server level. If so, ensuring
that this need is communicated to the systemadministrator, or taking care of implementing
message security at the GlassFish Server level.
ApplicationDeployer Responsibilities
The application deployer is responsible for the following:
Specifying (at application assembly) any required application-specifc message protection

policies if such policies have not already been specifed by upstreamroles (the developer or
assembler)
Modifying GlassFish Server deployment descriptors to specify application-specifc message

protection policies information (message-security-binding elements) to web service
endpoint and service references
These security tasks are discussed in Application-Specifc Message Protection on page 66. A
sample application using message security is discussed in Understanding and Running the
Sample Application on page 69.
SystemAdministrator Responsibilities
The systemadministrator is responsible for the following:
Confguring message security providers on the GlassFish Server.
Managing user databases.
Managing keystore and truststore fles.
Installing the sample. This is only done if the xms sample application is used to demonstrate
the use of message layer web services security.
Asystemadministrator uses the Administration Console to manage server security settings and
uses a command line tool to manage certifcate databases. Certifcates and private keys are
stored in key stores and are managed with keytool. If Network Security Services (NSS) is
installed, certifcates and private keys are stored in an NSS database, where they are managed
using certutil. Systemadministrator tasks are discussed in the Oracle GlassFish Server 3.1
Security Guide.
Application-Specifc Message Protection
When the GlassFish Server provided confguration is insufcient for your security needs, and
you want to override the default protection, you can apply application-specifc message security
to a web service.
Application-specifc security is implemented by adding the message security binding to the web
service endpoint, whether it is an EJB or servlet web service endpoint. Modify GlassFish Server
XML fles to add the message binding information.
Message security can also be specifed using a WSITsecurity policy in the WSDL fle. For
details, see the WSITpage at https://wsit.dev.java.net/.
For more information about message security providers, see Message Security Providers on
page 63.
For more details on message security binding for EJB web services, servlet web services, and
clients, see the XML fle descriptions in Appendix C, Elements of the GlassFish Server
Deployment Descriptors, in Oracle GlassFish Server 3.1 Application Deployment Guide.
For glassfish-ejb-jar.xml, see The glassfsh-ejb-jar.xml File in Oracle GlassFish

Server 3.1 Application Deployment Guide.
For glassfish-web.xml, see The glassfsh-web.xml File in Oracle GlassFish Server 3.1
For glassfish-application-client.xml, see The glassfsh-application-client.xml fle in

Oracle GlassFish Server 3.1 Application Deployment Guide.
Using a Signature to Enable Message Protection for All Methods on page 67
Confguring Message Protection for a Specifc Method Based on Digital Signatures on

page 68
Usinga Signature toEnable Message Protectionfor All Methods
To enable message protection for all methods using digital signature, update the
message-security-binding element for the EJB web service endpoint in the applications
glassfish-ejb-jar.xml fle. In this fle, add request-protection and response-protection
elements, which are analogous to the request-policy and response-policy elements
discussed in the Oracle GlassFish Server 3.1 Security Guide. To apply the same protection
mechanisms for all methods, leave the method-name element blank. Confguring Message
Protection for a Specifc Method Based on Digital Signatures on page 68 discusses listing
specifc methods or using wildcard characters.
This section uses the sample application discussed in Understanding and Running the Sample
Application on page 69 to apply application-level message security to showonly the
diferences necessary for protecting web services using various mechanisms.
ToEnable Message Protectionfor All Methods UsingDigital Signature

Ina text editor, openthe applications glassfish-ejb-jar.xml fle.
For the xms example, this fle is located in the directory app-dir/xms-ejb/src/conf, where
app-dir is defned in To Set Up the Sample Application on page 70.
1
Modify the glassfish-ejb-jar.xml fle by addingthe message-security-binding element as
shown:
<glassfish-ejb-jar>
<enterprise-beans>
<unique-id>1</unique-id>
<ejb>
<ejb-name>HelloWorld</ejb-name>
<jndi-name>HelloWorld</jndi-name>
<webservice-endpoint>
<port-component-name>HelloIF</port-component-name>
<endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
<message-security-binding auth-layer="SOAP">
<message-security>
<request-protection auth-source="content" />
<response-protection auth-source="content"/>
</message-security>
</message-security-binding>
</webservice-endpoint>
</ejb>
</enterprise-beans>
</glassfish-ejb-jar>
Compile, deploy, andrunthe applicationas describedinToRunthe Sample Applicationon
page 71.
ConfguringMessage Protectionfor a Specifc MethodBasedonDigital
Signatures
To enable message protection for a specifc method, or for a set of methods that can be
identifed using a wildcard value, followthese steps. As in the example discussed in Using a
Signature to Enable Message Protection for All Methods on page 67, to enable message
protection for a specifc method, update the message-security-binding element for the EJB
web service endpoint in the applications glassfish-ejb-jar.xml fle. To this fle, add
request-protection and response-protection elements, which are analogous to the
request-policy and response-policy elements discussed in the Oracle GlassFish Server 3.1
Security Guide. The administration guide includes a table listing the set and order of security
operations for diferent request and response policy confgurations.
This section uses the sample application discussed in Understanding and Running the Sample
Application on page 69 to apply application-level message security to showonly the
diferences necessary for protecting web services using various mechanisms.
ToEnable Message Protectionfor a Particular Methodor Set of

Methods UsingDigital Signature
Ina text editor, openthe applications glassfish-ejb-jar.xml fle.
For the xms example, this fle is located in the directory app-dir/xms-ejb/src/conf, where
app-dir is defned in To Set Up the Sample Application on page 70.
2
3
1
Modify the glassfish-ejb-jar.xml fle by addingthe message-security-binding element as
shown:
<glassfish-ejb-jar>
<enterprise-beans>
<ejb>
<ejb-name>HelloWorld</ejb-name>
<jndi-name>HelloWorld</jndi-name>
<webservice-endpoint>
<port-component-name>HelloIF</port-component-name>
<endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
<message-security-binding auth-layer="SOAP">
<message-security>
<message>
<java-method>
<method-name>ejbCreate</method-name>
</java-method>
</message>
<message>
<java-method>
<method-name>sayHello</method-name>
</java-method>
</message>
<request-protection auth-source="content" />
<response-protection auth-source="content"/>
</message-security>
</message-security-binding>
</webservice-endpoint>
</ejb>
</enterprise-beans>
Compile, deploy, andrunthe applicationas describedinToRunthe Sample Applicationon
page 71.
UnderstandingandRunningthe Sample Application
This section discusses the WSS sample application. This sample application is installed on your
systemonly if you installed the J2EE 1.4 samples. If you have not installed these samples, see
To Set Up the Sample Application on page 70.
The objective of this sample application is to demonstrate howa web service can be secured
with WSS. The web service in the xms example is a simple web service implemented using a Java
EE EJB endpoint and a web service endpoint implemented using a servlet. In this example, a
service endpoint interface is defned with one operation, sayHello, which takes a string then
sends a response with Hello prefxed to the given string. You can viewthe WSDL fle for the
service endpoint interface at app-dir/xms-ejb/src/conf/HelloWorld.wsdl, where app-dir is
defned in To Set Up the Sample Application on page 70.
2
3
In this application, the client looks up the service using the JNDI name
java:comp/env/service/HelloWorld and gets the port information using a static stub to
invoke the operation using a given name. For the name Duke, the client gets the response Hello
Duke!
This example shows howto use message security for web services at the GlassFish Server level.
For information about using message security at the application level, see Application-Specifc
Message Protection on page 66. The WSS message security mechanisms implement
message-level authentication (for example, XML digital signature and encryption) of SOAP
web services invocations using the X.509 and username/password profles of the OASIS
WS-Security standard, which can be viewed fromthe following URL: http://
docs.oasis-open.org/
wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.
To Set Up the Sample Application on page 70
To Run the Sample Application on page 71
ToSet Upthe Sample Application

To have access to this sample application, you must have previously installed the J2EE 1.4
samples. If the samples are not installed, followthe steps in the following section.
After you followthese steps, the sample application is located in the directory
as-install/j2ee14-samples/samples/webservices/security/ejb/apps/xms/ or in a
directory of your choice. For easy reference throughout the rest of this section, this directory is
referred to as simply app-dir.
Gotothe J2EE 1.4 downloadURL (http://www.oracle.com/technetwork/java/javaee/
download-141771.html) inyour browser.
Click onthe Downloadbuttonfor the Samples Bundle.
Click onAccept License Agreement.
Click onthe J2EE SDKSamples link.
Choose a locationfor the j2eesdk-1_4_03-samples.zip fle.
Saving the fle to as-install is recommended.
Unzipthe fle.
Unzipping to the as-install/j2ee14samples directory is recommended. For example, you can
use the following command.
unzip j2eesdk-1_4_03-samples.zip -d j2ee14-samples
BeforeYouBegin
1
2
3
4
5
6
ToRunthe Sample Application

Make sure that the GlassFishServer is running.
Message security providers are set up when the Ant targets are run, so you do not need to
confgure these on the GlassFish Server prior to running this example.
If youare not runningHTTPonthe default port of 8080, change theWSDL fle for the example to
refect the change, andchange the common.properties fle torefect the change as well.
The WSDL fle for this example is located at app-dir/xms-ejb/src/conf/HelloWorld.wsdl.
The port number is in the following section:
<service name="HelloWorld">
<port name="HelloIFPort" binding="tns:HelloIFBinding">
<soap:address location="http://localhost:8080/service/HelloWorld"/>
</port>
</service>
Verify that the properties in the as-install/samples/common.properties fle are set properly for
your installation and environment. If you need a more detailed description of this fle, refer to
the Confguration section for the web services security applications at
as-install/j2ee14samples/samples/webservices/security/docs/common.html#Logging.
Change tothe app-dir directory.
Runthe followingAnt targets tocompile, deploy, andrunthe example application:
a. Tocompile samples:
ant
b. Todeploy samples:
ant deploy
c. Torunsamples:
ant run
If the sample has compiled and deployed properly, you see the following response on your
screen after the application has run:
run:[echo] Running the xms program:[exec] Established message level security :
Hello Duke!
Toundeploy the sample, runthe followingAnt target:
ant undeploy
All of the web services security examples use the same web service name (HelloWorld) and web
service ports. These examples showonly the diferences necessary for protecting web services
using various mechanisms. Make sure to undeploy an application when you have completed
1
2
3
4
5
running it. If you do not, you receive an Already in Use error and deployment failures when
you try to deploy another web services example application.
Programmatic Login
Programmatic login allows a deployed Java EE application or module to invoke a login method.
If the login is successful, a SecurityContext is established as if the client had authenticated
using any of the conventional Java EE mechanisms. Programmatic login is supported for servlet
and EJB components on the server side, and for stand-alone or application clients on the client
side. Programmatic login is useful for an application having special needs that cannot be
accommodated by any of the Java EE standard authentication mechanisms.
Note Programmatic login is specifc to the GlassFish Server and not portable to other
application servers.
Programmatic Login Precautions on page 72
Granting Programmatic Login Permission on page 73
The ProgrammaticLogin Class on page 73

Programmatic LoginPrecautions
The GlassFish Server is not involved in howthe login information (user, password) is obtained
by the deployed application. Programmatic login places the burden on the application
developer with respect to assuring that the resulting systemmeets security requirements. If the
application code reads the authentication information across the network, the application
determines whether to trust the user.
Programmatic login allows the application developer to bypass the GlassFish Server-supported
authentication mechanisms and feed authentication data directly to the security service. While
fexible, this capability should not be used without some understanding of security issues.
Since this mechanismbypasses the container-managed authentication process and sequence,
the application developer must be very careful in making sure that authentication is established
before accessing any restricted resources or methods. It is also the application developers
responsibility to verify the status of the login attempt and to alter the behavior of the application
accordingly.
The programmatic login state does not necessarily persist in sessions or participate in single
sign-on.
Programmatic Login
Lazy authentication is not supported for programmatic login. If an access check is reached and
the deployed application has not properly authenticated using the programmatic login method,
access is denied immediately and the application might fail if not coded to account for this
occurrence. One way to account for this occurrence is to catch the access control or security
exception, performa programmatic login, and repeat the request.
GrantingProgrammatic LoginPermission
The ProgrammaticLoginPermission permission is required to invoke the programmatic login
mechanismfor an application if the security manager is enabled. For information about the
security manager, see The server.policy File on page 58. This permission is not granted by
default to deployed applications because this is not a standard Java EE mechanism.
To grant the required permission to the application, add the following to the
domain-dir/config/server.policy fle:
grant codeBase "file:jar-fle-path" {
permission com.sun.appserv.security.ProgrammaticLoginPermission
"login";
};
The jar-fle-path is the path to the applications JARfle.
The ProgrammaticLogin Class
The com.sun.appserv.security.ProgrammaticLogin class enables a user to performlogin
programmatically.
For Javadoc tool pages relevant to programmatic login, go to http://glassfish.java.net/
nonav/docs/v3/api/ and click on the com.sun.appserv.security package.
The ProgrammaticLogin class has four login methods, two for servlets or JSP fles and two for
EJB components.
The login methods for servlets or JSP fles have the following signatures:
public java.lang.Boolean login(String user, String password,
javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
String realm, javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response, boolean errors)
throws java.lang.Exception
The login methods for EJB components have the following signatures:
public java.lang.Boolean login(String user, String password)
Programmatic Login
String realm, boolean errors) throws java.lang.Exception
All of these login methods accomplish the following:
Performthe authentication
Return true if login succeeded, false if login failed

The login occurs on the realmspecifed unless it is null, in which case the domains default
realmis used. The methods with no realmparameter use the domains default realm.
If the errors fag is set to true, any exceptions encountered during the login are propagated to
the caller. If set to false, exceptions are thrown.
On the client side, realmand errors parameters are ignored and the actual login does not occur
until a resource requiring a login is accessed. Ajava.rmi.AccessException with COBRA
NO_PERMISSION occurs if the actual login fails.
The logout methods for servlets or JSP fles have the following signatures:
public java.lang.Boolean logout(HttpServletRequest request,
HttpServletResponse response)
public java.lang.Boolean logout(HttpServletRequest request,
HttpServletResponse response, boolean errors)
The logout methods for EJB components have the following signatures:
public java.lang.Boolean logout()
public java.lang.Boolean logout(boolean errors)
All of these logout methods return true if logout succeeded, false if logout failed.
If the errors fag is set to true, any exceptions encountered during the logout are propagated to
the caller. If set to false, exceptions are thrown.
User Authenticationfor Single Sign-on
The single sign-on feature of the GlassFish Server allows multiple web applications deployed to
the same virtual server to share the user authentication state. With single sign-on enabled, users
who log in to one web application become implicitly logged into other web applications on the
same virtual server that require the same authentication information. Otherwise, users would
have to log in separately to each web application whose protected resources they tried to access.
Asample application using the single sign-on scenario could be a consolidated airline booking
service that searches all airlines and provides links to diferent airline web sites. After the user
User Authentication for Single Sign-on
signs on to the consolidated booking service, the user information can be used by each
individual airline site without requiring another sign-on.
Single sign-on operates according to the following rules:
Single sign-on applies to web applications confgured for the same realmand virtual server.
The realmis defned by the realm-name element in the web.xml fle. For information about
virtual servers, see Chapter 14, Administering Internet Connectivity, in Oracle GlassFish
Server 3.1 Administration Guide.
As long as users access only unprotected resources in any of the web applications on a
virtual server, they are not challenged to authenticate themselves.
As soon as a user accesses a protected resource in any web application associated with a
virtual server, the user is challenged to authenticate himself or herself, using the login
method defned for the web application currently being accessed.
After authentication, the roles associated with this user are used for access control decisions
across all associated web applications, without challenging the user to authenticate to each
application individually.
When the user logs out of one web application (for example, by invalidating the
corresponding session), the users sessions in all web applications are invalidated. Any
subsequent attempt to access a protected resource in any application requires the user to
authenticate again.
The single sign-on feature utilizes HTTP cookies to transmit a token that associates each
request with the saved user identity, so it can only be used in client environments that support
cookies.
To confgure single sign-on, set the following virtual server properties:
sso-enabled - If false, single sign-on is disabled for this virtual server, and users must
authenticate separately to every application on the virtual server. The default is false.
sso-max-inactive-seconds - Specifes the time after which a users single sign-on record
becomes eligible for purging if no client activity is received. Since single sign-on applies
across several applications on the same virtual server, access to any of the applications keeps
the single sign-on record active. The default value is 5 minutes (300 seconds). Higher values
provide longer single sign-on persistence for the users at the expense of more memory use
on the server.
sso-reap-interval-seconds - Specifes the interval between purges of expired single

sign-on records. The default value is 60.
Here are example asadmin set commands with default values:
asadmin set server-config.http-service.virtual-server.vsrv1.property.sso-enabled="true"
asadmin set server-config.http-service.virtual-server.vsrv1.property.sso-max-inactive-seconds="300"
asadmin set server-config.http-service.virtual-server.vsrv1.property.sso-reap-interval-seconds="60"
User Authentication for Single Sign-on
AddingAuthenticationMechanisms tothe Servlet Container
You can use JSR196 in the web tier to facilitate the injection of pluggable authentication
modules within the servlet constraint processing engine. The GlassFish Server includes
implementations of a number of HTTP layer authentication mechanisms such as basic, form,
and digest authentication. You can add alternative implementations of the included
mechanisms or implementations of newmechanisms such as HTTP Negotiate/SPNEGO,
OpenID, or CAS.
The GlassFish Server and JSR196 on page 76
Writing a Server Authentication Module on page 77
Sample Server Authentication Module on page 78
Compiling and Installing a Server Authentication Module on page 82
Confguring a Server Authentication Module on page 82
Binding a Server Authentication Module to Your Application on page 83

The GlassFishServer andJSR196
The GlassFish Server implements the Servlet Container Profle of JSR196, Java Authentication
Service Provider Interface for Containers. JSR196 defnes a standard service provider interface
(SPI) that extends the concepts of the Java Authentication and Authorization Service (JAAS) to
enable pluggability of message authentication modules in message processing runtimes. The
JSR196 standard defnes profles that establish contracts for the use of the SPI in specifc
contexts. The Servlet Container Profle of JSR196 defnes the use of the SPI by a Servlet
container such that:
The resulting container can be confgured with newauthentication mechanisms.
The container employs the confgured mechanisms in its enforcement of the declarative
servlet security model (declared in a web.xml fle using security-constraint elements).
The JSR196 specifcation defnes a simple message processing model composed of four
interaction points:
1. secureRequest on the client
2. validateRequest on the server
3. secureResponse on the server
4. validateResponse on the client
Adding Authentication Mechanisms to the Servlet Container
Amessage processing runtime uses the SPI at these interaction points to delegate the
corresponding message security processing to authentication providers, also called
authentication modules, integrated into the runtime by way of the SPI.
Acompatible server-side message processing runtime, such as the GlassFish Server servlet
container, supports the validateRequest and secureResponse interaction points of the
message processing model. The servlet container uses the SPI at these interaction points to
delegate the corresponding message security processing to a server authentication module
(SAM), integrated by the SPI into the container.
Writinga Server AuthenticationModule
Akey step in adding an authentication mechanismto a compatible server-side message
processing runtime such as the GlassFish Server servlet container is acquiring a SAMthat
implements the desired authentication mechanism. One way to do that is to write the SAM
yourself.
ASAMimplements the javax.security.auth.message.module.ServerAuthModule interface as
defned by JSR196. ASAMis invoked indirectly by the message processing runtime at the
validateRequest and secureResponse interaction points. ASAMmust implement the fve
methods of the ServerAuthModule interface:
getSupportedMessageTypes An array of Class objects where each element defnes a

message type supported by the SAM. For a SAMto be compatible with the Servlet Container
Profle, the returned array must include the HttpServletRequest.class and
HttpServletResponse.class objects.
initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy,

CallbackHandler Map options) The container calls this method to provide the SAM
with confguration values and with a CallbackHandler. The confguration values are
returned in the policy arguments and in the options Map. The SAMuses CallbackHandler
to access services, such as password validation, provided by the container.
AuthStatus validateRequest(MessageInfo messageInfo, Subject clientSubject,

Subject serviceSubject) The container calls this method to process each received
HttpServletRequest. The request and its associated HttpServletResponse are passed by
the container to the SAMin the messageInfo argument. The SAMprocesses the request and
may establish the response to be returned by the container. The SAMuses the provided
Subject arguments to convey its authentication results. The SAMreturns diferent status
values to control the container's invocation processing. The status values and the
circumstances under which they are returned are as follows:
AuthStatus.SUCCESS is returned when the application request message is successfully

validated. The container responds to this status value by using the returned client
Subject to invoke the target of the request. When this value is returned, the SAM
(provided a customAuthConfigProvider is not being used) must use its
CallbackHandler to handle a CallerPrincipalCallback using the clientSubject as
an argument to the callback.
AuthStatus.SEND_CONTINUE indicates that message validation is incomplete and that

the SAMhas established a preliminary response as the response message in
messageInfo. The container responds to this status value by sending the response to the
client.
AuthStatus.SEND_FAILURE indicates that message validation failed and that the SAM
has established an appropriate failure response message in messageInfo. The container
responds to this status value by sending the response to the client.
AuthStatus.SEND_SUCCESS is not typically returned. This status value indicates the end
of a multi-message security dialog originating after the service interaction and during
the processing of the application response. The container responds to this status value by
sending the response to the client.
The validateRequest method may also throwan AuthException to indicate that the
message processing by the SAMfailed without establishing a failure response message in
messageInfo.
secureResponse(MessageInfo messageInfo, Subject serviceSubject) The

container calls this method before sending a response, resulting froman application
invocation, to the client. The response is passed to the SAMin the messageInfo argument.
In most cases, this method should just return the SEND_SUCCESS status.
cleanSubject(MessageInfo messageInfo, Subject subject) This method removes

the mechanism-specifc principals, credentials, or both fromthe subject. This method is not
currently called by the container. Alegitimate implementation could remove all the
principals fromthe argument subject.
See the Servlet Container Profle section in the JSR196 specifcation for additional background
and details.
Sample Server AuthenticationModule
The class MySam.java is a sample SAMimplementation. Notice that the sample implements the
fve methods of the ServerAuthModule interface. This SAMimplements an approximation of
HTTP basic authentication.
package tip.sam;
import java.io.IOException;
import java.util.Map;
import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import javax.security.auth.message.AuthException;
import javax.security.auth.message.AuthStatus;
import javax.security.auth.message.MessageInfo;
import javax.security.auth.message.MessagePolicy;
import javax.security.auth.message.callback.CallerPrincipalCallback;
import javax.security.auth.message.callback.GroupPrincipalCallback;
import javax.security.auth.message.callback.PasswordValidationCallback;
import javax.security.auth.message.module.ServerAuthModule;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.catalina.util.Base64;
public class MySam implements ServerAuthModule {
protected static final Class[]
supportedMessageTypes = new Class[]{
HttpServletRequest.class,
HttpServletResponse.class
};
private MessagePolicy requestPolicy;
private MessagePolicy responsePolicy;
private CallbackHandler handler;
private Map options;
private String realmName = null;
private String defaultGroup[] = null;
privte static final String REALM_PROPERTY_NAME =
"realm.name";
private static final String GROUP_PROPERTY_NAME =
"group.name";
private static final String BASIC = "Basic";
static final String AUTHORIZATION_HEADER =
"authorization";
static final String AUTHENTICATION_HEADER =
"WWW-Authenticate";
public void initialize(MessagePolicy reqPolicy,
MessagePolicy resPolicy,
CallbackHandler cBH, Map opts)
throws AuthException {
requestPolicy = reqPolicy;
responsePolicy = resPolicy;
handler = cBH;
options = opts;
if (options != null) {
realmName = (String)
options.get(REALM_PROPERTY_NAME);
if (options.containsKey(GROUP_PROPERTY_NAME)) {
defaultGroup = new String[]{(String)
options.get(GROUP_PROPERTY_NAME)};
}
}
}
public Class[] getSupportedMessageTypes() {
return supportedMessageTypes;
}
public AuthStatus validateRequest(
MessageInfo msgInfo, Subject client,
Subject server) throws AuthException {
try {
String username =
processAuthorizationToken(msgInfo, client);
if (username ==
null && requestPolicy.isMandatory()) {
return sendAuthenticateChallenge(msgInfo);
}
setAuthenticationResult(
username, client, msgInfo);
return AuthStatus.SUCCESS;
} catch (Exception e) {
AuthException ae = new AuthException();
ae.initCause(e);
throw ae;
}
}
private String processAuthorizationToken(
MessageInfo msgInfo, Subject s)
HttpServletRequest request =
(HttpServletRequest)
msgInfo.getRequestMessage();
String token =
request.getHeader(AUTHORIZATION_HEADER);
if (token != null && token.startsWith(BASIC + " ")) {
token = token.substring(6).trim();
// Decode and parse the authorization token
String decoded =
new String(Base64.decode(token.getBytes()));
int colon = decoded.indexOf(:);
if (colon <= 0 || colon == decoded.length() - 1) {
return (null);
}
String username = decoded.substring(0, colon);
// use the callback to ask the container to
// validate the password
PasswordValidationCallback pVC =
new PasswordValidationCallback(s, username,
decoded.substring(colon + 1).toCharArray());
try {
handler.handle(new Callback[]{pVC});
pVC.clearPassword();
} catch (Exception e) {
AuthException ae = new AuthException();
ae.initCause(e);
throw ae;
}
if (pVC.getResult()) {
return username;
}
}
return null;
}
private AuthStatus sendAuthenticateChallenge(
MessageInfo msgInfo) {
String realm = realmName;
// if the realm property is set use it,
// otherwise use the name of the server
// as the realm name.
if (realm == null) {
HttpServletRequest request =
(HttpServletRequest)
msgInfo.getRequestMessage();
realm = request.getServerName();
}
HttpServletResponse response =
(HttpServletResponse)
msgInfo.getResponseMessage();
String header = BASIC + " realm=\"" + realm + "\"";
response.setHeader(AUTHENTICATION_HEADER, header);
response.setStatus(
HttpServletResponse.SC_UNAUTHORIZED);
return AuthStatus.SEND_CONTINUE;
}
public AuthStatus secureResponse(
MessageInfo msgInfo, Subject service)
return AuthStatus.SEND_SUCCESS;
}
public void cleanSubject(MessageInfo msgInfo,
Subject subject)
if (subject != null) {
subject.getPrincipals().clear();
}
}
private static final String AUTH_TYPE_INFO_KEY =
"javax.servlet.http.authType";
// distinguish the caller principal
// and assign default groups
private void setAuthenticationResult(String name,
Subject s, MessageInfo m)
throws IOException,
UnsupportedCallbackException {
handler.handle(new Callback[]{
new CallerPrincipalCallback(s, name)
});
if (name != null) {
// add the default group if the property is set
if (defaultGroup != null) {
handler.handle(new Callback[]{
new GroupPrincipalCallback(s, defaultGroup)
});
}
m.getMap().put(AUTH_TYPE_INFO_KEY, ""MySAM");
}
}
}
Note that the initialize method looks for the group.name and realm.name properties. The
group.name property confgures the default group assigned as a result of any successful
authentication. The realm.name property defnes the realmvalue sent back to the browser in
the WWW-Authenticate challenge.
CompilingandInstallinga Server Authentication
Module
Before you can use the sample SAM, you need to compile, install, and confgure it. Then you
can bind it to an application.
To compile the SAM, include the SPI in your classpath. When the GlassFish Server is installed,
the JARfle containing the SPI, jmac-api.jar, is installed in the as-install/lib directory. After
you compile the SAM, install it by copying a JARfle containing the compiled SAMto the
as-install/lib directory.
Confguringa Server AuthenticationModule
You can confgure a SAMin one of these ways:
In the Administration Console, open the Security component under the relevant
confguration and go to the Message Security page. Set the following options:
Authentication Layer HttpServlet
Provider Type server or client-server
Provider IDSpecify a unique name for the SAM, for example MySAM
Class Name Specify the fully qualifed class name, for example tip.sam.MySam
Additional Property Name: group-name Value: user
Additional Property Name: realm-name Value: Sam

For details, click the Help button in the Administration Console.
Use the asadmin create-message-security-provider command to confgure a SAM. Set

the following options:
----layer HttpServlet
----providertype server or ----providertype client-server
----classname tip.sam.MySam
----property group-name=user:realm-name=Sam
Provider name operand Specify a unique name for the SAM, for example MySAM
Bindinga Server AuthenticationModule toYour
Application
After you install and confgure the SAM, you can bind it for use by the container on behalf of
one or more of your applications. You have two options in howyou bind the SAM, depending
on whether you are willing to repackage and redeploy your application:
If you are willing to repackage and redeploy, you can bind the SAMusing the
glassfish-web.xml fle. Set the value of the httpservlet-security-provider attribute of
the glassfish-web-app element to the SAM's confgured provider ID, for example, MySAM.
For more information about the glassfish-web.xml fle, see the Oracle GlassFish Server 3.1
Application Deployment Guide. This option leverages the native AuthConfigProvider
implementation that ships with the GlassFish Server.
Another approach is to develop your own AuthConfigProvider and register it with the
GlassFish Server AuthConfigFactory for use on behalf of your applications. For example, a
simple AuthConfigProvider can obtain, through its initialization properties, the classname
of a SAMto confgure on behalf of the applications for which the provider is registered. You
can fnd a description of the functionality of an AuthConfigProvider and of the registration
facilities provided by an AuthConfigFactory in the JSR196 specifcation.
84
DevelopingWeb Services
This chapter describes Oracle GlassFish Server support for web services. Java API for
XML-Based Web Services (JAX-WS) version 2.2 is supported. Java API for XML-Based Remote
Procedure Calls (JAX-RPC) version 1.1 is supported for backward compatibility.
Creating Portable Web Service Artifacts on page 86
Deploying a Web Service on page 86
The Web Service URI, WSDL File, and Test Page on page 87
GlassFish Java EE Service Engine on page 88

Note If you installed the Web Profle, web services are not supported unless the optional Metro
Web Services Stack add-on component is downloaded fromthe Update Tool. Without the
Metro add-on component, a servlet or EJB component cannot be a web service endpoint, and
the glassfish-web.xml and glassfish-ejb-jar.xml elements related to web services are
ignored. For information about the Update Tool, see Update Tool in Oracle GlassFish
Part III, Web Services, in The Java EE 6 Tutorial shows howto deploy simple web services to
the GlassFish Server.
For additional information about JAX-WS and web services, see Java Specifcation Request
(JSR) 224 (http://jcp.org/aboutJava/communityprocess/pfd/jsr224/index.html) and
JSR109 (http://jcp.org/en/jsr/detail?id=109).
For information about web services security, see Confguring Message Security for Web
Services on page 62.
The Fast Infoset standard specifes a binary format based on the XML Information Set. This
format is an efcient alternative to XML. For information about using Fast Infoset, see the
following links:
5
C H A P T E R 5
85
Java Web Services Developer Pack 1.6 Release Notes (http://download.oracle.com/

docs/cd/E17802_01/webservices/webservices/docs/1.6/ReleaseNotes.html)
Fast Infoset in Java Web Services Developer Pack, Version 1.6 (http://
download.oracle.com/
docs/cd/E17802_01/webservices/webservices/docs/1.6/jaxrpc/fastinfoset/
manual.html)
Fast Infoset Project (https://fi.dev.java.net/)

CreatingPortableWebService Artifacts
For a tutorial that shows howto use the wsimport and wsgen commands, see Part III, Web
Services, in The Java EE 6 Tutorial. For reference information on these commands, see the
Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
DeployingaWebService
You deploy a web service endpoint to the GlassFish Server just as you would any servlet,
stateless session bean (SLSB), or application.
Note For complex services with dependent classes, user specifed WSDL fles, or other
advanced features, autodeployment of an annotated fle is not sufcient.
The GlassFish Server deployment descriptor fles glassfish-web.xml and
glassfish-ejb-jar.xml provide optional web service enhancements in the
webservice-endpoint and webservice-description elements, including a
debugging-enabled subelement that enables the creation of a test page. The test page feature is
enabled by default and described in The Web Service URI, WSDL File, and Test Page on
page 87.
For more information about deployment, autodeployment, and deployment descriptors, see
the Oracle GlassFish Server 3.1 Application Deployment Guide. For more information about the
asadmin deploy command, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
Creating PortableWeb Service Artifacts
TheWebService URI, WSDL File, andTest Page
Clients can run a deployed web service by accessing its service endpoint address URI, which has
the following format:
http://host:port/context-root/servlet-mapping-url-pattern
The context-root is defned in the application.xml or web.xml fle, and can be overridden in
the glassfish-application.xml or glassfish-web.xml fle. The servlet-mapping-url-pattern
is defned in the web.xml fle.
In the following example, the context-root is my-ws and the servlet-mapping-url-pattern is
/simple:
http://localhost:8080/my-ws/simple
You can viewthe WSDL fle of the deployed service in a browser by adding ?WSDL to the end of
the URI. For example:
http://localhost:8080/my-ws/simple?WSDL
For debugging, you can run a test page for the deployed service in a browser by adding ?Tester
to the end of the URL. For example:
http://localhost:8080/my-ws/simple?Tester
You can also test a service using the Administration Console. Open the Web Services
component, select the web service in the listing on the General tab, and select Test. For details,
click the Help button in the Administration Console.
Note The test page works only for WS-I compliant web services. This means that the tester
servlet does not work for services with WSDL fles that use RPC/encoded binding.
Generation of the test page is enabled by default. You can disable the test page for a web service
by setting the value of the debugging-enabled element in the glassfish-web.xml and
glassfish-ejb-jar.xml deployment descriptor to false. For more information, see the
TheWeb Service URI, WSDL File, andTest Page
Chapter 5 DevelopingWeb Services 87
GlassFishJava EE Service Engine
GlassFish Server 3.1 provides the GlassFish Java EE Service Engine, a JSR208 compliant Java
Business Integration (JBI) runtime component that connects Java EE web services to JBI
components. The Java EE Service Engine is installed as an add-on component using the Update
Tool. Look for the JBI component named Java EE Service Engine. AJBI runtime is not installed
with or integrated into GlassFish Server 3.1 and must be obtained separately. For more
information about using the Update Tool to obtain the Java EE Service Engine and other
add-on components, see Update Tool in Oracle GlassFish Server 3.1 Administration Guide.
The Java EE Service Engine acts as a bridge between the Java EE and JBI runtime environments
for web service providers and web service consumers. The Java EE Service Engine provides
better performance than a SOAP over HTTP binding component due to in-process
communication between components and additional protocols provided by JBI binding
components such as JMS, SMTP, and File.
The JSR208 (http://jcp.org/en/jsr/detail?id=208) specifcation allows transactions to be
propagated to other components using a message exchange property specifed in the
JTA_TRANSACTION_PROPERTY_NAME feld. The Java EE Service Engine uses this property to set
and get a transaction object fromthe JBI message exchange. It then uses the transaction object
to take part in a transaction. This means a Java EE application or module can take part in a
transaction started by a JBI application. Conversely, a JBI application can take part in a
transaction started by a Java EE application or module.
Similarly, the JSR208 specifcation allows a security subject to be propagated as a message
exchange property named javax.jbi.security.subject. Thus a security subject can be
propagated froma Java EE application or module to a JBI application or the reverse.
To deploy a Java EE application or module as a JBI service unit, use the asadmin deploy
command, or autodeployment. For more information about the asadmin deploy command,
see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual. For more information about
autodeployment, see To Deploy an Application or Module Automatically in Oracle GlassFish
Usingthe jbi.xml File
Section 6.3.1 of the JSR208 specifcation describes the jbi.xml fle. This is a deployment
descriptor, located in the META-INF directory. To deploy a Java EE application or module as a
JBI service unit, you need only specify a small subset of elements in the jbi.xml fle. Here is an
example provider:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jbi version="1.0" xmlns="http://java.sun.com/xml/ns/jbi" xmlns:ns0="http://ejbws.jbi.misc/">
<services binding-component="false">
<provides endpoint-name="MiscPort" interface-name="ns0:Misc" service-name="ns0:MiscService"/>
GlassFish Java EE Service Engine
</services>
</jbi>
Here is an example consumer:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jbi version="1.0" xmlns="http://java.sun.com/xml/ns/jbi" xmlns:ns0="http://message.hello.jbi/">
<services binding-component="false">
<consumes endpoint-name="MsgPort" interface-name="ns0:Msg" service-name="ns0:MsgService"/>
</services>
</jbi>
The Java EE Service Engine enables the endpoints described in the provides section of the
jbi.xml fle in the JBI runtime. Similarly, the Java EE Service Engine routes invocations of the
endpoints described in the consumes section fromthe Java EE web service consumer to the JBI
runtime.
GlassFish Java EE Service Engine
Chapter 5 DevelopingWeb Services 89
90
Using the Java Persistence API
Oracle GlassFish Server support for the Java Persistence API includes all required features
described in the Java Persistence Specifcation, also known as JSR317 (http://jcp.org/en/
jsr/detail?id=317). The Java Persistence API can be used with non-EJB components outside
the EJB container.
The Java Persistence API provides an object/relational mapping facility to Java developers for
managing relational data in Java applications. For basic information about the Java Persistence
API, see Part VI, Persistence, in The Java EE 6 Tutorial.
This chapter contains GlassFish Server specifc information on using the Java Persistence API.
Specifying the Database on page 92
Additional Database Properties on page 94
Confguring the Cache on page 94
Setting the Logging Level on page 94
Using Lazy Loading on page 94
Primary Key Generation Defaults on page 95
Automatic Schema Generation on page 95
Query Hints on page 98
Changing the Persistence Provider on page 98
Restrictions and Optimizations on page 99

Note The default persistence provider in the GlassFish Server is based on the EclipseLink Java
Persistence API implementation. All confguration options in EclipseLink are available to
applications that use the GlassFish Server's default persistence provider.
6
C H A P T E R 6
91
jsr/detail?id=318).
Specifyingthe Database
The GlassFish Server uses the bundled Java DB (Derby) database by default, named
jdbc/__default. If the transaction-type element is omitted or specifed as JTA and both the
jta-data-source and non-jta-data-source elements are omitted in the persistence.xml
fle, Java DB is used as a JTAdata source. If transaction-type is specifed as RESOURCE_LOCAL
and both jta-data-source and non-jta-data-source are omitted, Java DB is used as a
non-JTAdata source.
To use a non-default database, either specify a value for the jta-data-source element, or set
the transaction-type element to RESOURCE_LOCAL and specify a value for the
non-jta-data-source element.
If you are using the default persistence provider, the provider attempts to automatically detect
the database type based on the connection metadata. This database type is used to issue SQL
statements specifc to the detected database type's dialect. You can specify the optional
eclipselink.target-database property to guarantee that the database type is correct. For
example:
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name ="em1">
<jta-data-source>jdbc/MyDB2DB</jta-data-source>
<properties>
<property name="eclipselink.target-database"
value="DB2"/>
</properties>
</persistence-unit>
</persistence>
The following eclipselink.target-database property values are allowed. Supported
platforms have been tested with the GlassFish Server and are found to be Java EE compatible.
//Supported platforms
JavaDB
Derby
Oracle
MySQL4
//Others available
SQLServer
DB2
Sybase
Specifying the Database
PostgreSQL
Informix
TimesTen
Attunity
HSQL
SQLAnyWhere
DBase
DB2Mainframe
Cloudscape
PointBase
For more information about the eclipselink.target-database property, see Using
EclipseLink JPAExtensions for Session, Target Database and Target Application Server.
To use the Java Persistence API outside the EJB container (in Java SE mode), do not specify the
jta-data-source or non-jta-data-source elements. Instead, specify the provider element
and any additional properties required by the JDBCdriver or the database. For example:
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<class>ejb3.war.servlet.JpaBean</class>
<properties>
<property name="eclipselink.target-database"
value="Derby"/>

<property name="eclipselink.jdbc.driver" value="org.apache.derby.jdbc.ClientDriver"/>
<property name="eclipselink.jdbc.url"
value="jdbc:derby://localhost:1527/testdb;retrieveMessagesFromServerOnGetMessage=true;create=true;"/>
<property name="eclipselink.jdbc.user" value="APP"/>
<property name="eclipselink.jdbc.password" value="APP"/>
</properties>
</persistence-unit>
</persistence>
For more information about eclipselink properties, see Additional Database Properties on
page 94.
For a list of the JDBCdrivers currently supported by the GlassFish Server, see the Oracle
GlassFish Server 3.1-3.1.1 Release Notes. For confgurations of supported and other drivers, see
Confguration Specifcs for JDBCDrivers in Oracle GlassFish Server 3.1 Administration
Guide.
To change the persistence provider, see Changing the Persistence Provider on page 98.
Specifying the Database
Chapter 6 Using the Java Persistence API 93
Additional Database Properties
If you are using the default persistence provider, you can specify in the persistence.xml fle
the database properties listed at Howto Use EclipseLink JPAExtensions for JDBCConnection
Communication.
For schema generation properties, see Generation Options on page 96. For query hints, see
Query Hints on page 98.
Confguringthe Cache
If you are using the default persistence provider, you can confgure whether caching occurs, the
type of caching, the size of the cache, and whether client sessions share the cache. Caching
properties for the default persistence provider are described in detail at Using EclipseLink JPA
Extensions for Entity Caching.
Settingthe LoggingLevel
One of the default persistence provider's properties that you can set in the persistence.xml fle
is eclipselink.logging.level. For example, setting the logging level to FINE or higher logs all
SQL statements. For details about this property, see Using EclipseLink JPAExtensions for
Logging.
You can also set the EclipseLink logging level globally in the GlassFish Server by setting a JVM
option using the asadmin create-jvm-options command. For example:
asadmin create-jvm-options -Declipselink.logging.level=FINE
Setting the logging level to OFF disables EclipseLink logging. Alogging level set in the
persistence.xml fle takes precedence over the global logging level.
UsingLazy Loading
OneToMany and ManyToMany mappings are loaded lazily by default in compliance with the Java
Persistence Specifcation. OneToOne and ManyToOne mappings are loaded eagerly by default.
For basic information about lazy loading, see What You May Need to KnowAbout EclipseLink
JPALazy Loading.
Additional Database Properties
Primary Key GenerationDefaults
In the descriptions of the @GeneratedValue, @SequenceGenerator, and @TableGenerator
annotations in the Java Persistence Specifcation, certain defaults are noted as specifc to the
persistence provider. The default persistence provider's primary key generation defaults are
listed here.
@GeneratedValue defaults are as follows:
Using strategy=AUTO (or no strategy) creates a @TableGenerator named SEQ_GEN with

default settings. Specifying a generator has no efect.
Using strategy=TABLE without specifying a generator creates a @TableGenerator named

SEQ_GEN_TABLE with default settings. Specifying a generator but no @TableGenerator
creates and names a @TableGenerator with default settings.
Using strategy=IDENTITY or strategy=SEQUENCE produces the same results, which are

database-specifc.
For Oracle databases, not specifying a generator creates a @SequenceGenerator named

SEQ_GEN_SEQUENCE with default settings. Specifying a generator but no
@SequenceGenerator creates and names a @SequenceGenerator with default settings.
For PostgreSQL databases, a SERIAL column named entity-table_pk-column_SEQ is

created.
For MySQL databases, an AUTO_INCREMENT column is created.
For other supported databases, an IDENTITY column is created.

The @SequenceGenerator annotation has one default specifc to the default provider. The
default sequenceName is the specifed name.
@TableGenerator defaults are as follows:
The default table is SEQUENCE.
The default pkColumnName is SEQ_NAME.
The default valueColumnName is SEQ_COUNT.
The default pkColumnValue is the specifed name, or the default name if no name is specifed.
Automatic Schema Generation
The automatic schema generation feature of the GlassFish Server defnes database tables based
on the felds or properties in entities and the relationships between the felds or properties. This
insulates developers frommany of the database related aspects of development, allowing them
to focus on entity development. The resulting schema is usable as-is or can be given to a
database administrator for tuning with respect to performance, security, and so on.
Annotations on page 96
Generation Options on page 96

Note Automatic schema generation is supported on an all-or-none basis: it expects that no
tables exist in the database before it is executed. It is not intended to be used as a tool to generate
extra tables or constraints.
Deployment won't fail if all tables are not created, and undeployment won't fail if not all tables
are dropped. Instead, an error is written to the server log. This is done to allowyou to
investigate the problemand fx it manually. You should not rely on the partially created
database schema to be correct for running the application.
Annotations
The following annotations are used in automatic schema generation: @AssociationOverride,
@AssociationOverrides, @AttributeOverride, @AttributeOverrides, @Column,
@DiscriminatorColumn, @DiscriminatorValue, @Embedded, @EmbeddedId, @GeneratedValue,
@Id, @IdClass, @JoinColumn, @JoinColumns, @JoinTable, @Lob, @ManyToMany, @ManyToOne,
@OneToMany, @OneToOne, @PrimaryKeyJoinColumn, @PrimaryKeyJoinColumns,
@SecondaryTable, @SecondaryTables, @SequenceGenerator, @Table, @TableGenerator,
@UniqueConstraint, and @Version. For information about these annotations, see the Java
Persistence Specifcation.
For @Column annotations, the insertable and updatable elements are not used in automatic
schema generation.
For @OneToMany and @ManyToOne annotations, no ForeignKeyConstraint is created in the
resulting DDL fles.
GenerationOptions
Schema generation properties or asadmin command line options can control automatic schema
generation by the following:
Creating tables during deployment
Dropping tables during undeployment
Dropping and creating tables during redeployment
Generating the DDL fles

Note Before using these options, make sure you have a properly confgured database. See
Specifying the Database on page 92.
Optional schema generation properties control the automatic creation of database tables. You
can specify themin the persistence.xml fle. For more information, see Using EclipseLink JPA
Extensions for Schema Generation.
The following options of the asadmin deploy or asadmin deploydir command control the
automatic creation of database tables at deployment.
TABLE 61 The asadmin deploy and asadmin deploydir Generation Options
Option Default Description
--createtables none If true, causes database tables to be created for entities that need them. No unique
constraints are created. If false, does not create tables. If not specifed, the value of
the eclipselink.ddl-generation property in persistence.xml is used.
--dropandcreatetables none If true, and if tables were automatically created when this application was last
deployed, tables fromthe earlier deployment are dropped and fresh ones are
created.
If true, and if tables were not automatically created when this application was last
deployed, no attempt is made to drop any tables. If tables with the same names as
those that would have been automatically created are found, the deployment
proceeds, but a warning is thrown to indicate that tables could not be created.
If false, the eclipselink.ddl-generation property setting in persistence.xml
is overridden.
The following options of the asadmin undeploy command control the automatic removal of
database tables at undeployment.
TABLE 62 The asadmin undeploy Generation Options
--droptables none If true, causes database tables that were automatically created when the entities were last
deployed to be dropped when the entities are undeployed. If false, does not drop tables.
If not specifed, tables are dropped only if the eclipselink.ddl-generation property setting in
persistence.xml is drop-and-create-tables.
For more information about the asadmin deploy, asadmin deploydir, and asadmin undeploy
When asadmin deployment options and persistence.xml options are both specifed, the
asadmin deployment options take precedence.
Query Hints
Query hints are additional, implementation-specifc confguration settings. You can use hints
in your queries in the following format:
setHint("hint-name", hint-value)
For example:
Customer customer = (Customer)entityMgr.
createNamedQuery("findCustomerBySSN").
setParameter("SSN", "123-12-1234").
setHint("eclipselink.refresh", true).
getSingleResult();
For more information about the query hints available with the default provider, see Howto Use
EclipseLink JPAQuery Hints.
Changingthe Persistence Provider
Note The previous sections in this chapter apply only to the default persistence provider. If you
change the provider for a module or application, the provider-specifc database properties,
query hints, and schema generation features described in this chapter do not apply.
You can change the persistence provider for an application in the manner described in the Java
Persistence API Specifcation.
First, install the provider. Copy the provider JARfles to the domain-dir/lib directory, and
restart the GlassFish Server. For more information about the domain-dir/lib directory, see
Using the Common Class Loader on page 34. The newpersistence provider is nowavailable
to all modules and applications deployed on servers that share the same confguration.
However, the default provider remains the same.
In your persistence unit, specify the provider and any properties the provider requires in the
persistence.xml fle. For example:
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<provider>com.company22.persistence.PersistenceProviderImpl</provider>
<properties>
<property name="company22.database.name" value="MyDB"/>
</properties>
</persistence-unit>
</persistence>
Query Hints
To migrate fromOracle TopLink to EclipseLink, see Migrating fromOracle TopLink to
EclipseLink (http://wiki.eclipse.org/EclipseLink/Examples/
MigratingFromOracleTopLink).
Restrictions andOptimizations
This section discusses restrictions and performance optimizations that afect using the Java
Persistence API.
Oracle Database Enhancements on page 99
Extended Persistence Context on page 99
Using @OrderBy with a Shared Session Cache on page 100
Using BLOB or CLOB Types with the Inet Oraxo JDBCDriver on page 100
Database Case Sensitivity on page 100
Sybase Finder Limitation on page 101
MySQL Database Restrictions on page 102

Oracle Database Enhancements
EclipseLink features a number of enhancements for use with Oracle databases. These
enhancements require classes fromthe Oracle JDBCdriver JARfles to be visible to EclipseLink
at runtime. If you place the JDBCdriver JARfles in domain-dir/lib, the classes are not visible
to GlassFish Server components, including EclipseLink.
If you are using an Oracle database, put JDBCdriver JARfles in domain-dir/lib/ext instead.
This ensures that the JDBCdriver classes are visible to EclipseLink.
If you do not want to take advantage of Oracle-specifc extensions fromEclipseLink or you
cannot put JDBCdriver JARfles in domain-dir/lib/ext, set the
eclipselink.target-database property to the value
org.eclipse.persistence.platform.database.OraclePlatform. For more information
about the eclipselink.target-database property, see Specifying the Database on page 92.
ExtendedPersistence Context
The Java Persistence API specifcation does not specify howthe container and persistence
provider should work together to serialize an extended persistence context. This also prevents
successful serialization of a reference to an extended persistence context in a stateful session
bean.
Even in a single-instance environment, if a stateful session bean is passivated, its extended
persistence context could be lost when the stateful session bean is activated.
Restrictions and Optimizations
Therefore, in GlassFish Server, a stateful session bean with an extended persistence context is
never passivated and cannot be failed over.
Using@OrderBy witha SharedSessionCache
Setting @OrderBy on a ManyToMany or OneToMany relationship feld in which a List represents
the Many side doesn't work if the session cache is shared. Use one of the following
workarounds:
Have the application maintain the order so the List is cached properly.
Refresh the session cache using EntityManager.refresh() if you don't want to maintain
the order during creation or modifcation of the List.
Disable session cache sharing in persistence.xml as follows:

<property name="eclipselink.cache.shared.default" value="false"/>
UsingBLOBor CLOBTypes withthe Inet OraxoJDBC
Driver
To use BLOB or CLOB data types larger than 4 KB for persistence using the Inet Oraxo JDBC
Driver for Oracle Databases, you must set the database's streamstolob property value to true.
Database Case Sensitivity
Mapping references to column or table names must be in accordance with the expected column
or table name case, and ensuring this is the programmer's responsibility. If column or table
names are not explicitly specifed for a feld or entity, the GlassFish Server uses upper case
column names by default, so any mapping references to the column or table names must be in
upper case. If column or table names are explicitly specifed, the case of all mapping references
to the column or table names must be in accordance with the case used in the specifed names.
The following are examples of howcase sensitivity afects mapping elements that refer to
columns or tables. Programmers must keep case sensitivity in mind when writing these
mappings.
Unique Constraints
If column names are not explicitly specifed on a feld, unique constraints and foreign key
mappings must be specifed using uppercase references. For example:
@Table(name="Department", uniqueConstraints={ @UniqueConstraint ( columnNames= { "DEPTNAME" } ) } )
The other way to handle this is by specifying explicit column names for each feld with the
required case. For example:
@Table(name="Department", uniqueConstraints={ @UniqueConstraint ( columnNames= { "deptName" } ) } )
public class Department{ @Column(name="deptName") private String deptName; }
Otherwise, the ALTER TABLE statement generated by the GlassFish Server uses the incorrect
case, and the creation of the unique constraint fails.
ForeignKey Mapping
Use @OneToMany(mappedBy="COMPANY") or specify an explicit column name for the Company
feld on the Many side of the relationship.
SQL Result Set Mapping
Use the following elements:
<sql-result-set-mapping name="SRSMName" >
<entity-result entity-class="entities.someEntity" />
<column-result name="UPPERCASECOLUMNNAME" />
</sql-result-set-mapping>
Or specify an explicit column name for the upperCaseColumnName feld.
NamedNative Queries andJDBCQueries
Column or table names specifed in SQL queries must be in accordance with the expected case.
For example, MySQL requires column names in the SELECT clause of JDBCqueries to be
uppercase, while PostgreSQL and Sybase require table names to be uppercase in all JDBC
queries.
PostgreSQL Case Sensitivity
PostgreSQL stores column and table names in lower case. JDBCqueries on PostgreSQL retrieve
column or table names in lowercase unless the names are quoted. For example:
use aliases Select m.ID AS \"ID\" from Department m
Use the backslash as an escape character in the class fle, but not in the persistence.xml fle.
Sybase Finder Limitation
If a fnder method with an input greater than 255 characters is executed and the primary key
column is mapped to a VARCHARcolumn, Sybase attempts to convert type VARCHARto type
TEXTand generates the following error:
com.sybase.jdbc2.jdbc.SybSQLException: Implicit conversion from datatype
TEXT to VARCHAR is not allowed. Use the CONVERT function to run this
query.
To avoid this error, make sure the fnder method input is less than 255 characters.
MySQL Database Restrictions
The following restrictions apply when you use a MySQL database with the GlassFish Server for
persistence.
MySQL treats int1 and int2 as reserved words. If you want to defne int1 and int2 as felds
in your table, use int1 and int2 feld names in your SQL fle.
When VARCHAR felds get truncated, a warning is displayed instead of an error. To get an
error message, start the MySQL database in strict SQL mode.
The order of felds in a foreign key index must match the order in the explicitly created
index on the primary table.
The CREATE TABLE syntax in the SQL fle must end with the following line.
) Engine=InnoDB;
InnoDB provides MySQL with a transaction-safe (ACIDcompliant) storage engine having
commit, rollback, and crash recovery capabilities.
For a FLOAT type feld, the correct precision must be defned. By default, MySQL uses four
bytes to store a FLOAT type that does not have an explicit precision defnition. For example,
this causes a number such as 12345.67890123 to be rounded of to 12345.7 during an
INSERT. To prevent this, specify FLOAT(10,2) in the DDL fle, which forces the database to
use an eight-byte double-precision column. For more information, see
http://dev.mysql.com/doc/mysql/en/numeric-types.html.
To use || as the string concatenation symbol, start the MySQL server with the
--sql-mode="PIPES_AS_CONCAT" option. For more information, see
http://dev.mysql.com/doc/refman/5.0/en/server-sql-mode.html and
http://dev.mysql.com/doc/mysql/en/ansi-mode.html.
MySQL always starts a newconnection when autoCommit==true is set. This ensures that
each SQL statement forms a single transaction on its own. If you try to rollback or commit
an SQL statement, you get an error message.
javax.transaction.SystemException: java.sql.SQLException:
Cant call rollback when autocommit=true
Error open transaction is not closed
To resolve this issue, add relaxAutoCommit=true to the JDBCURL. For more information,
see http://forums.mysql.com/read.php?39,31326,31404.
MySQL does not allowa DELETE on a rowthat contains a reference to itself. Here is an
example that illustrates the issue.
create table EMPLOYEE (
empId int NOT NULL,
salary float(25,2) NULL,
mgrId int NULL,
PRIMARY KEY (empId),
FOREIGN KEY (mgrId) REFERENCES EMPLOYEE (empId)
) ENGINE=InnoDB;
insert into Employee values (1, 1234.34, 1);
delete from Employee where empId = 1;
This example fails with the following error message.
ERROR 1217 (23000): Cannot delete or update a parent row:
a foreign key constraint fails
To resolve this issue, change the table creation script to the following:
empId int NOT NULL,
mgrId int NULL,
ON DELETE SET NULL
) ENGINE=InnoDB;
This can be done only if the foreign key feld is allowed to be null. For more information, see
http://dev.mysql.com/doc/mysql/en/innodb-foreign-key-constraints.html.
104
DevelopingWeb Applications
This chapter describes howweb applications are supported in the Oracle GlassFish Server.
Using Servlets on page 105
Using JavaServer Pages on page 110
Creating and Managing Sessions on page 114
Using Comet on page 122
Advanced Web Application Features on page 135

For general information about web applications, see Part II, The Web Tier, in The Java EE 6
Tutorial.
jsr/detail?id=318).
UsingServlets
GlassFish Server supports the Java Servlet Specifcation version 3.0.
Note Servlet API version 3.0 is fully backward compatible with versions 2.3, 2.4, and 2.5, so all
existing servlets should work without modifcation or recompilation.
To develop servlets, use the Java Servlet API. For information about using the Java Servlet API,
see the documentation at http://www.oracle.com/technetwork/java/javaee/servlet/
index.html.
7
C H A P T E R 7
105
The GlassFish Server provides the wscompile and wsdeploy tools to help you implement a web
service endpoint as a servlet. For more information about these tools, see the Oracle GlassFish
This section describes howto create efective servlets to control application interactions
running on a GlassFish Server, including standard-based servlets. In addition, this section
describes the GlassFish Server features to use to augment the standards.
Caching Servlet Results on page 106
About the Servlet Engine on page 109

CachingServlet Results
The GlassFish Server can cache the results of invoking a servlet, a JSP, or any URL pattern to
make subsequent invocations of the same servlet, JSP, or URL pattern faster. The GlassFish
Server caches the request results for a specifc amount of time. In this way, if another data call
occurs, the GlassFish Server can return the cached data instead of performing the operation
again. For example, if your servlet returns a stock quote that updates every 5 minutes, you set
the cache to expire after 300 seconds.
Whether to cache results and howto cache themdepends on the data involved. For example, it
makes no sense to cache the results of a quiz submission, because the input to the servlet is
diferent each time. However, it makes sense to cache a high level report showing demographic
data taken fromquiz results that is updated once an hour.
To defne howa GlassFish Server web application handles response caching, you edit specifc
felds in the glassfish-web.xml fle.
Note Aservlet that uses caching is not portable.
For Javadoc tool pages relevant to caching servlet results, go to http://glassfish.java.net/
nonav/docs/v3/api/ and click on the com.sun.appserv.web.cache package.
For information about JSP caching, see JSP Caching on page 111.
Caching Features on page 107
Default Cache Confguration on page 107
Caching Example on page 108
The CacheKeyGenerator Interface on page 109

Using Servlets
CachingFeatures
The GlassFish Server has the following web application response caching capabilities:
Caching is confgurable based on the servlet name or the URI.
When caching is based on the URI, this includes user specifed parameters in the query
string. For example, a response from/garden/catalog?category=roses is diferent froma
response from/garden/catalog?category=lilies. These responses are stored under
diferent keys in the cache.
Cache size, entry timeout, and other caching behaviors are confgurable.
Entry timeout is measured fromthe time an entry is created or refreshed. To override this
timeout for an individual cache mapping, specify the cache-mapping subelement timeout.
To determine caching criteria programmatically, write a class that implements the

com.sun.appserv.web.cache.CacheHelper interface. For example, if only a servlet knows
when a back end data source was last modifed, you can write a helper class to retrieve the
last modifed timestamp fromthe data source and decide whether to cache the response
based on that timestamp.
To determine cache key generation programmatically, write a class that implements the
com.sun.appserv.web.cache.CacheKeyGenerator interface. See The CacheKeyGenerator
Interface on page 109.
All non-ASCII request parameter values specifed in cache key elements must be URL
encoded. The caching subsystemattempts to match the rawparameter values in the request
query string.
Since newly updated classes impact what gets cached, the web container clears the cache
during dynamic deployment or reloading of classes.
The following HttpServletRequest request attributes are exposed.
com.sun.appserv.web.cachedServletName, the cached servlet target
com.sun.appserv.web.cachedURLPattern, the URL pattern being cached
Results produced by resources that are the target of a RequestDispatcher.include() or

RequestDispatcher.forward() call are cached if caching has been enabled for those
resources. For details, see cache-mapping in Oracle GlassFish Server 3.1 Application
Deployment Guide and dispatcher in Oracle GlassFish Server 3.1 Application Deployment
Guide. These are elements in the glassfish-web.xml fle.
Default Cache Confguration
If you enable caching but do not provide any special confguration for a servlet or JSP, the
default cache confguration is as follows:
The default cache timeout is 30 seconds.
Only the HTTP GETmethod is eligible for caching.
HTTP requests with cookies or sessions automatically disable caching.

Using Servlets
Chapter 7 DevelopingWeb Applications 107
No special consideration is given to Pragma:, Cache-control:, or Vary: headers.
The default key consists of the Servlet Path (minus pathInfo and the query string).
Aleast recently used list is maintained to evict cache entries if the maximumcache size is
exceeded.
Key generation concatenates the servlet path with key feld values, if any are specifed.
Results produced by resources that are the target of a RequestDispatcher.include() or

RequestDispatcher.forward() call are never cached.
CachingExample
Here is an example cache element in the glassfish-web.xml fle:
<cache max-capacity="8192" timeout="60">
<cache-helper name="myHelper" class-name="MyCacheHelper"/>
<cache-mapping>
<servlet-name>myservlet</servlet-name>
<timeout name="timefield">120</timeout>
<http-method>GET</http-method>
<http-method>POST</http-method>
</cache-mapping>
<cache-mapping>
<url-pattern> /catalog/* </url-pattern>

<constraint-field name=best scope=request.parameter/>
<constraint-field name=category scope=request.parameter>
<value> roses </value>
<value> lilies </value>
</constraint-field>

<constraint-field name=SKUnum scope=request.parameter>
<value match-expr=in-range> 1000 - 2000 </value>
</constraint-field>

<constraint-field name="category" scope="request.parameter>
<value match-expr="equals" cache-on-match-failure="true">
bogus
</value>
</constraint-field>
</cache-mapping>
<cache-mapping>
<servlet-name> InfoServlet </servlet-name>
<cache-helper-ref>myHelper</cache-helper-ref>
</cache-mapping>
</cache>
Using Servlets
For more information about the glassfish-web.xml caching settings, see cache in Oracle
The CacheKeyGenerator Interface
The built-in default CacheHelper implementation allows web applications to customize the key
generation. An application component (in a servlet or JSP) can set up a custom
CacheKeyGenerator implementation as an attribute in the ServletContext.
The name of the context attribute is confgurable as the value of the
cacheKeyGeneratorAttrName property in the default-helper element of the
glassfish-web.xml deployment descriptor. For more information, see default-helper in
About the Servlet Engine
Servlets exist in and are managed by the servlet engine in the GlassFish Server. The servlet
engine is an internal object that handles all servlet meta functions. These functions include
instantiation, initialization, destruction, access fromother components, and confguration
management.
Instantiating and Removing Servlets on page 109
Request Handling on page 109

InstantiatingandRemovingServlets
After the servlet engine instantiates the servlet, the servlet engine calls the servlets init method
to performany necessary initialization. You can override this method to performan
initialization function for the servlets life, such as initializing a counter.
When a servlet is removed fromservice, the servlet engine calls the destroy method in the
servlet so that the servlet can performany fnal tasks and deallocate resources. You can override
this method to write log messages or clean up any lingering connections that wont be caught in
garbage collection.
Request Handling
When a request is made, the GlassFish Server hands the incoming data to the servlet engine.
The servlet engine processes the requests input data, such as formdata, cookies, session
information, and URL name-value pairs, into an HttpServletRequest request object type.
The servlet engine also creates an HttpServletResponse response object type. The engine then
passes both as parameters to the servlets service method.
Using Servlets
In an HTTP servlet, the default service method routes requests to another method based on
the HTTP transfer method: POST, GET, DELETE, HEAD, OPTIONS, PUT, or TRACE. For example,
HTTP POST requests are sent to the doPost method, HTTP GET requests are sent to the doGet
method, and so on. This enables the servlet to process request data diferently, depending on
which transfer method is used. Since the routing takes place in the service method, you
generally do not override service in an HTTP servlet. Instead, override doGet, doPost, and so
on, depending on the request type you expect.
To performthe tasks to answer a request, override the service method for generic servlets, and
the doGet or doPost methods for HTTP servlets. Very often, this means accessing EJB
components to performbusiness transactions, then collating the information in the request
object or in a JDBCResultSet object.
UsingJavaServer Pages
The GlassFish Server supports the following JSP features:
JavaServer Pages (JSP) Specifcation
Precompilation of JSP fles, which is especially useful for production servers
JSP tag libraries and standard portable tags

For information about creating JSP fles, see the JavaServer Pages web site at
http://www.oracle.com/technetwork/java/javaee/jsp/index.html.
For information about Java Beans, see the JavaBeans web page at http://www.oracle.com/
technetwork/java/javase/tech/index-jsp-138795.html.
This section describes howto use JavaServer Pages (JSP fles) as page templates in a GlassFish
Server web application.
JSP Tag Libraries and Standard Portable Tags on page 110
JSP Caching on page 111
Options for Compiling JSP Files on page 114

JSPTagLibraries andStandardPortableTags
GlassFish Server supports tag libraries and standard portable tags. For more information, see
the JavaServer Pages Standard Tag Library (JSTL) page at http://www.oracle.com/
technetwork/java/index-jsp-135995.html.
Web applications dont need to bundle copies of the jsf-impl.jar or appserv-jstl.jar JSP
tag libraries (in as-install/lib) to use JavaServer Faces technology or JSTL, respectively. These
tag libraries are automatically available to all web applications.
Using JavaServer Pages
However, the as-install/lib/jspcachtags.jar tag library for JSP caching is not automatically
available to web applications. See JSP Caching on page 111, next.
JSPCaching
JSP caching lets you cache tag invocation results within the Java engine. Each can be cached
using diferent cache criteria. For example, suppose you have invocations to viewstock quotes,
weather information, and so on. The stock quote result can be cached for 10 minutes, the
weather report result for 30 minutes, and so on.
Enabling JSP Caching on page 111
Caching Scope on page 112
The cache Tag on page 112
The flush Tag on page 113

For more information about response caching as it pertains to servlets, see Caching Servlet
Results on page 106.
EnablingJSPCaching
To globally enable JSP caching, set the jspCachingEnabled property to true. The default is
false. For example:
asadmin set server-config.web-container.property.jspCachingEnabled="true"
To enable JSP caching for a single web application, followthese steps:
1. Extract the META-INF/jspcachtags.tld fle fromthe
as-install/glassfish/modules/web-glue.jar fle.
2. Create a newJARfle (for example, jspcachtags.jar) containing just the
META-INF/jspcachtags.tld fle previously extracted.
3. Bundle this newJARfle in the WEB-INF/lib directory of your web application.
Note Web applications that use JSP caching without bundling the tag library are not portable.
Refer to GlassFish Server tags in JSP fles as follows:
<%@ taglib prefix="prefx" uri="http://glassfish.org/taglibs/cache" %>
Subsequently, the cache tags are available as <prefx:cache> and <prefx:flush>. For example,
if your prefx is mypfx, the cache tags are available as <mypfx:cache> and <mypfx:flush>.
CachingScope
JSP caching is available in three diferent scopes: request, session, and application. The
default is application. To use a cache in request scope, a web application must specify the
com.sun.appserv.web.taglibs.cache.CacheRequestListener in its web.xml deployment
descriptor, as follows:
<listener>
<listener-class>
com.sun.appserv.web.taglibs.cache.CacheRequestListener
</listener-class>
</listener>
Likewise, for a web application to utilize a cache in session scope, it must specify the
com.sun.appserv.web.taglibs.cache.CacheSessionListener in its web.xml deployment
descriptor, as follows:
<listener>
<listener-class>
com.sun.appserv.web.taglibs.cache.CacheSessionListener
</listener-class>
</listener>
To utilize a cache in application scope, a web application need not specify any listener. The
com.sun.appserv.web.taglibs.cache.CacheContextListener is already specifed in the
jspcachtags.tld fle.
The cache Tag
The cache tag caches the body between the beginning and ending tags according to the
attributes specifed. The frst time the tag is encountered, the body content is executed and
cached. Each subsequent time it is run, the cached content is checked to see if it needs to be
refreshed and if so, it is executed again, and the cached data is refreshed. Otherwise, the cached
data is served.
Attributes of cache
The following table describes attributes for the cache tag.
TABLE 71 The cache Attributes
Attribute Default Description
key ServletPath_Sufx (optional) The name used by the container to access the cached entry. The
cache key is sufxed to the servlet path to generate a key to access the
cached entry. If no key is specifed, a number is generated according to the
position of the tag in the page.
TABLE 71 The cache Attributes (Continued)
timeout 60s (optional) The time in seconds after which the body of the tag is executed
and the cache is refreshed. By default, this value is interpreted in seconds.
To specify a diferent unit of time, add a sufx to the timeout value as
follows: s for seconds, m for minutes, h for hours, d for days. For example,
2h specifes two hours.
nocache false (optional) If set to true, the body content is executed and served as if there
were no cache tag. This ofers a way to programmatically decide whether
the cached response is sent or whether the body has to be executed, though
the response is not cached.
refresh false (optional) If set to true, the body content is executed and the response is
cached again. This lets you programmatically refresh the cache
immediately regardless of the timeout setting.
scope application (optional) The scope of the cache. Can be request, session, or
application. See Caching Scope on page 112.
Example of cache
The following example represents a cached JSP fle:
<%@ taglib prefix="mypfx" uri="http://glassfish.org/taglibs/cache" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<mypfx:cache key="${sessionScope.loginId}"
nocache="${param.nocache}"
refresh="${param.refresh}"
timeout="10m">
<c:choose>
<c:when test="${param.page == frontPage}">
<%-- get headlines from database --%>
</c:when>
<c:otherwise>
...
</c:otherwise>
</c:choose>
</mypfx:cache>
<mypfx:cache timeout="1h">
<h2> Local News </h2>
<%-- get the headline news and cache them --%>
</mypfx:cache>
The flush Tag
Forces the cache to be fushed. If a key is specifed, only the entry with that key is fushed. If no
key is specifed, the entire cache is fushed.
Attributes of fush
The following table describes attributes for the flush tag.
TABLE 72 The flush Attributes
key ServletPath_Sufx (optional) The name used by the container to access the cached entry. The
cache key is sufxed to the servlet path to generate a key to access the
cached entry. If no key is specifed, a number is generated according to the
position of the tag in the page.
scope application (optional) The scope of the cache. Can be request, session, or
application. See Caching Scope on page 112.
Examples of fush
To fush the entry with key="foobar":
<mypfx:flush key="foobar"/>
To fush the entire cache:
<c:if test="${empty sessionScope.clearCache}">
<mypfx:flush />
</c:if>
Options for CompilingJSPFiles
GlassFish Server provides the following ways of compiling JSP source fles into servlets:
JSP fles are automatically compiled at runtime.
The asadmin deploy command has a ----precompilejsp option. For details, see the
The jspc command line tool allows you to precompile JSP fles at the command line. For
CreatingandManagingSessions
This section describes howto create and manage HTTP sessions that allows users and
transaction information to persist between interactions.
Confguring Sessions on page 115
Session Managers on page 118

Creating and Managing Sessions
ConfguringSessions
HTTP Sessions, Cookies, and URL Rewriting on page 115
Coordinating Session Access on page 115
Saving Sessions During Redeployment on page 115
Logging Session Attributes on page 116
Distributed Sessions and Persistence on page 116

HTTPSessions, Cookies, andURL Rewriting
To confgure whether and howHTTP sessions use cookies and URL rewriting, edit the
session-properties and cookie-properties elements in the glassfish-web.xml fle for an
individual web application. For more about the properties you can confgure, see
session-properties in Oracle GlassFish Server 3.1 Application Deployment Guide and
cookie-properties in Oracle GlassFish Server 3.1 Application Deployment Guide.
For information about confguring default session properties for the entire web container, see
Using the default-web.xml File on page 138 and the Oracle GlassFish Server 3.1-3.1.1 High
Availability Administration Guide.
CoordinatingSessionAccess
Make sure that multiple threads dont simultaneously modify the same session object in
conficting ways. If the persistence type is replicated (see The replicated Persistence Type
on page 120), the following message in the log fle indicates that this might be happening:
Primary Key Constraint violation while saving session session_id
This is especially likely to occur in web applications that use HTML frames where multiple
servlets are executing simultaneously on behalf of the same client. Agood solution is to ensure
that one of the servlets modifes the session and the others have read-only access.
SavingSessions DuringRedeployment
Whenever a redeployment is done, the sessions at that transit time become invalid unless you
use the --keepstate=true option of the asadmin redeploy command. For example:
asadmin redeploy --keepstate=true --name hello.war
The default for --keepstate is false. This option is supported only on the default server
instance, named server. It is not supported and ignored for any other target.
For web applications, this feature is applicable only if in the glassfish-web-app.xml fle the
persistence-type attribute of the session-manager element is file.
If any active web session fails to be preserved or restored, none of the sessions will be available
when the redeployment is complete. However, the redeployment continues and a warning is
logged.
The newclass loader of the redeployed application is used to deserialize any sessions previously
saved. The usual restrictions about serialization and deserialization apply. For example, any
application-specifc class referenced by a session attribute may evolve only in a
backward-compatible fashion. For more information about class loaders, see Chapter 2, Class
Loaders.
LoggingSessionAttributes
You can write session attribute values to an access log. The access log format token
%session.name% logs one of the following:
The value of the session attribute with the name name
NULL-SESSION-ATTRIBUTE-name if the named attribute does not exist in the session
NULL-SESSION if no session exists

For more information about access logging and format tokens, see online help for the Access
Log tab of the HTTP Service page in the Administration Console.
DistributedSessions andPersistence
Adistributed HTTP session can run in multiple GlassFish Server instances, provided the
following criteria are met:
Each server instance has the same distributable web application deployed to it. The web-app
element of the web.xml deployment descriptor fle must have the distributable
subelement specifed.
The web application uses high-availability session persistence. If a non-distributable web

application is confgured to use high-availability session persistence, a warning is written to
the server log, and the session persistence type reverts to memory. See The replicated
Persistence Type on page 120.
All objects bound into a distributed session must be of the types listed in Table 73.
The web application must be deployed using the deploy or deploydir command with the
--availabilityenabled option set to true. See the Oracle GlassFish Server 3.1-3.1.1
Reference Manual.
Note Contrary to the Servlet 3.0 specifcation, GlassFish Server does not throwan
IllegalArgumentException if an object type not supported for failover is bound into a
distributed session.
Keep the distributed session size as small as possible. Session size has a direct impact on overall
systemthroughput.
In the event of an instance or hardware failure, another server instance can take over a
distributed session, with the following limitations:
If a distributable web application references a Java EE component or resource, the reference

might be lost. See Table 73 for a list of the types of references that HTTPSession failover
supports.
References to open fles or network connections are lost.

For information about howto work around these limitations, see the Oracle GlassFish Server 3.1
Deployment Planning Guide.
In the following table, No indicates that failover for the object type might not work in all cases
and that no failover support is provided. However, failover might work in some cases for that
object type. For example, failover might work because the class implementing that type is
serializable.
For more information about the InitialContext, see Accessing the Naming Context on
page 273. For more information about transaction recovery, see Chapter 15, Using the
Transaction Service. For more information about Administered Objects, see Administering
JMS Physical Destinations in Oracle GlassFish Server 3.1 Administration Guide.
TABLE 73 Object Types Supported for Java EE Web Application Session State Failover
Java Object Type Failover Support
Colocated or distributed stateless session, stateful
session, or entity bean reference
Yes
JNDI context Yes, InitialContext and java:comp/env
UserTransaction Yes, but if the instance that fails is never restarted, any
prepared global transactions are lost and might not be
correctly rolled back or committed.
JDBCDataSource No
Java Message Service (JMS) ConnectionFactory,
Destination
No
JavaMail Session No
TABLE 73 Object Types Supported for Java EE Web Application Session State Failover (Continued)
Connection Factory No
Administered Object No
Web service reference No
Serializable Java types Yes
Extended persistence context No
SessionManagers
Asession manager automatically creates newsession objects whenever a newsession starts. In
some circumstances, clients do not join the session, for example, if the session manager uses
cookies and the client does not accept cookies.
GlassFish Server ofers these session management options, determined by the
session-manager elements persistence-type attribute in the glassfish-web.xml fle:
The memory Persistence Type on page 118, the default
The file Persistence Type on page 119, which uses a fle to store session data
The replicated Persistence Type on page 120, which uses other servers in the cluster for
session persistence
The coherence-web Persistence Type on page 121, which uses Coherence*Web for session
persistence
Note If the session manager confguration contains an error, the error is written to the server
log and the default (memory) confguration is used.
For more information, see session-manager in Oracle GlassFish Server 3.1 Application
Deployment Guide.
The memory PersistenceType
This persistence type is not designed for a production environment that requires session
persistence. It provides no session persistence. However, you can confgure it so that the session
state in memory is written to the fle systemprior to server shutdown.
To specify the memory persistence type for a specifc web application, edit the
glassfish-web.xml fle as in the following example. The persistence-type attribute is
optional, but must be set to memory if included. This overrides the web container availability
settings for the web application.
<glassfish-web-app>
...
<session-config>
<session-manager persistence-type="memory" />
<manager-properties>
<property name="sessionFilename" value="sessionstate" />
</manager-properties>
</session-manager>
...
</session-config>
...
The only manager property that the memory persistence type supports is sessionFilename,
which is listed under manager-properties in Oracle GlassFish Server 3.1 Application
Deployment Guide. The sessionFilename property specifes the name of the fle where sessions
are serialized and persisted if the web application or the server is stopped. To disable this
behavior, specify an empty string as the value of sessionFilename. The default value is an
empty string.
For more information about the glassfish-web.xml fle, see Oracle GlassFish Server 3.1
The file PersistenceType
This persistence type provides session persistence to the local fle system, and allows a single
server domain to recover the session state after a failure and restart. The session state is
persisted in the background, and the rate at which this occurs is confgurable. The store also
provides passivation and activation of the session state to help control the amount of memory
used. This option is not supported in a production environment. However, it is useful for a
development systemwith a single server instance.
Note Make sure the delete option is set in the server.policy fle, or expired fle-based
sessions might not be deleted properly. For more information about server.policy, see The
server.policy File on page 58.
To specify the file persistence type for a specifc web application, edit the glassfish-web.xml
fle as in the following example. Note that persistence-type must be set to file. This
overrides the web container availability settings for the web application.
<glassfish-web-app>
...
<session-config>
<session-manager persistence-type="file">
<store-properties>
<property name="directory" value="sessiondir" />
</store-properties>
</session-manager>
...
</session-config>
...
The file persistence type supports all the manager properties listed under
manager-properties in Oracle GlassFish Server 3.1 Application Deployment Guide except
sessionFilename, and supports the directory store property listed under store-properties
in Oracle GlassFish Server 3.1 Application Deployment Guide.
The replicated PersistenceType
The replicated persistence type uses other servers in the cluster for session persistence.
Clustered server instances replicate session state. Each backup instance stores the replicated
data in memory. This allows sessions to be distributed. For details, see Distributed Sessions
and Persistence on page 116. In addition, you can confgure the frequency and scope of session
persistence. The other servers are also used as the passivation and activation store. Use this
option in a production environment that requires session persistence.
To use the replicated persistence type, you must enable availability. Select the Availability
Service component under the relevant confguration in the Administration Console. Check the
Availability Service box. To enable availability for the web container, select the Web Container
Availability tab, then check the Availability Service box. All instances in an GlassFish Server
cluster should have the same availability settings to ensure consistent behavior. For details, see
the Oracle GlassFish Server 3.1-3.1.1 High Availability Administration Guide.
To change settings such as persistence frequency and persistence scope for the entire web
container, use the Persistence Frequency and Persistence Scope drop-down lists on the Web
Container Availability tab in the Administration Console, or use the asadmin set command.
For example:
asadmin set
server-config.availability-service.web-container-availability.persistence-frequency=time-based
For more information, see the description of the asadmin set command in the Oracle GlassFish
To specify the replicated persistence type for a specifc web application, edit the
glassfish-web.xml fle as in the following example. Note that persistence-type must be set
to replicated. This overrides the web container availability settings for the web application.
<glassfish-web-app>
...
<session-config>
<session-manager persistence-type="replicated">
<manager-properties>
<property name="persistenceFrequency" value="web-method" />
</manager-properties>
<store-properties>
<property name="persistenceScope" value="session" />
</store-properties>
</session-manager>
...
</session-config>
...
The replicated persistence type supports all the manager properties listed under
manager-properties in Oracle GlassFish Server 3.1 Application Deployment Guide except
sessionFilename, and supports the persistenceScope store property listed under
store-properties in Oracle GlassFish Server 3.1 Application Deployment Guide.
To specify that web sessions for which high availability is enabled are frst bufered and then
replicated using a separate asynchronous thread, use the --asyncreplication=true option of
the asadmin deploy command. For example:
asadmin deploy --availabilityenabled=true --asyncreplication=true --name hello.war
If --asyncreplication is set to true (the default), performance is improved but availability is
reduced. If the instance where states are bufered but not yet replicated fails, the states are lost. If
set to false, performance is reduced but availability is guaranteed. States are not bufered but
immediately transmitted to other instances in the cluster.
The coherence-web PersistenceType
Built on top of Oracle Coherence, Coherence*Web is an HTTP session management module
dedicated to managing session state in clustered environments. Starting with Coherence 3.7
and GlassFish Server 3.1, there is a newfeature of Coherence*Web called ActiveCache for
GlassFish. ActiveCache for GlassFish provides Coherence*Web functionality in web
applications deployed on GlassFish Servers. Within GlassFish Server, Coherence*Web
functions as an additional web container persistence type, named coherence-web.
For information about howto confgure and deploy Coherence*Web on GlassFish Server, see
Using Coherence*Web with GlassFish Server (http://download.oracle.com/docs/cd/
E18686_01/coh.37/e18690/glassfish.htm).
UsingComet
This section explains the Comet programming technique and howto create and deploy a
Comet-enabled application with the Oracle GlassFish Server.
Introduction to Comet on page 122
Grizzly Comet on page 124
Bayeux Protocol on page 133

IntroductiontoComet
Comet is a programming technique that allows a web server to send updates to clients without
requiring the clients to explicitly request them.
This kind of programming technique is called server push, which means that the server pushes
data to the client. The opposite style is client pull, which means that the client must pull the data
fromthe server, usually through a user-initiated event, such as a button click.
Web applications that use the Comet technique can deliver updates to clients in a more timely
manner than those that use the client-pull style while avoiding the latency that results from
clients frequently polling the server.
One of the many use cases for Comet is a chat roomapplication. When the server receives a
message fromone of the chat clients, it needs to send the message to the other clients without
requiring themto ask for it. With Comet, the server can deliver messages to the clients as they
are posted rather than expecting the clients to poll the server for newmessages.
To accomplish this scenario, a Comet application establishes a long-lived HTTP connection.
This connection is suspended on the server side, waiting for an event to happen before
resuming. This kind of connection remains open, allowing an application that uses the Comet
technique to send updates to clients when they are available rather than expecting clients to
reopen the connection to poll the server for updates.
The Grizzly Implementationof Comet
Alimitation of the Comet technique is that you must use it with a web server that supports
non-blocking connections to avoid poor performance. Non-blocking connections are those
that do not need to allocate one thread for each request. If the web server were to use blocking
connections then it might end up holding many thousands of threads, thereby hindering its
scalability.
The GlassFish server includes the Grizzly HTTP Engine, which enables asynchronous request
processing (ARP) by avoiding blocking connections. Grizzly's ARP implementation
accomplishes this by using the Java NIOAPI.
Using Comet
With Java NIO, Grizzly enables greater performance and scalability by avoiding the limitations
experienced by traditional web servers that must run a thread for each request. Instead,
Grizzly's ARP mechanismmakes efcient use of a thread pool systemand also keeps the state of
requests so that it can keep requests alive without holding a single thread for each of them.
Grizzly supports two diferent implementations of Comet:
Grizzly Comet on page 124 Based on ARP, this includes a set of APIs that you use froma
web component to enable Comet functionality in your web application. Grizzly Comet is
specifc to the Oracle GlassFish Server.
Bayeux Protocol on page 133 Often referred to as Cometd, it consists of the JSON-based
Bayeux message protocol, a set of Dojo or Ajax libraries, and an event handler. The Bayeux
protocol uses a publish/subscribe model for server/client communication. The Bayeux
protocol is portable, but it is container dependent if you want to invoke it froman
Enterprise Java Beans (EJB) component. The Grizzly implementation of Cometd consists of
a servlet that you reference fromyour web application.
Client Technologies toUseWithComet
In addition to creating a web component that uses the Comet APIs, you need to enable your
client to accept asynchronous updates fromthe web component. To accomplish this, you can
use JavaScript, IFrames, or a framework, such as Dojo.
An IFrame is an HTML element that allows you to include other content in an HTML page. As
a result, the client can embed updated content in the IFrame without having to reload the page.
The example in this tutorial employs a combination of JavaScript and IFrames to allowthe
client to accept asynchronous updates. Aservlet included in the example writes out JavaScript
code to one of the IFrames. The JavaScript code contains the updated content and invokes a
function in the page that updates the appropriate elements in the page with the newcontent.
The next section explains the two kinds of connections that you can make to the server. While
you can use any of the client technologies listed in this section with either kind of connection, it
is more difcult to use JavaScript with an HTTP-streaming connection.
Types of Comet Connections
When working with Comet, as implemented in Grizzly, you have two diferent ways to handle
client connections to the server:
HTTP Streaming
Long Polling
HTTPStreaming
The HTTP Streaming technique keeps a connection open indefnitely. It never closes, even after
the server pushes data to the client.
Using Comet
In the case of HTTP streaming, the application sends a single request and receives responses as
they come, reusing the same connection forever. This technique signifcantly reduces the
network latency because the client and the server don't need to open and close the connection.
The basic life cycle of an application using HTTP-streaming is:
request --> suspend --> data available --> write response --> data available --> write response
The client makes an initial request and then suspends the request, meaning that it waits for a
response. Whenever data is available, the server writes it to the response.
LongPolling
The long-polling technique is a combination of server-push and client-pull because the client
needs to resume the connection after a certain amount of time or after the server pushes an
update to the client.
The basic life cycle of an application using long-polling is:
request -> suspend --> data available --> write response --> resume
The client makes an initial request and then suspends the request. When an update is available,
the server writes it to the response. The connection closes, and the client optionally resumes the
connection.
HowtoChoose theType of Connection
If you anticipate that your web application will need to send frequent updates to the client, you
should use the HTTP-streaming connection so that the client does not have to frequently
reestablish a connection. If you anticipate less frequent updates, you should use the long-polling
connection so that the web server does not need to keep a connection open when no updates are
occurring. One caveat to using the HTTP-streaming connection is that if you are streaming
through a proxy, the proxy can bufer the response fromthe server. So, be sure to test your
application if you plan to use HTTP-streaming behind a proxy.
Grizzly Comet
The Grizzly Comet API on page 125
The Hidden Frame Example on page 125
Creating a Comet-Enabled Application on page 126
Developing the Web Component on page 126
Creating the Client Pages on page 130
Creating the Deployment Descriptor on page 132

Using Comet
Deploying and Running a Comet-Enabled Application on page 132

The Grizzly Comet API
Grizzly's support for Comet includes a small set of APIs that make it easy to add Comet
functionality to your web applications. The Grizzly Comet APIs that developers use most often
are the following:
CometContext: AComet context, which is a shareable space to which applications subscribe

to receive updates.
CometEngine: The entry point to any component using Comet. Components can be servlets,
JavaServer Pages (JSP), JavaServer Faces components, or pure Java classes.
CometEvent: Contains the state of the CometContext object
CometHandler: The interface an application implements to be part of one or more Comet

contexts.
The way a developer would use this API in a web component is to performthe following tasks:
1. Register the context path of the application with the CometContext object:
CometEngine cometEngine =
CometEngine.getEngine();
CometContext cometContext =
cometEngine.register(contextPath)
2. Register the CometHandler implementation with the CometContext object:
cometContext.addCometHandler(handler)
3. Notify one or more CometHandler implementations when an event happens:
cometContext.notify((Object)(handler))
The HiddenFrame Example
This rest of this tutorial uses the Hidden Frame example to explain howto develop
Comet-enabled web applications. You can download the example from
grizzly.dev.java.net at Hidden example download. Fromthere, you can download a
prebuilt WARfle as well as a JARfle containing the servlet code.
The Hidden Frame example is so called because it uses hidden IFrames. The example allows
multiple clients to increment a counter on the server. When a client increments the counter, the
server broadcasts the newcount to the clients using the Comet technique.
The Hidden Frame example uses the long-polling technique, but you can easily modify it to use
HTTP-streaming by removing two lines. See To Notify the Comet Handler of an Event on
page 129 and To Create a HTML Page That Updates and Displays the Content on page 130 for
more information on converting the example to use the HTTP-streaming technique.
The client side of the example uses hidden IFrames with embedded JavaScript tags to connect to
the server and to asynchronously post content to and accept updates fromthe server.
Using Comet
The server side of the example consists of a single servlet that listens for updates fromclients,
updates the counter, and writes JavaScript code to the client that allows it to update the counter
on its page.
See Deploying and Running a Comet-Enabled Application on page 132 for instructions on
howto deploy and run the example.
When you run the example, the following happens:
1. The index.html page opens.
2. The browser loads three frames: The frst one accesses the servlet using an HTTP GET; the
second one loads the count.html page, which displays the current count; and the third one
loads the button.html page, which is used to send the POSTrequest.
3. After clicking the button on the button.html page, the page submits a POSTrequest to the
servlet.
4. The doPost method calls the onEvent method of the Comet handler and redirects the
incremented count along with some JavaScript to the count.html page on the client.
5. The updateCount() JavaScript function on the count.html page updates the counter on the
page.
6. Because this example uses long-polling, the JavaScript code on count.html calls doGet
again to resume the connection after the servlet pushes the update.
Creatinga Comet-EnabledApplication
This section uses the Hidden Frame example application to demonstrate howto develop a
Comet application. The main tasks for creating a simple Comet-enabled application are the
following:
DevelopingtheWebComponent
This section shows you howto create a Comet-enabled web component by giving you
instructions for creating the servlet in the Hidden Frame example.
Developing the web component involves performing the following steps:
1. Create a web component to support Comet requests.
2. Register the component with the Comet engine.
3. Defne a Comet handler that sends updates to the client.
4. Add the Comet handler to the Comet context.
5. Notify the Comet handler of an event using the Comet context.
Using Comet
ToCreate aWebComponent toSupport Comet

Create anempty servlet class, like the following:
import javax.servlet.*;
public class HiddenCometServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
private String contextPath = null;
@Override
public void init(ServletConfig config) throws ServletException {}
@Override
protected void doGet(HttpServletRequest req,
HttpServletResponse res)
throws ServletException, IOException {}
@Override
protected void doPost(HttpServletRequest req,
HttpServletResponse res)
throws ServletException, IOException {);
}
Import the followingComet packages intothe servlet class:
import com.sun.grizzly.comet.CometContext;
import com.sun.grizzly.comet.CometEngine;
import com.sun.grizzly.comet.CometEvent;
import com.sun.grizzly.comet.CometHandler;
Import these additional classes that youneedfor incrementinga counter andwritingoutput to
the clients:
import java.io.IOException;
import java.io.PrintWriter;
import java.util.concurrent.atomic.AtomicInteger;
Adda private variable for the counter:
private final AtomicInteger counter = new AtomicInteger();
ToRegister the Servlet Withthe Comet Engine

Inthe servlet's init method, addthe followingcode toget the component's context path:
ServletContext context = config.getServletContext();
contextPath = context.getContextPath() + "/hidden_comet";
Get aninstance of the Comet engine by addingthis line after the lines fromStep1:
CometEngine engine = CometEngine.getEngine();
Register the component withthe Comet engine by addingthe followinglines after those from
Step2:
CometContext cometContext = engine.register(contextPath);
cometContext.setExpirationDelay(30 * 1000);
1
2
3
4
1
2
3
Using Comet
ToDefne a Comet Handler toSendUpdates tothe Client

Create a private class that implements CometHandler andaddit tothe servlet class:
private class CounterHandler
implements CometHandler<HttpServletResponse> {
private HttpServletResponse response;
}
Addthe followingmethods tothe class:
public void onInitialize(CometEvent event)
throws IOException {}
public void onInterrupt(CometEvent event)
throws IOException {
removeThisFromContext();
}
public void onTerminate(CometEvent event)
removeThisFromContext();
}
public void attach(HttpServletResponse attachment) {
this.response = attachment;
}
private void removeThisFromContext() throws IOException {
response.getWriter().close();
CometContext context =
CometEngine.getEngine().getCometContext(contextPath);
context.removeCometHandler(this);
}
You need to provide implementations of these methods when implementing CometHandler.
The onInterrupt and onTerminate methods execute when certain changes occur in the status
of the underlying TCP communication. The onInterrupt method executes when
communication is resumed. The onTerminate method executes when communication is
closed. Both methods call removeThisFromContext, which removes the CometHandler object
fromthe CometContext object.
ToAddthe Comet Handler tothe Comet Context

Get aninstance of the Comet handler andattachthe response toit by addingthe followinglines
tothe doGet method:
CounterHandler handler = new CounterHandler();
handler.attach(res);
Get the Comet context by addingthe followinglines to doGet:
CometContext context = engine.getCometContext(contextPath);
1
2
1
2
Using Comet
Addthe Comet handler tothe Comet context by addingthis line to doGet:
context.addCometHandler(handler);
ToNotify the Comet Handler of anEvent

AddanonEvent methodtothe CometHandler implementationclass todefne what happens
whenanevent occurs:
public void onEvent(CometEvent event)
if (CometEvent.NOTIFY == event.getType()) {
int count = counter.get();
PrintWriter writer = response.getWriter();
writer.write("<script type=text/javascript>" +
"parent.counter.updateCount(" + count + ")" +
"</script>\n");
writer.flush();
event.getCometContext().resumeCometHandler(this);
}
}
This method frst checks if the event type is NOTIFY, which means that the web component is
notifying the CometHandler object that a client has incremented the count. If the event type is
NOTIFY, the onEvent method gets the updated count, and writes out JavaScript to the client. The
JavaScript includes a call to the updateCount() function, which will update the count on the
clients' pages.
The last line resumes the Comet request and removes it fromthe list of active CometHandler
objects. By this line, you can tell that this application uses the long-polling technique. If you
were to delete this line, the application would use the HTTP-Streaming technique.
For HTTP-Streaming:
Add the same code as for long-polling, except do not include the following line:
event.getCometContext().resumeCometHandler(this);
You don't include this line because you do not want to resume the request. Instead, you want
the connection to remain open.
Increment the counter andforwardthe response by addingthe followinglines tothe doPost
method:
counter.incrementAndGet();
CometContext<?> context =
engine.getCometContext(contextPath);
context.notify(null);
req.getRequestDispatcher("count.html").forward(req, res);
When a user clicks the button, the doPost method is called. The doPost method increments the
counter. It then obtains the current CometContext object and calls its notify method. By calling
context.notify, the doPost method triggers the onEvent method you created in the previous
step. After onEvent executes, doPost forwards the response to the clients.
3
1
2
Using Comet
Creatingthe Client Pages
Developing the HTML pages for the client involves performing these steps:
1. Create a welcome HTML page, called index.html, that contains: one hidden frame for
connecting to the servlet through an HTTP GET; one IFrame that embeds the count.html
page, which contains the updated content; and one IFrame that embeds the button.html
page, which is used for posting updates using HTTP POST.
2. Create the count.html page that contains an HTML element that displays the current count
and the JavaScript for updating the HTML element with the newcount.
3. Create the button.html page that contains a button for the users to submit updates.
ToCreate a HTMLWelcome PageThat Contains IFrames for Receiving

andSendingUpdates
Create anHTML page calledindex.html.
Addthe followingcontent tothe page:
<html>
<head>
<title>Comet Example: Counter with Hidden Frame</title>
</head>
<body>
</body>
</html>
AddIFrames for connectingtothe server andreceivingandsendingupdates toindex.html in
betweenthe body tags:
<frameset>
<iframe name="hidden" src="hidden_comet"
frameborder="0" height="0" width="100%"></iframe>
<iframe name="counter" src="count.html"
frameborder="0" height="100%" width="100%"></iframe>
<iframe name="button" src="button.html" frameborder="0" height="30%" widget="100%"></iframe>
</frameset>
The frst frame, which is hidden, points to the servlet by referencing its context path. The
second frame displays the content fromcount.html, which displays the current count. The
second frame displays the content frombutton.html, which contains the submit button for
incrementing the counter.
ToCreate a HTML PageThat Updates andDisplays the Content

Create anHTML page calledcount.html andaddthe followingcontent toit:
<html>
<head>
</head>
1
2
3
1
Using Comet
<body>
<center>
<h3>Comet Example: Counter with Hidden Frame</h3>
<p>
<b id="count"> </b>
<p>
</center>
</body>
</html>
This page displays the current count.
AddJavaScript code that updates the count inthe page. Addthe followinglines inbetweenthe
head tags of count.html:
<script type=text/javascript>
function updateCount(c) {
document.getElementById(count).innerHTML = c;
parent.hidden.location.href = "hidden_comet";
};
</script>
The JavaScript takes the updated count it receives fromthe servlet and updates the count
element in the page. The last line in the updateCount() function invokes the servlet's doGet
method again to reestablish the connection.
For HTTP-Streaming:
Add the same code as for long-polling, except for the following line:
parent.hidden.location.href = hidden_comet
This line invokes the doGet method of CometServlet again, which would reestablish the
connection. In the case of HTTP-Streaming, you want the connection to remain open.
Therefore, you don't include this line of code.
ToCreate the HTML PageThat Allows SubmittingUpdates

Create anHTML page calledbutton.html andaddthe followingcontent toit:
<html>
<head>
</head>
<body>
<center>
<form method="post" action="hidden_comet">
<input type="submit" value="Click">
</form>
</center>
</body>
</html>
This page displays a formwith a button that allows a user to update the count on the server. The
servlet will then broadcast the updated count to all clients.
2
Using Comet
Creatingthe Deployment Descriptor
This section describes howto create a deployment descriptor to specify howyour
Comet-enabled web application should be deployed.
ToCreate the Deployment Descriptor

Create a fle calledweb.xml andput the followingcontents init:
<web-app version="3.0"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd ">
<servlet>
<servlet-name>HiddenCometServlet</servlet-name>
<servlet-class>
com.sun.grizzly.samples.comet.HiddenCometServlet
</servlet-class>
<load-on-startup>0</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>HiddenCometServlet</servlet-name>
<url-pattern>/hidden_comet</url-pattern>
</servlet-mapping>
</web-app>
This deployment descriptor contains a servlet declaration and mapping for
HiddenCometServlet. The load-on-startup attribute must be set to 0 so that the
Comet-enabled servlet will not load until the client makes a request to it.
DeployingandRunninga Comet-EnabledApplication
Before running a Comet-enabled application in the GlassFish Server, you need to enable Comet
in the server. Then you can deploy the application just as you would any other web application.
When running the application, you need to connect to it fromat least two diferent browsers to
experience the efect of the servlet updating all clients in response to one client posting an
update to the server.
EnablingComet inthe GlassFishServer
Before running a Comet-enabled application, you need to enable Comet in the HTTP listener
for your application by setting a special attribute in the associated protocol confguration. The
following example shows the asadmin set command that adds this attribute:
asadmin set server-config.network-config.protocols.protocol.http-1.http.comet-support-enabled="true"
Substitute the name of the protocol for http-1.
Using Comet
ToDeploy the Example

These instructions tell you howto deploy the Hidden Frame example.
Downloadgrizzly-comet-hidden-1.7.3.1.war.
Runthe followingcommandtodeploy the example:
as-install/bin/asadmin deploy grizzly-comet-hidden-1.7.3.1.war
ToRunthe Example
These instructions tell you howto run the Hidden Frame example.
Opentwowebbrowsers, preferably twodiferent brands of webbrowser.
Enter the followingURL inbothbrowsers:
http://localhost:8080/grizzly-comet-hidden/index.html
Whenthe frst page loads inbothbrowsers, click the buttoninone of the browsers andwatch
the count change inthe other browser window.
Bayeux Protocol
The Bayeux protocol, often referred to as Cometd, greatly simplifes the use of Comet. No
server-side coding is needed for servers such as GlassFish Server that support the Bayeux
protocol. Just enable Comet and the Bayeux protocol, then write and deploy the client.
Enabling Comet on page 133
To Confgure the web.xml File on page 134
To Write, Deploy, and Run the Client on page 134

EnablingComet
Before running a Comet-enabled application, you need to enable Comet in the HTTP listener
for your application by setting a special attribute in the associated protocol confguration. The
following example shows the asadmin set command that adds this attribute:
asadmin set server-config.network-config.protocols.protocol.http-1.http.comet-support-enabled="true"
Substitute the name of the protocol for http-1.
1
2
1
2
3
Using Comet
ToConfgure the web.xml File

To enable the Bayeux protocol on the GlassFish Server, you must reference the CometdServlet
in your web application's web.xml fle. In addition, if your web application includes a servlet, set
the load-on-startup value for your servlet to 0 (zero) so that it will not load until the client
makes a request to it.
Openthe web.xml fle for your webapplicationina text editor.
Addthe followingXML code tothe web.xml fle:
<servlet>
<servlet-name>Grizzly Cometd Servlet</servlet-name>
<servlet-class>
com.sun.grizzly.cometd.servlet.CometdServlet
</servlet-class>
<init-param>
<description>
expirationDelay is the long delay before a request is
resumed. -1 means never.
</description>
<param-name>expirationDelay</param-name>
<param-value>-1</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>Grizzly Cometd Servlet</servlet-name>
<url-pattern>/cometd/*</url-pattern>
</servlet-mapping>
Note that the load-on-startup value for the CometdServlet is 1.
If your webapplicationincludes a servlet, set the load-on-startup value to0 for your servlet
(not the CometdServlet) as follows:
<servlet>
...
</servlet>
Save the web.xml fle.
ToWrite, Deploy, andRunthe Client

Addscript tags tothe HTML page. For example:
<script type="text/javascript" src="chat.js"></script>
Inthe script, call the neededlibraries. For example:
dojo.require("dojo.io.cometd");
1
2
3
4
1
2
Using Comet
Inthe script, use publish andsubscribe methods tosendandreceive messages. For example:
cometd.subscribe("/chat/demo", false, room, "_chat");
cometd.publish("/chat/demo", { user: room._username, chat: text});
Deploy the webapplicationas youwouldany other webapplication. For example:
asadmin deploy cometd-example.war
Runthe applicationas youwouldany other webapplication.
The context root for the example chat application is /cometd and the HTML page is
index.html. So the URL might look like this:
http://localhost:8080/cometd/index.html
For more information about deployment in the GlassFish Server, see the Oracle GlassFish
For more information about the Bayeux protocol, see Bayeux Protocol (http://
svn.cometd.com/trunk/bayeux/bayeux.html).
For more information about the Dojo toolkit, see http://dojotoolkit.org/.
For information about REpresentational State Transfer (RESTful) web services and Comet, see
RESTful Web Services and Comet (http://developers.sun.com/appserver/reference/
techart/cometslideshow.html).
AdvancedWebApplicationFeatures
Internationalization Issues on page 136
Virtual Server Properties on page 137
Class Loader Delegation on page 137
Using the default-web.xml File on page 138
Confguring Logging and Monitoring in the Web Container on page 139
Confguring Idempotent URL Requests on page 139
Header Management on page 140
Confguring Valves and Catalina Listeners on page 140
Alternate Document Roots on page 140
Using a context.xml File on page 142
Enabling WebDav on page 143
Using SSI on page 144
Using CGI on page 145

3
4
5
See Also
AdvancedWeb Application Features
InternationalizationIssues
The Server's Default Locale on page 136
Servlet Character Encoding on page 136

The Server's Default Locale
To set the default locale of the entire GlassFish Server, which determines the locale of the
Administration Console, the logs, and so on, use the Administration Console. Select the
domain component. Then type a value in the Locale feld. For details, click the Help button in
the Administration Console.
Servlet Character Encoding
This section explains howthe GlassFish Server determines the character encoding for the
servlet request and the servlet response. For encodings you can use, see http://
download.oracle.com/
javase/6/docs/technotes/guides/intl/encoding.doc.html.
Servlet Request
When processing a servlet request, the server uses the following order of precedence, frst to
last, to determine the request character encoding:
The getCharacterEncoding method
Ahidden feld in the form, specifed by the form-hint-field attribute of the

parameter-encoding element in the glassfish-web.xml fle
The default-charset attribute of the parameter-encoding element in the

glassfish-web.xml fle
The default, which is ISO-8859-1

For details about the parameter-encoding element, see parameter-encoding in Oracle
Servlet Response
When processing a servlet response, the server uses the following order of precedence, frst to
last, to determine the response character encoding:
The setCharacterEncoding or setContentType method
The setLocale method
The default, which is ISO-8859-1

Virtual Server Properties
You can set virtual server properties in the following ways:
You can defne virtual server properties using the asadmin create-virtual-server
command. For example:
asadmin create-virtual-server --hosts localhost --property authRealm=ldap MyVS
For details and a complete list of virtual server properties, see create-virtual-server(1).
You can defne virtual server properties using the asadmin set command. For example:
asadmin set server-config.http-service.virtual-server.MyVS.property.authRealm="ldap"
For details, see set(1).
You can defne virtual server properties using the Administration Console. Select the HTTP
Service component under the relevant confguration, select Virtual Servers, and select the
desired virtual server. Select Add Property, enter the property name and value, check the
enable box, and select Save. For details and a complete list of virtual server properties, click
the Help button in the Administration Console.
Some virtual server properties can be set for a specifc web application. For details, see
glassfsh-web-app in Oracle GlassFish Server 3.1 Application Deployment Guide.
Class Loader Delegation
The Servlet specifcation recommends that a web application class loader look in the local class
loader before delegating to its parent. To make the web application class loader followthe
delegation model in the Servlet specifcation, set delegate="false" in the class-loader
element of the glassfish-web.xml fle. Its safe to do this only for a web module that does not
interact with any other modules.
The default value is delegate="true", which causes the web application class loader to delegate
in the same manner as the other class loaders. Use delegate="true" for a web application that
accesses EJB components or that acts as a web service client or endpoint. For details about
glassfish-web.xml, see Oracle GlassFish Server 3.1 Application Deployment Guide.
For a number of packages, including java.* and javax.*, symbol resolution is always
delegated to the parent class loader regardless of the delegate setting. This prevents
applications fromoverriding core Java runtime classes or changing the API versions of
specifcations that are part of the Java EE platform.
For general information about class loaders, see Chapter 2, Class Loaders.
Usingthe default-web.xml File
You can use the default-web.xml fle to defne features such as flters and security constraints
that apply to all web applications.
For example, directory listings are disabled by default for added security. To enable directory
listings, in your domain's default-web.xml fle, search for the defnition of the servlet whose
servlet-name is equal to default, and set the value of the init-param named listings to
true. Then redeploy your web application if it has already been deployed, or restart the server.
<init-param>
<param-name>listings</param-name>
<param-value>true</param-value>
</init-param>
If listings is set to true, you can also determine howdirectory listings are sorted. Set the value
of the init-param named sortedBy to NAME, SIZE, or LAST_MODIFIED. Then redeploy your web
application if it has already been deployed, or restart the server.
<init-param>
<param-name>sortedBy</param-name>
<param-value>LAST_MODIFIED</param-value>
</init-param>
The mime-mapping elements in default-web.xml are global and inherited by all web
applications. You can override these mappings or defne your own using mime-mapping
elements in your web application's web.xml fle. For more information about mime-mapping
elements, see the Servlet specifcation.
You can use the Administration Console to edit the default-web.xml fle. For details, click the
Help button in the Administration Console. As an alternative, you can edit the fle directly using
the following steps.
ToUse the default-web.xml File

Place the JARfle for the flter, security constraint, or other feature inthe domain-dir/lib
directory.
Edit the domain-dir/config/default-web.xml fle torefer tothe JARfle.
Restart the server.
1
2
3
ConfguringLoggingandMonitoringintheWeb
Container
For information about confguring logging and monitoring in the web container using the
Administration Console, click the Help button in the Administration Console. Select Logger
Settings under the relevant confguration, or select the Stand-Alone Instances component,
select the instance fromthe table, and select the Monitor tab.
ConfguringIdempotent URL Requests
An idempotent request is one that does not cause any change or inconsistency in an application
when retried. To enhance the availability of your applications deployed on an GlassFish Server
cluster, confgure the load balancer to retry failed idempotent HTTP requests on all the
GlassFish Server instances in a cluster. This option can be used for read-only requests, for
example, to retry a search request.
Specifying an Idempotent URL on page 139
Characteristics of an Idempotent URL on page 139

SpecifyinganIdempotent URL
To confgure idempotent URL response, specify the URLs that can be safely retried in
idempotent-url-pattern elements in the glassfish-web.xml fle. For example:
<idempotent-url-pattern url-pattern="sun_java/*" no-of-retries="10"/>
For details, see idempotent-url-pattern in Oracle GlassFish Server 3.1 Application Deployment
Guide.
If none of the server instances can successfully serve the request, an error page is returned.
Characteristics of anIdempotent URL
Since all requests for a given session are sent to the same application server instance, and if that
GlassFish Server instance is unreachable, the load balancer returns an error message. Normally,
the request is not retried on another GlassFish Server instance. However, if the URL pattern
matches that specifed in the glassfish-web.xml fle, the request is implicitly retried on
another GlassFish Server instance in the cluster.
In HTTP, some methods (such as GET) are idempotent, while other methods (such as POST)
are not. In efect, retrying an idempotent URL should not cause values to change on the server
or in the database. The only diference should be a change in the response received by the user.
Examples of idempotent requests include search engine queries and database queries. The
underlying principle is that the retry does not cause an update or modifcation of data.
Asearch engine, for example, sends HTTP requests with the same URL pattern to the load
balancer. Specifying the URL pattern of the search request to the load balancer ensures that
HTTP requests with the specifed URL pattern are implicitly retried on another GlassFish
Server instance.
For example, if the request URL sent to the GlassFish Server is of the type
/search/something.html, then the URL pattern can be specifed as /search/*.
Examples of non-idempotent requests include banking transactions and online shopping. If
you retry such requests, money might be transferred twice fromyour account.
Header Management
In all Editions of the GlassFish Server, the Enumeration fromrequest.getHeaders() contains
multiple elements (one element per request header) instead of a single, aggregated value.
The header names used in HttpServletResponse.addXXXHeader() and
HttpServletResponse.setXXXHeader() are returned as they were created.
ConfguringValves andCatalina Listeners
You can confgure customvalves and Catalina listeners for web modules or virtual servers by
defning properties. Avalve class must implement the org.apache.catalina.Valve interface from
Tomcat or previous GlassFish Server releases, or the org.glassfsh.web.valve.GlassFishValve
interface fromthe current GlassFish Server release. Alistener class for a virtual server must
implement the org.apache.catalina.ContainerListener or org.apache.catalina.LifecycleListener
interface. Alistener class for a web module must implement the
org.apache.catalina.ContainerListener, org.apache.catalina.LifecycleListener, or
org.apache.catalina.InstanceListener interface.
In the glassfish-web.xml fle, valve and listener properties for a web module look like this:
<glassfish-web-app ...>
...
<property name="valve_1" value="org.glassfish.extension.Valve"/>
<property name="listener_1" value="org.glassfish.extension.MyLifecycleListener"/>
You can defne these same properties for a virtual server. For more information, see Virtual
Server Properties on page 137.
Alternate Document Roots
An alternate document root (docroot) allows a web application to serve requests for certain
resources fromoutside its own docroot, based on whether those requests match one (or more)
of the URI patterns of the web application's alternate docroots.
To specify an alternate docroot for a web application or a virtual server, use the
alternatedocroot_n property, where n is a positive integer that allows specifcation of more
than one. This property can be a subelement of a glassfish-web-app element in the
glassfish-web.xml fle or a virtual server property. For more information about these
elements, see glassfsh-web-app in Oracle GlassFish Server 3.1 Application Deployment Guide
or .
Avirtual server's alternate docroots are considered only if a request does not map to any of the
web modules deployed on that virtual server. Aweb module's alternate docroots are considered
only once a request has been mapped to that web module.
If a request matches an alternate docroot's URI pattern, it is mapped to the alternate docroot by
appending the request URI (minus the web application's context root) to the alternate docroot's
physical location (directory). If a request matches multiple URI patterns, the alternate docroot
is determined according to the following precedence order:
Exact match
Longest path match
Extension match
For example, the following properties specify three glassfish-web.xml docroots. The URI
pattern of the frst alternate docroot uses an exact match, whereas the URI patterns of the
second and third alternate docroots use extension and longest path prefx matches, respectively.
<property name="alternatedocroot_1" value="from=/my.jpg dir=/srv/images/jpg"/>
<property name="alternatedocroot_2" value="from=*.jpg dir=/srv/images/jpg"/>
<property name="alternatedocroot_3" value="from=/jpg/* dir=/src/images"/>
The value of each alternate docroot has two components: The frst component, from, specifes
the alternate docroot's URI pattern, and the second component, dir, specifes the alternate
docroot's physical location (directory).
Suppose the above examples belong to a web application deployed at
http://company22.com/myapp. The frst alternate docroot maps any requests with this URL:
http://company22.com/myapp/my.jpg
To this resource:
/svr/images/jpg/my.jpg
The second alternate docroot maps any requests with a *.jpg sufx, such as:
http://company22.com/myapp/*.jpg
To this physical location:
/svr/images/jpg
The third alternate docroot maps any requests whose URI starts with /myapp/jpg/, such as:
http://company22.com/myapp/jpg/*
To the same directory as the second alternate docroot.
For example, the second alternate docroot maps this request:
http://company22.com/myapp/abc/def/my.jpg
To:
/srv/images/jpg/abc/def/my.jpg
The third alternate docroot maps:
http://company22.com/myapp/jpg/abc/resource
To:
/srv/images/jpg/abc/resource
If a request does not match any of the target web application's alternate docroots, or if the target
web application does not specify any alternate docroots, the request is served fromthe web
application's standard docroot, as usual.
Usinga context.xml File
You can defne a context.xml fle for all web applications, for web applications assigned to a
specifc virtual server, or for a specifc web application.
To defne a global context.xml fle, place the fle in the domain-dir/config directory and name
it context.xml.
Use the contextXmlDefault property to specify the name and the location, relative to
domain-dir, of the context.xml fle for a specifc virtual server. Specify this property in one of
the following ways:
In the Administration Console, open the HTTP Service component under the relevant
confguration. Open the Virtual Servers component and scroll down to the bottomof the
page. Enter contextXmlDefault as the property name and the path and fle name relative to
domain-dir as the property value.
Use the asadmin create-virtual-server command. For example:

asadmin create-virtual-server --property contextXmlDefault=config/vs1ctx.xml vs1
Use the asadmin set command for an existing virtual server. For example:
asadmin set server-config.http-service.virtual-server.vs1.property.contextXmlDefault=config/myctx.xml
To defne a context.xml fle for a specifc web application, place the fle in the META-INF
directory and name it context.xml.
For more information about virtual server properties, see Virtual Server Properties on
page 137. For more information about the context.xml fle, see The Context Container
(http://tomcat.apache.org/tomcat-5.5-doc/config/context.html). Context parameters,
environment entries, and resource defnitions in context.xml are supported in the GlassFish
Server.
EnablingWebDav
To enable WebDav in the GlassFish Server, you edit the web.xml and glassfish-web.xml fles
as follows.
First, enable the WebDav servlet in your web.xml fle:
<servlet>
<servlet-name>webdav</servlet-name>
<servlet-class>org.apache.catalina.servlets.WebdavServlet</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>listings</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>readonly</param-name>
<param-value>false</param-value>
</init-param>
</servlet>
Then defne the servlet mapping associated with your WebDav servlet in your web.xml fle:
<servlet-mapping>
<servlet-name>webdav</servlet-name>
<url-pattern>/webdav/*</url-pattern>
</servlet-mapping>
To protect the WebDav servlet so other users can't modify it, add a security constraint in your
web.xml fle:
<security-constraint>
<web-resource-collection>
<web-resource-name>Login Resources</web-resource-name>
<url-pattern>/webdav/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>Admin</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>default</realm-name>
</login-config>
<security-role>
</security-role>
</security-constraint>
Then defne a security role mapping in your glassfish-web.xml fle:
<group-name>Admin</group-name>
If you are using the file realm, create a user and password. For example:
asadmin create-file-user --groups Admin --authrealmname default admin
Enable the security manager as described in Enabling and Disabling the Security Manager on
page 61.
You can nowuse any WebDav client by connecting to the WebDav servlet URL, which has this
format:
http://host:port/context-root/webdav/fle
For example:
http://localhost:80/glassfish-webdav/webdav/index.html
You can add the WebDav servlet to your default-web.xml fle to enable it for all applications,
but you can't set up a security role mapping to protect it.
UsingSSI
To enable SSI (server-side includes) processing for a specifc web module, add the SSIServlet
to your web.xml fle as follows:
<web-app>
<servlet>
<servlet-name>ssi</servlet-name>
<servlet-class>org.apache.catalina.ssi.SSIServlet</servlet-class>
</servlet>
...
<servlet-mapping>
<servlet-name>ssi</servlet-name>
<url-pattern>*.shtml</url-pattern>
</servlet-mapping>
...
<mime-mapping>
<extension>shtml</extension>
<mime-type>text/html</mime-type>
</mime-mapping>
</web-app>
To enable SSI processing for all web modules, un-comment the corresponding sections in the
default-web.xml fle.
If the mime-mapping is not specifed in web.xml, GlassFish Server attempts to determine the
MIME type fromdefault-web.xml or the operating systemdefault.
You can confgure the following init-param values for the SSIServlet.
TABLE 74 SSIServlet init-param Values
init-param Type Default Description
bufered boolean false Specifes whether the output should be
bufered.
debug int 0 (for no debugging) Specifes the debugging level.
expires Long Expires header in
HTTP response not
set
Specifes the expiration time in seconds.
inputEncoding String operating system
encoding
Specifes encoding for the SSI input if there is
no URL content encoding specifed.
isVirtualWebappRelative boolean false (relative to the
given SSI fle)
Specifes whether the virtual path of the
#include directive is relative to the
content-root.
outputEncoding String UTF-8 Specifes encoding for the SSI output.
For more information about SSI, see http://httpd.apache.org/docs/2.2/mod/
mod_include.html.
UsingCGI
To enable CGI (common gateway interface) processing for a specifc web module, add the
CGIServlet to your web.xml fle as follows:
<web-app>
<servlet>
<servlet-name>cgi</servlet-name>
<servlet-class>org.apache.catalina.servlets.CGIServlet</servlet-class>
</servlet>
...
<servlet-mapping>
<servlet-name>cgi</servlet-name>
<url-pattern>/cgi-bin/*</url-pattern>
</servlet-mapping>
</web-app>
To enable CGI processing for all web modules, un-comment the corresponding sections in the
default-web.xml fle.
Package the CGI programunder the cgiPathPrefix. The default cgiPathPrefix is
WEB-INF/cgi. For security, it is highly recommended that the contents and binaries of CGI
programs be prohibited fromdirect viewing or download. For information about hiding
directory listings, see Using the default-web.xml File on page 138.
Invoke the CGI programusing a URL of the following format:
http://host:8080/context-root/cgi-bin/cgi-name
For example:
http://localhost:8080/mycontext/cgi-bin/hello
You can confgure the following init-param values for the CGIServlet.
TABLE 75 CGIServlet init-param Values
init-param Type Default Description
cgiPathPrefx String WEB-INF/cgi Specifes the subdirectory containing the
CGI programs.
debug int 0 (for no debugging) Specifes the debugging level.
executable String perl Specifes the executable for running the
CGI script.
parameterEncoding String System.getProperty
("file.encoding",
"UTF-8")
Specifes the parameter's encoding.
passShellEnvironment boolean false Specifes whether to pass shell environment
properties to the CGI program.
To work with a native executable, do the following:
1. Set the value of the init-param named executable to an empty String in the web.xml fle.
2. Make sure the executable has its executable bits set correctly.
3. Use directory deployment to deploy the web module. Do not deploy it as a WARfle,
because the executable bit information is lost during the process of jar and unjar. For more
information about directory deployment, see the Oracle GlassFish Server 3.1 Application
Deployment Guide.
148
Using Enterprise JavaBeans Technology
This chapter describes howEnterprise JavaBeans (EJB) technology is supported in the Oracle
GlassFish Server.
Value Added Features on page 149
EJB Timer Service on page 153
Using Session Beans on page 156
Using Read-Only Beans on page 163
Using Message-Driven Beans on page 167

For general information about enterprise beans, see Part IV, Enterprise Beans, in The Java
EE 6 Tutorial.
jsr/detail?id=318).
The GlassFish Server is backward compatible with 1.1, 2.0, 2.1, and 3.0 enterprise beans.
However, to take advantage of version 3.1 features, you should develop newbeans as 3.1
enterprise beans.
Value AddedFeatures
The GlassFish Server provides a number of value additions that relate to EJB development.
References to more in-depth material are included.
8
C H A P T E R 8
149
Read-Only Beans on page 150
The pass-by-reference Element on page 150
Pooling and Caching on page 151
Priority Based Scheduling of Remote Bean Invocations on page 152
Immediate Flushing on page 152

Read-Only Beans
Another feature that the GlassFish Server provides is the read-only bean, an EJB 2.1 entity bean
that is never modifed by an EJB client. Read-only beans avoid database updates completely.
Note Read-only beans are specifc to the GlassFish Server and are not part of the Enterprise
JavaBeans Specifcation, v2.1. Use of this feature for an EJB 2.1 bean results in a non-portable
application.
To make an EJB 3.0 entity read-only, use @Column annotations to mark its columns
insertable=false and updatable=false.
Aread-only bean can be used to cache a database entry that is frequently accessed but rarely
updated (externally by other beans). When the data that is cached by a read-only bean is
updated by another bean, the read-only bean can be notifed to refresh its cached data.
The GlassFish Server provides a number of ways by which a read-only beans state can be
refreshed. By setting the refresh-period-in-seconds element in the glassfish-ejb-jar.xml
fle and the trans-attribute element (or @TransactionAttribute annotation) in the
ejb-jar.xml fle, it is easy to confgure a read-only bean that is one of the following:
Always refreshed
Periodically refreshed
Never refreshed
Programmatically refreshed
Read-only beans are best suited for situations where the underlying data never changes, or
changes infrequently. For further information and usage guidelines, see Using Read-Only
Beans on page 163.
The pass-by-reference Element
The pass-by-reference element in the glassfish-ejb-jar.xml fle allows you to specify the
parameter passing semantics for colocated remote EJB invocations. This is an opportunity to
improve performance. However, use of this feature results in non-portable applications. See
pass-by-reference in Oracle GlassFish Server 3.1 Application Deployment Guide.
Value Added Features
PoolingandCaching
The EJB container of the GlassFish Server pools anonymous instances (message-driven beans,
stateless session beans, and entity beans) to reduce the overhead of creating and destroying
objects. The EJB container maintains the free pool for each bean that is deployed. Bean
instances in the free pool have no identity (that is, no primary key associated) and are used to
serve method calls. The free beans are also used to serve all methods for stateless session beans.
Bean instances in the free pool transition froma Pooled state to a Cached state after ejbCreate
and the business methods run. The size and behavior of each pool is controlled using
pool-related properties in the EJB container or the glassfish-ejb-jar.xml fle.
In addition, the GlassFish Server supports a number of tunable parameters that can control the
number of stateful instances (stateful session beans and entity beans) cached as well as the
duration they are cached. Multiple bean instances that refer to the same database rowin a table
can be cached. The EJB container maintains a cache for each bean that is deployed.
To achieve scalability, the container selectively evicts some bean instances fromthe cache,
usually when cache overfows. These evicted bean instances return to the free bean pool. The
size and behavior of each cache can be controlled using the cache-related properties in the EJB
container or the glassfish-ejb-jar.xml fle.
Pooling and caching parameters for the glassfish-ejb-jar.xml fle are described in
bean-cache in Oracle GlassFish Server 3.1 Application Deployment Guide.
PoolingParameters
One of the most important parameters for GlassFish Server pooling is steady-pool-size.
When steady-pool-size is set to a value greater than 0, the container not only pre-populates
the bean pool with the specifed number of beans, but also attempts to ensure that this number
of beans is always available in the free pool. This ensures that there are enough beans in the
ready-to-serve state to process user requests.
Note that the steady-pool-size and max-pool-size parameters only govern the number of
instances that are pooled over a long period of time. They do not necessarily guarantee that the
number of instances that may exist in the JVMat a given time will not exceed the value specifed
by max-pool-size. For example, suppose an idle stateless session container has a
fully-populated pool with a steady-pool-size of 10. If 20 concurrent requests arrive for the
EJB component, the container creates 10 additional instances to satisfy the burst of requests.
The advantage of this is that it prevents the container fromblocking any of the incoming
requests. However, if the activity dies down to 10 or fewer concurrent requests, the additional
10 instances are discarded.
Another parameter, pool-idle-timeout-in-seconds, allows the administrator to specify the
amount of time a bean instance can be idle in the pool. When pool-idle-timeout-in-seconds
is set to greater than 0, the container removes or destroys any bean instance that is idle for this
specifed duration.
Chapter 8 Using Enterprise JavaBeans Technology 151
CachingParameters
GlassFish Server provides a way that completely avoids caching of entity beans, using commit
option C. Commit option Cis particularly useful if beans are accessed in large number but very
rarely reused. For additional information, refer to Commit Options on page 269.
The GlassFish Server caches can be either bounded or unbounded. Bounded caches have limits
on the number of beans that they can hold beyond which beans are passivated. For stateful
session beans, there are three ways (LRU, NRUand FIFO) of picking victimbeans when cache
overfowoccurs. Caches can also passivate beans that are idle (not accessed for a specifed
duration).
Priority BasedSchedulingof Remote BeanInvocations
You can create multiple thread pools, each having its own work queues. An optional element in
the glassfish-ejb-jar.xml fle, use-thread-pool-id, specifes the thread pool that processes
the requests for the bean. The bean must have a remote interface, or use-thread-pool-id is
ignored. You can create diferent thread pools and specify the appropriate thread pool IDfor a
bean that requires a quick response time. If there is no such thread pool confgured or if the
element is absent, the default thread pool is used.
Immediate Flushing
Normally, all entity bean updates within a transaction are batched and executed at the end of
the transaction. The only exception is the database fush that precedes execution of a fnder or
select query.
Since a transaction often spans many method calls, you might want to fnd out if the updates
made by a method succeeded or failed immediately after method execution. To force a fush at
the end of a methods execution, use the flush-at-end-of-method element in the
glassfish-ejb-jar.xml fle. Only non-fnder methods in an entity bean can be fush-enabled.
(For an EJB 2.1 bean, these methods must be in the Local, Local Home, Remote, or Remote
Home interface.) See fush-at-end-of-method in Oracle GlassFish Server 3.1 Application
Deployment Guide.
Upon completion of the method, the EJB container updates the database. Any exception
thrown by the underlying data store is wrapped as follows:
If the method that triggered the fush is a create method, the exception is wrapped with
CreateException.
If the method that triggered the fush is a remove method, the exception is wrapped with
RemoveException.
For all other methods, the exception is wrapped with EJBException.

All normal end-of-transaction database synchronization steps occur regardless of whether the
database has been fushed during the transaction.
EJBTimer Service
The EJB Timer Service uses a database to store persistent information about EJB timers. The
EJB Timer Service in GlassFish Server is preconfgured to use an embedded version of the Java
DB database.
The EJB Timer Service confguration can store persistent timer information in any database
supported by the GlassFish Server for persistence. For a list of the JDBCdrivers currently
supported by the GlassFish Server, see the Oracle GlassFish Server 3.1-3.1.1 Release Notes. For
confgurations of supported and other drivers, see Confguration Specifcs for JDBCDrivers
in Oracle GlassFish Server 3.1 Administration Guide.
The timer service is automatically enabled when you deploy an application or module that uses
it. You can verify that the timer service is running by accessing the following URL:
http://localhost:8080/ejb-timer-service-app/timer
To change the database used by the EJB Timer Service, set the EJB Timer Services Timer
DataSource setting to a valid JDBCresource. If the EJB Timer Service has already been started
in a server instance, you must also create the timer database table. DDL fles are located in
as-install/lib/install/databases.
Using the EJB Timer Service is equivalent to interacting with a single JDBCresource manager.
If an EJB component or application accesses a database either directly through JDBCor
indirectly (for example, through an entity beans persistence mechanism), and also interacts
with the EJB Timer Service, its data source must be confgured with an XAJDBCdriver.
You can change the following EJB Timer Service settings. You must restart the server for the
changes to take efect.
MinimumDelivery Interval
Specifes the minimumtime in milliseconds before an expiration for a particular timer can
occur. This guards against extremely small timer increments that can overload the server.
The default is 1000.
MaximumRedeliveries
Specifes the maximumnumber of times the EJB timer service attempts to redeliver a timer
expiration after an exception or rollback of a container-managed transaction. The default is
1.
Redelivery Interval
Specifes howlong in milliseconds the EJB timer service waits after a failed ejbTimeout
delivery before attempting a redelivery. The default is 5000.
EJBTimer Service
Timer DataSource
Specifes the database used by the EJB Timer Service. The default is jdbc/__TimerPool.
Caution Do not use the jdbc/__TimerPool resource for timers in clustered GlassFish Server
environments. You must instead use a customJDBCresource or the jdbc/__default
resource. See the instructions below, in To Deploy an EJB Timer to a Cluster on page 154.
Also refer to Enabling the jdbc/__default Resource in a Clustered Environment in Oracle
GlassFish Server 3.1 Administration Guide.
For information about the asadmin list-timers and asadmin migrate-timers
subcommands, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual. For information
about migrating EJB timers, see Migrating EJB Timers in Oracle GlassFish Server 3.1-3.1.1
High Availability Administration Guide.
You can use the --keepstate option of the asadmin redeploy command to retain EJB timers
between redeployments.
When the --keepstate is set to true, each application that uses an EJB timer is assigned an ID
in the timer database. The EJB object that is associated with a given application is assigned an
IDthat is constructed fromthe application IDand a numerical sufx. To preserve active timer
data, GlassFish Server stores the application IDand the EJB IDin the timer database. To restore
the data, the class loader of the newly redeployed application retrieves the EJB timers that
correspond to these IDs fromthe timer database.
For more information about the asadmin redeploy command, see the Oracle GlassFish
ToDeploy anEJBTimer toa Cluster

This procedure explains howto deploy an EJB timer to a cluster.
By default, the GlassFish Server 3.1 timer service points to the preconfgured
jdbc/__TimerPool resource, which uses an embedded Java DB (Derby) database confguration
that will not work in clustered environments.
The problemis that embedded Java DB runs in the GlassFish Server Java VM, so when you use
the jdbc/__TimerPool resource, each DAS and each clustered server instance will have its own
database table. Because of this, clustered server instances will not be able to fnd the database
table on the DAS, and the DAS will not be able to fnd the tables on the clustered server
instances.
EJBTimer Service
The solution is to use either a customJDBCresource or the jdbc/__default resource that is
preconfgured but not enabled by default in GlassFish Server. The jdbc/__default resource
does not use embedded Java DB by default.
If creating a newtimer resource, the resource should be created before deploying applications
that will use the timer.
Caution Do not use the jdbc/__TimerPool resource for timers in clustered GlassFish Server
environments. You must instead use a customJDBCresource or the jdbc/__default resource.
See Enabling the jdbc/__default Resource in a Clustered Environment in Oracle GlassFish
Execute the followingcommand:
asadmin set configs.config.cluster_name-config.ejb-container.ejb-timer-service.timer-
datasource=jdbc/my-timer-resource
Restart the DAS andthe target cluster(s).
asadmin stop-cluster cluster-name
asadmin stop-domain domain-name
asadmin start-domain domain-name
asadmin start-cluster cluster-name
If you inadvertently used the jdbc/__TimerPool resource for your EJB timer in a clustered
GlassFish Server environment, the DAS and the clustered server instances will be using separate
Java DB database tables that are running in individual Java VMs. For timers to work in a
clustered environment, the DAS and the clustered server instances must share a common
database table.
If you attempt to deploy an application with EJB timers without setting the timer resource
correctly, the startup will fail, and you will be left with a marker fle, named
ejb-timer-service-app, on the DAS that will prevent the Timer Service fromcorrectly
creating the database table.
The solution is to remove the marker fle on the DAS, restart the DAS and the clusters, and then
redploy any applications that rely on the ofending EJB timer. The marker fle is located on the
DAS in as-install-parent/glassfish/domains/domain-name/generated/ejb/
ejb-timer-service-app.
BeforeYouBegin
1
2
Troubleshooting
EJBTimer Service
UsingSessionBeans
This section provides guidelines for creating session beans in the GlassFish Server environment.
About the Session Bean Containers on page 156
Stateful Session Bean Failover on page 157
Session Bean Restrictions and Optimizations on page 162

Information on session beans is contained in the Enterprise JavaBeans Specifcation, v3.1.
About the SessionBeanContainers
Like an entity bean, a session bean can access a database through Java Database Connectivity
(JDBC) calls. Asession bean can also provide transaction settings. These transaction settings
and JDBCcalls are referenced by the session beans container, allowing it to participate in
transactions managed by the container.
Acontainer managing stateless session beans has a diferent charter froma container managing
stateful session beans.
Stateless Container on page 156
Stateful Container on page 157

Stateless Container
The stateless container manages stateless session beans, which, by defnition, do not carry
client-specifc states. All session beans (of a particular type) are considered equal.
Astateless session bean container uses a bean pool to service requests. The GlassFish Server
specifc deployment descriptor fle, glassfish-ejb-jar.xml, contains the properties that
defne the pool:
steady-pool-size
resize-quantity
max-pool-size
pool-idle-timeout-in-seconds
For more information about glassfish-ejb-jar.xml, see The glassfsh-ejb-jar.xml File in
The GlassFish Server provides the wscompile and wsdeploy tools to help you implement a web
service endpoint as a stateless session bean. For more information about these tools, see the
Using Session Beans
Stateful Container
The stateful container manages the stateful session beans, which, by defnition, carry the
client-specifc state. There is a one-to-one relationship between the client and the stateful
session beans. At creation, each stateful session bean (SFSB) is given a unique session IDthat is
used to access the session bean so that an instance of a stateful session bean is accessed by a
single client only.
Stateful session beans are managed using cache. The size and behavior of stateful session beans
cache are controlled by specifying the following glassfish-ejb-jar.xml parameters:
max-cache-size
resize-quantity
cache-idle-timeout-in-seconds
removal-timeout-in-seconds
victim-selection-policy
The max-cache-size element specifes the maximumnumber of session beans that are held in
cache. If the cache overfows (when the number of beans exceeds max-cache-size), the
container then passivates some beans or writes out the serialized state of the bean into a fle. The
directory in which the fle is created is obtained fromthe EJB container using the confguration
APIs.
The passivated beans are stored on the fle system. The Session Store Location setting in the EJB
container allows the administrator to specify the directory where passivated beans are stored.
By default, passivated stateful session beans are stored in application-specifc subdirectories
created under domain-dir/session-store.
Note Make sure the delete option is set in the server.policy fle, or expired fle-based
sessions might not be deleted properly. For more information about server.policy, see The
The Session Store Location setting also determines where the session state is persisted if it is not
highly available; see Choosing a Persistence Store on page 159.
Stateful SessionBeanFailover
An SFSBs state can be saved in a persistent store in case a server instance fails. The state of an
SFSB is saved to the persistent store at predefned points in its life cycle. This is called
checkpointing. If SFSB checkpointing is enabled, checkpointing generally occurs after any
transaction involving the SFSB is completed, even if the transaction rolls back.
Using Session Beans
However, if an SFSB participates in a bean-managed transaction, the transaction might be
committed in the middle of the execution of a bean method. Since the beans state might be
undergoing transition as a result of the method invocation, this is not an appropriate instant to
checkpoint the beans state. In this case, the EJB container checkpoints the beans state at the end
of the corresponding method, provided the bean is not in the scope of another transaction when
that method ends. If a bean-managed transaction spans across multiple methods,
checkpointing is delayed until there is no active transaction at the end of a subsequent method.
The state of an SFSB is not necessarily transactional and might be signifcantly modifed as a
result of non-transactional business methods. If this is the case for an SFSB, you can specify a list
of checkpointed methods. If SFSB checkpointing is enabled, checkpointing occurs after any
checkpointed methods are completed.
The following table lists the types of references that SFSB failover supports. All objects bound
into an SFSB must be one of the supported types. In the table, No indicates that failover for the
object type might not work in all cases and that no failover support is provided. However,
failover might work in some cases for that object type. For example, failover might work
because the class implementing that type is serializable.
TABLE 81 Object Types Supported for Java EE Stateful Session Bean State Failover
Colocated or distributed stateless session, stateful
session, or entity bean reference
Yes
JNDI context Yes, InitialContext and java:comp/env
UserTransaction Yes, but if the instance that fails is never restarted, any
prepared global transactions are lost and might not be
correctly rolled back or committed.
JDBCDataSource No
Java Message Service (JMS) ConnectionFactory,
Destination
No
JavaMail Session No
Connection Factory No
Administered Object No
Web service reference No
Serializable Java types Yes
Extended persistence context No
Using Session Beans
For more information about the InitialContext, see Accessing the Naming Context on
page 273. For more information about transaction recovery, see Chapter 15, Using the
Transaction Service. For more information about Administered Objects, see Administering
JMS Physical Destinations in Oracle GlassFish Server 3.1 Administration Guide.
Note Idempotent URLs are supported along the HTTP path, but not the RMI-IIOP path. For
more information, see Confguring Idempotent URL Requests on page 139.
If a server instance to which an RMI-IIOP client request is sent crashes during the request
processing (before the response is prepared and sent back to the client), an error is sent to the
client. The client must retry the request explicitly. When the client retries the request, the
request is sent to another server instance in the cluster, which retrieves session state
information for this client.
HTTP sessions can also be saved in a persistent store in case a server instance fails. In addition,
if a distributable web application references an SFSB, and the web applications session fails
over, the EJB reference is also failed over. For more information, see Distributed Sessions and
Persistence on page 116.
If an SFSB that uses session persistence is undeployed while the GlassFish Server instance is
stopped, the session data in the persistence store might not be cleared. To prevent this,
undeploy the SFSB while the GlassFish Server instance is running.
Confgure SFSB failover by:
Choosing a Persistence Store on page 159
Enabling Checkpointing on page 161
Specifying Methods to Be Checkpointed on page 161

Choosinga Persistence Store
The following types of persistent storage are supported for passivation and checkpointing of the
SFSB state:
The local fle system- Allows a single server instance to recover the SFSB state after a failure
and restart. This store also provides passivation and activation of the state to help control
the amount of memory used. This option is not supported in a production environment that
requires SFSB state persistence. This is the default storage mechanismif availability is not
enabled.
Other servers - Uses other server instances in the cluster for session persistence. Clustered
server instances replicate session state. Each backup instance stores the replicated data in
memory. This is the default storage mechanismif availability is enabled.
Using Session Beans
Choose the persistence store in one of the following ways:
To use the local fle system, frst disable availability. Select the Availability Service
component under the relevant confguration in the Administration Console. Uncheck the
Availability Service box. Then select the EJB Container component and edit the Session
Store Location value. The default is domain-dir/session-store.
To use other servers, select the Availability Service component under the relevant
confguration in the Administration Console. Check the Availability Service box. To enable
availability for the EJB container, select the EJB Container Availability tab, then check the
Availability Service box. All instances in an GlassFish Server cluster should have the same
availability settings to ensure consistent behavior.
For more information about SFSB state persistence, see the Oracle GlassFish Server 3.1-3.1.1
High Availability Administration Guide.
Usingthe --keepstate Option
If you are using the fle systemfor persistence, you can use the --keepstate option of the
asadmin redeploy command to retain the SFSB state between redeployments.
Some changes to an application between redeployments prevent this feature fromworking
properly. For example, do not change the set of instance variables in the SFSB bean class.
If any active SFSB instance fails to be preserved or restored, none of the SFSB instances will be
available when the redeployment is complete. However, the redeployment continues and a
warning is logged.
To preserve active state data, GlassFish Server serializes the data and saves it in memory. To
restore the data, the class loader of the newly redeployed application deserializes the data that
was previously saved.
For more information about the asadmin redeploy command, see the Oracle GlassFish
Usingthe --asyncreplicationOption
If you are using replication on other servers for persistence, you can use the
--asyncreplication option of the asadmin deploy command to specify that SFSB states are
frst bufered and then replicated using a separate asynchronous thread. If
--asyncreplication is set to true (default), performance is improved but availability is
reduced. If the instance where states are bufered but not yet replicated fails, the states are lost. If
set to false, performance is reduced but availability is guaranteed. States are not bufered but
immediately transmitted to other instances in the cluster.
Using Session Beans
For more information about the asadmin deploy command, see the Oracle GlassFish
EnablingCheckpointing
The following sections describe howto enable SFSB checkpointing:
Server Instance and EJB Container Levels on page 161
Application and EJB Module Levels on page 161
SFSB Level on page 161

Server Instance andEJBContainer Levels
To enable SFSB checkpointing at the server instance or EJB container level, see Choosing a
Persistence Store on page 159.
ApplicationandEJBModule Levels
To enable SFSB checkpointing at the application or EJB module level during deployment, use
the asadmin deploy or asadmin deploydir command with the --availabilityenabled
option set to true. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
SFSBLevel
To enable SFSB checkpointing at the SFSB level, set availability-enabled="true" in the ejb
element of the SFSBs glassfish-ejb-jar.xml fle as follows:
<glassfish-ejb-jar>
...
<enterprise-beans>
...
<ejb availability-enabled="true">
<ejb-name>MySFSB</ejb-name>
</ejb>
...
</enterprise-beans>
SpecifyingMethods toBe Checkpointed
If SFSB checkpointing is enabled, checkpointing generally occurs after any transaction
involving the SFSB is completed, even if the transaction rolls back.
To specify additional optional checkpointing of SFSBs at the end of non-transactional business
methods that cause important modifcations to the beans state, use the
checkpoint-at-end-of-method element within the ejb element in glassfish-ejb-jar.xml.
For example:
Using Session Beans
<glassfish-ejb-jar>
...
<enterprise-beans>
...
<ejb availability-enabled="true">
<ejb-name>ShoppingCartEJB</ejb-name>
<checkpoint-at-end-of-method>
<method>
<method-name>addToCart</method-name>
</method>
</checkpoint-at-end-of-method>
</ejb>
...
</enterprise-beans>
For details, see checkpoint-at-end-of-method in Oracle GlassFish Server 3.1 Application
Deployment Guide.
The non-transactional methods in the checkpoint-at-end-of-method element can be the
following:
create methods defned in the home or business interface of the SFSB, if you want to
checkpoint the initial state of the SFSB immediately after creation
For SFSBs using container managed transactions only, methods in the remote interface of
the bean marked with the transaction attribute TX_NOT_SUPPORTEDor TX_NEVER
For SFSBs using bean managed transactions only, methods in which a bean managed
transaction is neither started nor committed
Any other methods mentioned in this list are ignored. At the end of invocation of each of these
methods, the EJB container saves the state of the SFSB to persistent store.
Note If an SFSB does not participate in any transaction, and if none of its methods are explicitly
specifed in the checkpoint-at-end-of-method element, the beans state is not checkpointed at
all even if availability-enabled="true" for this bean.
For better performance, specify a small subset of methods. The methods chosen should
accomplish a signifcant amount of work in the context of the Java EE application or should
result in some important modifcation to the beans state.
SessionBeanRestrictions andOptimizations
This section discusses restrictions on developing session beans and provides some optimization
guidelines.
Optimizing Session Bean Performance on page 163
Restricting Transactions on page 163
EJB Singletons on page 163

Using Session Beans
OptimizingSessionBeanPerformance
For stateful session beans, colocating the stateful beans with their clients so that the client and
bean are executing in the same process address space improves performance.
RestrictingTransactions
The following restrictions on transactions are enforced by the container and must be observed
as session beans are developed:
Asession bean can participate in, at most, a single transaction at a time.
If a session bean is participating in a transaction, a client cannot invoke a method on the

bean such that the trans-attribute element (or @TransactionAttribute annotation) in
the ejb-jar.xml fle would cause the container to execute the method in a diferent or
unspecifed transaction context or an exception is thrown.
If a session bean instance is participating in a transaction, a client cannot invoke the remove
method on the session objects home or business interface object, or an exception is thrown.
EJBSingletons
EJB Singletons are created for each server instance in a cluster, and not once per cluster.
UsingRead-Only Beans
Aread-only bean is an EJB 2.1 entity bean that is never modifed by an EJB client. The data that a
read-only bean represents can be updated externally by other enterprise beans, or by other
means, such as direct database updates.
application.
To make an EJB 3.0 entity bean read-only, use @Column annotations to mark its columns
insertable=false and updatable=false.
changes infrequently.
Read-Only Bean Characteristics and Life Cycle on page 164
Read-Only Bean Good Practices on page 165
Refreshing Read-Only Beans on page 165

Using Read-Only Beans
Deploying Read-Only Beans on page 166

Read-Only BeanCharacteristics andLife Cycle
changes infrequently. For example, a read-only bean can be used to represent a stock quote for a
particular company, which is updated externally. In such a case, using a regular entity bean
might incur the burden of calling ejbStore, which can be avoided by using a read-only bean.
Read-only beans have the following characteristics:
Only entity beans can be read-only beans.
Either bean-managed persistence (BMP) or container-managed persistence (CMP) is

allowed. If CMP is used, do not create the database schema during deployment. Instead,
work with your database administrator to populate the data into the tables. See Chapter 9,
Using Container-Managed Persistence.
Only container-managed transactions are allowed; read-only beans cannot start their own
transactions.
Read-only beans dont update any bean state.
ejbStore is never called by the container.
ejbLoad is called only when a transactional method is called or when the bean is initially
created (in the cache), or at regular intervals controlled by the beans
refresh-period-in-seconds element in the glassfish-ejb-jar.xml fle.
The home interface can have any number of fnd methods. The return type of the fnd
methods must be the primary key for the same bean type (or a collection of primary keys).
If the data that the bean represents can change, then refresh-period-in-seconds must be
set to refresh the beans at regular intervals. ejbLoad is called at this regular interval.
Aread-only bean comes into existence using the appropriate fnd methods.
Read-only beans are cached and have the same cache properties as entity beans. When a
read-only bean is selected as a victimto make roomin the cache, ejbPassivate is called and the
bean is returned to the free pool. When in the free pool, the bean has no identity and is used
only to serve any fnder requests.
Read-only beans are bound to the naming service like regular read-write entity beans, and
clients can look up read-only beans the same way read-write entity beans are looked up.
Read-Only BeanGoodPractices
For best results, followthese guidelines when developing read-only beans:
Avoid having any create or remove methods in the home interface.
Use any of the valid EJB 2.1 transaction attributes for the trans-attribute element.
The reason for having TX_SUPPORTED is to allowreading uncommitted data in the same
transaction. Also, the transaction attributes can be used to force ejbLoad.
RefreshingRead-Only Beans
There are several ways of refreshing read-only beans, as addressed in the following sections:
Invoking a Transactional Method on page 165
Refreshing Periodically on page 165
Refreshing Programmatically on page 166

InvokingaTransactional Method
Invoking any transactional method invokes ejbLoad.
RefreshingPeriodically
Use the refresh-period-in-seconds element in the glassfish-ejb-jar.xml fle to refresh a
read-only bean periodically.
If the value specifed in refresh-period-in-seconds is zero or not specifed, which is the

default, the bean is never refreshed (unless a transactional method is accessed).
If the value is greater than zero, the bean is refreshed at the rate specifed.
Note This is the only way to refresh the bean state if the data can be modifed external to the
GlassFish Server.
By default, a single timer is used for all instances of a read-only bean. When that timer fres, all
bean instances are marked as expired and are refreshed fromthe database the next time they are
used.
Use the -Dcom.sun.ejb.containers.readonly.relative.refresh.mode=true fag to refresh
each bean instance independently upon access if its refresh period has expired. The default is
false. Note that each instance still has the same refresh period. This additional level of
granularity can improve the performance of read-only beans that do not need to be refreshed at
the same time.
To set this fag, use the asadmin create-jvm-options command. For example:
asadmin create-jvm-options -Dcom.sun.ejb.containers.readonly.relative.refresh.mode=true
RefreshingProgrammatically
Typically, beans that update any data that is cached by read-only beans need to notify the
read-only beans to refresh their state. Use ReadOnlyBeanNotifer to force the refresh of
read-only beans.
To do this, invoke the following methods on the ReadOnlyBeanNotifer bean:
public interface ReadOnlyBeanNotifier extends java.rmi.Remote {
refresh(Object PrimaryKey) throws RemoteException;
}
The implementation of the ReadOnlyBeanNotifer interface is provided by the container. The
bean looks up ReadOnlyBeanNotifer using a fragment of code such as the following example:
com.sun.appserv.ejb.ReadOnlyBeanHelper helper =
new com.sun.appserv.ejb.ReadOnlyBeanHelper();
com.sun.appserv.ejb.ReadOnlyBeanNotifier notifier =
helper.getReadOnlyBeanNotifier("java:comp/env/ejb/ReadOnlyCustomer");
notifier.refresh(PrimaryKey);
For a local read-only bean notifer, the lookup has this modifcation:
helper.getReadOnlyBeanLocalNotifier("java:comp/env/ejb/LocalReadOnlyCustomer");
Beans that update any data that is cached by read-only beans need to call the refresh methods.
The next (non-transactional) call to the read-only bean invokes ejbLoad.
For Javadoc tool pages relevant to read-only beans, go to http://glassfish.java.net/nonav/
docs/v3/api/ and click on the com.sun.appserv.ejb package.
DeployingRead-Only Beans
Read-only beans are deployed in the same manner as other entity beans. However, in the entry
for the bean in the glassfish-ejb-jar.xml fle, the is-read-only-bean element must be set
to true. That is:
<is-read-only-bean>true</is-read-only-bean>
Also, the refresh-period-in-seconds element in the glassfish-ejb-jar.xml fle can be set
to some value that specifes the rate at which the bean is refreshed. If this element is missing, no
refresh occurs.
All requests in the same transaction context are routed to the same read-only bean instance. Set
the allow-concurrent-access element to either true (to allowconcurrent accesses) or false
(to serialize concurrent access to the same read-only bean). The default is false.
For further information on these elements, refer to The glassfsh-ejb-jar.xml File in Oracle
UsingMessage-DrivenBeans
This section describes message-driven beans and explains the requirements for creating themin
the GlassFish Server environment.
Message-Driven Bean Confguration on page 167
Message-Driven Bean Restrictions and Optimizations on page 168

Message-DrivenBeanConfguration
Connection Factory and Destination on page 167
Message-Driven Bean Pool on page 167
Domain-Level Settings on page 168

For information about setting up load balancing for message-driven beans, see Load-Balanced
Message Infow on page 284.
ConnectionFactory andDestination
Amessage-driven bean is a client to a Connector inbound resource adapter. The
message-driven bean container uses the JMS service integrated into the GlassFish Server for
message-driven beans that are JMS clients. JMS clients use JMS Connection Factory- and
Destination-administered objects. AJMS Connection Factory administered object is a resource
manager Connection Factory object that is used to create connections to the JMS provider.
The mdb-connection-factory element in the glassfish-ejb-jar.xml fle for a
message-driven bean specifes the connection factory that creates the container connection to
the JMS provider.
The jndi-name element of the ejb element in the glassfish-ejb-jar.xml fle specifes the
JNDI name of the administered object for the JMS Queue or Topic destination that is associated
with the message-driven bean.
Message-DrivenBeanPool
The container manages a pool of message-driven beans for the concurrent processing of a
streamof messages. The glassfish-ejb-jar.xml fle contains the elements that defne the
pool (that is, the bean-pool element):
Using Message-Driven Beans
steady-pool-size
resize-quantity
max-pool-size
pool-idle-timeout-in-seconds
Domain-Level Settings
You can control the following domain-level message-driven bean settings in the EJB container:
Initial and MinimumPool Size
Specifes the initial and minimumnumber of beans maintained in the pool. The default is 0.
MaximumPool Size
Specifes the maximumnumber of beans that can be created to satisfy client requests. The
default is 32.
Pool Resize Quantity
Specifes the number of beans to be created if a request arrives when the pool is empty
(subject to the Initial and MinimumPool Size), or the number of beans to remove if idle for
more than the Idle Timeout. The default is 8.
Idle Timeout
Specifes the maximumtime in seconds that a bean can remain idle in the pool. After this
amount of time, the bean is destroyed. The default is 600 (10 minutes). Avalue of 0 means a
bean can remain idle indefnitely.
For information on monitoring message-driven beans, click the Help button in the
Administration Console. Select the Stand-Alone Instances component, select the instance from
the table, and select the Monitor tab. Or select the Clusters component, select the cluster from
the table, select the Instances tab, select the instance fromthe table, and select the Monitor tab.
Note Running monitoring when it is not needed might impact performance, so you might
choose to turn monitoring of when it is not in use. For details, see Chapter 8, Administering
the Monitoring Service, in Oracle GlassFish Server 3.1 Administration Guide.
Message-DrivenBeanRestrictions andOptimizations
This section discusses the following restrictions and performance optimizations that pertain to
developing message-driven beans:
Pool Tuning and Monitoring on page 169
The onMessage Runtime Exception on page 169

Pool TuningandMonitoring
The message-driven bean pool is also a pool of threads, with each message-driven bean instance
in the pool associating with a server session, and each server session associating with a thread.
Therefore, a large pool size also means a high number of threads, which impacts performance
and server resources.
When confguring message-driven bean pool properties, make sure to consider factors such as
message arrival rate and pattern, onMessage method processing time, overall server resources
(threads, memory, and so on), and any concurrency requirements and limitations fromother
resources that the message-driven bean accesses.
When tuning performance and resource usage, make sure to consider potential JMS provider
properties for the connection factory used by the container (the mdb-connection-factory
element in the glassfish-ejb-jar.xml fle). For example, you can tune the GlassFish Server
Message Queue fowcontrol related properties for connection factory in situations where the
message incoming rate is much higher than max-pool-size can handle.
Refer to Chapter 8, Administering the Monitoring Service, in Oracle GlassFish Server 3.1
Administration Guide for information on howto get message-driven bean pool statistics.
The onMessage Runtime Exception
Message-driven beans, like other well-behaved MessageListeners, should not, in general, throw
runtime exceptions. If a message-driven beans onMessage method encounters a system-level
exception or error that does not allowthe method to successfully complete, the Enterprise
JavaBeans Specifcation, v3.0 provides the following guidelines:
If the bean method encounters a runtime exception or error, it should simply propagate the
error fromthe bean method to the container.
If the bean method performs an operation that results in a checked exception that the bean
method cannot recover, the bean method should throwthe javax.ejb.EJBException that
wraps the original exception.
Any other unexpected error conditions should be reported using javax.ejb.EJBException

(javax.ejb.EJBException is a subclass of java.lang.RuntimeException).
Under container-managed transaction demarcation, upon receiving a runtime exception from
a message-driven beans onMessage method, the container rolls back the container-started
transaction and the message is redelivered. This is because the message delivery itself is part of
the container-started transaction. By default, the GlassFish Server container closes the
containers connection to the JMS provider when the frst runtime exception is received froma
message-driven bean instances onMessage method. This avoids potential message redelivery
looping and protects server resources if the message-driven beans onMessage method
continues misbehaving. To change this default container behavior, use the
cmt-max-runtime-exceptions property of the MDB container. Here is an example asadmin
set command that sets this property:
asadmin set server-config.mdb-container.property.cmt-max-runtime-exceptions="5"
The cmt-max-runtime-exceptions property specifes the maximumnumber of runtime
exceptions allowed froma message-driven beans onMessage method before the container starts
to close the containers connection to the message source. By default this value is 1; -1 disables
this container protection.
Amessage-driven beans onMessage method can use the
javax.jms.Message.getJMSRedelivered method to check whether a received message is a
redelivered message.
Note The cmt-max-runtime-exceptions property is deprecated.
Using Container-Managed Persistence
This chapter contains information on howEJB 2.1 container-managed persistence (CMP)
works in Oracle GlassFish Server.
GlassFish Server Support for CMP on page 171
CMP Mapping on page 172
Automatic Schema Generation for CMP on page 177
Schema Capture on page 182
Confguring the CMP Resource on page 184
Performance-Related Features on page 184
Confguring Queries for 1.1 Finders on page 187
CMP Restrictions and Optimizations on page 191

jsr/detail?id=318).
GlassFishServer Support for CMP
GlassFish Server support for EJB 2.1 CMP beans includes:
Full support for the J2EE v1.4 specifcations CMP model. Extensive information on CMP is
contained in chapters 10, 11, and 14 of the Enterprise JavaBeans Specifcation, v2.1. This
includes the following:
Support for commit options B and Cfor transactions. See Commit Options on
page 269.
9
C H A P T E R 9
171
The primary key class must be a subclass of java.lang.Object. This ensures portability,
and is noted because some vendors allowprimitive types (such as int) to be used as the
primary key class.
The GlassFish Server CMP implementation, which provides the following:
An Object/Relational (O/R) mapping tool that creates XML deployment descriptors for
EJB JARfles that contain beans that use CMP.
Support for compound (multi-column) primary keys.
Support for sophisticated customfnder methods.
Standards-based query language (EJB QL).
CMP runtime support. See Confguring the CMP Resource on page 184.
GlassFish Server performance-related features, including the following:
Version column consistency checking
Relationship prefetching
Read-Only Beans
For details, see Performance-Related Features on page 184.
CMPMapping
Implementation for entity beans that use CMP is mostly a matter of mapping CMP felds and
CMRfelds (relationships) to the database.
Mapping Capabilities on page 172
The Mapping Deployment Descriptor File on page 173
Mapping Considerations on page 174

MappingCapabilities
Mapping refers to the ability to tie an object-based model to a relational model of data, usually
the schema of a relational database. The CMP implementation provides the ability to tie a set of
interrelated beans containing data and associated behaviors to the schema. This object
representation of the database becomes part of the Java application. You can also customize this
mapping to optimize these beans for the particular needs of an application. The result is a single
data model through which both persistent database information and regular transient program
data are accessed.
The mapping capabilities provided by the GlassFish Server include:
Mapping a CMP bean to one or more tables

CMP Mapping
Mapping CMP felds to one or more columns
Mapping CMP felds to diferent column types
Mapping tables with compound primary keys
Mapping tables with unknown primary keys
Mapping CMP relationships to foreign keys
Mapping tables with overlapping primary and foreign keys

The MappingDeployment Descriptor File
Each module with CMP beans must have the following fles:
ejb-jar.xml The J2EE standard fle for assembling enterprise beans. For a detailed
description, see the Enterprise JavaBeans Specifcation, v2.1.
glassfish-ejb-jar.xml The GlassFish Server standard fle for assembling enterprise

beans. For a detailed description, see The glassfsh-ejb-jar.xml File in Oracle GlassFish
sun-cmp-mappings.xml The mapping deployment descriptor fle, which describes the

mapping of CMP beans to tables in a database. For a detailed description, see The
sun-cmp-mappings.xml File in Oracle GlassFish Server 3.1 Application Deployment Guide.
The sun-cmp-mappings.xml fle can be automatically generated and does not have to exist prior
to deployment. For details, see Generation Options for CMP on page 179.
The sun-cmp-mappings.xml fle maps CMP felds and CMRfelds (relationships) to the
database. Aprimary table must be selected for each CMP bean, and optionally, multiple
secondary tables. CMP felds are mapped to columns in either the primary or secondary
table(s). CMRfelds are mapped to pairs of column lists (normally, column lists are the lists of
columns associated with primary and foreign keys).
Note Table names in databases can be case-sensitive. Make sure that the table names in the
sun-cmp-mappings.xml fle match the names in the database.
Relationships should always be mapped to the primary key feld(s) of the related table.
The sun-cmp-mappings.xml fle conforms to the sun-cmp-mapping_1_2.dtd fle and is
packaged with the user-defned bean classes in the EJB JARfle under the META-INF directory.
The GlassFish Server creates the mappings in the sun-cmp-mappings.xml fle automatically
during deployment if the fle is not present.
To map the felds and relationships of your entity beans manually, edit the
sun-cmp-mappings.xml deployment descriptor. Only do this if you are profcient in editing
XML.
CMP Mapping
Chapter 9 Using Container-Managed Persistence 173
The mapping information is developed in conjunction with the database schema (.dbschema)
fle, which can be automatically captured when you deploy the bean (see Automatic Database
Schema Capture on page 183). You can manually generate the schema using the
capture-schema utility (Using the capture-schema Utility on page 183).
MappingConsiderations
Join Tables and Relationships on page 174
Automatic Primary Key Generation on page 174
Fixed Length CHARPrimary Keys on page 175
Managed Fields on page 175
BLOB Support on page 175
CLOB Support on page 176

The data types used in automatic schema generation are also suggested for manual mapping.
These data types are described in Supported Data Types for CMP on page 177.
JoinTables andRelationships
Use of join tables in the database schema is supported for all types of relationships, not just
many-to-many relationships. For general information about relationships, see section 10.3.7 of
the Enterprise JavaBeans Specifcation, v2.1.
Automatic Primary Key Generation
The GlassFish Server supports automatic primary key generation for EJB 1.1, 2.0, and 2.1 CMP
beans. To specify automatic primary key generation, give the prim-key-class element in the
ejb-jar.xml fle the value java.lang.Object. CMP beans with automatically generated
primary keys can participate in relationships with other CMP beans. The GlassFish Server does
not support database-generated primary key values.
If the database schema is created during deployment, the GlassFish Server creates the schema
with the primary key column, then generates unique values for the primary key column at
runtime.
If the database schema is not created during deployment, the primary key column in the
mapped table must be of type NUMERIC with a precision of 19 or more, and must not be mapped
to any CMP feld. The GlassFish Server generates unique values for the primary key column at
runtime.
CMP Mapping
FixedLengthCHARPrimary Keys
If an existing database table has a primary key column in which the values vary in length, but the
type is CHAR instead of VARCHAR, the GlassFish Server automatically trims any extra spaces when
retrieving primary key values. It is not a good practice to use a fxed length CHAR column as a
primary key. Use this feature with schemas that cannot be changed, such as a schema inherited
froma legacy application.
ManagedFields
Amanaged feld is a CMP or CMRfeld that is mapped to the same database column as another
CMP or CMRfeld. CMP felds mapped to the same column and CMRfelds mapped to exactly
the same column lists always have the same value in memory. For CMRfelds that share only a
subset of their mapped columns, changes to the columns afect the relationship felds in
memory diferently. Basically, the GlassFish Server always tries to keep the state of the objects in
memory synchronized with the database.
Amanaged feld can have any fetched-with subelement. If the fetched-with subelement is
<default/>, the -DAllowManagedFieldsInDefaultFetchGroup fag must be set to true. See
Default Fetch Group Flags on page 186 and fetched-with in Oracle GlassFish Server 3.1
BLOBSupport
Binary Large Object (BLOB) is a data type used to store values that do not correspond to other
types such as numbers, strings, or dates. Java felds whose types implement java.io.Serializable
or are represented as byte[] can be stored as BLOBs.
If a CMP feld is defned as Serializable, it is serialized into a byte[] before being stored in the
database. Similarly, the value fetched fromthe database is deserialized. However, if a CMP feld
is defned as byte[], it is stored directly instead of being serialized and deserialized when stored
and fetched, respectively.
To enable BLOB support in the GlassFish Server environment, defne a CMP feld of type
byte[] or a user-defned type that implements the java.io.Serializable interface. If you map the
CMP bean to an existing database schema, map the feld to a column of type BLOB.
To use BLOB or CLOB data types larger than 4 KB for CMP using the Inet Oraxo JDBCDriver
for Oracle Databases, you must set the streamstolob property value to true.
Guide.
CMP Mapping
For automatic mapping, you might need to change the default BLOB column length for the
generated schema using the schema-generator-properties element in
glassfish-ejb-jar.xml. See your database vendor documentation to determine whether you
need to specify the length. For example:
<schema-generator-properties>
<property>
<name>Employee.voiceGreeting.jdbc-type</name>
<value>BLOB</value>
</property>
<property>
<name>Employee.voiceGreeting.jdbc-maximum-length</name>
<value>10240</value>
</property>
...
</schema-generator-properties>
CLOBSupport
Character Large Object (CLOB) is a data type used to store and retrieve very long text felds.
CLOBs translate into long strings.
To enable CLOB support in the GlassFish Server environment, defne a CMP feld of type
java.lang.String. If you map the CMP bean to an existing database schema, map the feld to a
column of type CLOB.
To use BLOB or CLOB data types larger than 4 KB for CMP using the Inet Oraxo JDBCDriver
for Oracle Databases, you must set the streamstolob property value to true.
Guide.
For automatic mapping, you might need to change the default CLOB column length for the
generated schema using the schema-generator-properties element in
glassfish-ejb-jar.xml. See your database vendor documentation to determine whether you
need to specify the length. For example:
<schema-generator-properties>
<property>
<name>Employee.resume.jdbc-type</name>
<value>CLOB</value>
</property>
<property>
<name>Employee.resume.jdbc-maximum-length</name>
<value>10240</value>
</property>
...
</schema-generator-properties>
CMP Mapping
Automatic Schema Generationfor CMP
The automatic schema generation feature provided in the GlassFish Server defnes database
tables based on the felds in entity beans and the relationships between the felds. This insulates
developers frommany of the database related aspects of development, allowing themto focus
on entity bean development. The resulting schema is usable as-is or can be given to a database
administrator for tuning with respect to performance, security, and so on.
Supported Data Types for CMP on page 177
Generation Options for CMP on page 179

Note Automatic schema generation is supported on an all-or-none basis: it expects that no
tables exist in the database before it is executed. It is not intended to be used as a tool to generate
extra tables or constraints.
Deployment won't fail if all tables are not created, and undeployment won't fail if not all tables
are dropped. This is done to allowyou to investigate the problemand fx it manually. You
should not rely on the partially created database schema to be correct for running the
application.
SupportedDataTypes for CMP
CMP supports a set of JDBCdata types that are used in mapping Java data felds to SQL types.
Supported JDBCdata types are as follows: BIGINT, BIT, BLOB, CHAR, CLOB, DATE,
DECIMAL, DOUBLE, FLOAT, INTEGER, NUMERIC, REAL, SMALLINT, TIME,
TIMESTAMP, TINYINT, VARCHAR.
The following table contains the mappings of Java types to JDBCtypes when automatic
mapping is used.
TABLE 91 Java Type to JDBCType Mappings for CMP
JavaType JDBCType Nullability
boolean BIT No
java.lang.Boolean BIT Yes
byte TINYINT No
java.lang.Byte TINYINT Yes
double DOUBLE No
java.lang.Double DOUBLE Yes
Automatic Schema Generation for CMP
TABLE 91 Java Type to JDBCType Mappings for CMP (Continued)
JavaType JDBCType Nullability
float REAL No
java.lang.Float REAL Yes
int INTEGER No
java.lang.Integer INTEGER Yes
long BIGINT No
java.lang.Long BIGINT Yes
short SMALLINT No
java.lang.Short SMALLINT Yes
java.math.BigDecimal DECIMAL Yes
java.math.BigInteger DECIMAL Yes
char CHAR No
java.lang.Character CHAR Yes
java.lang.String VARCHAR or CLOB Yes
Serializable BLOB Yes
byte[] BLOB Yes
java.util.Date DATE (Oracle only)
TIMESTAMP (all other databases)
Yes
java.sql.Date DATE Yes
java.sql.Time TIME Yes
java.sql.Timestamp TIMESTAMP Yes
Note Java types assigned to CMP felds must be restricted to Java primitive types, Java
Serializable types, java.util.Date, java.sql.Date, java.sql.Time, or java.sql.Timestamp.
An entity bean local interface type (or a collection of such) can be the type of a CMRfeld.
The following table contains the mappings of JDBCtypes to database vendor-specifc types
when automatic mapping is used. For a list of the JDBCdrivers currently supported by the
GlassFish Server, see the Oracle GlassFish Server 3.1-3.1.1 Release Notes. For confgurations of
supported and other drivers, see Confguration Specifcs for JDBCDrivers in Oracle GlassFish
TABLE 92 Mappings of JDBCTypes to Database Vendor Specifc Types for CMP
JDBCType
Java DB, Derby,
CloudScape Oracle DB2 Sybase ASE 12.5 MS-SQL Server
BIT SMALLINT SMALLINT SMALLINT TINYINT BIT
TINYINT SMALLINT SMALLINT SMALLINT TINYINT TINYINT
SMALLINT SMALLINT SMALLINT SMALLINT SMALLINT SMALLINT
INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER
BIGINT BIGINT NUMBER BIGINT NUMERIC NUMERIC
REAL REAL REAL FLOAT FLOAT REAL
DOUBLE DOUBLE PRECISION DOUBLE PRECISION DOUBLE DOUBLE PRECISION FLOAT
DECIMAL(p,s) DECIMAL(p,s) NUMBER(p,s) DECIMAL(p,s) DECIMAL(p,s) DECIMAL(p,s)
VARCHAR VARCHAR VARCHAR2 VARCHAR VARCHAR VARCHAR
DATE DATE DATE DATE DATETIME DATETIME
TIME TIME DATE TIME DATETIME DATETIME
TIMESTAMP TIMESTAMP TIMESTAMP(9) TIMESTAMP DATETIME DATETIME
BLOB BLOB BLOB BLOB IMAGE IMAGE
CLOB CLOB CLOB CLOB TEXT NTEXT
GenerationOptions for CMP
Deployment descriptor elements or asadmin command line options can control automatic
schema generation by the following:
Creating tables during deployment
Dropping tables during undeployment
Dropping and creating tables during redeployment
Specifying the database vendor
Specifying that table names are unique
Specifying type mappings for individual CMP felds

Note Before using these options, make sure you have a properly confgured CMP resource. See
Confguring the CMP Resource on page 184.
For a read-only bean, do not create the database schema during deployment. Instead, work with
your database administrator to populate the data into the tables. See Using Read-Only Beans
on page 163.
Automatic schema generation is not supported for beans with version column consistency
checking. Instead, work with your database administrator to create the schema and add the
required triggers. See Version Column Consistency Checking on page 184.
The following optional data subelements of the cmp-resource element in the
glassfish-ejb-jar.xml fle control the automatic creation of database tables at deployment.
For more information about the cmp-resource element, see cmp-resource in Oracle
GlassFish Server 3.1 Application Deployment Guide and Confguring the CMP Resource on
page 184.
TABLE 93 The glassfish-ejb-jar.xml GenerationElements
Element Default Description
create-tables-at-deploy false If true, causes database tables to be created for beans that are automatically
mapped by the EJB container. No unique constraints are created. If false, does
not create tables.
drop-tables-at-undeploy false If true, causes database tables that were automatically created when the bean(s)
were last deployed to be dropped when the bean(s) are undeployed. If false, does
not drop tables.
database-vendor-name none Specifes the name of the database vendor for which tables are created. Allowed
values are javadb, db2, mssql, mysql, oracle, postgresql, pointbase, derby
(also for CloudScape), and sybase, case-insensitive.
If no value is specifed, a connection is made to the resource specifed by the
jndi-name subelement of the cmp-resource element in the
glassfish-ejb-jar.xml fle, and the database vendor name is read. If the
connection cannot be established, or if the value is not recognized, SQL-92
compliance is presumed.
TABLE 93 The glassfish-ejb-jar.xml GenerationElements (Continued)
Element Default Description
schema-generator-properties none Specifes feld-specifc column attributes in property subelements. Each property
name is of the following format:
bean-name.feld-name.attribute
For example:
Employee.firstName.jdbc-type
Also allows you to set the use-unique-table-names property. If true, this
property specifes that generated table names are unique within each GlassFish
Server domain. The default is false.
For further information and an example, see schema-generator-properties in
The following options of the asadmin deploy or asadmin deploydir command control the
automatic creation of database tables at deployment.
TABLE 94 The asadmin deploy and asadmin deploydir Generation Options for CMP
--createtables none If true, causes database tables to be created for beans that need them. No unique
constraints are created. If false, does not create tables. If not specifed, the value of
the create-tables-at-deploy attribute in glassfish-ejb-jar.xml is used.
--dropandcreatetables none If true, and if tables were automatically created when this application was last
deployed, tables fromthe earlier deployment are dropped and fresh ones are
created.
If true, and if tables were not automatically created when this application was last
deployed, no attempt is made to drop any tables. If tables with the same names as
those that would have been automatically created are found, the deployment
proceeds, but a warning indicates that tables could not be created.
If false, settings of create-tables-at-deploy or drop-tables-at-undeploy in
the glassfish-ejb-jar.xml fle are overridden.
--uniquetablenames none If true, specifes that table names are unique within each GlassFish Server domain.
If not specifed, the value of the use-unique-table-names property in
glassfish-ejb-jar.xml is used.
TABLE 94 The asadmin deploy and asadmin deploydir Generation Options for CMP (Continued)
--dbvendorname none Specifes the name of the database vendor for which tables are created. Allowed
values are javadb, db2, mssql, oracle, postgresql, pointbase, derby (also for
CloudScape), and sybase, case-insensitive.
If not specifed, the value of the database-vendor-name attribute in
If no value is specifed, a connection is made to the resource specifed by the
jndi-name subelement of the cmp-resource element in the
glassfish-ejb-jar.xml fle, and the database vendor name is read. If the
connection cannot be established, or if the value is not recognized, SQL-92
compliance is presumed.
If one or more of the beans in the module are manually mapped and you use any of the asadmin
deploy or asadmin deploydir options, the deployment is not harmed in any way, but the
options have no efect, and a warning is written to the server log.
The following options of the asadmin undeploy command control the automatic removal of
database tables at undeployment.
TABLE 95 The asadmin undeploy Generation Options for CMP
--droptables none If true, causes database tables that were automatically created when the bean(s) were last
deployed to be dropped when the bean(s) are undeployed. If false, does not drop tables.
If not specifed, the value of the drop-tables-at-undeploy attribute in
For more information about the asadmin deploy, asadmin deploydir, and asadmin undeploy
When command line and glassfish-ejb-jar.xml options are both specifed, the asadmin
options take precedence.
Schema Capture
Automatic Database Schema Capture on page 183
Using the capture-schema Utility on page 183

Schema Capture
Automatic Database Schema Capture
You can confgure a CMP bean in GlassFish Server to automatically capture the database
metadata and save it in a .dbschema fle during deployment. If the sun-cmp-mappings.xml fle
contains an empty <schema/> entry, the cmp-resource entry in the glassfish-ejb-jar.xml
fle is used to get a connection to the database, and automatic generation of the schema is
performed.
Note Before capturing the database schema automatically, make sure you have a properly
confgured CMP resource. See Confguring the CMP Resource on page 184.
Usingthe capture-schema Utility
You can use the capture-schema command to manually generate the database metadata
(.dbschema) fle. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
The capture-schema utility does not modify the schema in any way. Its only purpose is to
provide the persistence engine with information about the structure of the database (the
schema).
Keep the following in mind when using the capture-schema command:
The name of a .dbschema fle must be unique across all deployed modules in a domain.
If more than one schema is accessible for the schema user, more than one table with the
same name might be captured if the -schemaname option of capture-schema is not set.
The schema name must be upper case.
Table names in databases are case-sensitive. Make sure that the table name matches the
name in the database.
PostgreSQL databases internally convert all names to lower case. Before running the
capture-schema command on a PostgreSQL database, make sure table and column names
are lower case in the sun-cmp-mappings.xml fle.
An Oracle database user running the capture-schema command needs ANALYZE ANY
TABLE privileges if that user does not own the schema. These privileges are granted to the
user by the database administrator.
Schema Capture
Confguringthe CMPResource
An EJB module that contains CMP beans requires the JNDI name of a JDBCresource in the
jndi-name subelement of the cmp-resource element in the glassfish-ejb-jar.xml fle. Set
PersistenceManagerFactory properties as properties of the cmp-resource element in the
glassfish-ejb-jar.xml fle. See cmp-resource in Oracle GlassFish Server 3.1 Application
Deployment Guide.
In the Administration Console, open the Resources component, then select JDBC. Click the
Help button in the Administration Console for information on creating a newJDBCresource.
Guide.
For example, if the JDBCresource has the JNDI name jdbc/MyDatabase, set the CMP resource
in the glassfish-ejb-jar.xml fle as follows:
<cmp-resource>
<jndi-name>jdbc/MyDatabase</jndi-name>
</cmp-resource>
Performance-RelatedFeatures
The GlassFish Server provides the following features to enhance performance or allowmore
fne-grained data checking. These features are supported only for entity beans with container
managed persistence.
Version Column Consistency Checking on page 184
Relationship Prefetching on page 185
Read-Only Beans on page 186
Default Fetch Group Flags on page 186

Note Use of any of these features results in a non-portable application.
VersionColumnConsistency Checking
The version consistency feature saves the bean state at frst transactional access and caches it
between transactions. The state is copied fromthe cache instead of being read fromthe
database. The bean state is verifed by primary key and version column values at fush for
customqueries (for dirty instances only) and at commit (for clean and dirty instances).
Confguring the CMP Resource
ToUseVersionConsistency
Create the versioncolumninthe primary table.
Give the versioncolumna numeric data type.
Provide appropriate update triggers onthe versioncolumn.
These triggers must increment the version column on each update of the specifed row.
Specify the versioncolumn.
This is specifed in the check-version-of-accessed-instances subelement of the
consistency element in the sun-cmp-mappings.xml fle. See consistency in Oracle GlassFish
Mapthe CMPbeantoanexistingschema.
Automatic schema generation is not supported for beans with version column consistency
checking. Instead, work with your database administrator to create the schema and add the
required triggers.
RelationshipPrefetching
In many cases when an entity beans state is fetched fromthe database, its relationship felds are
always accessed in the same transaction. Relationship prefetching saves database round trips by
fetching data for an entity bean and those beans referenced by its CMRfelds in a single
database round trip.
To enable relationship prefetching for a CMRfeld, use the default subelement of the
fetched-with element in the sun-cmp-mappings.xml fle. By default, these CMRfelds are
prefetched whenever findByPrimaryKey or a customfnder is executed for the entity, or when
the entity is navigated to froma relationship. (Recursive prefetching is not supported, because it
does not usually enhance performance.) See fetched-with in Oracle GlassFish Server 3.1
To disable prefetching for specifc customfnders, use the prefetch-disabled element in the
glassfish-ejb-jar.xml fle. See prefetch-disabled in Oracle GlassFish Server 3.1 Application
Deployment Guide.
Multilevel relationship prefetching is supported for CMP 2.1 entity beans. To enable multilevel
relationship prefetching, set the following property using the asadmin create-jvm-options
command:
asadmin create-jvm-options -Dcom.sun.jdo.spi.persistence.support.sqlstore.MULTILEVEL_PREFETCH=true
1
2
3
4
5
Performance-Related Features
Read-Only Beans
Another feature that the GlassFish Server provides is the read-only bean, an entity bean that is
never modifed by an EJB client. Read-only beans avoid database updates completely.
application.
Aread-only bean can be used to cache a database entry that is frequently accessed but rarely
updated (externally by other beans). When the data that is cached by a read-only bean is
updated by another bean, the read-only bean can be notifed to refresh its cached data.
The GlassFish Server provides a number of ways by which a read-only beans state can be
refreshed. By setting the refresh-period-in-seconds element in the glassfish-ejb-jar.xml
fle and the trans-attribute element (or @TransactionAttribute annotation) in the
ejb-jar.xml fle, it is easy to confgure a read-only bean that is one of the following:
Always refreshed
Periodically refreshed
Never refreshed
Programmatically refreshed
Access to CMRfelds of read-only beans is not supported. Deployment will succeed, but an
exception will be thrown at runtime if a get or set method is invoked.
changes infrequently. For further information and usage guidelines, see Using Read-Only
Beans on page 163.
Default FetchGroupFlags
Using the following fags can improve performance.
Setting -DAllowManagedFieldsInDefaultFetchGroup=true allows CMP felds that by default
cannot be placed into the default fetch group to be loaded along with all other felds that are
fetched when the CMP state is loaded into memory. These could be multiple felds mapped to
the same column in the database table, for example, an instance feld and a CMR. By default this
fag is set to false.
For additional information, see level in Oracle GlassFish Server 3.1 Application Deployment
Guide.
Default Fetch Group Flags
Setting -DAllowMediatedWriteInDefaultFetchGroup specifes howupdated CMP felds are
written back to the database. If the fag is false, all felds in the CMP bean are written back to
the database if at least one feld in the default fetch group has been changed in a transaction. If
the fag is true, only felds modifed by the bean are written back to the database. Specifying
true can improve performance, particularly on database tables with many columns that have
not been updated. By default this fag is set to false.
To set one of these fags, use the asadmin create-jvm-options command. For example:
asadmin create-jvm-options -DAllowManagedFieldsInDefaultFetchGroup=true
ConfguringQueries for 1.1Finders
About JDOQL Queries on page 187
Query Filter Expression on page 188
Query Parameters on page 189
Query Variables on page 189
JDOQL Examples on page 189

About JDOQL Queries
The Enterprise JavaBeans Specifcation, v1.1 does not specify the format of the fnder method
description. The GlassFish Server uses an extension of Java Data Objects Query Language
(JDOQL) queries to implement fnder and selector methods. You can specify the following
elements of the underlying JDOQL query:
Filter expression - AJava-like expression that specifes a condition that each object
returned by the query must satisfy. Corresponds to the WHERE clause in EJB QL.
Query parameter declaration - Specifes the name and the type of one or more query input
parameters. Follows the syntax for formal parameters in the Java language.
Query variable declaration - Specifes the name and type of one or more query variables.
Follows the syntax for local variables in the Java language. Aquery flter might use query
variables to implement joins.
Query ordering declaration - Specifes the ordering expression of the query. Corresponds
to the ORDERBYclause of EJB QL.
The GlassFish Server specifc deployment descriptor (glassfish-ejb-jar.xml) provides the
following elements to store the EJB 1.1 fnder method settings:
query-filter
query-params
query-variables
query-ordering
Confguring Queries for 1.1 Finders
The bean developer uses these elements to construct a query. When the fnder method that uses
these elements executes, the values of these elements are used to execute a query in the database.
The objects fromthe JDOQL query result set are converted into primary key instances to be
returned by the EJB 1.1 ejbFind method.
The JDOspecifcation, JSR12 (http://jcp.org/en/jsr/detail?id=12), provides a
comprehensive description of JDOQL. The following information summarizes the elements
used to defne EJB 1.1 fnders.
Query Filter Expression
The flter expression is a String containing a Boolean expression evaluated for each instance of
the candidate class. If the flter is not specifed, it defaults to true. Rules for constructing valid
expressions followthe Java language, with the following diferences:
Equality and ordering comparisons between primitives and instances of wrapper classes are
valid.
Equality and ordering comparisons of Date felds and Date parameters are valid.
Equality and ordering comparisons of String felds and String parameters are valid.
White space (non-printing characters space, tab, carriage return, and line feed) is a
separator and is otherwise ignored.
The following assignment operators are not supported.
Comparison operators such as =, +=, and so on
Pre- and post-increment
Pre- and post-decrement
Methods, including object construction, are not supported, except for these methods.
Collection.contains(Object o)
Collection.isEmpty()
String.startsWith(String s)
String.endsWith(String e)
In addition, the GlassFish Server supports the following nonstandard JDOQL methods.
String.like(String pattern)
String.like(String pattern, char escape)
String.substring(int start, int length)
String.indexOf(String str)
String.indexOf(String str, int start)
String.length()
Math.abs(numeric n)
Math.sqrt(double d)
Navigation through a null-valued feld, which throws a NullPointerException, is treated as

if the sub-expression returned false.
Note Comparisons between foating point values are by nature inexact. Therefore, equality
comparisons (== and !=) with foating point values should be used with caution. Identifers in
the expression are considered to be in the name space of the candidate class, with the addition of
declared parameters and variables. As in the Java language, this is a reserved word, and refers
to the current instance being evaluated.
The following expressions are supported.
Relational operators (==, !=, >, <, >=, <=)
Boolean operators (&, &&, |, ||, ~, !)
Arithmetic operators (+, -, *, /)
String concatenation, only for String + String
Parentheses to explicitly mark operator precedence
Cast operator
Promotion of numeric operands for comparisons and arithmetic operations

The rules for promotion followthe Java rules extended by BigDecimal, BigInteger, and numeric
wrapper classes. See the numeric promotions of the Java language specifcation.
Query Parameters
The parameter declaration is a String containing one or more parameter type declarations
separated by commas. This follows the Java syntax for method signatures.
QueryVariables
The type declarations followthe Java syntax for local variable declarations.
JDOQL Examples
This section provides a fewquery examples.
Example 1
The following query returns all players called Michael. It defnes a flter that compares the name
feld with a string literal:
name == "Michael"
The finder element of the glassfish-ejb-jar.xml fle looks like this:
<finder>
<method-name>findPlayerByName</method-name>
<query-filter>name == "Michael"</query-filter>
</finder>
Example 2
This query returns all products in a specifed price range. It defnes two query parameters which
are the lower and upper bound for the price: double low, double high. The flter compares the
query parameters with the price feld:
low < price && price < high
Query ordering is set to price ascending.
<finder>
<method-name>findInRange</method-name>
<query-params>double low, double high</query-params>
<query-filter>low < price && price &lt high</query-filter>
<query-ordering>price ascending</query-ordering>
</finder>
Example 3
This query returns all players having a higher salary than the player with the specifed name. It
defnes a query parameter for the name java.lang.String name. Furthermore, it defnes a
variable to which the players salary is compared. It has the type of the persistence capable class
that corresponds to the bean:
mypackage.PlayerEJB_170160966_JDOState player
The flter compares the salary of the current player denoted by the this keyword with the salary
of the player with the specifed name:
(this.salary > player.salary) && (player.name == name)
<finder>
<method-name>findByHigherSalary</method-name>
<query-params>java.lang.String name</query-params>
<query-filter>
(this.salary > player.salary) && (player.name == name)
</query-filter>
<query-variables>
mypackage.PlayerEJB_170160966_JDOState player
</query-variables>
</finder>
CMPRestrictions andOptimizations
This section discusses restrictions and performance optimizations that pertain to using CMP.
Disabling ORDERBYValidation on page 191
Setting the Heap Size on DB2 on page 191
Eager Loading of Field State on page 192
Restrictions on Remote Interfaces on page 192
PostgreSQL Case Insensitivity on page 192
No Support for lock-when-loaded on Sybase on page 192
Sybase Finder Limitation on page 193
Date and Time Fields on page 193
Set RECURSIVE_TRIGGERS to false on MSSQL on page 193
MySQL Database Restrictions on page 194

DisablingORDERBYValidation
EJB QL as defned in the EJB 2.1 Specifcation defnes certain restrictions for the SELECTclause
of an ORDERBYquery (see section 11.2.8 ORDERBYClause). This ensures that a query does
not order by a feld that is not returned by the query. By default, the EJB QL compiler checks the
above restriction and throws an exception if the query does not conform.
However, some databases support SQL statements with an ORDERBYcolumn that is not
included in the SELECTclause. To disable the validation of the ORDERBYclause against the
SELECTclause, set the DISABLE_ORDERBY_VALIDATION JVMoption as follows:
asadmin create-jvm-options
-Dcom.sun.jdo.spi.persistence.support.ejb.ejbqlc.DISABLE_ORDERBY_VALIDATION=true
The DISABLE_ORDERBY_VALIDATION option is set to false by default. Setting it to true results in
a non-portable module or application.
Settingthe HeapSize onDB2
On DB2, the database confguration parameter APPLHEAPSZ determines the heap size. If you are
using the Oracle or DataDirect database driver, set this parameter to at least 2048 for CMP. For
more information, see http://publib.boulder.ibm.com/
infocenter/db2luw/v8/index.jsp?topic=/com.ibm.db2.udb.doc/opt/tsbp2024.htm.
CMP Restrictions and Optimizations
Eager Loadingof FieldState
By default, the EJB container loads the state for all persistent felds (excluding relationship,
BLOB, and CLOB felds) before invoking the ejbLoad method of the abstract bean. This
approach might not be optimal for entity objects with large state if most business methods
require access to only parts of the state.
Use the fetched-with element in sun-cmp-mappings.xml for felds that are used infrequently.
See fetched-with in Oracle GlassFish Server 3.1 Application Deployment Guide.
Restrictions onRemote Interfaces
The following restrictions apply to the remote interface of an EJB 2.1 bean that uses CMP:
Do not expose the get and set methods for CMRfelds or the persistence collection classes
that are used in container-managed relationships through the remote interface of the bean.
However, you are free to expose the get and set methods that correspond to the CMP felds
of the entity bean through the beans remote interface.
Do not expose the container-managed collection classes that are used for relationships
through the remote interface of the bean.
Do not expose local interface types or local home interface types through the remote
interface or remote home interface of the bean.
Dependent value classes can be exposed in the remote interface or remote home interface, and
can be included in the client EJB JARfle.
PostgreSQL Case Insensitivity
Case-sensitive behavior cannot be achieved for PostgreSQL databases. PostgreSQL databases
internally convert all names to lower case, which makes the following workarounds necessary:
In the CMP 2.1 runtime, PostgreSQL table and column names are not quoted, which makes
these names case insensitive.
Before running the capture-schema command on a PostgreSQL database, make sure table
and column names are lower case in the sun-cmp-mappings.xml fle.
NoSupport for lock-when-loaded onSybase
For EJB 2.1 beans, the lock-when-loaded consistency level is implemented by placing update
locks on the data corresponding to a bean when the data is loaded fromthe database. There is
no suitable mechanismavailable on Sybase databases to implement this feature. Therefore, the
lock-when-loaded consistency level is not supported on Sybase databases. See consistency in
Sybase Finder Limitation
If a fnder method with an input greater than 255 characters is executed and the primary key
column is mapped to a VARCHARcolumn, Sybase attempts to convert type VARCHARto type
TEXTand generates the following error:
com.sybase.jdbc2.jdbc.SybSQLException: Implicit conversion from datatype
TEXT to VARCHAR is not allowed. Use the CONVERT function to run this
query.
To avoid this error, make sure the fnder method input is less than 255 characters.
Date andTime Fields
If a feld type is a Java date or time type (java.util.Date, java.sql.Date, java.sql.Time,
java.sql.Timestamp), make sure that the feld value exactly matches the value in the database.
For example, the following code uses a java.sql.Date type as a primary key feld:
java.sql.Date myDate = new java.sql.Date(System.currentTimeMillis())
BeanA.create(myDate, ...);
For some databases, this code results in only the year, month, and date portion of the feld value
being stored in the database. Later if the client tries to fnd this bean by primary key as follows,
the bean is not found in the database because the value does not match the one that is stored in
the database.
myBean = BeanA.findByPrimaryKey(myDate);
Similar problems can happen if the database truncates the timestamp value while storing it, or if
a customquery has a date or time value comparison in its WHERE clause.
For automatic mapping to an Oracle database, felds of type java.util.Date, java.sql.Date,
and java.sql.Time are mapped to Oracles DATE data type. Fields of type
java.sql.Timestamp are mapped to Oracles TIMESTAMP(9) data type.
Set RECURSIVE_TRIGGERS tofalse onMSSQL
For version consistency triggers on MSSQL, the property RECURSIVE_TRIGGERS must be set to
false, which is the default. If set to true, triggers throwa java.sql.SQLException.
Set this property as follows:
EXEC sp_dboption database-name, recursive triggers, FALSE
go
You can test this property as follows:
SELECT DATABASEPROPERTYEX(database-name, IsRecursiveTriggersEnabled)
go
MySQL Database Restrictions
The following restrictions apply when you use a MySQL database with the GlassFish Server for
persistence.
MySQL treats int1 and int2 as reserved words. If you want to defne int1 and int2 as felds
in your table, use int1 and int2 feld names in your SQL fle.
When VARCHAR felds get truncated, a warning is displayed instead of an error. To get an
error message, start the MySQL database in strict SQL mode.
The order of felds in a foreign key index must match the order in the explicitly created
index on the primary table.
The CREATE TABLE syntax in the SQL fle must end with the following line.
) Engine=InnoDB;
InnoDB provides MySQL with a transaction-safe (ACIDcompliant) storage engine having
commit, rollback, and crash recovery capabilities.
For a FLOAT type feld, the correct precision must be defned. By default, MySQL uses four
bytes to store a FLOAT type that does not have an explicit precision defnition. For example,
this causes a number such as 12345.67890123 to be rounded of to 12345.7 during an
INSERT. To prevent this, specify FLOAT(10,2) in the DDL fle, which forces the database to
use an eight-byte double-precision column. For more information, see
http://dev.mysql.com/doc/mysql/en/numeric-types.html.
To use || as the string concatenation symbol, start the MySQL server with the
--sql-mode="PIPES_AS_CONCAT" option. For more information, see
http://dev.mysql.com/doc/refman/5.0/en/server-sql-mode.html and
http://dev.mysql.com/doc/mysql/en/ansi-mode.html.
MySQL always starts a newconnection when autoCommit==true is set. This ensures that
each SQL statement forms a single transaction on its own. If you try to rollback or commit
an SQL statement, you get an error message.
Cant call rollback when autocommit=true
Error open transaction is not closed
To resolve this issue, add relaxAutoCommit=true to the JDBCURL. For more information,
see http://forums.mysql.com/read.php?39,31326,31404.
Change the trigger create format fromthe following:

CREATE TRIGGER T_UNKNOWNPKVC1
BEFORE UPDATE ON UNKNOWNPKVC1
FOR EACH ROW
WHEN (NEW.VERSION = OLD.VERSION)
BEGIN
:NEW.VERSION := :OLD.VERSION + 1;
END;
/
To the following:
DELIMITER |
CREATE TRIGGER T_UNKNOWNPKVC1
BEFORE UPDATE ON UNKNOWNPKVC1
FOR EACH ROW
WHEN (NEW.VERSION = OLD.VERSION)
BEGIN
:NEW.VERSION := :OLD.VERSION + 1;
END
|
DELIMITER ;
For more information, see http://dev.mysql.com/doc/mysql/en/create-trigger.html.
MySQL does not allowa DELETE on a rowthat contains a reference to itself. Here is an
example that illustrates the issue.
empId int NOT NULL,
mgrId int NULL,
) ENGINE=InnoDB;
This example fails with the following error message.
ERROR 1217 (23000): Cannot delete or update a parent row:
a foreign key constraint fails
empId int NOT NULL,
mgrId int NULL,
ON DELETE SET NULL
) ENGINE=InnoDB;
This can be done only if the foreign key feld is allowed to be null. For more information, see
http://dev.mysql.com/doc/mysql/en/innodb-foreign-key-constraints.html.
When an SQL script has foreign key constraints defned, capture-schema fails to capture
the table information correctly. To work around the problem, remove the constraints and
then run capture-schema. Here is an example that illustrates the issue.
CREATE TABLE ADDRESSBOOKBEANTABLE (ADDRESSBOOKNAME VARCHAR(255)
NOT NULL PRIMARY KEY,
CONNECTEDUSERS BLOB NULL,
OWNER VARCHAR(256),
FK_FOR_ACCESSPRIVILEGES VARCHAR(256),
CONSTRAINT FK_ACCESSPRIVILEGE FOREIGN KEY (FK_FOR_ACCESSPRIVILEGES)
REFERENCES ACCESSPRIVILEGESBEANTABLE (ROOT)
) ENGINE=InnoDB;
CREATE TABLE ADDRESSBOOKBEANTABLE (ADDRESSBOOKNAME VARCHAR(255)
NOT NULL PRIMARY KEY,
CONNECTEDUSERS BLOB NULL,
OWNER VARCHAR(256),
FK_FOR_ACCESSPRIVILEGES VARCHAR(256)
) ENGINE=InnoDB;
Developing Java Clients
This chapter describes howto develop, assemble, and deploy Java clients.
Introducing the Application Client Container on page 197
Developing Clients Using the ACC on page 199
Developing Clients Without the ACC on page 217

Note The Web Profle of the OracleGlassFish Server supports the EJB3.1 Lite specifcation,
which allows enterprise beans within web applications, among other features. The full GlassFish
jsr/detail?id=318).
Accordingly, the Application Client Container is supported only in the full GlassFish Server,
not in the Web Profle.
JMS resources are supported only in the full GlassFish Server, not in the Web Profle. See
Introducingthe ApplicationClient Container
The Application Client Container (ACC) includes a set of Java classes, libraries, and other fles
that are required for and distributed with Java client programs that execute in their own Java
Virtual Machine (JVM). The ACCmanages the execution of Java EE application client
components (application clients), which are used to access a variety of Java EE services (such as
JMS resources, EJB components, web services, security, and so on.) froma JVMoutside the
Oracle GlassFish Server.
The ACCcommunicates with the GlassFish Server using RMI-IIOP protocol and manages the
details of RMI-IIOP communication using the client ORB that is bundled with it. Compared to
other Java EE containers, the ACCis lightweight.
10
C H A P T E R 1 0
197
For information about debugging application clients, see Application Client Debugging on
page 39.
Note Interoperability between application clients and GlassFish Servers running under
diferent major versions is not supported.
ACCSecurity
The ACCdetermines when authentication is needed. This typically occurs when the client
refers to an EJB component that requires authorization or when annotations in the client's main
class trigger injection which, in turn, requires contact with the GlassFish Server's naming
service. To authenticate the end user, the ACCprompts for any required information, such as a
username and password. The ACCitself provides a very simple dialog box to prompt for and
read these values.
The ACCintegrates with the GlassFish Servers authentication system. It also supports SSL
(Secure Socket Layer)/IIOP if confgured and when necessary; see Using RMI/IIOP Over SSL
on page 214.
You can provide an alternate implementation to gather authentication information, tailored to
the needs of the application client. To do so, include the class to performthese duties in the
application client and identify the fully-qualifed name of this class in the callback-handler
element of the application-client.xml descriptor for the client. The ACCuses this class
instead of its default class for asking for and reading the authentication information. The class
must implement the javax.security.auth.callback.CallbackHandler interface. See the Java EE
specifcation, section 9.2, Application Clients: Security, for more details.
Application clients can use Programmatic Login on page 72.
ACCNaming
The client container enables the application clients to use the Java Naming and Directory
Interface (JNDI) to look up Java EE services (such as JMS resources, EJB components, web
services, security, and so on.) and to reference confgurable parameters set at the time of
deployment.
ApplicationClient Annotation
Annotation is supported for the main class and the optional callback handler class in
application clients. For more information, see Deployment Descriptors and Annotations in
Introducing the Application Client Container
JavaWebStart
Java Web Start allows your application client to be easily launched and automatically
downloaded and updated. It is enabled for all application clients by default. For more
information, see Using Java Web Start on page 202.
ApplicationClient JARFile
In GlassFish Server 3.1, the downloaded appclient JARfle is smaller than in previous releases,
with dependent classes in separate JARfles. When copying the downloaded appclient to
another location, make sure to include the JARfles containing the dependent classes as well.
You can also use the asadmin get-client-stubs command to retrieve the appclient and all
associated application JARfles and place themin another location.
DevelopingClients Usingthe ACC
This section describes the procedure to develop, assemble, and deploy client applications using
the ACC.
To Access an EJB Component Froman Application Client on page 199
To Access a JMS Resource Froman Application Client on page 201
Using Java Web Start on page 202
Using the Embeddable ACC on page 212
Running an Application Client Using the appclient Script on page 213
Using the package-appclient Script on page 214
The client.policy File on page 214
Using RMI/IIOP Over SSL on page 214
Connecting to a Remote EJB Module Through a Firewall on page 216
Specifying a Splash Screen on page 216
Setting Login Retries on page 217
Using Libraries with Application Clients on page 217
ToAccess anEJBComponent FromanApplication

Client
Inyour client code, reference the EJBcomponent by usingan@EJB annotationor by lookingup
the JNDI name as defnedinthe ejb-jar.xml fle.
For more information about naming and lookups, see Accessing the Naming Context on
page 273.
1
Developing Clients Using the ACC
Chapter 10 Developing Java Clients 199
If load balancing is enabled as in Step 7 and the EJB components being accessed are in a
diferent cluster, the endpoint list must be included in the lookup, as follows:
corbaname:host1:port1,host2:port2,.../NameService#ejb/jndi-name
Defne the @EJB annotations or the ejb-ref elements inthe application-client.xml fle.
Defne the correspondingejb-ref elements inthe glassfish-application-client.xml fle.
For more information on the glassfish-application-client.xml fle, see The
glassfsh-application-client.xml fle in Oracle GlassFish Server 3.1 Application Deployment
Guide. For a general explanation of howto map JNDI names using reference elements, see
Mapping References on page 280.
Deploy the applicationclient andEJBcomponent together inanapplication.
For more information on deployment, see the Oracle GlassFish Server 3.1 Application
Deployment Guide. To get the client JAR fle, use the --retrieve option of the asadmin deploy
command.
To retrieve the stubs and ties generated during deployment, use the asadmin
get-client-stubs command. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference
Manual.
Ensure that the client JARfle includes the followingfles:
AJava class to access the bean.
application-client.xml - (optional) Java EE application client deployment descriptor.
glassfish-application-client.xml - (optional) GlassFish Server specifc client

deployment descriptor. For information on the glassfish-application-client.xml fle,
see The glassfsh-application-client.xml fle in Oracle GlassFish Server 3.1 Application
Deployment Guide.
The MANIFEST.MF fle. This fle contains a reference to the main class, which states the
complete package prefx and class name of the Java client.
Prepare the client machine.
This step is not needed for Java Web Start. This step is not needed if the client and server
machines are the same.
If you are using the appclient script, package the GlassFish Server systemfles required to
launch application clients on remote systems using the package-appclient script, then retrieve
the application client itself using the asadmin get-client-stubs command.
For more information, see Using the package-appclient Script on page 214 and the Oracle
Toaccess EJBcomponents that are residingina remote system, make the followingchanges to
the sun-acc.xml fle or the appclient script. This stepis not neededfor JavaWebStart.
2
3
4
5
6
Defne the target-server elements address and port attributes to reference the remote
server machine and its ORB port. See target-server in Oracle GlassFish Server 3.1
Use the -targetserver option of the appclient script to reference the remote server
machine and its ORB port. For more information, see Running an Application Client
Using the appclient Script on page 213.
To determine the ORB port on the remote server, use the asadmin get command. For example:
asadmin --host rmtsrv get server-config.iiop-service.iiop-listener.iiop-listener1.port
For more information about the asadmin get command, see the Oracle GlassFish
Toset uploadbalancingandfailover of remote EJBreferences, defne at least two
target-server elements inthe sun-acc.xml fle or the appclient script. This stepis not
neededfor JavaWebStart.
If the GlassFish Server instance on which the application client is deployed participates in a
cluster, the ACCfnds all currently active IIOP endpoints in the cluster automatically. However,
a client should have at least two endpoints specifed for bootstrapping purposes, in case one of
the endpoints has failed.
The target-server elements in the sun-acc.xml fle specify one or more IIOP endpoints used
for load balancing. The address attribute is an IPv4 address or host name, and the port
attribute specifes the port number. See client-container in Oracle GlassFish Server 3.1
The --targetserver option of the appclient script specifes one or more IIOP endpoints used
for load balancing. For more information, see Running an Application Client Using the
appclient Script on page 213.
For instructions on running the application client, see Using Java Web Start on page 202 or
Running an Application Client Using the appclient Script on page 213.
For more information about RMI-IIOP load balancing and failover, see Chapter 12,
RMI-IIOP Load Balancing and Failover, in Oracle GlassFish Server 3.1-3.1.1 High
Availability Administration Guide.
ToAccess a JMS Resource FromanApplicationClient

Create a JMS client.
For detailed instructions on developing a JMS client, see Chapter 33: The Java Message Service
API in the The Java EE 6 Tutorial (http://download.oracle.com/javaee/6/tutorial/doc/
).
7
Next Steps
1
Next, confgure a JMS resource onthe GlassFishServer.
For information on confguring JMS resources, see Administering JMS Connection Factories
and Destinations in Oracle GlassFish Server 3.1 Administration Guide.
Defne the @Resource or @Resources annotations or the resource-ref elements inthe
application-client.xml fle. Defne the correspondingresource-ref elements inthe
glassfish-application-client.xml fle.
For more information on the glassfish-application-client.xml fle, see The
glassfsh-application-client.xml fle in Oracle GlassFish Server 3.1 Application Deployment
Guide. For a general explanation of howto map JNDI names using reference elements, see
Mapping References on page 280.
Ensure that the client JARfle includes the followingfles:
AJava class to access the resource.
application-client.xml - (optional) Java EE application client deployment descriptor.
glassfish-application-client.xml - (optional) GlassFish Server specifc client

deployment descriptor. For information on the glassfish-application-client.xml fle,
see The glassfsh-application-client.xml fle in Oracle GlassFish Server 3.1 Application
Deployment Guide.
The MANIFEST.MF fle. This fle contains a reference to the main class, which states the
complete package prefx and class name of the Java client.
Prepare the client machine.
This step is not needed for Java Web Start. This step is not needed if the client and server
machines are the same.
If you are using the appclient script, package the GlassFish Server systemfles required to
launch application clients on remote systems using the package-appclient script, then retrieve
the application client itself using the asadmin get-client-stubs command.
For more information, see Using the package-appclient Script on page 214 and the Oracle
Runthe applicationclient.
See Using Java Web Start on page 202 or Running an Application Client Using the appclient
Script on page 213.
UsingJavaWebStart
Java Web Start allows your application client to be easily launched and automatically
downloaded and updated. General information about Java Web Start is available at
http://www.oracle.com/technetwork/java/javase/tech/index-jsp-136112.html.
2
3
4
5
6
Enabling and Disabling Java Web Start on page 203
Downloading and Launching an Application Client on page 203
The Application Client URL on page 204
Signing JARFiles Used in Java Web Start on page 205
Error Handling on page 207
Vendor Icon, Splash Screen, and Text on page 207
Creating a CustomJNLP File on page 208

EnablingandDisablingJavaWebStart
Java Web Start is enabled for all application clients by default.
The application developer or deployer can specify that Java Web Start is always disabled for an
application client by setting the value of the eligible element to false in the
glassfish-application-client.xml fle. See the Oracle GlassFish Server 3.1 Application
Deployment Guide.
The GlassFish Server administrator can disable Java Web Start for a previously deployed eligible
application client using the asadmin set command.
To disable Java Web Start for all eligible application clients in an application, use the following
command:
asadmin set applications.application.app-name.property.java-web-start-enabled="false"
To disable Java Web Start for a stand-alone eligible application client, use the following
command:
asadmin set applications.application.module-name.property.java-web-start-enabled="false"
Setting java-web-start-enabled="true" re-enables Java Web Start for an eligible application
client. For more information about the asadmin set command, see the Oracle GlassFish
DownloadingandLaunchinganApplicationClient
If Java Web Start is enabled for your deployed application client, you can launch it for testing.
Simply click on the Launch button next to the application client or application's listing on the
App Client Modules page in the Administration Console.
On other machines, you can download and launch the application client using Java Web Start in
the following ways:
Using a web browser, directly enter the URL for the application client. See The Application
Client URL on page 204.
Click on a link to the application client froma web page.

Use the Java Web Start command javaws, specifying the URL of the application client as a
command line argument.
If the application has previously been downloaded using Java Web Start, you have
additional alternatives.
Use the desktop icon that Java Web Start created for the application client. When Java
Web Start downloads an application client for the frst time it asks you if such an icon
should be created.
Use the Java Web Start control panel to launch the application client.
When you launch an application client, Java Web Start contacts the server to see if a newer
client version is available. This means you can redeploy an application client without having to
worry about whether client machines have the latest version.
The ApplicationClient URL
The default URL for an application or module generally is as follows:
http://host:port/context-root
The default URL for a stand-alone application client module is as follows:
http://host:port/appclient-module-id
The default URL for an application client module embedded within an application is as follows.
Note that the relative path to the application client JARfle is included.
http://host:port/application-id/appclient-path
If the context-root, appclient-module-id, or application-id is not specifed during deployment,
the name of the JARor EARfle without the extension is used. If the application client module
or application is not in JARor EARfle format, an appclient-module-id or application-id is
generated.
Regardless of howthe context-root or id is determined, it is written to the server log when you
deploy the application. For details about naming, see Naming Standards in Oracle GlassFish
To set a diferent URL for an application client, use the context-root subelement of the
java-web-start-access element in the glassfish-application-client.xml fle. This
overrides the appclient-module-id or application-id. See Oracle GlassFish Server 3.1 Application
Deployment Guide.
You can also pass arguments to the ACCor to the application client's main method as query
parameters in the URL. If multiple application client arguments are specifed, they are passed in
the order specifed.
Aquestion mark separates the context root fromthe arguments. Ampersands (&) separate the
arguments and their values. Each argument and each value must begin with arg=. Here is an
example URL with a -color argument for a stand-alone application client. The -color
argument is passed to the application client's main method.
http://localhost:8080/testClient?arg=-color&arg=red
Note If you are using the javaws URL command to launch Java Web Start with a URL that
contains arguments, enclose the URL in double quotes (") to avoid breaking the URL at the
ampersand (&) symbol.
Ideally, you should build your production application clients with user-friendly interfaces that
collect information which might otherwise be gathered as command-line arguments. This
minimizes the degree to which users must customize the URLs that launch application clients
using Java Web Start. Command-line argument support is useful in a development
environment and for existing application clients that depend on it.
SigningJARFiles UsedinJavaWebStart
Java Web Start enforces a security sandbox. By default it grants any application, including
application clients, only minimal privileges. Because Java Web Start applications can be so
easily downloaded, Java Web Start provides protection frompotentially harmful programs that
might be accessible over the network. If an application requires a higher privilege level than the
sandbox permits, the code that needs privileges must be in a JARfle that was signed.
When Java Web Start downloads such a signed JARfle, it displays information about the
certifcate that was used to sign the JARif that certifcate is not trusted. It then asks you whether
you want to trust that signed code. If you agree, the code receives elevated permissions and
runs. If you reject the signed code, Java Web Start does not start the downloaded application.
Your frst Java Web Start launch of an application client is likely to involve this prompting
because by default GlassFish Server uses a self-signed certifcate that is not linked to a trusted
authority.
The GlassFish Server serves two types of signed JARfles in response to Java Web Start requests.
One type is a JARfle installed as part of the GlassFish Server, which starts an application client
during a Java Web Start launch: as-install/lib/gf-client.jar.
The other type is a generated application client JARfle. As part of deployment, the GlassFish
Server generates a newapplication client JARfle that contains classes, resources, and
descriptors needed to run the application client on end-user systems. When you deploy an
application with the asadmin deploy command's --retrieve option, use the asadmin
get-client-stubs command, or select the Generate RMIStubs option fromthe EJB Modules
deployment page in the Administration Console, this is one of the JARfles retrieved to your
system. Because application clients need access beyond the minimal sandbox permissions to
work in the Java Web Start environment, the generated application client JARfle must be
signed before it can be downloaded to and executed on an end-user system.
AJARfle can be signed automatically or manually.
Automatically Signing JARFiles on page 206
Using the jar-signing-alias Deployment Property on page 206

Automatically SigningJARFiles
The GlassFish Server automatically creates a signed version of the required JARfle if none
exists. When a Java Web Start request for the gf-client.jar fle arrives, the GlassFish Server
looks for domain-dir/java-web-start/gf-client.jar. When a request for an application's
generated application client JARfle arrives, the GlassFish Server looks in the directory
domain-dir/java-web-start/app-name for a fle with the same name as the generated JARfle
created during deployment.
In either case, if the requested signed JARfle is absent or older than its unsigned counterpart,
the GlassFish Server creates a signed version of the JARfle automatically and deposits it in the
relevant directory. Whether the GlassFish Server just signed the JARfle or not, it serves the fle
fromthe domain-dir/java-web-start directory tree in response to the Java Web Start request.
To sign these JARfles, by default the GlassFish Server uses its self-signed certifcate. When you
create a newdomain, either by installing the GlassFish Server or by using the asadmin
create-domain command, the GlassFish Server creates a self-signed certifcate and adds it to
the domain's key store.
Aself-signed certifcate is generally untrustworthy because no certifcation authority vouches
for its authenticity. The automatic signing feature uses the same certifcate to create all required
signed JARfles.
Usingthe jar-signing-alias Deployment Property
The asadmin deploy command property jar-signing-alias specifes the alias for the security
certifcate with which the application client container JARfle is signed.
Java Web Start won't execute code requiring elevated permissions unless it resides in a JARfle
signed with a certifcate that the user's systemtrusts. For your convenience, GlassFish Server
signs the JARfle automatically using the self-signed certifcate fromthe domain, s1as. Java
Web Start then asks the user whether to trust the code and displays the GlassFish Server
certifcate information.
To sign this JARfle with a diferent certifcate, frst add the certifcate to the domain keystore.
You can use a certifcate froma trusted authority, which avoids the Java Web Start prompt. To
add a certifcate to the domain keystore, see Administering JSSE Certifcates in Oracle
GlassFish Server 3.1 Security Guide.
Next, deploy your application using the jar-signing-alias property. For example:
asadmin deploy --property jar-signing-alias=MyAlias MyApp.ear
For more information about the asadmin deploy command, see the Oracle GlassFish
Error Handling
When an application client is launched using Java Web Start, any error that the application
client logic does not catch and handle is written to System.err and displayed in a dialog box.
This display appears if an error occurs even before the application client logic receives control.
It also appears if the application client code does not catch and handle errors itself.
Vendor Icon, SplashScreen, andText
To specify a vendor-specifc icon, splash screen, text string, or a combination of these for Java
Web Start download and launch screens, use the vendor element in the
glassfish-application-client.xml fle. The complete format of this element's data is as
follows:
<vendor>icon-image-URI::splash-screen-image-URI::vendor-text</vendor>
The following example vendor element contains an icon, a splash screen, and a text string:
<vendor>images/icon.jpg::otherDir/splash.jpg::MyCorp, Inc.</vendor>
The following example vendor element contains an icon and a text string:
<vendor>images/icon.jpg::MyCorp, Inc.</vendor>
The following example vendor element contains a splash screen and a text string; note the initial
double colon:
<vendor>::otherDir/splash.jpg::MyCorp, Inc.</vendor>
The following example vendor element contains only a text string:
<vendor>MyCorp, Inc.</vendor>
The default value is the text string Application Client.
For more information about the glassfish-application-client.xml fle, see the Oracle
You can also specify a vendor-specifc icon, splash screen, text string, or a combination by using
a customJNLP fle; see Creating a CustomJNLP File on page 208.
Creatinga CustomJNLPFile
You can partially customize the Java Network Launching Protocol (JNLP) fle that GlassFish
Server uses for Java Web Start.
Specifying the JNLP File in the Deployment Descriptor on page 208
Referring to JARFiles fromthe JNLP File on page 208
Referring to Other JNLP Files on page 209
Combining Customand Automatically Generated Content on page 209

For more information about JNLP, see the Java Web Start Architecture JNLP Specifcation and
API Documentation (http://java.sun.com/
javase/technologies/desktop/javawebstart/download-spec.html).
Specifyingthe JNLPFile inthe Deployment Descriptor
To specify a customJNLP fle for Java Web Start, use the jnlp-doc element in the
glassfish-application-client.xml fle. If none is specifed, a default JNLP fle is generated.
The value of the jnlp-doc element is a relative path with the following format:
[path-to-JAR-in-EAR!]path-to-JNLP-in-JAR
The default path-to-JAR-in-EAR is the current application client JARfle. For example, if the
JNLP fle is in the application client JARfle at custom/myInfo.jnlp, the element value would
look like this:
<java-web-start-access>
<jnlp-doc>custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>
If the application client is inside an EARfle, you can place the customJNLP fle inside another
JARfle in the EAR. For example, if the JNLP fle is in a JARfle at other/myLib.jar, the
element value would look like this, with an exclamation point (!) separating the path to the JAR
fromthe path in the JAR:
<java-web-start-access>
<jnlp-doc>other/myLib.jar!custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>
For more information about the glassfish-application-client.xml fle, see the Oracle
GlassFish Server 3.0.1 Application Deployment Guide.
ReferringtoJARFiles fromthe JNLPFile
As with any JNLP document, the customJNLP fle can refer to JARfles the application client
requires.
Do not specify every JARon which the client depends. GlassFish Server automatically handles
JARfles that the Java EE specifcation requires to be available to the application client. This
includes JARfles listed in the application client JARfle's manifest Class-Path and JARfles in
the EARfle's library directory (if any) and their transitive closures. The customJNLP fle
should specify only those JARfles the client needs that GlassFish Server would not otherwise
include.
Package these JARfles in the EARfle, as with any JARfle required by an application client.
Use relative URIs in the <jar href="..."> and <nativelib href="..."> elements to point to
the JARfles. The codebase that GlassFish Server assigns for the fnal client JNLP fle
corresponds to the top level of the EARfle. Therefore, relative href references correspond
directly to the relative path to the JARfles within the EARfle.
Neither the Java EE specifcation nor GlassFish Server supports packaging JARfles inside the
application client JARfle itself. Nothing prevents this, but GlassFish Server does no special
processing of such JARfles. They do not appear in the runtime class path and they cannot be
referenced fromthe customJNLP fle.
ReferringtoOther JNLPFiles
The JNLP fle can also refer to other customJNLP fles using <extension href="..."/>
elements. To be consistent with relative href references to JARfles, the relative href references
to JNLP fles are resolved within the EARfle. You can place these JNLP fles directly in the EAR
fle or inside JARfles that the EARfle contains. Use one of these formats for these href
references:
[path-to-JAR-in-EAR!]path-to-JNLP-in-JAR
path-to-JNLP-in-EAR
Note that these formats are not equivalent to the format of the jnlp-doc element in the
glassfish-application-client.xml fle.
These formats followthe standard entry-within-a-JARURI syntax and semantics. Support for
this syntax comes fromthe automated Java Web Start support in GlassFish Server. This is not a
feature of Java Web Start or the JNLP standard.
CombiningCustomandAutomatically GeneratedContent
GlassFish Server recognizes these types of content in the JNLP fle:
Owned GlassFish Server owns the content and ignores any customcontent
Merged Automatically generated content and customcontent are merged
Defaulted Customcontent is used if present, otherwise default content is provided

You can compose a complete JNLP fle and package it with the application client. GlassFish
Server then combines it with its automatically generated JNLP fle. You can also provide
content that only adds to or replaces what GlassFish Server generates. The customcontent must
conformto the general structure of the JNLP format so that GlassFish Server can properly place
it in the fnal JNLP fle.
For example, to specify a single native library to be included only for Windows systems, the new
element to add might be as follows:
<nativelib href="windows/myLib.jar"/>
However, you must indicate where in the overall document this element belongs. The actual
customJNLP fle should look like this:
<jnlp>
<resources os="Windows">
<nativelib href="windows/myLib.jar"/>
</resources>
</jnlp>
GlassFish Server provides default <information> and <resources> elements, without
specifying attributes such as os, arch, platform, or locale. GlassFish Server merges its own
content within those elements with customcontent under those elements. Further, you can
provide your own <information> and <resources> elements (and fragments within them)
that specify at least one of these attributes.
In general, you can performthe following customizations:
Override the GlassFish Server defaults for the child elements of <information> elements
that have no attribute settings for os, arch, platform, and locale. Among these child
elements are <title>, <vendor>, <description>, <icon>, and so on.
Add <information> elements with os, arch, platform, or locale settings. You can also add
child elements.
Add child elements of <resources> elements that have no attribute settings for os, arch, or
locale. Among these child elements are <jar>, <property>, <nativelib>, and so on. You
can also customize attributes of the <java> child element.
Add <resources> elements that specify at least one of os, arch, or locale. You can also add
child elements.
This fexibility allows you to add JARfles to the application (including platform-specifc native
libraries) and set properties to control the behavior of your application clients.
The following tables provide more detail about what parts of the JNLP fle you can add to and
modify.
TABLE 101 OwnedJNLPFile Content
JNLPFile Fragment Description
<jnlp codebase="xxx" ...> GlassFish Server controls this content for application clients
packaged in EARfles. The developer controls this content for
application clients packaged in WARfles.
<jnlp href="xxx" ...> GlassFish Server controls this content for application clients
packaged in EARfles. The developer controls this content for
application clients packaged in WARfles.
<jnlp>
<security>
GlassFish Server must control the permissions requested for
each JNLP fle. All permissions are needed for the main fle,
which launches the ACC. The permissions requested for other
JNLP documents depend on whether the JARfles referenced in
those documents are signed.
<jnlp>
<application-desc>
<argument> ...
GlassFish Server sets the main-class and the arguments to be
passed to the client.
TABLE 102 DefaultedJNLPFile Content
<jnlp spec="xxx" ...> Specifes the JNLP specifcation version.
<jnlp>
<information [no-attributes]>
Specifes the application title, vendor, home page, various
description text values, icon images, and whether ofine
execution is allowed.
<jnlp>
<resources [no-attributes]>
<java version="xxx"
java-vm-args="yyy" ...>
Specifes the Java SE version or selected VMparameter settings.
TABLE 103 MergedJNLPFile Content
<jnlp>
<information [attributes]>
You can specify one or more of the os, arch, platform, and
locale attributes for the <information> element. You can also
specify child elements; GlassFish Server provides no default
children.
<jnlp>
<resources [attributes]>
You can specify one or more of the os, arch, platform, and
locale attributes for the <resources> element. You can also
specify child elements; GlassFish Server provides no default
children.
TABLE 103 Merged JNLPFile Content (Continued)
<jnlp>
<jar ...>
Adds JARfles to be included in the application to the JARfles
provided by GlassFish Server.
<jnlp>
<nativelib ...>
Adds native libraries to be included in the application. Each
entry in a JARlisted in a <nativelib> element must be a native
library for the correct platform. The full syntax of the
<nativelib> element lets the developer specify the platformfor
that native library.
<jnlp>
<property ...>
Adds systemproperties to be included in the application to the
systemproperties defned by GlassFish Server.
<jnlp>
<extension ...>
Specifes another customJNLP fle.
<jnlp>
<component-desc ...>
Includes another customJNLP fle that specifes a component
extension.
<jnlp>
<installer-desc ...>
Includes another customJNLP fle that specifes an installer
extension.
Usingthe Embeddable ACC
You can embed the ACCinto your application client. If you place the
as-install/lib/gf-client.jar fle in your runtime classpath, your application creates the ACC
after your application code has started, then requests that the ACCstart the application client
portion. The basic model for coding is as follows:
1. Create a builder object.
2. Operate on the builder to confgure the ACC.
3. Obtain a newACCinstance fromthe builder.
4. Present a client archive or class to the ACCinstance.
5. Start the client running within the newly created ACCinstance.
Your code should followthis general pattern:
// one TargetServer for each ORB endpoint for bootstrapping
TargetServer[] servers = ...;
// Get a builder to set up the ACC
AppClientContainer.Builder builder = AppClientContainer.newBuilder(servers);
// Fine-tune the ACCs configuration. Note ability to "chain" invocations.
builder.callbackHandler("com.acme.MyHandler").authRealm("myRealm"); // Modify config
// Get a container for a client.
URI clientURI = ...; // URI to the client JAR
AppClientContainer acc = builder.newContainer(clientURI);
or
Class mainClass = ...;
AppClientContainer acc = builder.newContainer(mainClass);
// In either case, start the client running.
String[] appArgs = ...;
acc.startClient(appArgs); // Start the client
...
acc.close(); // close the ACC(optional)
The ACCloads the application client's main class, performs any required injection, and
transfers control to the static main method. The ACC's run method returns to the calling
application as soon as the client's main method returns to the ACC.
If the application client's main method starts any asynchronous activity, that work continues
after the ACCreturns. The ACChas no knowledge of whether the client's main method triggers
asynchronous work. Therefore, if the client causes work on threads other than the calling
thread, and if the embedding application needs to knowwhen the client's asynchronous work
completes, the embedding application and the client must agree on howthis happens.
The ACC's shutdown handling is invoked fromthe ACC's close method. The calling
application can invoke acc.close() to close down any services started by the ACC. If the
application client code started any asynchronous activity that might still depend on ACC
services, invoking close before that asynchronous activity completes could cause unpredictable
and undesirable results. The shutdown handling is also run automatically at VMshutdown if
the code has not invoked close before then.
The ACCdoes not prevent the calling application fromcreating or running more than one ACC
instance during a single execution of the application either serially or concurrently. However,
other services used by the ACC(transaction manager, security, ORB, and so on) might or might
not support such serial or concurrent reuse.
RunninganApplicationClient Usingthe appclient
Script
To run an application client, you can launch the ACCusing the appclient script, whether or
not Java Web Start is enabled. This is optional. This script is located in the as-install/bin
directory. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
Usingthe package-appclient Script
You can package the GlassFish Server systemfles required to launch application clients on
remote systems into a single JARfle using the package-appclient script. This is optional. This
script is located in the as-install/bin directory. For details, see the Oracle GlassFish
The client.policy File
The client.policy fle is the J2SE policy fle used by the application client. Each application
client has a client.policy fle. The default policy fle limits the permissions of Java EE
deployed application clients to the minimal set of permissions required for these applications to
operate correctly. If an application client requires more than this default set of permissions, edit
the client.policy fle to add the custompermissions that your application client needs. Use
the J2SE standard policy tool or any text editor to edit this fle.
For more information on using the J2SE policy tool, see http://download.oracle.com/
javase/tutorial/security/tour2/index.html.
For more information about the permissions you can set in the client.policy fle, see
javase/6/docs/technotes/guides/security/permissions.html.
UsingRMI/IIOPOver SSL
You can confgure RMI/IIOP over SSL in two ways: using a username and password, or using a
client certifcate.
To use a username and password, confgure the ior-security-config element in the
glassfish-ejb-jar.xml fle. The following confguration establishes SSL between an
application client and an EJB component using a username and password. The user has to login
to the ACCusing either the sun-acc.xml mechanismor the Programmatic Login on page 72
mechanism.
<ior-security-config>
<transport-config>
<integrity>required</integrity>
<confidentiality>required</confidentiality>
<establish-trust-in-target>supported</establish-trust-in-target>
<establish-trust-in-client>none</establish-trust-in-client>
</transport-config>
<as-context>
<auth-method>username_password</auth-method>
<realm>default</realm>
<required>true</required>
</as-context>
<sas-context>
<caller-propagation>none</caller-propagation>
</sas-context>
</ior-security-config>
For more information about the glassfish-ejb-jar.xml and sun-acc.xml fles, see the Oracle
To use a client certifcate, confgure the ior-security-config element in the
glassfish-ejb-jar.xml fle. The following confguration establishes SSL between an
application client and an EJB component using a client certifcate.
<ior-security-config>
<transport-config>
<integrity>required</integrity>
<confidentiality>required</confidentiality>
<establish-trust-in-target>supported</establish-trust-in-target>
<establish-trust-in-client>required</establish-trust-in-client>
</transport-config>
<as-context>
<auth-method>none</auth-method>
<realm>default</realm>
<required>false</required>
</as-context>
<sas-context>
<caller-propagation>none</caller-propagation>
</sas-context>
</ior-security-config>
To use a client certifcate, you must also specify the systemproperties for the keystore and
truststore to be used in establishing SSL. To use SSL with the Application Client Container
(ACC), you need to set these systemproperties in one of the following ways:
Use the newsyntax of the appclient script and specify the systemproperties as JVM
options. See Running an Application Client Using the appclient Script on page 213.
Set the environment variable VMARGS in the shell. For example, in the ksh or bash shell, the
command to set this environment variable would be as follows:
export VMARGS="-Djavax.net.ssl.keyStore=${keystore.db.file}
-Djavax.net.ssl.trustStore=${truststore.db.file}
-Djavax.net.ssl.keyStorePass word=${ssl.password}
-Djavax.net.ssl.trustStorePassword=${ssl.password}"
Optionally, you can set the env element using Ant. For example:
<target name="runclient">
<exec executable="${S1AS_HOME}/bin/appclient">
<env key="VMARGS" value=" -Djavax.net.ssl.keyStore=${keystore.db.file}
-Djavax.net.ssl.trustStore=${truststore.db.file}
-Djavax.net.ssl.keyStorePasword=${ssl.password}
-Djavax.net.ssl.trustStorePassword=${ssl.password}"/>
<arg value="-client"/>
<arg value="${appClient.jar}"/>
</exec>
</target>
Connectingtoa Remote EJBModuleThrougha
Firewall
To deploy and run an application client that connects to an EJB module on a GlassFish Server
instance that is behind a frewall, you must set ORB Virtual Address Agent Implementation
(ORBVAA) options. Use the asadmin create-jvm-options command as follows:
asadmin create-jvm-options -Dcom.sun.corba.ee.ORBVAAHost=public-IP-adress
asadmin create-jvm-options -Dcom.sun.corba.ee.ORBVAAPort=public-port
asadmin create-jvm-options
-Dcom.sun.corba.ee.ORBUserConfigurators.com.sun.corba.ee.impl.plugin.hwlb.VirtualAddressAgentImpl=x
Set the ORBVAAHost and ORBVAAPort options to the host and port of the public address. The
ORBUserConfigurators option tells the ORB to create an instance of the
VirtualAddressAgentImpl class and invoke the configure method on the resulting object,
which must implement the com.sun.corba.ee.spi.orb.ORBConfgurator interface. The
ORBUserConfigurators value doesn't matter. Together, these options create an ORB that in
turn creates Object references (the underlying implementation of remote EJB references)
containing the public address, while the ORB listens on the private address specifed for the
IIOP port in the GlassFish Server confguration.
Specifyinga SplashScreen
Java SE 6 ofers splash screen support, either through a Java command-line option or a manifest
entry in the application's JARfle. To take advantage of this Java SE feature in your application
client, you can do one of the following:
Create the appclient JARfle so that its manifest contains a SplashScreen-Image entry that
specifes the path to the image in the client. The java command displays the splash screen
before starting the ACCor your client, just as with any Java application.
Use the new appclient ... -jar launch format, using the -splash command-line option
at runtime or the SplashScreen-Image manifest entry at development time. See Running
an Application Client Using the appclient Script on page 213.
In the environment that runs the appclient script, set the VMOPTS environment variable to
include the -splash option before invoking the appclient script to launch the client.
Build an application client that uses the embeddable ACCfeature and specify the splash
screen image using one of the following:
The -splash option of the java command
SplashScreen-Image in the manifest for your program(not the manifest for the
application client)
See Using the Embeddable ACC on page 212.
During application (EARfle) deployment, the GlassFish Server generates faade JARfles, one
for the application and one for each application client in the application. During application
client module deployment, the GlassFish Server generates a single facade JARfor the
application client. The appclient script supports splash screens inside the application client
JARonly if you launch an application client facade or appclient client JAR. If you launch the
facade for an application or the undeployed application itself, the appclient script cannot take
advantage of the Java SE 6 splash screen feature.
SettingLoginRetries
You can set a JVMoption using the appclient script that determines the number of login
retries allowed. This option is -Dorg.glassfish.appclient.acc.maxLoginRetries=n where
n is a positive integer. The default number of retries is 3.
This retry loop happens when the ACCattempts to performinjection if you annotated the
client's main class (for example, using @Resource). If instead of annotations your client uses the
InitialContext explicitly to look up remote resources, the retry loop does not apply. In this
case, you could write logic to catch an exception around the lookup and retry explicitly.
For details about the appclient script syntax, see the Oracle GlassFish Server 3.1-3.1.1 Reference
Manual.
UsingLibraries withApplicationClients
The Libraries feld in the Administration Console's deployment page and the --libraries
option of the asadmin deploy command do not apply to application clients. Neither do the
as-install/lib, domain-dir/lib, and domain-dir/lib/classes directories comprising the
Common Class Loader. These apply only to applications and modules deployed to the server.
For more information, see Chapter 2, Class Loaders.
To use libraries with an application client, package the application client in an application (EAR
fle). Then, either place the libraries in the /lib directory of the EARfle or specify their location
in the application client JARfle's manifest Class-Path.
DevelopingClients Without the ACC
This section describes the procedure to create, assemble, and deploy a Java-based client that is
not packaged using the Application Client Container (ACC).
Developing Clients Without the ACC
To access an EJB component froma stand-alone client on page 218
To access an EJB component froma server-side module on page 219
To access a JMS resource froma stand-alone client on page 221

For information about using the ACC, see Developing Clients Using the ACC on page 199.
For general information about EJB components and clients, see EJB FAQ
(http://glassfish.java.net/javaee5/ejb/EJB_FAQ.html).
Toaccess anEJBcomponent froma stand-alone client

Inyour client code, instantiate the InitialContext:
InitialContext ctx = new InitialContext();
It is not necessary to explicitly instantiate a naming context that points to the CosNaming
service.
Inthe client code, look upthe home object by specifyingthe JNDI name of the home object.
Here is an EJB 2.x example:
Object ref = ctx.lookup("jndi-name");
BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);
BeanRemoteBusiness bean =(BeanRemoteBusiness) ctx.lookup("com.acme.BeanRemoteBusiness");
page 273.
Deploy the EJBcomponent tobe accessed.
For more information on deployment, see About Deployment Tools in Oracle GlassFish
Copy the as-install/lib/gf-client.jar fle tothe client machine andinclude it inthe classpath
onthe client side.
The gf-client.jar fle references GlassFish Server JARfles in its MANIFEST.MF fle. If there is
no GlassFish Server installation on the client machine, you must also copy the
as-install/modules directory to the client machine and maintain its directory structure relative
to the as-install/lib/gf-client.jar fle. Or you can use the package-appclient script; see
Using the package-appclient Script on page 214.
1
2
3
4
Toaccess EJBcomponents that are residingina remote system, set the followingsystem
properties for the JavaVirtual Machine startupoptions:
-Dorg.omg.CORBA.ORBInitialHost=${ORBhost}
-Dorg.omg.CORBA.ORBInitialPort=${ORBport}
Here ORBhost is the Application Server hostname and ORBport is the ORB port number
(default is 3700 for the default server instance, named server).
You can use the asadmin get command to get the IIOP port numbers. For example:
asadmin get "configs.config.server-config.iiop-service.iiop-listener.orb-listener-1.*"
Toset uploadbalancingandremote EJBreference failover, defne the endpoints property as
follows:
-Dcom.sun.appserv.iiop.endpoints=host1:port1,host2:port2,...
The endpoints property specifes a comma-separated list of one or more IIOP endpoints used
for load balancing. An IIOP endpoint is in the formhost:port, where the host is an IPv4 address
or host name, and the port specifes the port number.
If the endpoints list is changed dynamically in the code, the newlist is used only if a new
InitialContext is created.
Runthe stand-alone client.
As long as the client environment is set appropriately and the JVMis compatible, you merely
need to run the main class.
Toaccess anEJBcomponent froma server-side

module
Aserver-side module can be a servlet, another EJB component, or another type of module.
Inyour module code, instantiate the InitialContext:
It is not necessary to explicitly instantiate a naming context that points to the CosNaming
service.
To set up load balancing and remote EJB reference failover, defne the endpoints property as
follows:
Hashtable env = new Hashtable();
env.put("com.sun.appserv.iiop.endpoints","host1:port1,host2:port2,...");
InitialContext ctx = new InitialConext(env);
5
6
7
1
The endpoints property specifes a comma-separated list of one or more IIOP endpoints used
for load balancing. An IIOP endpoint is in the formhost:port, where the host is an IPv4 address
or host name, and the port specifes the port number.
If the endpoints list is changed dynamically in the code, the newlist is used only if a new
InitialContext is created.
Inthe module code, look upthe home object by specifyingthe JNDI name of the home object.
Object ref = ctx.lookup("jndi-name");
BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);
BeanRemoteBusiness bean =(BeanRemoteBusiness) ctx.lookup("com.acme.BeanRemoteBusiness");
page 273.
Deploy the EJBcomponent tobe accessed.
Deploy the module.
2
3
4
5
Toaccess a JMS resource froma stand-alone client

Create a JMS client.
For detailed instructions on developing a JMS client, see Chapter 48, Java Message Service
Examples, in The Java EE 6 Tutorial.
Confgure a JMS resource onGlassFishServer.
For information on confguring JMS resources, see Administering JMS Connection Factories
and Destinations in Oracle GlassFish Server 3.1 Administration Guide.
Copy the followingJARfles tothe client machine andinclude theminthe classpathonthe
client side:
gf-client.jar - available at as-install/lib
imqjmsra.jar - available at as-install/lib/install/aplications/jmsra

The gf-client.jar fle references GlassFish Server JARfles in its MANIFEST.MF fle. If there is
no GlassFish Server installation on the client machine, you must also copy the
as-install/modules directory to the client machine and maintain its directory structure relative
to the as-install/lib/gf-client.jar fle. Or you can use the package-appclient script; see
Using the package-appclient Script on page 214.
Runthe stand-alone client.
As long as the client environment is set appropriately and the JVMis compatible, you merely
need to run the main class.
1
2
3
4
5
222
Developing Connectors
This chapter describes Oracle GlassFish Server support for the Java EE 1.6 Connector
Architecture, also known as JSR322 (http://jcp.org/en/jsr/detail?id=322).
The Java EE Connector Architecture provides a Java solution to the problemof connectivity
between multiple application servers and existing enterprise information systems (EISs). By
using the Java EE Connector architecture, EIS vendors no longer need to customize their
product for each application server. Application server vendors who conformto the Java EE
Connector architecture do not need to write customcode to add connectivity to a newEIS.
This chapter uses the terms connector and resource adapter interchangeably. Both terms refer to
a resource adapter module that is developed in conformance with the Java EE Connector
Architecture Specifcation.
Note If you installed the Web Profle, connector modules that use only outbound
communication features and work-management that does not involve inbound
communication features are supported. Other connector features are supported only in the full
GlassFish Server.
For more information about connectors, see Java EE Connector Architecture
(http://java.sun.com/j2ee/connector/) and Chapter 37: Java EE Connector Architecture
in the The Java EE 6 Tutorial (http://download.oracle.com/javaee/6/tutorial/doc/).
For connector examples, see http://developers.sun.com/appserver/reference/techart/
as8_connectors.
For information about deploying a connector to the GlassFish Server, see the Oracle GlassFish
11
C H A P T E R 1 1
223
Connector Support in the GlassFish Server on page 224
Advanced Connector Confguration Options on page 225
Inbound Communication Support on page 231
Outbound Communication Support on page 232
Confguring a Message Driven Bean to Use a Resource Adapter on page 232

Connector Support inthe GlassFishServer
The GlassFish Server supports the development and deployment of resource adapters that are
compatible with the Connector 1.6 specifcation (and, for backward compatibility, the
Connector 1.0 and 1.5 specifcations).
The Connector 1.0 specifcation defnes the outbound connectivity systemcontracts between
the resource adapter and the GlassFish Server. The Connector 1.5 specifcation introduces
major additions in defning systemlevel contracts between the GlassFish Server and the
resource adapter with respect to inbound connectivity, life cycle management, and thread
management. The Connector 1.6 specifcation introduces further additions in defning system
level contracts between the GlassFish Server and the resource adapter with respect to the
following:
Generic work context contract Ageneric contract that enables a resource adapter to
control the execution context of a Work instance that it has submitted to the GlassFish Server
for execution. The Generic work contract provides the mechanismfor a resource adapter to
augment the runtime context of a Work instance with additional contextual information
fown-in fromthe EIS. This contract enables a resource adapter to control, in a more fexible
manner, the contexts in which the Work instances submitted by it are executed by the
application server's WorkManager.
Security work context Astandard contract that enables a resource adapter to establish
security information while submitting a Work instance for execution to a WorkManager and
while delivering messages-to-message endpoints residing in the GlassFish Server. This
contract provides a mechanismto support the execution of a Work instance in the context of
an established identity. It also supports the propagation of user information or Principal
information froman EIS to a MessageEndpoint during message infow.
Transaction context The transaction context contract between the resource adapter and
the application server leverages the Generic Work Context mechanismby describing a
standard WorkContext, the TransactionContext. It represents the standard interface a
resource adapter can use to propagate transaction context information fromthe EIS to the
application server.
Connector Support in the GlassFish Server
Connector Architecture for JMS andJDBC
In the Administration Console, connector, JMS, and JDBCresources are handled diferently,
but they use the same underlying Connector architecture. In the GlassFish Server, all
communication to an EIS, whether to a message provider or an RDBMS, happens through the
Connector architecture. To provide JMS infrastructure to clients, the GlassFish Server uses the
GlassFish Server Message Queue software. To provide JDBCinfrastructure to clients, the
GlassFish Server uses its own JDBCsystemresource adapters. The GlassFish Server
automatically makes these systemresource adapters available to any client that requires them.
For more information about JMS in the GlassFish Server, see Chapter 17, Using the Java
Message Service. For more information about JDBCin the GlassFish Server, see Chapter 14,
Using the JDBCAPI for Database Access.
Connector Confguration
The GlassFish Server does not need to use sun-ra.xml, which previous GlassFish Server
versions used, to store server-specifc deployment information inside a Resource Adapter
Archive (RAR) fle. (However, the sun-ra.xml fle is still supported for backward
compatibility.) Instead, the information is stored in the server confguration. As a result, you
can create multiple connector connection pools for a connection defnition in a functional
resource adapter instance, and you can create multiple user-accessible connector resources
(that is, registering a resource with a JNDI name) for a connector connection pool. In addition,
dynamic changes can be made to connector connection pools and the connector resource
properties without restarting the GlassFish Server.
AdvancedConnector ConfgurationOptions
Thread Associations on page 226
Security Maps on page 226
Work Security Maps on page 227
Overriding Confguration Properties on page 227
Testing a Connector Connection Pool on page 228
Flushing a Connector Connection Pool on page 228
Handling Invalid Connections on page 229
Setting the Shutdown Timeout on page 229
Specifying the Class Loading Policy on page 230
Using Last Agent Optimization of Transactions on page 230
Disabling Pooling for a Connection on page 231
Using Application-Scoped Connectors on page 231

Advanced Connector Confguration Options
Chapter 11 Developing Connectors 225
ThreadAssociations
Connectors can submit work instances to the GlassFish Server for execution. By default, the
GlassFish Server services work requests for all connectors fromits default thread pool.
However, you can associate a specifc user-created thread pool to service work requests froma
connector. Athread pool can service work requests frommultiple resource adapters. To create
a thread pool:
In the Administration Console, select Thread Pools under the relevant confguration. For
Use the asadmin create-threadpool command. For details, see the Oracle GlassFish
To associate a connector with a thread pool:
In the Administration Console, open the Applications component and select Resource
Adapter Confgs. Specify the name of the thread pool in the Thread Pool IDfeld. For details,
Use the ----threadpoolid option of the asadmin create-resource-adapter-config

command. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
If you create a resource adapter confguration for a connector module that is already deployed,
the connector module deployment is restarted with the newconfguration properties.
Security Maps
Create a security map for a connector connection pool to map an application principal or a user
group to a back end EIS principal. The security map is usually used in situations where one or
more EIS back end principals are used to execute operations (on the EIS) initiated by various
principals or user groups in the application.
To create or update security maps for a connector connection pool:
In the Administration Console, open the Resources component, select Connectors, select
Connector Connection Pools, and select the Security Maps tab. For details, click the Help
button in the Administration Console.
Use the asadmin create-connector-security-map command. For details, see the Oracle
If a security map already exists for a connector connection pool, the newsecurity map is
appended to the previous one. The connector security map confguration supports the use of
the wildcard asterisk (*) to indicate all users or all user groups.
When an application principal initiates a request to an EIS, the GlassFish Server frst checks for
an exact match to a mapped back end EIS principal using the security map defned for the
connector connection pool. If there is no exact match, the GlassFish Server uses the wild card
character specifcation, if any, to determined the mapped back end EIS principal.
WorkSecurity Maps
Awork security map for a resource adapter maps an EIS principal or group to a application
principal or group. Awork security map is useful in situations where one or more application
principals execute operations initiated by principals or user groups in the EIS. Aresource
adapter can have multiple work security maps. Awork security map can map either principals
or groups, but not both.
To create a work security map, use the asadmin create-connector-work-security-map
command. For details, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
The work security map confguration supports the wildcard asterisk (*) character to indicate all
users or all user groups. When an EIS principal sends a request to the GlassFish Server, the
GlassFish Server frst checks for an exact match to a mapped application principal using the
work security map defned for the resource adapter. If there is no exact match, the GlassFish
Server uses the wild card character specifcation, if any, to determine the application principal.
OverridingConfgurationProperties
You can override the properties (config-property elements) specifed in the ra.xml fle of a
resource adapter:
In the Administration Console, open the Resources component and select Resource
Adapter Confgs. Create a newresource adapter confguration or select an existing one to
edit. Then enter property names and values in the Additional Properties table. For details,
Use the asadmin create-resource-adapter-config command to create a confguration

for a resource adapter. Use this commands ----property option to specify a name-value
pair for a resource adapter property. For details, see the Oracle GlassFish Server 3.1-3.1.1
Reference Manual.
You can specify confguration properties either before or after resource adapter deployment. If
you specify properties after deploying the resource adapter, the existing resource adapter is
restarted with the newproperties.
You can also use token replacement for overriding resource adapter confguration properties in
individual server instances when the resource adapter is deployed to a cluster. For example, for
a property called inboundPort, you can assign the value ${inboundPort}. You can then assign a
diferent value to this property for each server instance. Changes to systemproperties take efect
upon server restart.
Testinga Connector ConnectionPool
You can test a connector connection pool for usability in one of these ways:
In the Administration Console, open the Resources component, open the Connector
component, select Connection Pools, and select the connection pool you want to test. Then
select the Ping button in the top right corner of the page. For details, click the Help button in
the Administration Console.
Use the asadmin ping-connection-pool command. For details, see the Oracle GlassFish
Both these commands fail and display an error message unless they successfully connect to the
connection pool.
You can also specify that a connection pool is automatically tested when created or
reconfgured by setting the Ping attribute to true (the default is false) in one of the following
ways:
Enter a Ping value in the Connector Connection Pools page in the Administration Console.
For more information, click the Help button in the Administration Console.
Specify the ----ping option in the asadmin create-connector-connection-pool

command. For more information, see the Oracle GlassFish Server 3.1-3.1.1 Reference
Manual.
Flushinga Connector ConnectionPool
Flushing a connector connection pool recreates all the connections in the pool and brings the
pool to the steady pool size without the need for reconfguring the pool. Connection pool
reconfguration can result in application redeployment, which is a time-consuming operation.
Flushing destroys existing connections, and any existing transactions are lost and must be
retired.
You can fush a connector connection pool in one of these ways:
In the Administration Console, open the Resources component, open the Connector
component, select Connection Pools, and select the connection pool you want to fush.
Then select the Flush button in the top right corner of the page. For details, click the Help
Use the asadmin flush-connection-pool command. For details, see the Oracle GlassFish
HandlingInvalidConnections
If a resource adapter generates a ConnectionErrorOccured event, the GlassFish Server
considers the connection invalid and removes the connection fromthe connection pool.
Typically, a resource adapter generates a ConnectionErrorOccured event when it fnds a
ManagedConnection object unusable. Reasons can be network failure with the EIS, EIS failure,
fatal problems with the resource adapter, and so on.
If the fail-all-connections setting in the connection pool confguration is set to true, and a
single connection fails, all connections are closed and recreated. If this setting is false,
individual connections are recreated only when they are used. The default is false.
The is-connection-validation-required setting specifes whether connections have to be
validated before being given to the application. If a resources validation fails, it is destroyed,
and a newresource is created and returned. The default is false.
The prefer-validate-over-recreate property specifes that validating idle connections is
preferable to closing them. This property has no efect on non-idle connections. If set to true,
idle connections are validated during pool resizing, and only those found to be invalid are
destroyed and recreated. If false, all idle connections are destroyed and recreated during pool
resizing. The default is false.
You can set the fail-all-connections, is-connection-validation-required, and
prefer-validate-over-recreate confguration settings during creation of a connector
connection pool. Or, you can use the asadmin set command to dynamically reconfgure a
setting. For example:
asadmin set server.resources.connector-connection-pool.CCP1.fail-all-connections="true"
asadmin set server.resources.connector-connection-pool.CCP1.is-connection-validation-required="true"
asadmin set server.resources.connector-connection-pool.CCP1.property.prefer-validate-over-recreate="true"
The interface ValidatingManagedConnectionFactory exposes the method
getInvalidConnections to allowretrieval of the invalid connections. The GlassFish Server
checks if the resource adapter implements this interface, and if it does, invalid connections are
removed when the connection pool is resized.
Settingthe ShutdownTimeout
According to the Connector specifcation, while an application server shuts down, all resource
adapters should be stopped. Aresource adapter might hang during shutdown, since shutdown
is typically a resource intensive operation. To avoid such a situation, you can set a timeout that
aborts resource adapter shutdown if exceeded. The default timeout is 30 seconds per resource
adapter module. To confgure this timeout:
In the Administration Console, select Connector Service under the relevant confguration
and edit the shutdown Timeout feld. For details, click the Help button in the
Use the following asadmin set command:

asadmin set server.connector-service.shutdown-timeout-in-seconds="num-secs"
The GlassFish Server deactivates all message-driven bean deployments before stopping a
resource adapter.
Specifyingthe Class LoadingPolicy
Use the class-loading-policy setting to determine which resource adapters accessible to
applications. Allowed values are:
derived Applications access resource adapters based on references in their deployment

descriptors. These references can be resource-ref, resource-env-ref,
resource-adapter-mid, or equivalent annotations.
global All stand-alone resource adapters are available to all applications.

To confgure this setting, use the asadmin set command. For example:
asadmin set server.connector-service.class-loading-policy="global"
UsingLast Agent Optimizationof Transactions
Transactions that involve multiple resources or multiple participant processes are distributed or
global transactions. Aglobal transaction can involve one non-XAresource if last agent
optimization is enabled. Otherwise, all resources must be XA. For more information about
transactions in the GlassFish Server, see Chapter 15, Using the Transaction Service.
The Connector specifcation requires that if a resource adapter supports XATransaction, the
ManagedConnection created fromthat resource adapter must support both distributed and
local transactions. Therefore, even if a resource adapter supports XATransaction, you can
confgure its connector connection pools as non-XAor without transaction support for better
performance. Anon-XAresource adapter becomes the last agent in the transactions in which it
participates.
The value of the connection pool confguration property transaction-support defaults to the
value of the transaction-support property in the ra.xml fle. The connection pool
confguration property can override the ra.xml fle property if the transaction level in the
connection pool confguration property is lower. If the value in the connection pool
confguration property is higher, it is ignored.
DisablingPoolingfor a Connection
To disable connection pooling, set the Pooling attribute to false. The default is true. You can
enable or disable connection pooling in one of the following ways:
Enter a Pooling value in the Connector Connection Pools page in the Administration
Console. For more information, click the Help button in the Administration Console.
Specify the ----pooling option in the asadmin create-connector-connection-pool

Manual.
UsingApplication-ScopedConnectors
You can defne an application-scoped connector or other resource for an enterprise application,
web module, EJB module, connector module, or application client module by supplying a
glassfish-resources.xml deployment descriptor fle. For details, see Application-Scoped
Resources in Oracle GlassFish Server 3.1 Application Deployment Guide.
InboundCommunicationSupport
The Connector specifcation defnes the transaction and message infowsystemcontracts for
achieving inbound connectivity froman EIS. The message infowcontract also serves as a
standard message provider pluggability contract, thereby allowing various message providers to
seamlessly plug in their products with any application server that supports the message infow
contract. In the inbound communication model, the EIS initiates all communication to an
application. An application can be composed of enterprise beans (session, entity, or
message-driven beans), which reside in an EJB container.
Incoming messages are received through a message endpoint, which is a message-driven bean.
This message-driven bean asynchronously consumes messages froma message provider. An
application can also synchronously send and receive messages directly using messaging style
APIs.
Aresource adapter supporting inbound communication provides an instance of an
ActivationSpec JavaBean class for each supported message listener type. Each class contains a
set of confgurable properties that specify endpoint activation confguration information
during message-driven bean deployment. The required config-property element in the
ra.xml fle provides a list of confguration property names required for each activation
Inbound Communication Support
specifcation. An endpoint activation fails if the required property values are not specifed.
Values for the properties that are overridden in the message-driven beans deployment
descriptor are applied to the ActivationSpec JavaBean when the message-driven bean is
deployed.
Administered objects can also be specifed for a resource adapter, and these JavaBeans are
specifc to a messaging style or message provider. For example, some messaging styles may need
applications to use special administered objects (such as Queue and Topic objects in JMS).
Applications use these objects to send and synchronously receive messages using connection
objects using messaging style APIs. For more information about administered objects, see
OutboundCommunicationSupport
The Connector specifcation defnes the systemcontracts for achieving outbound connectivity
froman EIS. Aresource adapter supporting outbound communication provides an instance of
a ManagedConnectionFactory JavaBean class. AManagedConnectionFactory JavaBean
represents outbound connectivity information to an EIS instance froman application.
The 1.6 Connector specifcation introduces a mechanismthrough which the transaction level of
a ManagedConnectionFactory can be detected at runtime. During the confguration of a
ManagedConnectionFactory in the Connector Connection Pools page in the Administration
Console, the Administration Console can instantiate the ManagedConnectionFactory and
showthe level of transaction support. The three levels are no-tx, local-tx, xa-tx. If a
ManagedConnectionFactory returns local-tx as the level it can support, it is assumed that
xa-tx is not supported, and the Administration Console shows only no-tx and local-tx as the
available support levels.
For more information, click the Help button in the Administration Console.
Confguringa Message DrivenBeantoUse a Resource Adapter
The Connectors specifcations message infowcontract provides a generic mechanismto plug
in a wide-range of message providers, including JMS, into a Java-EE-compatible application
server. Message providers use a resource adapter and dispatch messages to message endpoints,
which are implemented as message-driven beans.
The message-driven bean developer provides activation confguration information in the
message-driven beans ejb-jar.xml fle. Confguration information includes
messaging-style-specifc confguration details, and possibly message-provider-specifc details as
well. The message-driven bean deployer uses this confguration information to set up the
activation specifcation JavaBean. The activation confguration properties specifed in
ejb-jar.xml override confguration properties in the activation specifcation defnition in the
ra.xml fle.
Outbound Communication Support
According to the EJB specifcation, the messaging-style-specifc descriptor elements contained
within the activation confguration element are not specifed because they are specifc to a
messaging provider. In the following sample message-driven bean ejb-jar.xml, a
message-driven bean has the following activation confguration property names:
destinationType, SubscriptionDurability, and MessageSelector.


...
<activation-config>
<activation-config-property>
<activation-config-property-name>
destinationType
</activation-config-property-name>
<activation-config-property-value>
javax.jms.Topic
</activation-config-property-value>
</activation-config-property>
SubscriptionDurability
Durable
MessageSelector
JMSType = car AND color = blue
...
</activation-config>
...
When the message-driven bean is deployed, the value for the resource-adapter-mid element
in the glassfish-ejb-jar.xml fle is set to the resource adapter module name that delivers
messages to the message endpoint (to the message-driven bean). In the following example, the
jmsra JMS resource adapter, which is the bundled resource adapter for the Message Queue
message provider, is specifed as the resource adapter module identifer for the SampleMDB bean.
<glassfish-ejb-jar>
<enterprise-beans>
<ejb>
<ejb-name>SampleMDB</ejb-name>
<jndi-name>SampleQueue</jndi-name>

...
<mdb-resource-adapter>
<resource-adapter-mid>jmsra</resource-adapter-mid>
Confguring a Message Driven Bean to Use a Resource Adapter

</mdb-resource-adapter>
...
</ejb>
...
</enterprise-beans>
...
When the message-driven bean is deployed, the GlassFish Server uses the
resourceadapter-mid setting to associate the resource adapter with a message endpoint
through the message infowcontract. This message infowcontract with the GlassFish Server
gives the resource adapter a handle to the MessageEndpointFactory and the ActivationSpec
JavaBean, and the adapter uses this handle to deliver messages to the message endpoint
instances (which are created by the MessageEndpointFactory).
When a message-driven bean frst created for use on the GlassFish Server 7 is deployed, the
Connector runtime transparently transforms the previous deployment style to the current
connector-based deployment style. If the deployer specifes neither a resource-adapter-mid
element nor the Message Queue resource adapters activation confguration properties, the
Connector runtime maps the message-driven bean to the jmsra systemresource adapter and
converts the JMS-specifc confguration to the Message Queue resource adapters activation
confguration properties.
Confguring a Message Driven Bean to Use a Resource Adapter
Developing Lifecycle Listeners
Lifecycle listener modules provide a means of running short or long duration Java-based tasks
within the Oracle GlassFish Server environment, such as instantiation of singletons or RMI
servers. These modules are automatically initiated at server startup and are notifed at various
phases of the server life cycle.
Note Lifecycle listener modules are deprecated. Support for themis included for backward
compatibility. Implementing the org.glassfsh.api.Startup interface instead is recommended.
All lifecycle module classes and interfaces are in the as-install/modules/glassfish-api.jar
fle.
For Javadoc tool pages relevant to lifecycle modules, go to http://glassfish.java.net/
nonav/docs/v3/api/ and click on the com.sun.appserv.server package.
Server Life Cycle Events on page 236
The LifecycleListener Interface on page 236
The LifecycleEvent Class on page 236
The Server Lifecycle Event Context on page 237
Deploying a Lifecycle Module on page 237
Considerations for Lifecycle Modules on page 238

12
C H A P T E R 1 2
235
Server Life Cycle Events
Alifecycle module listens for and performs its tasks in response to the following events in the
server life cycle:
After the INIT_EVENT, the server reads the confguration, initializes built-in subsystems
(such as security and logging services), and creates the containers.
After the STARTUP_EVENT, the server loads and initializes deployed applications.
After the READY_EVENT, the server is ready to service requests.
After the SHUTDOWN_EVENT, the server destroys loaded applications and stops.
After the TERMINATION_EVENT, the server closes the containers, the built-in subsystems, and
the server runtime environment.
These events are defned in the LifecycleEvent class.
The lifecycle modules that listen for these events implement the LifecycleListener interface.
The LifecycleListener Interface
To create a lifecycle module is to confgure a customized class that implements the
com.sun.appserv.server.LifecycleListener interface. You can create and simultaneously execute
multiple lifecycle modules.
The LifecycleListener interface defnes this method:
public void handleEvent(com.sun.appserv.server.LifecycleEvent event)
throws ServerLifecycleException
This method responds to a lifecycle event and throws a
com.sun.appserv.server.ServerLifecycleException if an error occurs.
Asample implementation of the LifecycleListener interface is the
LifecycleListenerImpl.java fle, which you can use for testing lifecycle events.
The LifecycleEvent Class
The com.sun.appserv.server.LifecycleEvent class defnes a server life cycle event. The
following methods are associated with the event:
public java.lang.Object.getData()
This method returns an instance of java.util.Properties that contains the properties
defned for the lifecycle module.
public int getEventType()

Server Life Cycle Events
This method returns the type of the last event, which is INIT_EVENT, STARTUP_EVENT,
READY_EVENT, SHUTDOWN_EVENT, or TERMINATION_EVENT.
public
com.sun.appserv.server.LifecycleEventContext.getLifecycleEventContext()
This method returns the lifecycle event context, described next.
ALifecycleEvent instance is passed to the LifecycleListener.handleEvent method.
The Server Lifecycle Event Context
The com.sun.appserv.server.LifecycleEventContext interface exposes runtime information
about the server. The lifecycle event context is created when the LifecycleEvent class is
instantiated at server initialization. The LifecycleEventContext interface defnes these methods:
public java.lang.String[].getCmdLineArgs()
This method returns the server startup command-line arguments.
public java.lang.String.getInstallRoot()
This method returns the server installation root directory.
public java.lang.String.getInstanceName()
This method returns the server instance name.
public javax.naming.InitialContext.getInitialContext()
This method returns the initial JNDI naming context. The naming environment for lifecycle
modules is installed after the STARTUP_EVENT. Alifecycle module can look up any resource
by its jndi-name attribute after the READY_EVENT.
If a lifecycle module needs to look up resources, it can do so after the READY_EVENT. It can use
the getInitialContext method to get the initial context to which all the resources are bound.
Deployinga Lifecycle Module
For instructions on howto deploy a lifecycle module, see the Oracle GlassFish Server 3.1
Application Deployment Guide, or see the asadmin create-lifecycle-module command in
the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
You do not need to specify a classpath for the lifecycle module if you place it in the
domain-dir/lib or domain-dir/lib/classes directory for the Domain Administration Server.
Do not place it in the lib directory for a particular instance, or it will be deleted when that
instance synchronizes with the Domain Administration Server.
Deploying a Lifecycle Module
Chapter 12 Developing Lifecycle Listeners 237
Considerations for Lifecycle Modules
The resources allocated at initialization or startup should be freed at shutdown or termination.
The lifecycle module classes are called synchronously fromthe main server thread, therefore it
is important to ensure that these classes dont block the server. Lifecycle modules can create
threads if appropriate, but these threads must be stopped in the shutdown and termination
phases.
The LifeCycleModule class loader is the parent class loader for lifecycle modules. Each lifecycle
modules classpath is used to construct its class loader. All the support classes needed by a
lifecycle module must be available to the LifeCycleModule class loader or its parent, the
Connector class loader.
You must ensure that the server.policy fle is appropriately set up, or a lifecycle module
trying to performa System.exec() might cause a security access violation. For details, see The
The confgured properties for a lifecycle module are passed as properties after the INIT_EVENT.
The JNDI naming context is not available before the STARTUP_EVENT. If a lifecycle module
requires the naming context, it can get this after the STARTUP_EVENT, READY_EVENT, or
SHUTDOWN_EVENT.
Considerations for Lifecycle Modules
Developing OSGi-enabled Java EE Applications
This chapter describes the features and interfaces that GlassFish Server provides to develop
OSGi-enabled enterprise applications. This chapter includes the following sections:
Overviewof OSGi Application and GlassFish Server on page 239
Developing OSGi Application Bundles for GlassFish Server on page 240
Deploying OSGi Bundles in GlassFish Server on page 247

Note Many of the features and interfaces presented in this chapter are demonstrated in samples
and video clips available fromthe OSGi section of the GlassFish Server wiki. See
http://wikis.sun.com/display/GlassFish/Osgi for more information.
Overviewof OSGi ApplicationandGlassFishServer
GlassFish Server is fully-compliant with Java EE 6, so it provides the latest Java EE APIs and
frameworks. It is built using OSGi technology, and includes as its OSGi module management
subsystemthe Apache Felix OSGi framework, which is a fully-compliant implementation of the
OSGi Service PlatformR4 Version 4.2 specifcation. GlassFish Server supports deployment of
OSGi-based applications using this framework. OSGi applications can make use of core as well
as enterprise OSGi features. GlassFish Server makes available many of its Java EE platform
services, such as the transaction service, HTTP service, JDBCService and JMS, as OSGi services.
It also enables use of Java EE programming model in OSGi applications, so enterprise Java
application developers can continue to leverage their existing skills in OSGi-based applications.
See Benefts of Using OSGi in Enterprise Java Applications on page 240 for more information.
OSGi applications are deployed as one or more OSGi bundles, and the GlassFish Server
deployment and administration infrastructure enables you to deploy and manage your OSGi
bundles. This chapter classifes OSGi bundles into two categories based on the features they use:
Plain OSGi Application Bundles bundles that do not contain any Java EE components.
See Developing Plain OSGi Bundles on page 241.
13
C H A P T E R 1 3
239
Hybrid Application Bundles bundles that are an OSGi bundle as wells as a Java EE
module. At runtime, such modules have both an OSGi bundle context and a Java EE context.
GlassFish Server supports the following hybrid application bundles:
Web Application Bundles (or WABs) , see Developing Web Application Bundles on
page 244.
EJB Application Bundles, see Developing EJB Application Bundles on page 246.
Benefts of UsingOSGi inEnterprise Java Applications
Enterprise applications typically need transactional, secured access to data stores, messaging
systems and other such enterprise information systems, and have to cater to a wide variety of
clients such as web browsers and desktop applications, and so on. Java EE makes development
of such applications easier with a rich set of APIs and frameworks. It also provides a scalable,
reliable and easy to administer runtime to host such applications.
The OSGi platformcomplements these features with modularity. It enables applications to be
separated into smaller, reusable modules with a well defned and robust dependency
specifcation. Amodule explicitly specifes its capabilities and requirements. This explicit
dependency specifcation encourages developers to visualize dependencies among their
modules and help themmake their modules highly cohesive and less coupled. The OSGi
module systemis dynamic: it allows modules to be added and removed at runtime. OSGi has
very good support for versioning: it supports package versioning as well module versioning. In
fact, it allows multiple versions of the same package to coexist in the same runtime, thus
allowing greater fexibility to deployers. The service layer of the OSGi platformencourages a
more service-oriented approach to build a system. The service-oriented approach and dynamic
module systemused together allowa systemto be more agile during development as well as in
production. It makes thembetter suited to run in an Platform-as-a-Service (PaaS) environment.
With GlassFish Server, you do not have to chose one of the two platforms. Ahybrid approach
like OSGi enabling your Java EE applications allows newcapabilities to applications hitherto
unavailable to applications built using just one of the two platforms.
DevelopingOSGi ApplicationBundles for GlassFishServer
GlassFish Server enables interaction between OSGi components and Java EE components.
OSGi services managed by the OSGi framework can invoke Java EE components managed by
the Java EE container and vice versa. For example, developers can declaratively export EJBs as
OSGi services without having to write any OSGi code. This allows any plain OSGi component,
which is running without the Java EE context, to discover the EJB and invoke it. Similarly, Java
EE components can locate OSGi services provided by plain OSGi bundles and use themas well.
GlassFish Server extends the Java EE Context and Dependency Injection (CDI) framework to
make it easier for Java EE components to consume dynamic OSGi services in a type-safe
manner.
Developing OSGi Application Bundles for GlassFish Server
Developing Plain OSGi Bundles on page 241
Developing Web Application Bundles on page 244
Developing EJB Application Bundles on page 246

DevelopingPlainOSGi Bundles
Java EE components (like an EJB or Servlet) can look up Java EE platformservices using JNDI
names in the associated Java EE naming context. Such code can rely on the Java EE container to
inject the required services as well. Unfortunately, neither of themworks when the code runs
outside a Java EE context. An example of such code is the BundleActivator of an OSGi bundle.
For such code to access Java EE platformservices, GlassFish Server makes key services and
resources of the underlying Java EE platformavailable as OSGi services. Thus, an OSGi bundle
deployed in GlassFish Server can access these services using OSGi Service look-up APIs or by
using a white board pattern. The following Java EE services are available as OSGi services:
HTTP Service on page 241
Transaction Service on page 242
JDBCData Source Service on page 243
JMS Resource Service on page 243

HTTPService
The GlassFish Server web container is made available as a service for OSGi users who do not use
OSGi Web Application Bundles (WABs). This service is made available using the standard
OSGi/HTTP service specifcation, which is a light API that predates the concept of a web
application as we knowit today. This simple API allows users to register servlets and static
resources dynamically and drawa boundary around themin the formof a HttpContext. This
simple API can be used to build featurerich web application, such as the Felix Web Console for
example.
The GlassFish Server web container has one or more virtual servers. Avirtual server has one or
more web application deployed in it. Each web application has a distinct context path. Each
virtual server has a set of HTTP listeners. Each HTTP listener listens on a particular port. When
multiple virtual servers are present, one of themis treated as the default virtual server. Every
virtual server comes confgured with a default web application. The default web application is
used to serve static content fromthe docroot of GlassFish Server. This default web application
uses / as the context path. Aweb application contains static and dynamic resources. Each
virtual server is mapped to an org.osgi.services.http.HttpService instance. When there
are multiple virtual servers present, there will be multiple occurrences of HttpService
registered in the service registry. In order to distinguish one service fromanother, each service
is registered with a service property named VirtualServer, whose value is the name of the
virtual server. The service corresponding to default virtual server has the highest ranking, so
when looking up a service of type HttpService without any additional criteria returns the
Chapter 13 Developing OSGi-enabled Java EE Applications 241
HttpService corresponding to the default virtual server. In a typical GlassFish Server
installation, the default virtual server is confgured to listen on port 8080 for the HTTP protocol
and port 8181 for the HTTPS protocol.
The context path / is reserved for the default web application. Every resource and servlet
registered using the registerResource() and registerServlet() methods of HttpService
are made available under a special context path named /osgi in the virtual server. The /osgi
context path can be changed to some other value by setting an appropriate value in the OSGi
confguration property or in a systemproperty called org.glassfish.osgihttp.ContextPath.
For example, HelloWorldServlet will be available at
http://localhost:8080/osgi/helloworld when the following code is executed:
HttpService httpService = getHttpService(); // Obtain HttpService
httpService.registerServlet(httpService.registerServlet("/helloworld",
new HelloWorldServlet(), null, ctx);
TransactionService
The Java Transaction API (JTA) defnes three interfaces to interact with the transaction
management system: UserTransaction, TransactionManager, and
TransactionSynchronizationRegistry. They all belong to the javax.transaction package.
TransactionManagerand TransactionSynchronizationRegistry are intended for system
level code, such as a persistence provider. Whereas, UserTransaction is the entity that you
should use to control transactions. All the objects of the underlying JTAlayer are made
available in the OSGi service registry using the following service interfaces:
javax.transaction.UserTransaction
javax.transaction.TransactionManager
javax.transaction.TransactionSynchronisationRegistry
There is no additional service property associated with them. Although UserTransaction
appears to be a singleton, in reality any call to it gets rerouted to the actual transaction
associated with the calling thread. Code that runs in the context of a Java EE component
typically gets a handle on UserTransaction by doing a JNDI lookup in the component naming
context or by using injection, as shown here:
(UserTransaction)(new InitialContext().lookup("java:comp/UserTransaction"));
or
@Resource UserTransaction utx;
When certain code (such as an OSGi Bundle Activator), which does not have a Java EE
component context, wants to get hold of UserTransaction, or any of the other JTAartifacts,
then they can look it up in the service registry. Here is an example of such code:
BundleContext context;
ServiceReference txRef =
context.getServiceReference(UserTransaction.class.getName());
UserTransaction utx = (UserTransaction);
context.getService(txRef);
JDBCData Source Service
Any JDBCdata source created in GlassFish Server is automatically made available as an OSGi
Service; therefore, OSGi bundles can track availability of JDBCdata sources using the
ServiceTracking facility of the OSGi platform. The life of the OSGi service matches that of the
underlying data source created in GlassFish Server. For instructions on administering JDBC
resources in GlassFish Server, see the Oracle GlassFish Server 3.1 Administration Guide.
GlassFish Server registers each JDBCdata source as an OSGi service with objectClass =
javax.sql.DataSource and a service property called jndi-name, which is set to the JNDI
name of the data source. Here is a code sample that looks up a data source service:
@Inject
@OSGiService(true,
"(jndi-name=jdbc/MyDS)")
private DataSource ds;
JMS Resource Service
Like JDBCdata sources, JMS administered objects, such as destinations and connection
factories, are also automatically made available as OSGi services. Their service mappings are as
follows.
JMS Object Service Interface Service Properties Comments
JMS Queue destination javax.jms.Queue jndi-name jndi-name is set to the
JNDI name of the queue
JMS Topic destination javax.jms.Topic jndi-name jndi-name is set to the
JNDI name of the topic
JMS connection factory javax.jms.QueueConnectionFactory
or
javax.jms.TopicConnectionFactory
or
javax.jms.ConnectionFactory
jndi-name jndi-name is set to the
JNDI name of the topic.
The actual service
interface depends on
which type of connection
factory was created.
DevelopingWebApplicationBundles
When a web application is packaged and deployed as an OSGi bundle, it is called a Web
Application Bundle (WAB). WAB support is based on the OSGi Web Application specifcation ,
which is part of the OSGi Service Platform, Enterprise Specifcation, Release 4, Version 4.2. A
WAB is packaged as an OSGi bundle, so all the OSGi packaging rules apply to WAB packaging.
When a WAB is not packaged like a WAR, the OSGi Web Container of GlassFish Server maps
the WAB to the hierarchical structure of web application using the following rules:
The root of the WAB corresponds to the docroot of the web application.
Every JARin the Bundle-ClassPath of the WAB is treated like a JARin WEB-INF/lib/.
Every directory except . in the Bundle-ClassPath of the WAB is treated like

WEB-INF/classes/.
Bundle-ClassPath entry of type . is treated as if the entire WAB is a JARin WEB-INF/lib/.
Bundle-ClassPath includes the Bundle-ClassPath entries of any attached fragment bundles.

The simplest way to avoid knowing these mapping rules is to avoid the problemin the frst
place. Moreover, there are many packaging tools and development time tools that understand
WARstructure. Therefore, we strongly recommend that you package the WAB exactly like a
WAR, with only additional OSGi metadata.
RequiredWABMetadata
In addition to the standard OSGi metadata, the main attributes of META-INF/MANIFEST.MF of
the WAB must have an additional attribute called Web-ContextPath. The Web-ContextPath
attribute specifes the value of the context path of the web application. Since the root of a WAB
is mapped to the docroot of the web application, it should not be used in the
Bundle-ClassPath. Moreover, WEB-INF/classes/ should be specifed ahead of WEB-INF/lib/
in the Bundle-ClassPath in order to be compliant with the search order used for traditional
WARfles.
Assuming the WAB is structured as follows:
foo.war/
index.html
foo.jsp
WEB-INF/classes/
foo/BarServlet.class
WEB-INF/lib/lib1.jar
WEB-INF/lib/lib2.jar
Then the OSGi metadata for the WAB as specifed in META-INF/MANIFEST.MF of the WAB
would appear as follows:
MANIFEST.MF:Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName: com.acme.foo
Bundle-Version: 1.0
Bundle-Name: Foo Web Application Bundle Version 1.0
Import-Package: javax.servlet; javax.servlet.http, version=[3.0, 4.0)
Bundle-ClassPath: WEB-INF/classes, WEB-INF/lib/lib1.jar, WEB-INF/lib/lib2.jar
Web-ContextPath: /foo
HowWABs Consume OSGi Services
Since a WAB has a valid Bundle-Context, it can consume OSGi services. Although you are free
to use any OSGi API to locate OSGi services, GlassFish Server makes it easy for WAB users to
use OSGi services by virtue of extending the Context and Dependency Injection (CDI)
framework. Here's an example of the injection of an OSGi Service into a Servlet:
@WebServlet
public class MyServlet extends HttpServlet {
@Inject @OSGiService(dynamic=true)
FooService fooService;
}
To learn more about this feature, refer to OSGi CDI Extension for WABs on page 245.
OSGi CDI Extensionfor WABs
GlassFish Server includes a CDI extension that enables web applications, such as servlets, that
are part of WABs to express a type-safe dependency on an OSGi service using CDI APIs. An
OSGi service can be provided by any OSGi bundle without any knowledge of Java EE/CDI, and
they are allowed to be injected transparently in a type-safe manner into a web application.
AcustomCDI Qualifer, @org.glassfish.osgicdi.OSGiService, is used by the component to
represent dependency on an OSGi service. The qualifer has additional metadata to customize
the service discovery and injection behavior. The following @OsgiService attributes are
currently available:
serviceCriteria An LDAP flter query used for service selection in the OSGi service
registry.
waitTimeout Waits the specifed duration for a service that matches the criteria specifed
to appear in the OSGi service registry.
dynamic Dynamically obtain a service reference (true/false).

Since OSGi services are dynamic, they may not match the life cycle of the application
component that has injected a reference to the service. Through this attribute, you could
indicate that a service reference can be obtained dynamically or not. For stateless or
idempotent services, a dynamic reference to a service implementation would be useful. The
container then injects a proxy to the service and dynamically switches to an available
implementation when the current service reference is invalid.
EXAMPLE 131 Example of a WABUsing CDI
In this example, Bundle B0 defnes a service contract called com.acme.Foo and exports the
com.acme package for use by other bundles. Bundle B1 in turn provides a service
implementation, FooImpl, of the com.acme.Foo interface. It then registers the service FooImpl
service with the OSGi service registry with com.acme.Foo as the service interface.
Bundle B2 is a hybrid application bundle that imports the com.acme package. It has a
component called BarServlet that expresses a dependency to com.acme.Foo by adding a
feld/setter method and qualifes that injection point with @OsgiService. For instance,
BarServlet could look like:
@Servlet
public void BarServlet extends HttpServlet{
private com.acme.Foo f;
}
DevelopingEJBApplicationBundles
Another type of hybrid application bundle is the EJB Application Bundle. When an EJB Jar is
packaged with additional OSGi metadata and deployed as an OSGi bundle it is called an EJB
Application Bundle. GlassFish Serversupports only packaging the OSGi bundle as a simple JAR
fle with required OSGi metadata, just as you would package an ejb-jar fle.
RequiredEJBMetadata
An EJB Application Bundle must have a manifest metadata called Export-EJB in order to be
considered as an EJB Bundle. For syntax of Export-EJB header, please refer to the Publishing
EJB as OSGi Service section. Here's an example of an EJB Application Bundle with its metadata:
myEjb.jar/
com/acme/Foo
com/acme/impl/FooEJB
META-INF/MANIFEST.MF
MANIFEST.MF:
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName: com.acme.foo EJB bundle
Bundle-Version: 1.0.0.BETA
Bundle-Name: com.acme.foo EJB bundle version 1.0.0.BETA
Export-EJB: ALL
Export-Package: com.acme; version=1.0
Import-Package: javax.ejb; version=[3.0, 4.0), com.acme; version=[1.0, 1.1)
HowEJBBundles Consume OSGi Services
Since an EJB has a valid Bundle-Context, it can consume OSGi services. Although you are free
to use any OSGi API to locate OSGi services, GlassFish Server makes it easy to use OSGi services
by virtue of extending the Context and Dependency Injection (CDI) framework. Here's an
example of injection of an OSGi Service into a servlet:
@Stateless
public class MyEJB {
Foo foo;
...
}
To learn more about this feature, refer to Using the OSGi CDI Extension With EJB Bundles
on page 247.
Usingthe OSGi CDI ExtensionWithEJBBundles
GlassFish Server includes a CDI extension that enables EJB application bundles to express a
type-safe dependency on an OSGi Service using CDI APIs. An OSGi service can be provided by
any OSGi bundle without any knowledge of Java EE/CDI, and they are allowed to be injected
transparently in a type-safe manner into an EJB bundle.
AcustomCDI Qualifer, @org.glassfish.osgicdi.OSGiService, is used by the component to
represent dependency on an OSGi service. The qualifer has additional metadata to customize
the service discovery and injection behavior. The following @OsgiService attributes are
currently available:
dynamic Dynamically obtain a service reference (true/false).
waitTimeout Waits for specifed duration for a service to appear in the OSGi service
registry.
serviceCriteria An LDAP flter query used for service selection.

DeployingOSGi Bundles inGlassFishServer
For instruction on deploying OSGi bundle, see OSGi Bundle Deployment Guidelines in
Deploying OSGi Bundles in GlassFish Server
248
Using Services and APIs
P A R T I I I
249
250
Using the JDBC API for Database Access
This chapter describes howto use the Java Database Connectivity (JDBC) API for database
access with the Oracle GlassFish Server. This chapter also provides high level JDBC
implementation instructions for servlets and EJB components using the GlassFish Server. If the
JDKversion 1.6 is used, the GlassFish Server supports the JDBC4.0 API.
The JDBCspecifcations are available at http://www.oracle.com/technetwork/java/
javase/jdbc/index.html.
Auseful JDBCtutorial is located at http://download.oracle.com/javase/tutorial/jdbc/
index.html.
Note The GlassFish Server does not support connection pooling or transactions for an
applications database access if it does not use standard Java EE DataSource objects.
Statements on page 252
Connections on page 255
Connection Wrapping on page 260
Allowing Non-Component Callers on page 262
Using Application-Scoped Resources on page 262
Restrictions and Optimizations on page 263

14
C H A P T E R 1 4
251
Statements
Using an Initialization Statement on page 252
Setting a Statement Timeout on page 252
Statement Leak Detection and Leaked Statement Reclamation on page 253
Statement Caching on page 253
Statement Tracing on page 254

UsinganInitializationStatement
You can specify a statement that executes each time a physical connection to the database is
created (not reused) froma JDBCconnection pool. This is useful for setting request or session
specifc properties and is suited for homogeneous requests in a single application. Set the Init
SQL attribute of the JDBCconnection pool to the SQL string to be executed in one of the
following ways:
Enter an Init SQL value in the Edit Connection Pool Advanced Attributes page in the
Administration Console. For more information, click the Help button in the
Specify the --initsql option in the asadmin create-jdbc-connection-pool command.

For more information, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.
Specify the init-sql option in the asadmin set command. For example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.init-sql="sql-string"
Settinga Statement Timeout
An abnormally long running JDBCquery executed by an application may leave it in a hanging
state unless a timeout is explicitly set on the statement. Setting a statement timeout guarantees
that all queries automatically time out if not completed within the specifed period. When
statements are created, the queryTimeout is set according to the statement timeout setting. This
works only when the underlying JDBCdriver supports queryTimeout for Statement,
PreparedStatement, CallableStatement, and ResultSet.
You can specify a statement timeout in the following ways:
Enter a Statement Timeout value in the Edit Connection Pool Advanced Attributes page in
the Administration Console. For more information, click the Help button in the
Statements
Specify the --statementtimeout option in the asadmin create-jdbc-connection-pool

Manual.
Statement LeakDetectionandLeakedStatement
Reclamation
If statements are not closed by an application after use, it is possible for the application to run
out of cursors. Enabling statement leak detection causes statements to be considered as leaked if
they are not closed within a specifed period. Additionally, leaked statements can reclaimed
automatically.
To enable statement leak detection, set Statement Leak Timeout In Seconds for the JDBC
connection pool to a positive, nonzero value in one of the following ways:
Specify the --statementleaktimeout option in the create-jdbc-connection-pool

subcommand. For more information, see create-jdbc-connection-pool(1).
Specify the statement-leak-timeout-in-seconds option in the set subcommand. For

example:
asadmin set resources.jdbc-connection-pool.pool-name.statement-leak-timeout-in-seconds=300
When selecting a value for Statement Leak Timeout In Seconds, make sure that:
It is less than the Connection Leak Timeout; otherwise, the connection could be closed
before the statement leak is recognized.
It is greater than the Statement Timeout; otherwise, a long running query could be mistaken
as a statement leak.
After enabling statement leak detection, enable leaked statement reclamation by setting
ReclaimLeaked Statements for the JDBCconnection pool to a true value in one of the
following ways:
Specify the --statementleakreclaim=true option in the create-jdbc-connection-pool

Specify the statement-leak-reclaim option in the set subcommand. For example:

asadmin set resources.jdbc-connection-pool.pool-name.statement-leak-reclaim=true
Statement Caching
Statement caching stores statements, prepared statements, and callable statements that are
executed repeatedly by applications in a cache, thereby improving performance. Instead of the
statement being prepared each time, the cache is searched for a match. The overhead of parsing
and creating newstatements each time is eliminated.
Statements
Chapter 14 Using the JDBC API for Database Access 253
Statement caching is usually a feature of the JDBCdriver. The GlassFish Server provides
caching for drivers that do not support caching. To enable this feature, set the Statement Cache
Size for the JDBCconnection pool in one of the following ways:
Enter a Statement Cache Size value in the Edit Connection Pool Advanced Attributes page
in the Administration Console. For more information, click the Help button in the
Specify the --statementcachesize option in the asadmin create-jdbc-connection-pool

Manual.
Specify the statement-cache-size option in the asadmin set command. For example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.statement-cache-size=10
By default, this attribute is set to zero and the statement caching is turned of. To enable
statement caching, you can set any positive nonzero value. The built-in cache eviction strategy
is LRU-based (Least Recently Used). When a connection pool is fushed, the connections in the
statement cache are recreated.
Statement Tracing
You can trace the SQL statements executed by applications that use a JDBCconnection pool.
Set the SQL Trace Listeners attribute to a comma-separated list of trace listener implementation
classes in one of the following ways:
Enter an SQL Trace Listeners value in the Edit Connection Pool Advanced Attributes page
in the Administration Console. For more information, click the Help button in the
Specify the --sqltracelisteners option in the asadmin create-jdbc-connection-pool

Manual.
Specify the sql-trace-listeners option in the asadmin set command. For example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.sql-trace-listeners=listeners
The GlassFish Server provides a public interface, org.glassfsh.api.jdbc.SQLTraceListener, that
implements a means of recording SQLTraceRecord objects. To make customimplementations
of this interface available to the GlassFish Server, place the implementation classes in
as-install/lib.
The GlassFish Server provides an SQL tracing logger to log the SQL operations in the formof
SQLTraceRecord objects in the server.log fle. The module name under which the SQL
Statements
operation is logged is javax.enterprise.resource.sqltrace. SQL traces are logged as FINE
messages along with the module name to enable easy fltering of the SQL logs. Asample SQL
trace record looks like this:
[#|2009-11-27T15:46:52.202+0530|FINE|glassfishv3.0|javax.enterprise.resource.sqltrace.com.sun.gjc.util
|_ThreadID=29;_ThreadName=Thread-1;ClassName=com.sun.gjc.util.SQLTraceLogger;MethodName=sqlTrace;
|ThreadID=77 | ThreadName=p: thread-pool-1; w: 6 | TimeStamp=1259317012202
| ClassName=com.sun.gjc.spi.jdbc40.PreparedStatementWrapper40 | MethodName=executeUpdate
| arg[0]=insert into table1(colName) values(100) | arg[1]=columnNames | |#]
This trace shows that an executeUpdate(String sql, String columnNames) operation is
being done.
When SQL statement tracing is enabled and JDBCconnection pool monitoring is enabled,
GlassFish Server maintains a tracing cache of recent queries and their frequency of use. The
following JDBCconnection pool properties can be confgured to control this cache and the
monitoring statistics available fromit:
time-to-keep-queries-in-minutes
Specifes howlong in minutes to keep a query in the tracing cache, tracking its frequency of
use. The default value is 5 minutes.
number-of-top-queries-to-report
Specifes howmany of the most used queries, in frequency order, are listed the monitoring
report. The default value is 10 queries.
Set these parameters in one of the following ways:
Add themas properties in the Edit JDBCConnection Pool Properties page in the
Specify themusing the --property option in the create-jdbc-connection-pool

Set themusing the set subcommand. For example:

asadmin set resources.jdbc-connection-pool.pool-name.property.time-to-keep-queries-in-minutes=10
Connections
Transparent Pool Reconfguration on page 256
Disabling Pooling on page 256
Associating Connections with Threads on page 257
CustomConnection Validation on page 258
Sharing Connections on page 258
Marking Bad Connections on page 259

Connections
Handling Invalid Connections on page 259

Transparent Pool Reconfguration
When the properties or attributes of a JDBCconnection pool are changed, the connection pool
is destroyed and re-created. Normally, applications using the connection pool must be
redeployed as a consequence. This restriction can be avoided by enabling transparent JDBC
connection pool reconfguration. When this feature is enabled, applications do not need to be
redeployed. Instead, requests for a newconnections are blocked until the reconfguration
operation completes. Connection requests fromany in-fight transactions are served using the
old pool confguration so as to complete the transaction. Then, connections are created using
the pool's newconfguration, and any blocked connection requests are served with connections
fromthe re-created pool..
To enable transparent JDBCconnection pool reconfguration, set the
dynamic-reconfiguration-wait-timeout-in-seconds property of the JDBCconnection
pool to a positive, nonzero value in one of the following ways:
Add it as a property in the Edit JDBCConnection Pool Properties page in the

Specify it using the --property option in the create-jdbc-connection-pool

Set it using the set subcommand. For example:

asadmin set resources.jdbc-connection-pool.pool-name.property.dynamic-reconfiguration-wait-timeout-in-seconds=15
This property specifes the time in seconds to wait for in-use connections to close and in-fight
transactions to complete. Any connections in use or transaction in fight past this time must be
retried.
DisablingPooling
To disable connection pooling, set the Pooling attribute to false. The default is true. You can
enable or disable connection pooling in one of the following ways:
Enter a Pooling value in the Edit Connection Pool Advanced Attributes page in the
Specify the --pooling option in the asadmin create-jdbc-connection-pool command.

Specify the pooling option in the asadmin set command. For example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.pooling=false
Connections
The pooling option and the systemproperty com.sun.enterprise.connectors.
SwitchoffACCConnectionPooling, which turns of connection pooling in the Application
Client Container, do not afect each other.
An exception is thrown if associate-with-thread is set to true and pooling is disabled. An
exception is thrown if you attempt to fush a connection pool when pooling is disabled. A
warning is logged if the following attributes are used, because they are useful only in a pooled
environment:
connection-validation
validate-atmost-once-period
match-connections
max-connection-usage
idle-timeout
AssociatingConnections withThreads
To associate connections with a thread, set the Associate With Thread attribute to true. The
default is false. Atrue setting allows connections to be saved as ThreadLocal in the calling
thread. Connections get reclaimed only when the calling thread dies or when the calling thread
is not in use and the pool has run out of connections. If the setting is false, the thread must
obtain a connection fromthe pool each time the thread requires a connection.
The Associate With Thread attribute associates connections with a thread such that when the
same thread is in need of connections, it can reuse the connections already associated with that
thread. In this case, the overhead of getting connections fromthe pool is avoided. However,
when this value is set to true, you should verify that the value of the Max Pool Size attribute is
comparable to the Max Thread Pool Size attribute of the thread pool. If the Max Thread Pool
Size value is much higher than the Max Pool Size value, a lot of time is spent associating
connections with a newthread after dissociating themfroman older one. Use this attribute in
cases where the thread pool should reuse connections to avoid this overhead.
You can set the Associate With Thread attribute in the following ways:
Enter an Associate With Thread value in the Edit Connection Pool Advanced Attributes
page in the Administration Console. For more information, click the Help button in the
Specify the --associatewiththread option in the asadmin

create-jdbc-connection-pool command. For more information, see the Oracle GlassFish
Specify the associate-with-thread option in the asadmin set command. For example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.associate-with-thread=true
Connections
CustomConnectionValidation
You can specify a customimplementation for Connection Validation that is faster or optimized
for a specifc database. Set the Validation Method attribute to the value custom-validation.
(Other validation methods available are table (the default), auto-commit, and meta-data.)
The GlassFish Server provides a public interface, org.glassfsh.api.jdbc.ConnectionValidation,
which you can implement to plug in your implementation. Anewattribute, Validation
Classname, specifes the fully qualifed name of the class that implements the
ConnectionValidation interface. The Validation Classname attribute is required if Connection
Validation is enabled and Validation Method is set to CustomValidation.
To enable this feature, set Connection Validation, Validation Method, and Validation
Classname for the JDBCconnection pool in one of the following ways:
Enter Connection Validation, Validation Method, and Validation Classname values in the
Edit Connection Pool Advanced Attributes page in the Administration Console. You can
select fromamong validation class names for common databases in the Validation
Classname feld. For more information, click the Help button in the Administration
Console.
Specify the --isconnectionvalidatereq, --validationmethod, and

--validationclassname options in the asadmin create-jdbc-connection-pool
Manual.
Specify the is-connection-validation-required, connection-validation-method, and

validation-classname options in the asadmin set command. For example:
asadmin set domain1.resources.jdbc-connection-pool.MyPool.is-connection-validation-required=true
asadmin set domain1.resources.jdbc-connection-pool.MyPool.connection-validation-method=custom-validation
asadmin set domain1.resources.jdbc-connection-pool.MyPool.validation-classname=impl-class
By default, optimized validation mechanisms are provided for DB2, Java DB, MSSQL, MySQL,
Oracle, PostgreSQL and Sybase databases. Additionally, for JDBC4.0 compliant database
drivers, a validation mechanismis provided that uses the Connection.isValid(0)
implementation.
SharingConnections
When multiple connections acquired by an application use the same JDBCresource, the
connection pool provides connection sharing within the same transaction scope. For example,
suppose Bean Astarts a transaction and obtains a connection, then calls a method in Bean B. If
Connections
Bean B acquires a connection to the same JDBCresource with the same sign-on information,
and if Bean Acompletes the transaction, the connection can be shared.
Connections obtained through a resource are shared only if the resource reference declared by
the Java EE component allows it to be shareable. This is specifed in a components deployment
descriptor by setting the res-sharing-scope element to Shareable for the particular resource
reference. To turn of connection sharing, set res-sharing-scope to Unshareable.
For general information about connections and JDBCURLs, see Chapter 12, Administering
Database Connectivity, in Oracle GlassFish Server 3.1 Administration Guide.
MarkingBadConnections
The DataSource implementation in the GlassFish Server provides a markConnectionAsBad
method. Amarked bad connection is removed fromits connection pool when it is closed. The
method signature is as follows:
public void markConnectionAsBad(java.sql.Connection con)
For example:
com.sun.appserv.jdbc.DataSource ds=
(com.sun.appserv.jdbc.DataSource)context.lookup("dataSource");
Connection con = ds.getConnection();
Statement stmt = null;
try{
stmt = con.createStatement();
stmt.executeUpdate("Update");
}
catch (BadConnectionException e){
ds.markConnectionAsBad(con) //marking it as bad for removal
}
finally{
stmt.close();
con.close(); //Connection will be destroyed during close.
}
HandlingInvalidConnections
If a ConnectionErrorOccured event occurs, the GlassFish Server considers the connection
invalid and removes the connection fromthe connection pool. Typically, a JDBCdriver
generates a ConnectionErrorOccured event when it fnds a ManagedConnection object
unusable. Reasons can be database failure, network failure with the database, fatal problems
with the connection pool, and so on.
If the fail-all-connections setting in the connection pool confguration is set to true, and a
single connection fails, all connections are closed and recreated. If this setting is false,
individual connections are recreated only when they are used. The default is false.
Connections
The is-connection-validation-required setting specifes whether connections have to be
validated before being given to the application. If a resources validation fails, it is destroyed,
and a newresource is created and returned. The default is false.
The prefer-validate-over-recreate property specifes that validating idle connections is
preferable to closing them. This property has no efect on non-idle connections. If set to true,
idle connections are validated during pool resizing, and only those found to be invalid are
destroyed and recreated. If false, all idle connections are destroyed and recreated during pool
resizing. The default is false.
You can set the fail-all-connections, is-connection-validation-required, and
prefer-validate-over-recreate confguration settings during creation of a JDBC
connection pool. Or, you can use the asadmin set command to dynamically reconfgure a
setting. For example:
asadmin set server.resources.jdbc-connection-pool.JCPool1.fail-all-connections="true"
asadmin set server.resources.jdbc-connection-pool.JCPool1.is-connection-validation-required="true"
asadmin set server.resources.jdbc-connection-pool.JCPool1.property.prefer-validate-over-recreate="true"
The interface ValidatingManagedConnectionFactory exposes the method
getInvalidConnections to allowretrieval of the invalid connections. The GlassFish Server
checks if the JDBCdriver implements this interface, and if it does, invalid connections are
removed when the connection pool is resized.
ConnectionWrapping
Wrapping Connections on page 260
Obtaining a Physical Connection Froma Wrapped Connection on page 261
Using the Connection.unwrap() Method on page 261

WrappingConnections
If the Wrap JDBCObjects option is true (the default), wrapped JDBCobjects are returned for
Statement, PreparedStatement, CallableStatement, ResultSet, and DatabaseMetaData.
This option ensures that Statement.getConnection() is the same as
DataSource.getConnection(). Therefore, this option should be true when both
Statement.getConnection() and DataSource.getConnection() are done.
You can specify the Wrap JDBCObjects option in the following ways:
ConnectionWrapping
Check or uncheck the Wrap JDBCObjects box on the Edit Connection Pool Advanced
Attributes page in the Administration Console. For more information, click the Help button
in the Administration Console.
Specify the --wrapjdbcobjects option in the asadmin create-jdbc-connection-pool

Manual.
Obtaininga Physical ConnectionFromaWrapped
Connection
The DataSource implementation in the GlassFish Server provides a getConnection method
that retrieves the JDBCdrivers SQLConnection fromthe GlassFish Servers Connection
wrapper. The method signature is as follows:
public java.sql.Connection getConnection(java.sql.Connection con)
throws java.sql.SQLException
For example:
com.sun.appserv.jdbc.DataSource ds = (com.sun.appserv.jdbc.DataSource)
ctx.lookup("jdbc/MyBase");
Connection drivercon = ds.getConnection(con); //get physical connection from wrapper
// Do db operations.
// Do not close driver connection.
con.close(); // return wrapped connection to pool.
Usingthe Connection.unwrap() Method
If the JDKversion 1.6 is used, the GlassFish Server supports JDBC4.0 if the JDBCdriver is
JDBC4.0 compliant. Using the Connection.unwrap() method on a vendor-provided interface
returns an object or a wrapper object implementing the vendor-provided interface, which the
application can make use of to do vendor-specifc database operations. Use the
Connection.isWrapperFor() method on a vendor-provided interface to check whether the
connection can provide an implementation of the vendor-provided interface. Check the JDBC
driver vendor's documentation for information on these interfaces.
ConnectionWrapping
AllowingNon-Component Callers
You can allownon-Java-EE components, such as servlet flters, lifecycle modules, and third
party persistence managers, to use this JDBCconnection pool. The returned connection is
automatically enlisted with the transaction context obtained fromthe transaction manager.
Standard Java EE components can also use such pools. Connections obtained by
non-component callers are not automatically closed at the end of a transaction by the container.
They must be explicitly closed by the caller.
You can enable non-component callers in the following ways:
Check the AllowNon Component Callers box on the Edit Connection Pool Advanced
Attributes page in the Administration Console. The default is false. For more information,
Specify the --allownoncomponentcallers option in the asadmin

Specify the allow-non-component-callers option in the asadmin set command. For

example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.allow-non-component-callers=true
Create a JDBCresource with a __pm sufx.

Accessing a DataSource using the Synchronization.beforeCompletion() method requires
setting AllowNon Component Callers to true. For more information about the Transaction
Synchronization Registry, see The Transaction Manager, the Transaction Synchronization
Registry, and UserTransaction on page 271.
UsingApplication-ScopedResources
You can defne an application-scoped database or other resource for an enterprise application,
Allowing Non-Component Callers
Restrictions andOptimizations
This section discusses restrictions and performance optimizations that afect using the JDBC
API.
DisablingStoredProcedure CreationonSybase
By default, DataDirect and Oracle JDBCdrivers for Sybase databases create a stored procedure
for each parameterized PreparedStatement. On the GlassFish Server, exceptions are thrown
when primary key identity generation is attempted. To disable the creation of these stored
procedures, set the property PrepareMethod=direct for the JDBCconnection pool.
264
Using theTransaction Service
The Java EE platformprovides several abstractions that simplify development of dependable
transaction processing for applications. This chapter discusses Java EE transactions and
transaction support in the Oracle GlassFish Server.
Handling Transactions with Databases on page 265
Handling Transactions with Enterprise Beans on page 268
Handling Transactions with the Java Message Service on page 270
The Transaction Manager, the Transaction Synchronization Registry, and

UserTransaction on page 271
For more information about the Java Transaction API (JTA) and Java Transaction Service
(JTS), see Chapter 19, Administering Transactions, in Oracle GlassFish Server 3.1
Administration Guide and the following sites: http://www.oracle.com/technetwork/java/
javaee/jta/index.html and http://www.oracle.com/technetwork/java/javaee/tech/
index.html.
You might also want to read Chapter 44, Transactions, in The Java EE 6 Tutorial.
HandlingTransactions withDatabases
Using JDBCTransaction Isolation Levels on page 266
Using Non-Transactional Connections on page 267

15
C H A P T E R 1 5
265
UsingJDBCTransactionIsolationLevels
Not all database vendors support all transaction isolation levels available in the JDBCAPI. The
GlassFish Server permits specifying any isolation level your database supports. The following
table defnes transaction isolation levels.
TABLE 151 TransactionIsolationLevels
TransactionIsolationLevel getTransactionIsolation ReturnValue Description
read-uncommitted 1 Dirty reads, non-repeatable reads, and phantomreads can
occur.
read-committed 2 Dirty reads are prevented; non-repeatable reads and
phantomreads can occur.
repeatable-read 4 Dirty reads and non-repeatable reads are prevented;
phantomreads can occur.
serializable 8 Dirty reads, non-repeatable reads and phantomreads are
prevented.
By default, the transaction isolation level is undefned (empty), and the JDBCdriver's default
isolation level is used. You can specify the transaction isolation level in the following ways:
Select the value fromthe Transaction Isolation drop-down list on the NewJDBC
Connection Pool or Edit Connection Pool page in the Administration Console. For more
information, click the Help button in the Administration Console.
Specify the --isolationlevel option in the asadmin create-jdbc-connection-pool

Manual.
Specify the transaction-isolation-level option in the asadmin set command. For

example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.transaction-isolation-level=serializable
Note that you cannot call setTransactionIsolation during a transaction.
You can set the default transaction isolation level for a JDBCconnection pool. For details, see
To Create a JDBCConnection Pool in Oracle GlassFish Server 3.1 Administration Guide.
To verify that a level is supported by your database management system, test your database
programmatically using the supportsTransactionIsolationLevel method in
java.sql.DatabaseMetaData, as shown in the following example:
HandlingTransactions with Databases
DataSource ds = (DataSource)
ctx.lookup("jdbc/MyBase");
DatabaseMetaData dbmd = con.getMetaData();
if (dbmd.supportsTransactionIsolationLevel(TRANSACTION_SERIALIZABLE)
{ Connection.setTransactionIsolation(TRANSACTION_SERIALIZABLE); }
For more information about these isolation levels and what they mean, see the JDBCAPI
specifcation.
Setting or resetting the transaction isolation level for every getConnection call can degrade
performance. So by default the isolation level is not guaranteed.
Applications that change the transaction isolation level on a pooled connection
programmatically risk polluting the JDBCconnection pool, which can lead to errors. If an
application changes the isolation level, enabling the is-isolation-level-guaranteed setting
in the pool can minimize such errors.
You can guarantee the transaction isolation level in the following ways:
Check the Isolation Level Guaranteed box on the NewJDBCConnection Pool or Edit
Connection Pool page in the Administration Console. For more information, click the Help
Specify the --isisolationguaranteed option in the asadmin

Specify the is-isolation-level-guaranteed option in the asadmin set command. For

example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.is-isolation-level-guaranteed=true
UsingNon-Transactional Connections
You can specify a non-transactional database connection in any of these ways:
Check the Non-Transactional Connections box on the NewJDBCConnection Pool or Edit

Connection Pool page in the Administration Console. The default is unchecked. For more
information, click the Help button in the Administration Console.
Specify the ----nontransactionalconnections option in the asadmin

Specify the non-transactional-connections option in the asadmin set command. For

example:
asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.non-transactional-connections=true
HandlingTransactions with Databases
Chapter 15 Using theTransaction Service 267
Use the DataSource implementation in the GlassFish Server, which provides a

getNonTxConnection method. This method retrieves a JDBCconnection that is not in the
scope of any transaction. There are two variants.
public java.sql.Connection getNonTxConnection() throws java.sql.SQLException
public java.sql.Connection getNonTxConnection(String user, String password)
throws java.sql.SQLException
Create a resource with the JNDI name ending in __nontx. This forces all connections looked
up using this resource to be non transactional.
Typically, a connection is enlisted in the context of the transaction in which a getConnection
call is invoked. However, a non-transactional connection is not enlisted in a transaction context
even if a transaction is in progress.
The main advantage of using non-transactional connections is that the overhead incurred in
enlisting and delisting connections in transaction contexts is avoided. However, use such
connections carefully. For example, if a non-transactional connection is used to query the
database while a transaction is in progress that modifes the database, the query retrieves the
unmodifed data in the database. This is because the in-progress transaction hasnt committed.
For another example, if a non-transactional connection modifes the database and a transaction
that is running simultaneously rolls back, the changes made by the non-transactional
connection are not rolled back.
Here is a typical use case for a non-transactional connection: a component that is updating a
database in a transaction context spanning over several iterations of a loop can refresh cached
data by using a non-transactional connection to read data before the transaction commits.
HandlingTransactions withEnterprise Beans
This section describes the transaction support built into the Enterprise JavaBeans programming
model for the GlassFish Server.
As a developer, you can write an application that updates data in multiple databases distributed
across multiple sites. The site might use EJB servers fromdiferent vendors.
Flat Transactions on page 269
Global and Local Transactions on page 269
Commit Options on page 269
Bean-Level Container-Managed Transaction Timeouts on page 270

HandlingTransactions with Enterprise Beans
Flat Transactions
The Enterprise JavaBeans Specifcation, v3.0 requires support for fat (as opposed to nested)
transactions. In a fat transaction, each transaction is decoupled fromand independent of other
transactions in the system. Another transaction cannot start in the same thread until the
current transaction ends.
Flat transactions are the most prevalent model and are supported by most commercial database
systems. Although nested transactions ofer a fner granularity of control over transactions, they
are supported by far fewer commercial database systems.
Global andLocal Transactions
Both local and global transactions are demarcated using the javax.transaction.UserTransaction
interface, which the client must use. Local transactions bypass the XAcommit protocol and are
faster. For more information, see The Transaction Manager, the Transaction Synchronization
Registry, and UserTransaction on page 271.
Commit Options
The EJB protocol is designed to give the container the fexibility to select the disposition of the
instance state at the time a transaction is committed. This allows the container to best manage
caching an entity objects state and associating an entity object identity with the EJB instances.
There are three commit-time options:
Option A The container caches a ready instance between transactions. The container
ensures that the instance has exclusive access to the state of the object in persistent storage.
In this case, the container does not have to synchronize the instances state fromthe
persistent storage at the beginning of the next transaction.
Note Commit option Ais not supported for this GlassFish Server release.
Option B The container caches a ready instance between transactions, but the container
does not ensure that the instance has exclusive access to the state of the object in persistent
storage. This is the default.
In this case, the container must synchronize the instances state by invoking ejbLoad from
persistent storage at the beginning of the next transaction.
Option C The container does not cache a ready instance between transactions, but instead
returns the instance to the pool of available instances after a transaction has completed.
The life cycle for every business method invocation under commit option Clooks like this.
HandlingTransactions with Enterprise Beans
ejbActivate ejbLoad business method ejbStore ejbPassivate
If there is more than one transactional client concurrently accessing the same entity, the frst
client gets the ready instance and subsequent concurrent clients get newinstances fromthe
pool.
The glassfish-ejb-jar.xml deployment descriptor has an element, commit-option, that
specifes the commit option to be used. Based on the specifed commit option, the appropriate
handler is instantiated.
Bean-Level Container-ManagedTransactionTimeouts
The transaction timeout for the domain is specifed using the Transaction Timeout setting of
the Transaction Service. Atransaction started by the container must commit (or rollback)
within this time, regardless of whether the transaction is suspended (and resumed), or the
transaction is marked for rollback. The default value, 0, specifes that the server waits
indefnitely for a transaction to complete.
To override this timeout for an individual bean, use the optional cmt-timeout-in-seconds
element in glassfish-ejb-jar.xml. The default value, 0, specifes that the Transaction Service
timeout is used. The value of cmt-timeout-in-seconds is used for all methods in the bean that
start a newcontainer-managed transaction. This value is not used if the bean joins a client
transaction.
HandlingTransactions withthe Java Message Service
Transactions and Non-Persistent Messages on page 270
Using the ConfgurableTransactionSupport Interface on page 270

Transactions andNon-Persistent Messages
During transaction recovery, non-persistent messages might be lost. If the broker fails between
the transaction managers prepare and commit operations, any non-persistent message in the
transaction is lost and cannot be delivered. Amessage that is not saved to a persistent store is
not available for transaction recovery.
Usingthe ConfgurableTransactionSupport Interface
The Java EE Connector 1.6 specifcation allows a resource adapter to use the
transaction-support attribute to specify the level of transaction support that the resource
HandlingTransactions with the Java Message Service
adapter handles. However, the resource adapter vendor does not have a mechanismto fgure
out the current transactional context in which a ManagedConnectionFactory is used.
If a ManagedConnectionFactory implements an optional interface called com.sun.appserv.
connectors.spi.ConfgurableTransactionSupport, the GlassFish Server notifes the
ManagedConnectionFactory of the transaction-support confgured for the connector
connection pool when the ManagedConnectionFactory instance is created for the pool.
Connections obtained fromthe pool can then be used with a transaction level at or lower than
the confgured value. For example, a connection obtained froma pool that is set to
XA_TRANSACTION could be used as a LOCAL resource in a last-agent-optimized transaction or in
a non-transactional context.
TheTransactionManager, theTransactionSynchronization
Registry, andUserTransaction
To access a UserTransaction instance, you can either look it up using the java:comp/
UserTransaction JNDI name or inject it using the @Resource annotation.
Accessing a DataSource using the Synchronization.beforeCompletion() method requires
setting AllowNon Component Callers to true. The default is false. For more information
about non-component callers, see Allowing Non-Component Callers on page 262.
If possible, you should use the javax.transaction.TransactionSynchronizationRegistry interface
instead of javax.transaction.TransactionManager, for portability. You can look up the
implementation of this interface by using the JNDI name java:comp/
TransactionSynchronizationRegistry. For details, see the Javadoc page for Interface
TransactionSynchronizationRegistry (http://download.oracle.com/
javaee/5/api/javax/transaction/TransactionSynchronizationRegistry.html) and Java
Specifcation Request (JSR) 907 (http://www.jcp.org/en/jsr/detail?id=907).
If accessing the javax.transaction.TransactionManager implementation is absolutely necessary,
you can look up the GlassFish Server implementation of this interface using the JNDI name
java:appserver/TransactionManager. This lookup should not be used by the application code.
TheTransaction Manager, theTransaction Synchronization Registry, and UserTransaction
272
Using the Java Naming and Directory Interface
Anaming service maintains a set of bindings, which relate names to objects. The Java EE
naming service is based on the Java Naming and Directory Interface (JNDI) API. The JNDI API
allows application components and clients to look up distributed resources, services, and EJB
components. For general information about the JNDI API, see http://www.oracle.com/
technetwork/java/jndi/index.html. You can also see the JNDI tutorial at
http://download.oracle.com/javase/jndi/tutorial/.
Accessing the Naming Context on page 273
Confguring Resources on page 276
Using a Customjndi.properties File on page 280
Mapping References on page 280

jsr/detail?id=318).
Accessingthe NamingContext
The Oracle GlassFish Server provides a naming environment, or context, which is compliant
with standard Java EE requirements. AContext object provides the methods for binding names
to objects, unbinding names fromobjects, renaming objects, and listing the bindings. The
InitialContext is the handle to the Java EE naming service that application components and
clients use for lookups.
The JNDI API also provides subcontext functionality. Much like a directory in a fle system, a
subcontext is a context within a context. This hierarchical structure permits better organization
16
C H A P T E R 1 6
273
of information. For naming services that support subcontexts, the Context class also provides
methods for creating and destroying subcontexts.
Global JNDI Names on page 274
Accessing EJB Components Using the CosNaming Naming Context on page 275
Accessing EJB Components in a Remote GlassFish Server on page 275
Naming Environment for Lifecycle Modules on page 276

Note Each resource within a server instance must have a unique name. However, two resources
in diferent server instances or diferent domains can have the same name.
Global JNDI Names
Global JNDI names are assigned according to the following precedence rules:
1. Aglobal JNDI name assigned in the glassfish-ejb-jar.xml, glassfish-web.xml, or
glassfish-application-client.xml deployment descriptor fle has the highest
precedence. See Mapping References on page 280.
2. Aglobal JNDI name assigned in a mapped-name element in the ejb-jar.xml, web.xml, or
application-client.xml deployment descriptor fle has the second highest precedence.
The following elements have mapped-name subelements: resource-ref,
resource-env-ref, ejb-ref, message-destination, message-destination-ref,
session, message-driven, and entity.
3. Aglobal JNDI name assigned in a mappedName attribute of an annotation has the third
highest precedence. The following annotations have mappedName attributes:
@javax.annotation.Resource, @javax.ejb.EJB, @javax.ejb.Stateless,
@javax.ejb.Singleton, @javax.ejb.Stateful, and @javax.ejb.MessageDriven.
4. Adefault global JNDI name is assigned in some cases if no name is assigned in deployment
descriptors or annotations.
For an EJB 2.x dependency or a session or entity bean with a remote interface, the default
is the fully qualifed name of the home interface.
For an EJB 3.0 dependency or a session bean with a remote interface, the default is the
fully qualifed name of the remote business interface.
If both EJB 2.x and EJB 3.0 remote interfaces are specifed, or if more than one 3.0
remote interface is specifed, there is no default, and the global JNDI name must be
specifed.
For all other component dependencies that must be mapped to global JNDI names, the
default is the name of the dependency relative to java:comp/env. For example, in the
@Resource(name="jdbc/Foo") DataSource ds; annotation, the global JNDI name is
jdbc/Foo.
Accessing the Naming Context
AccessingEJBComponents Usingthe CosNaming
NamingContext
The preferred way of accessing the naming service, even in code that runs outside of a Java EE
container, is to use the no-argument InitialContext constructor. However, if EJB client code
explicitly instantiates an InitialContext that points to the CosNaming naming service, it is
necessary to set the java.naming.factory.initial property to
com.sun.jndi.cosnaming.CNCtxFactory in the client JVMsoftware when accessing EJB
components. You can set this property as a command-line argument, as follows:
-Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
Or you can set this property in the code, as follows:
Properties properties = null;
try {
properties = new Properties();
properties.put("java.naming.factory.initial",
"com.sun.jndi.cosnaming.CNCtxFactory");
...
The java.naming.factory.initial property applies to only one instance. The property is not
cluster-aware.
AccessingEJBComponents ina Remote GlassFish
Server
The recommended approach for looking up an EJB component in a remote GlassFish Server
froma client that is a servlet or EJB component is to use the Interoperable Naming Service
syntax. Host and port information is prepended to any global JNDI names and is automatically
resolved during the lookup. The syntax for an interoperable global name is as follows:
corbaname:iiop:host:port#a/b/name
This makes the programming model for accessing EJB components in another GlassFish Server
exactly the same as accessing themin the same server. The deployer can change the way the EJB
components are physically distributed without having to change the code.
For Java EE components, the code still performs a java:comp/env lookup on an EJB reference.
The only diference is that the deployer maps the ejb-reference element to an interoperable
name in a GlassFish Server deployment descriptor fle instead of to a simple global JNDI name.
For example, suppose a servlet looks up an EJB reference using java:comp/env/ejb/Foo, and
the target EJB component has a global JNDI name of a/b/Foo.
The ejb-ref element in glassfish-web.xml looks like this:
Accessing the Naming Context
Chapter 16 Using the Java Naming and Directory Interface 275
<ejb-ref>
<ejb-ref-name>ejb/Foo</ejb-ref-name>
<jndi-name>corbaname:iiop:host:port#a/b/Foo</jndi-name>
<ejb-ref>
The code looks like this:
Context ic = new InitialContext();
Object o = ic.lookup("java:comp/env/ejb/Foo");
For a client that doesnt run within a Java EE container, the code just uses the interoperable
global name instead of the simple global JNDI name. For example:
Context ic = new InitialContext();
Object o = ic.lookup("corbaname:iiop:host:port#a/b/Foo");
Objects stored in the interoperable naming context and component-specifc (java:comp/env)
naming contexts are transient. On each server startup or application reloading, all relevant
objects are re-bound to the namespace.
NamingEnvironment for Lifecycle Modules
Lifecycle listener modules provide a means of running short or long duration tasks based on
Java technology within the GlassFish Server environment, such as instantiation of singletons or
RMI servers. These modules are automatically initiated at server startup and are notifed at
various phases of the server life cycle. For details about lifecycle modules, see Chapter 12,
Developing Lifecycle Listeners.
The confgured properties for a lifecycle module are passed as properties during server
initialization (the INIT_EVENT). The initial JNDI naming context is not available until server
initialization is complete. Alifecycle module can get the InitialContext for lookups using the
method LifecycleEventContext.getInitialContext() during, and only during, the
STARTUP_EVENT, READY_EVENT, or SHUTDOWN_EVENT server life cycle events.
ConfguringResources
The GlassFish Server exposes special resources in the naming environment.
External JNDI Resources on page 277
CustomResources on page 277
Built-in Factories for CustomResources on page 277
Disabling GlassFish Server V2 Vendor-Specifc JNDI Names on page 279
Using Application-Scoped Resources on page 280

Confguring Resources
External JNDI Resources
An external JNDI resource defnes customJNDI contexts and implements the
javax.naming.spi.InitialContextFactory interface. There is no specifc JNDI parent context for
external JNDI resources, except for the standard java:comp/env/.
Create an external JNDI resource in one of these ways:
To create an external JNDI resource using the Administration Console, open the Resources
component, open the JNDI component, and select External Resources. For details, click the
To create an external JNDI resource, use the asadmin create-jndi-resource command.

CustomResources
Acustomresource specifes a customserver-wide resource object factory that implements the
javax.naming.spi.ObjectFactory interface. There is no specifc JNDI parent context for external
JNDI resources, except for the standard java:comp/env/.
Create a customresource in one of these ways:
To create a customresource using the Administration Console, open the Resources

component, open the JNDI component, and select CustomResources. For details, click the
To create a customresource, use the asadmin create-custom-resource command. For

Built-inFactories for CustomResources
The GlassFish Server provides built-in factories for the following types of customresources:
JavaBeanFactory on page 277
PropertiesFactory on page 278
PrimitivesAndStringFactory on page 278
URLFactory on page 279

Template glassfish-resources.xml fles for these built-in factories and a README fle are
available at as-install/lib/install/templates/resources/custom/. For more information
about the glassfish-resources.xml fle, see the Oracle GlassFish Server 3.1 Application
Deployment Guide.
JavaBeanFactory
To create a customresource that provides instances of a JavaBean class, followthese steps:
1. Set the customresource's factory class to
org.glassfish.resources.custom.factory.JavaBeanFactory.
2. Create a property in the customresource for each setter method in the JavaBean class.
For example, if the JavaBean class has a method named setAccount, specify a property
named account and give it a value.
3. Make sure the JavaBean class is accessible to the GlassFish Server.
For example, you can place the JavaBean class in the as-install/lib directory.
PropertiesFactory
To create a customresource that provides properties to applications, set the customresource's
factory class to org.glassfish.resources.custom.factory.PropertiesFactory, then
specify one or both of the following:
Create a property in the customresource named org.glassfish.resources.

custom.factory.PropertiesFactory.fileName and specify as its value the path to a
properties fle or an XML fle.
The path can be absolute or relative to as-install. The fle must be accessible to the GlassFish
Server.
If an XML fle is specifed, it must match the document type defnition (DTD) specifed in
the API defnition of java.util.Properties (http://download.oracle.com/javase/6/docs/
api/java/util/Properties.html).
Create the desired properties directly as properties of the customresource.

If both the fileName property and other properties are specifed, the resulting property set is
the union. If the same property is defned in the fle and directly in the customresource, the
value of the latter takes precedence.
PrimitivesAndStringFactory
To create a customresource that provides Java primitives to applications, followthese steps:
org.glassfish.resources.custom.factory.PrimitivesAndStringFactory.
2. Set the customresource's resource type to one of the following or its fully qualifed wrapper
class name equivalent:
int
long
double
float
char
short
byte
boolean
String
3. Create a property in the customresource named value and give it the value needed by the
application.
For example, If the application requires a double of value 22.1, create a property with the
name value and the value 22.1.
URLFactory
To create a customresource that provides URL instances to applications, followthese steps:
org.glassfish.resources.custom.factory.URLObjectFactory.
2. Choose which of the following constructors to use:
URL(protocol, host, port, file)
URL(protocol, host, file)
URL(spec)
3. Defne properties according to the chosen constructor.
For example, for the frst constructor, defne properties named protocol, host, port, and
file. Example values might be http, localhost, 8085, and index.html, respectively.
For the third constructor, defne a property named spec and assign it the value of the entire
URL.
DisablingGlassFishServer V2Vendor-Specifc JNDI
Names
The EJB 3.1 specifcation supported by GlassFish Server 3.1 defnes portable EJB JNDI names.
Because of this, there is less need to continue to use older vendor-specifc JNDI names.
By default, GlassFish Server V2specifc JNDI names are applied automatically by GlassFish
Server 3.1 for backward compatibility. However, this can lead to some ease-of-use issues. For
example, deploying two diferent applications containing a remote EJB component that exposes
the same remote interface causes a confict between the default JNDI names.
The default handling of V2specifc JNDI names in GlassFish Server 3.1 can be managed by
using the asadmin command:
asadmin> set server.ejb-container.property.disable-nonportable-jndi-names="true"
disable-nonportable-jndi-names is a boolean property that can take the following values:
false
Enables the automatic use of GlassFish Server V2specifc JNDI names. This is the default
setting.
true
Disables the automatic use of V2specifc JNDI names. In all cases, 3.1-compatible JNDI
names are used.
Note that this setting applies to all EJB components deployed to the server.
UsingApplication-ScopedResources
You can defne an application-scoped JNDI or other resource for an enterprise application, web
module, EJB module, connector module, or application client module by supplying a
Usinga Customjndi.properties File
To use a customjndi.properties fle, place the fle in the domain-dir/lib/classes directory
or JARit and place it in the domain-dir/lib directory. This adds the customjndi.properties
fle to the Common class loader. For more information about class loading, see Chapter 2,
Class Loaders.
For each property found in more than one jndi.properties fle, the Java EE naming service
either uses the frst value found or concatenates all of the values, whichever makes sense.
MappingReferences
The following XML elements in the GlassFish Server deployment descriptors map resource
references in application client, EJB, and web application components to JNDI names
confgured in the GlassFish Server:
resource-env-ref - Maps the @Resource or @Resources annotation (or the

resource-env-ref element in the corresponding Java EE XML fle) to the absolute JNDI
name confgured in the GlassFish Server.
resource-ref - Maps the @Resource or @Resources annotation (or the resource-ref

element in the corresponding Java EE XML fle) to the absolute JNDI name confgured in
the GlassFish Server.
ejb-ref - Maps the @EJB annotation (or the ejb-ref element in the corresponding Java EE
XML fle) to the absolute JNDI name confgured in the GlassFish Server.
JNDI names for EJB components must be unique. For example, appending the application
name and the module name to the EJB name is one way to guarantee unique names. In this
case, mycompany.pkging.pkgingEJB.MyEJB would be the JNDI name for an EJB in the
module pkgingEJB.jar, which is packaged in the pkging.ear application.
Using a Customjndi.properties File
These elements are part of the glassfish-web.xml, glassfish-application-client.xml,
glassfish-ejb-jar.xml, and glassfish-application.xml deployment descriptor fles. For
more information about howthese elements behave in each of the deployment descriptor fles,
see Appendix C, Elements of the GlassFish Server Deployment Descriptors, in Oracle
The rest of this section uses an example of a JDBCresource lookup to describe howto reference
resource factories. The same principle is applicable to all resources (such as JMS destinations,
JavaMail sessions, and so on).
The @Resource annotation in the application code looks like this:
@Resource(name="jdbc/helloDbDs") javax.sql.DataSource ds;
This references a resource with the JNDI name of java:jdbc/helloDbDs. If this is the JNDI
name of the JDBCresource confgured in the GlassFish Server, the annotation alone is enough
to reference the resource.
However, you can use a GlassFish Server specifc deployment descriptor to override the
annotation. For example, the resource-ref element in the glassfish-web.xml fle maps the
res-ref-name (the name specifed in the annotation) to the JNDI name of another JDBC
resource confgured in the GlassFish Server.
<resource-ref>
<res-ref-name>jdbc/helloDbDs</res-ref-name>
<jndi-name>jdbc/helloDbDataSource</jndi-name>
</resource-ref>
Mapping References
282
Using the Java Message Service
This chapter describes howto use the Java Message Service (JMS) API. The Oracle GlassFish
Server has a fully integrated JMS provider: the GlassFish Server Message Queue software.
Note JMS resources are supported only in the full GlassFish Server, not in the Web Profle.
For general information about the JMS API, see Chapter 31: The Java Message Service API in
the The Java EE 6 Tutorial (http://download.oracle.com/javaee/6/tutorial/doc/).
For detailed information about JMS concepts and JMS support in the GlassFish Server, see
Chapter 17, Administering the Java Message Service (JMS), in Oracle GlassFish Server 3.1
Administration Guide.
For more information about Message Queue software, see the Oracle GlassFish Server Message
Queue 4.5 Administration Guide.
Using Application-Scoped JMS Resources on page 283
Load-Balanced Message Infow on page 284
Authentication With ConnectionFactory on page 284
Delivering SOAP Messages Using the JMS API on page 285

UsingApplication-ScopedJMS Resources
You can defne an application-scoped JMS or other resource for an enterprise application, web
module, EJB module, connector module, or application client module by supplying a
17
C H A P T E R 1 7
283
Load-BalancedMessage Infow
You can confgure ActivationSpec properties of the jmsra resource adapter in the
glassfish-ejb-jar.xml fle for a message-driven bean using activation-config-property
elements. Whenever a message-driven bean (EndPointFactory) is deployed, the connector
runtime engine fnds these properties and confgures themaccordingly in the resource adapter.
See activation-confg-property in Oracle GlassFish Server 3.1 Application Deployment Guide.
The GlassFish Server transparently enables messages to be delivered in randomfashion to
message-driven beans having same ClientID. The ClientID is required for durable
subscribers.
For nondurable subscribers in which the ClientID is not confgured, all instances of a specifc
message-driven bean that subscribe to same topic are considered equal. When a
message-driven bean is deployed to multiple instances of the GlassFish Server, only one of the
message-driven beans receives the message. If multiple distinct message-driven beans subscribe
to same topic, one instance of each message-driven bean receives a copy of the message.
To support multiple consumers using the same queue, set the maxNumActiveConsumers
property of the physical destination to a large value. If this property is set, the Oracle Message
Queue software allows multiple message-driven beans to consume messages fromsame queue.
The message is delivered randomly to the message-driven beans. If maxNumActiveConsumers is
set to -1, there is no limit to the number of consumers.
To ensure that local delivery is preferred, set addresslist-behavior to priority. This setting
specifes that the frst broker in the AddressList is selected frst. This frst broker is the local
colocated Message Queue instance. If this broker is unavailable, connection attempts are made
to brokers in the order in which they are listed in the AddressList. This setting is the default for
GlassFish Server instances that belong to a cluster.
AuthenticationWithConnectionFactory
If your web, EJB, or client module has res-auth set to Container, but you use the
ConnectionFactory.createConnection("user","password") method to get a connection, the
GlassFish Server searches the container for authentication information before using the
supplied user and password. Version 7 of the GlassFish Server threwan exception in this
situation.
Load-Balanced Message Infow
DeliveringSOAPMessages Usingthe JMS API
Web service clients use the Simple Object Access Protocol (SOAP) to communicate with web
services. SOAP uses a combination of XML-based data structuring and Hyper Text Transfer
Protocol (HTTP) to defne a standardized way of invoking methods in objects distributed in
diverse operating environments across the Internet.
For more information about SOAP, see the Apache SOAP web site at http://xml.apache.org/
soap/index.html.
You can take advantage of the JMS providers reliable messaging when delivering SOAP
messages. You can convert a SOAP message into a JMS message, send the JMS message, then
convert the JMS message back into a SOAP message.
To Send SOAP Messages Using the JMS API on page 285
To Receive SOAP Messages Using the JMS API on page 286
ToSendSOAPMessages Usingthe JMS API

Import the MessageTransformer library.
import com.sun.messaging.xml.MessageTransformer;
This is the utility whose methods you use to convert SOAP messages to JMS messages and the
reverse. You can then send a JMS message containing a SOAP payload as if it were a normal
JMS message.
Initialize the TopicConnectionFactory, TopicConnection, TopicSession, andpublisher.
tcf = new TopicConnectionFactory();
tc = tcf.createTopicConnection();
session = tc.createTopicSession(false,Session.AUTO_ACKNOWLEDGE);
topic = session.createTopic(topicName);
publisher = session.createPublisher(topic);
Construct a SOAPmessage usingthe SOAPwithAttachments API for Java (SAAJ).
/*construct a default soap MessageFactory */
MessageFactory mf = MessageFactory.newInstance();
* Create a SOAP message object.*/
SOAPMessage soapMessage = mf.createMessage();
/** Get SOAP part.*/
SOAPPart soapPart = soapMessage.getSOAPPart();
/* Get SOAP envelope. */
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
/* Get SOAP body.*/
SOAPBody soapBody = soapEnvelope.getBody();
/* Create a name object. with name space */
/* http://www.sun.com/imq. */
1
2
3
Delivering SOAP Messages Using the JMS API
Chapter 17 Using the Java Message Service 285
Name name = soapEnvelope.createName("HelloWorld", "hw",
"http://www.sun.com/imq");
* Add child element with the above name. */
SOAPElement element = soapBody.addChildElement(name)
/* Add another child element.*/
element.addTextNode( "Welcome to GlassFish Web Services." );
/* Create an atachment with activation API.*/
URL url = new URL ("http://java.sun.com/webservices/");
DataHandler dh = new DataHandler (url);
AttachmentPart ap = soapMessage.createAttachmentPart(dh);
/*set content type/ID. */
ap.setContentType("text/html");
ap.setContentId("cid-001");
/** add the attachment to the SOAP message.*/
soapMessage.addAttachmentPart(ap);
soapMessage.saveChanges();
Convert the SOAPmessage toa JMS message by callingthe
MessageTransformer.SOAPMessageintoJMSMessage() method.
Message m = MessageTransformer.SOAPMessageIntoJMSMessage (soapMessage,
session );
Publishthe JMS message.
publisher.publish(m);
Close the JMS connection.
tc.close();
ToReceive SOAPMessages Usingthe JMS API

Import the MessageTransformer library.
import com.sun.messaging.xml.MessageTransformer;
This is the utility whose methods you use to convert SOAP messages to JMS messages and the
reverse. The JMS message containing the SOAP payload is received as if it were a normal JMS
message.
Initialize the TopicConnectionFactory, TopicConnection, TopicSession, TopicSubscriber,
andTopic.
messageFactory = MessageFactory.newInstance();
tcf = new com.sun.messaging.TopicConnectionFactory();
tc = tcf.createTopicConnection();
session = tc.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
topic = session.createTopic(topicName);
subscriber = session.createSubscriber(topic);
subscriber.setMessageListener(this);
tc.start();
4
5
6
1
2
Use the OnMessage methodtoreceive the message. Use the SOAPMessageFromJMSMessage
methodtoconvert the JMS message toa SOAPmessage.
public void onMessage (Message message) {
SOAPMessage soapMessage =
MessageTransformer.SOAPMessageFromJMSMessage( message,
messageFactory ); }
Retrieve the content of the SOAPmessage.
3
4
Chapter 17 Using the Java Message Service 287
288
Using the JavaMail API
This chapter describes howto use the JavaMail API, which provides a set of abstract classes
defning objects that comprise a mail system.
Introducing JavaMail on page 289
Creating a JavaMail Session on page 290
JavaMail Session Properties on page 290
Looking Up a JavaMail Session on page 290
Sending and Reading Messages Using JavaMail on page 291
Using Application-Scoped JavaMail Resources on page 292

Note JavaMail resources are supported only in the full OracleGlassFish Server, not in the Web
Profle.
IntroducingJavaMail
The JavaMail API defnes classes such as Message, Store, and Transport. The API can be
extended and can be subclassed to provide newprotocols and to add functionality when
necessary. In addition, the API provides concrete subclasses of the abstract classes. These
subclasses, including MimeMessage and MimeBodyPart, implement widely used Internet mail
protocols and conformto the RFC822 and RFC2045 specifcations. The JavaMail API includes
support for the IMAP4, POP3, and SMTP protocols.
The JavaMail architectural components are as follows:
The abstract layer declares classes, interfaces, and abstract methods intended to support
mail handling functions that all mail systems support.
The internet implementation layer implements part of the abstract layer using the RFC822
and MIME internet standards.
18
C H A P T E R 1 8
289
JavaMail uses the JavaBeans Activation Framework (JAF) to encapsulate message data and to
handle commands intended to interact with that data.
For more information, see Chapter 16, Administering the JavaMail Service, in Oracle
GlassFish Server 3.1 Administration Guide and the JavaMail specifcation at
http://www.oracle.com/technetwork/java/javamail/index.html. Auseful JavaMail
tutorial is located at http://java.sun.com/developer/onlineTraining/JavaMail/.
Creatinga JavaMail Session
You can create a JavaMail session in the following ways:
In the Administration Console, open the Resources component and select JavaMail
Sessions. For details, click the Help button in the Administration Console.
Use the asadmin create-javamail-resource command. For details, see the Oracle
JavaMail SessionProperties
You can set properties for a JavaMail Session object. Every property name must start with a
mail- prefx. The GlassFish Server changes the dash (-) character to a period (.) in the name of
the property and saves the property to the MailConfiguration and JavaMail Session objects. If
the name of the property doesnt start with mail-, the property is ignored.
For example, if you want to defne the property mail.from in a JavaMail Session object, frst
defne the property as follows:
Name mail-from
Value [email protected]
LookingUpa JavaMail Session
The standard Java Naming and Directory Interface (JNDI) subcontext for JavaMail sessions is
java:comp/env/mail.
Registering JavaMail sessions in the mail naming subcontext of a JNDI namespace, or in one of
its child subcontexts, is standard. The JNDI namespace is hierarchical, like a fle systems
directory structure, so it is easy to fnd and nest references. AJavaMail session is bound to a
logical JNDI name. The name identifes a subcontext, mail, of the root context, and a logical
name. To change the JavaMail session, you can change its entry in the JNDI namespace without
having to modify the application.
The resource lookup in the application code looks like this:
Creating a JavaMail Session
InitialContext ic = new InitialContext();
String snName = "java:comp/env/mail/MyMailSession";
Session session = (Session)ic.lookup(snName);
For more information about the JNDI API, see Chapter 16, Using the Java Naming and
Directory Interface.
SendingandReadingMessages UsingJavaMail
To Send a Message Using JavaMail on page 291
To Read a Message Using JavaMail on page 292
ToSenda Message UsingJavaMail

Import the packages that youneed.
import java.util.*;
import javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.naming.*;
Look upthe JavaMail session.
Session session = (Session)ic.lookup(snName);
For more information, see Looking Up a JavaMail Session on page 290.
Override the JavaMail sessionproperties if necessary.
For example:
Properties props = session.getProperties();
props.put("mail.from", "[email protected]");
Create a MimeMessage.
The msgRecipient, msgSubject, and msgTxt variables in the following example contain input
fromthe user:
Message msg = new MimeMessage(session);
msg.setSubject(msgSubject);
msg.setSentDate(new Date());
msg.setFrom();
msg.setRecipients(Message.RecipientType.TO,
InternetAddress.parse(msgRecipient, false));
msg.setText(msgTxt);
1
2
3
4
Sending and Reading Messages Using JavaMail
Chapter 18 Using the JavaMail API 291
Sendthe message.
Transport.send(msg);
ToReada Message UsingJavaMail

Import the packages that youneed.
import java.util.*;
import javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.naming.*;
Look upthe JavaMail session.
Session session = (javax.mail.Session)ic.lookup(snName);
For more information, see Looking Up a JavaMail Session on page 290.
Override the JavaMail sessionproperties if necessary.
For example:
Properties props = session.getProperties();
props.put("mail.from", "[email protected]");
Get a Store object fromthe Session, thenconnect tothe mail server usingthe Store objects
connect method.
You must supply a mail server name, a mail user name, and a password.
Store store = session.getStore();
store.connect("MailServer", "MailUser", "secret");
Get the INBOXfolder.
Folder folder = store.getFolder("INBOX");
It is efcient toreadthe Message objects (whichrepresent messages onthe server) intoanarray.
Message[] messages = folder.getMessages();
UsingApplication-ScopedJavaMail Resources
You can defne an application-scoped JavaMail or other resource for an enterprise application,
5
1
2
3
4
5
6
Using Application-Scoped JavaMail Resources
Index
Numbers andSymbols
@OrderBy and session cache sharing, 100
A
ACC, 197199
naming, 198
security, 198, 214215
ACCclients
appclient script, 213
failover, 201
invoking a JMS resource, 201202
invoking an EJB component, 199201
Java Web Start, 202212
libraries, 217
load balancing, 201
making a remote call, 200
package-appclient script, 214
running, 202212, 213
SSL, 198, 214215
activation-confg-property element, 284
ActivationSpec properties, 284
ActiveCache for GlassFish, 121
Admin Console, 27
App Client Modules page, 203
Audit Modules page, 57
CMP resource confguration, 184
Connector Connection Pools page
Flush button, 228
Ping button, 228
Ping feld, 228
Admin Console, Connector Connection Pools page
(Continued)
Pooling feld, 231
Connector Service page
Shutdown Timeout feld, 230
connector thread pool assignment, 226
Debug Enabled feld, 38
Edit Connection Pool Advanced Attributes page
AllowNon Component Callers feld, 262
Associate With Thread feld, 257
Connection Validation feld, 258
Pooling feld, 256
SQL Trace Listeners feld, 254
Statement Cache Size feld, 254
Statement Timeout feld, 252
Validation Classname feld, 258
Validation Method feld, 258
Wrap JDBCObjects feld, 261
Edit Connection Pool page
Init SQL feld, 252
Isolation Level Guaranteed option, 267
Non-Transactional Connections feld, 267
Transaction Isolation feld, 266
Generate RMIStubs feld, 205
HPROF confguration, 42
JACCProviders page, 56
JavaMail Sessions page, 290
JNDI page
CustomResources page, 277
External Resources page, 277
JProbe confguration, 43
Libraries feld, 32
293
Admin Console (Continued)
Locale feld, 136
Logging tab, 41, 139
Message Security page, 82
creating providers, 64
enabling providers, 63
Monitor tab, 139
NewJDBCConnection Pool page
Isolation Level Guaranteed option, 267
Non-Transactional Connections feld, 267
Transaction Isolation feld, 266
online help for, 27
Realms page, 52
Resource Adapter Confgs, 227
role mapping confguration, 51
Security Manager Enabled feld, 62
Security Maps tab, 226
Thread Pools page, 226
Web Services page
Test button, 87
allow-concurrent-access element, 166
AllowManagedFieldsInDefaultFetchGroup fag, 186
AllowMediatedWriteInDefaultFetchGroup fag, 187
alternate document roots, 140142
annotation
application clients, 198
JNDI names, 274
message layer, 62
schema generation, 96
security, 49
appclient script, 213
Applib class loader, 30
Application Client Container, See ACC
application client JARfle, 199
application clients, annotation, 198
application-scoped
connectors, 231
resources, 262, 280, 283, 292
applications, examples, 28
AppservPasswordLoginModule class, 54
AppservRealmclass, 54
Archive class loader, 30
asadmin command, 27
create-audit-module, 57
asadmin command (Continued)
create-auth-realm, 52
create-connector-connection-pool
--ping option, 228
--pooling option, 231
create-connector-security-map, 226
create-custom-resource, 277
create-domain, 206
create-javamail-resource, 290
create-jdbc-connection-pool
--allownoncomponentcallers option, 262
--associatewiththread option, 257
--initsql option, 252
--isconnectionvalidatereq option, 258
--isisolationguaranteed option, 267
--isolationlevel option, 266
--nontransactionalconnections option, 267
--sqltracelisteners option, 254
--statementcachesize option, 254
--statementtimeout option, 253
--validationclassname option, 258
--validationmethod option, 258
--wrapjdbcobjects option, 261
create-jndi-resource, 277
create-jvm-options, 165, 187
java.security.debug option, 61
create-message-security-provider, 64, 83
create-resource-adapter-confg, 226, 227
create-threadpool, 226
delete-jvm-options
java.security.manager option, 62
deploy
--availabilityenabled option, 161
--libraries option, 33
--precompilejsp option, 114
--retrieve option, 200, 205
schema generation, 97, 181
deploydir
fush-connection-pool, 228
generate-jvm-report, 39
get-client-stubs, 199, 200, 205
Index
asadmin command (Continued)
list-timers, 154
migrate-timers, 154
ping-connection-pool, 228
set
allow-non-component-callers option, 262
associate-with-thread option, 257
connection-validation-method option, 258
default message security provider, 63
default principal settings, 51
init-sql option, 252
is-connection-validation-required option, 258
is-isolation-level-guaranteed option, 267
java-web-start-enabled attribute, 203
non-transactional-connections option, 267
pooling option, 256
sql-trace-listeners option, 254
statement-cache-size option, 254
transaction-isolation-level option, 266
validation-classname option, 258
undeploy
audit modules, 5658
AuditModule class, 5758
authentication
audit modules, 57
JAAS, 5356
JMS, 284
message-level, 70
programmatic login, 72
realms, 52
single sign-on, 7476
authentication mechanisms for the Servlet
container, 7683
authorization
audit modules, 57
JAAS, 5356
JACC, 56
roles, 5051
automatic schema generation
for CMP, 177182
Java Persistence options, 9697
availability
confguring HTTP session persistence, 120121
feature summary, 26
for ACCclients, 201
for stateful session beans, 157162
for web modules, 116118
of message-driven beans, 284
B
Bayeux protocol, 133135
BLOB support, 175176
Bootstrap class loader, 30
build.xml fle, 28
C
cache for servlets
default confguration, 107
example confguration, 108
helper class, 107, 109
cache sharing and @OrderBy, 100
cache tag, 112113
CacheHelper interface, 109
cacheKeyGeneratorAttrName property, 109
caching
a bean's state using version consistency, 184
data using a non-transactional connection, 268
EJB components, 151
entities, 269
JSP fles, 111114
read-only beans, 164
servlet results, 106109
stateful session beans, 157
using a read-only bean for, 150, 166, 186
capture-schema command, 183
Catalina listeners, defning custom, 140
certifcate realm, 52
CGI, 145147
checkpoint-at-end-of-method element, 161
checkpointing, 157
selecting methods for, 161
class-loader element, 31, 137
Index
295
class loaders, 2936
application-specifc, 3234
circumventing isolation, 3436
delegation hierarchy, 3031
isolation, 32
client JARfle, 35, 199
client.policy fle, 214
clients, non-ACC, 217221
CLOB support, 176
CMP, See container-managed persistence
cmp-resource element, 184
cmt-max-runtime-exceptions property, 169
Coherence*Web, 121
Comet, 122135
Cometd, 133135
command-line server confguration, See asadmin
command
commit options, 269
Common class loader, 30
using to circumvent isolation, 34
common gateway interface, 145147
compiling JSP fles, 114
ConfgurableTransactionSupport interface, 270271
connection factory, 167
Connector class loader, 30, 238
connectors, 223234
and JDBC, 225
and JMS, 225
and message-driven beans, 232234
application-scoped, 231
class loading policy, 230
confguration options, 225231
confguring, 225
fushing connection pools, 228
inbound connectivity, 231232
invalid connections, 229
last agent optimization, 230231
Oracle GlassFish Server support, 224225
outbound connectivity, 232
shutdown timeout, 229230
testing connection pools, 228
thread associations, 226
container-managed persistence
confguring 1.1 fnders, 187188
container-managed persistence (Continued)
data types for mapping, 177179
deployment descriptor, 173174
mapping, 172173
performance features, 184186
prefetching, 185
resource manager, 184
restrictions, 191196
support, 171172
version consistency, 184185
context, for JNDI naming, 273276
context.xml fle, 142143
CosNaming naming service, 275
create-audit-module command, 57
create-auth-realmcommand, 52
create-connector-connection-pool command
--ping option, 228
create-connector-security-map command, 226
create-custom-resource command, 277
create-domain command, 206
create-javamail-resource command, 290
create-jdbc-connection-pool command
--allownoncomponentcallers option, 262
--associatewiththread option, 257
--initsql option, 252
--isconnectionvalidatereq option, 258
--isisolationguaranteed option, 267
--isolationlevel option, 266
--nontransactionalconnections option, 267
--sqltracelisteners option, 254
--statementcachesize option, 254
--statementtimeout option, 253
--validationclassname option, 258
--validationmethod option, 258
--wrapjdbcobjects option, 261
create-jndi-resource command, 277
create-jvm-options command, 165, 187
java.security.debug option, 61
create-message-security-provider command, 64, 83
create-resource-adapter-confg command, 226, 227
create-threadpool command, 226
customresource, 277
Index
customresource (Continued)
factory for, 277279
D
data types, for CMP mapping, 177179
database properties, 94
databases
CMP resource manager, 184
properties, 94
schema capture, 183
specifying for Java Persistence, 9293
debug property, 65
debugging, 3744
enabling, 3738
generating a stack trace, 39
JPDAoptions, 3839
DeclareRoles annotation, 5051
default-web.xml fle, 138
delegation, class loader, 31
delete-jvm-options command, java.security.manager
option, 62
deploy command
--libraries option, 33
--precompilejsp option, 114
--retrieve option, 200, 205
deploydir command
deployment
read-only beans, 166
signing JARfles, 206207
deployment descriptor fles, 281
destroy method, 109
development environment
creating, 2528
tools for developers, 2628
digest authentication, 52
directory listings, disabling, 138
distributable web application, 116
distributed HTTP sessions, 116118
document roots, alternate, 140142
doGet method, 110
doPost method, 110
dynamic.username.password property, 65
E
Eclipse IDE, 28
EclipseLink, 91
eclipselink.target-database property, 92
EJB, singletons, 163
EJB 3.0, Java Persistence, 91103
EJB components
caching, 151152
calling froma diferent application, 35
fushing, 152153
pooling, 151152, 156
remote bean invocations, 152
security, 50
thread pools, 152
EJB QL queries, 187188
ejb-ref element, 280
ejb-ref mapping, using JNDI name instead, 35
EJB reference failover, 201
EJB Timer Service, 153155
ejbPassivate, 164
encoding, of servlets, 136
encryption.key.alias property, 65
endorsed standards override mechanism, 32
events, server life cycle, 236
example applications, 28
Extension class loader, 30
external JNDI resource, 277
F
fail-all-connections setting, 229, 259260
failover
for ACCclients, 201
object types supported for, 117118, 158159
of stateful session bean state, 157162
of web module sessions, 116118
fetch group, options for, 186187
Index
297
fle realm, 52
fnder limitation for Sybase, 101102, 193
fnder methods, 187188
fat transactions, 269
fush-connection-pool command, 228
fush tag, 113114
fushing of EJB components, 152153
G
generate-jvm-report command, 39
get-client-stubs command, 199, 200, 205
getCharacterEncoding method, 136
getCmdLineArgs method, 237
getConnection method, 261
getData method, 236
getEventType method, 236
getHeaders method, 140
getInitialContext method, 237, 276
getInstallRoot method, 237
getInstanceName method, 237
getLifecycleEventContext method, 237
gf-client.jar fle, 205
glassfsh-api.jar fle, 235
glassfsh-ejb-jar.xml fle, 161
GlassFish Java EE Service Engine, 8889
GlassFish Server Message Queue, debugging, 40
glassfsh-web.xml fle
and class loaders, 31, 137
Grizzly, Comet, 124133
H
handling requests, 109
header management, 140
help for Admin Console tasks, 27
high availability, See availability
HPROF profler, 4243
HTTP sessions, 114121
and redeployment, 115116
cookies, 115
distributed, 116118
logging attributes, 116
HTTP sessions (Continued)
object types supported for failover, 117118
session managers, 118121
URL rewriting, 115
HttpServletRequest, 107
I
idempotent requests, 139
IMAP4 protocol, 289290
inbound connectivity, 231232
Inet Oracle JDBCdriver, 100, 175, 176
INIT_EVENT, 236
init method, 109
InitialContext naming service handle, 273276
installation, 2526
instantiating servlets, 109
internationalization, 136
Interoperable Naming Service, 275276
is-connection-validation-required setting, 229,
259260
is-read-only-bean element, 166
isolation of class loaders, 32, 3436
J
J2SE policy fle, 214
JACC, 56
JARfle, client for a deployed application, 35
jar-signing-alias property, 206207
Java Authentication and Authorization Service
(JAAS), 5356
Java Authorization Contract for Containers, See JACC
Java Business Integration (JBI), 8889
Java Database Connectivity, See JDBC
Java DB database, 9293
Java Debugger (jdb), 37
Java EE, security model, 48
Java EE Connector architecture, 223234
Java EE Service Engine, 8889
Java EE tutorial, 105
Java Message Service
See JMS
Index
Java Naming and Directory Interface, See JNDI
Java optional package mechanism, 31
Java Persistence, 91103
annotation for schema generation, 96
changing the provider, 9899
database for, 9293
deployment options for schema generation, 9697
restrictions, 99103
Java PlatformDebugger Architecture, See JPDA
Java Servlet API, 105
Java Studio Enterprise, 27
Java Transaction API (JTA), 265271
Java Transaction Service (JTS), 265271
Java Web Start, 202212
signing client JARfles, 205207
JavaBeanFactory, 277278
JavaBeans, 110
JavaMail
and JNDI lookups, 290291
architecture, 289
creating sessions, 290
defned, 289292
messages
reading, 292
sending, 291292
session properties, 290
specifcation, 290
JDBC
and the Transaction Synchronization Registry, 262
Connection wrapper, 261
integrating driver JARfles, 34
invalid connections, 259260
non-component callers, 262
non-transactional connections, 267268
restrictions, 263
sharing connections, 258259
specifcation, 251
transaction isolation levels, 266
tutorial, 251
jdbc realm, 52
JDOQL, 187188
JMS, 167, 283287
authentication, 284
JMS (Continued)
ConfgurableTransactionSupport
interface, 270271
debugging, 40
load balancing, 284
SOAP messages, 285287
transactions and non-persistent messages, 270
JNDI
and EJB components, 280
and JavaMail, 290291
and lifecycle modules, 237, 238, 276
customresource, 277
customresource factories, 277279
defned, 273281
external JNDI resources, 277
for message-driven beans, 167
global names, 274
mapping references, 280281
name for container-managed persistence, 184
tutorial, 273
using instead of ejb-ref mapping, 35
vendor-specifc names, 279280
join tables, 174
JPDAdebugging options, 3839
JProbe profler, 4344
JSP fles
caching, 111114
command-line compiler, 114
precompiling, 114
specifcation, 110
tag libraries, 110111
jspc command, 114
jspcachtags.jar fle, 111
jspcachtags.tld fle, 111
JSR109, 85
JSR115, 48, 56, 57
JSR12, 188
JSR181, 86
JSR196, 48, 63, 7683
JSR220, 91
JSR224, 85
JSR907, 271
Index
299
K
key attribute
of cache tag, 112
of fush tag, 114
L
last agent optimization, 230231
ldap realm, 52
lib directory
and the Common class loader, 30
for a web application, 35
libraries, 3234, 34
and application clients, 217
lifecycle modules, 235
allocating and freeing resources, 238
and class loaders, 238
and the server.policy fle, 238
deployment, 237
naming environment, 276
LifecycleEvent class, 236
LifecycleEventContext interface, 237
LifecycleListener interface, 236
LifecycleListenerImpl.java fle, 236
LifeCycleModule class loader, 30, 238
list-timers command, 154
listeners, Catalina, defning custom, 140
load balancing
and idempotent requests, 139
of ACCclients, 201
of message-driven beans, 284
locale, setting default, 136
lock-when-loaded consistency level, 192
logging, 41
in the web container, 139
login, programmatic, 72
login method, 73
login retries, 217
LoginModule, 54
M
main.xml fle, 28
managed felds, 175
mapping for container-managed persistence
considerations, 174176
data types, 177179
features, 172
mapping resource references, 280281
markConnectionAsBad method, 259
mdb-connection-factory element, 167, 169
message-driven beans, 167
administering, 168
connection factory, 167
debugging, 40
load balancing, 284
monitoring, 168
onMessage runtime exception, 169170
pool monitoring, 169
pooling, 167
using with connectors, 232234
message security, 6272
responsibilities, 65
sample application, 6972
migrate-timers command, 154
Migration Tool, 27
mime-mapping element, 138
modules, lifecycle, 235
monitoring in the web container, 139
MSSQL version consistency triggers, 193194
MySQL database restrictions, 102103, 194196
N
naming service, 273281
native library path
confguring for hprof, 42
confguring for JProbe, 43
nested transactions, 269
NetBeans
about, 27
profler, 41
nocache attribute, of cache tag, 113
non-ACCclients, 217221
Index
O
Oasis Web Services Security, See message security
object references supported for failover, 117118,
158159
online help, 27
onMessage method, 169, 287
Oracle automatic mapping of date and time felds, 193
Oracle Inet JDBCdriver, 100, 175, 176
Oracle TopLink, 99
ORDERBYvalidation, disabling, 191
outbound connectivity, 232
P
package-appclient script, 214
pass-by-reference element, 150
permissions
changing in server.policy, 5961
default in server.policy, 58
persistence, Coherence*Web, 121
persistence store
for HTTP sessions, 116118, 120121
for stateful session bean state, 157162
persistence.xml fle, 9293, 97
ping-connection-pool command, 228
pool monitoring for MDBs, 169
pooling, 164
POP3 protocol, 289290
precompiling JSP fles, 114
prefer-validate-over-recreate property, 229, 259260
prefetching, 185
primary key, 172, 174, 175
PrimitivesAndStringFactory, 278279
proflers, 4144
ProgrammaticLogin class, 73
ProgrammaticLoginPermission permission, 73
PropertiesFactory, 278
Public API class loader, 30
Q
query hints, 98
R
read-only beans, 150, 163167, 186
deploying, 166
refreshing, 165166
readonly.relative.refresh.mode fag, 165
ReadOnlyBeanNotifer, 166
READY_EVENT, 236
realms
confguring, 52
custom, 5356
supported, 52
references supported for failover, 117118, 158159
refresh attribute, of cache tag, 113
refresh-period-in-seconds element, 164
removing servlets, 109
request object, 109
res-sharing-scope deployment descriptor
setting, 258259
resource-adapter-mid element, 233
resource adapters, See connectors
resource-env-ref element, 280
resource-ref element, 280
resource references, mapping, 280281
resources
application-scoped, 262, 280, 283, 292
RMI/IIOP over SSL, 214215
roles, 5051
S
sample applications, 28
schema capture, 183
schema generation
automatic for CMP, 177182
Java Persistence options for automatic, 9697
scope attribute
of cache tag, 113
of fush tag, 114
secondary table, 173
security, 4783
ACC, 198, 214215
annotations, 49
application level, 49
Index
301
security (Continued)
audit modules, 5658
declarative, 49
disabling directory listings, 138
EJB components, 50
GlassFish Server features, 48
goals, 48
JACC, 56
Java EE model, 48
JMS, 284
message security, 6272
of containers, 4950
programmatic, 50
roles, 5051
server.policy fle, 5862
web applications, 50
security.confg property, 65
security manager, enabling and disabling, 6162
security map, 226227
server
installation, 2526
lib directory of, 30
life cycle events, 236
optimizing for development, 26
value-added features, 149153
Server Authentication Module, 7683
server.policy fle, 5862
and lifecycle modules, 238
changing permissions, 5961
default permissions, 58
ProgrammaticLoginPermission, 73
server-side includes, 144145
ServerLifecycleException, 236
service method, 110
Servlet container, authentication mechanisms, 7683
servlets, 105110
caching, 106109
character encoding, 136
destroying, 109
engine, 109
instantiating, 109
removing, 109
request handling, 109
servlets (Continued)
specifcation, 105
class loading, 137
mime-mapping, 138
object unsupported for failover, 117
session beans, 156
container for, 156157
EJB singletons, 163
optimizing performance, 163
transactions, 163
session cache sharing and @OrderBy, 100
session managers, 118121
session persistence
Coherence*Web, 121
for stateful session beans, 157162
for web modules, 116118
object types supported, 117118, 158159
set command
allow-non-component-callers option, 262
associate-with-thread option, 257
connection-validation-method option, 258
default message security provider, 63
default principal settings, 51
init-sql option, 252
is-connection-validation-required option, 258
is-isolation-level-guaranteed option, 267
java-web-start-enabled attribute, 203
non-transactional-connections option, 267
pooling option, 256
sql-trace-listeners option, 254
statement-cache-size option, 254
transaction-isolation-level option, 266
validation-classname option, 258
setCharacterEncoding method, 136
setContentType method, 136
setLocale method, 136
setTransactionIsolation method, 266
SHUTDOWN_EVENT, 236
signature.key.alias property, 65
signing client JARfles, 205207
signing JARfles at deployment, 206207
Simple Object Access Protocol, See SOAP messages
single sign-on, 7476
Index
singletons, EJB, 163
Sitraka web site, 4344
SMTP protocol, 289290
SOAP messages, 285287
SOAP with Attachments API for Java (SAAJ), 285
solaris realm, 52
specifcation
connectors, 223
EJB 2.1 and CMP, 171
EJB 2.1 and JDOQL queries, 187
JAAS, 53
Java Persistence, 91
JavaBeans, 110
JDBC, 251
JSP, 110
Liberty Alliance Project, 63
programmatic security, 50
security manager, 58
servlet, 105
class loading, 31
WSS, 63
splash screen, 216217
SSI, 144145
stack trace, generating, 39
STARTUP_EVENT, 236, 237
stateful session beans, 157
object references supported for failover, 158159
session persistence, 157162
stateless session beans, 156
sun-cmp-mappings.xml fle, 173
sun-ra.xml fle, 225
supportsTransactionIsolationLevel method, 266
Sybase
fnder limitation, 101102, 193
lock-when-loaded limitation, 192
T
tag libraries, 110111
tags for JSP caching, 111114
TERMINATION_EVENT, 236
thread associations, and connectors, 226
thread pools, for bean invocation scheduling, 152
timeout attribute, of cache tag, 113
tools, for developers, 2628
transaction-support property, 230
transactions, 265271
and EJB components, 268270
and non-component callers, 271
and non-persistent JMS messages, 270
and session beans, 163
and session persistence, 158, 161
commit options, 269
ConfgurableTransactionSupport
interface, 270271
fat, 269
global, 269
in the Java EE tutorial, 265
JDBCisolation levels, 266
local, 269
nested, 269
timeouts, 270
transaction manager, 271
transaction synchronization registry, 271
UserTransaction, 271
U
undeploy command
unwrap method, 261
URL rewriting, 115
URLFactory, 279
use-thread-pool-id element, 152
use-unique-table-names property, 181
utility classes, 3234, 34
V
valves, defning custom, 140
vendor-specifc, JNDI names, 279280
verbose mode, 40
version consistency, 184185
triggers, 193194
virtual server properties, 137
Index
303
W
web application class loader
changing delegation in, 31, 137
web applications, 105147, 239247
distributable, 116
security, 50
web container, logging and monitoring, 139
web services, 8589
creating portable artifacts, 86
debugging, 86, 87
deployment, 86
in the Java EE tutorial, 85
JBI, 8889
security
See message security
test page, 87
URL, 87
WSDL fle, 87
WebDav, 143144
work security map, 227
WSIT, 48
WSS, See message security
X
XML parser, specifying alternative, 33
Index

821 2418

Uploaded by

Copyright:

Available Formats

821 2418

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

821 2418

Uploaded by

Copyright:

Available Formats

Oracle GlassFishServer 3.

GlassFish Server Documentation Set on page 15

Related Documentation on page 17

Typographic Conventions on page 18

Symbol Conventions on page 19

Default Paths and File Names on page 19

Documentation, Support, and Training on page 20

Searching Oracle Product Documentation on page 20

Third-Party Web Site References on page 21

Your First Cup: An Introduction to the Java EE Platform(http://download.oracle.com/

The Java EE 6 Tutorial (http://download.oracle.com/javaee/6/tutorial/doc/). This

The API specifcation for version 6 of Java EE is located at http://download.oracle.com/

Installing and Preparing the Server for Development on page 25

High Availability Features on page 26

Development Tools on page 26

Sample Applications on page 28

GlassFish Server core

Java Platform, Standard Edition (Java SE) 6

Java EE 6 compliant application server

Other development and deployment tools

GlassFish Server Message Queue software

Java DB database, based on the Derby database fromApache (http://db.apache.org/

Load balancer plug-ins for web servers

Set up debugging. For more information, see Chapter 3, Debugging Applications.

The asadmin Command on page 27

The Administration Console on page 27

The Migration Tool on page 27

The NetBeans IDE on page 27

The Eclipse IDE on page 28

Debugging Tools on page 28

Profling Tools on page 28

The build.xml fle defnes Ant targets for the sample.

The Class Loader Hierarchy on page 30

Using the Java Optional Package Mechanism on page 31

Using the Endorsed Standards Override Mechanism on page 32

Class Loader Universes on page 32

Application-Specifc Class Loading on page 32

Circumventing Class Loader Isolation on page 34

Adirectory pointed to by the Libraries feld or ----libraries option used during

Adirectory pointed to by the library-directory element in the application.xml

Using the Common Class Loader on page 34

Sharing Libraries Across a Cluster on page 34

Packaging the Client JARfor One Application in Another Application on page 35

ToPackage the Client JARfor One Applicationin

Enabling Debugging on page 37

Generating a Stack Trace for Debugging on page 39

Application Client Debugging on page 39

GlassFish Server Message Queue Debugging on page 40

Enabling Verbose Mode on page 40

Class Loader Debugging on page 40

GlassFish Server Logging on page 41

Profling Tools on page 41

Java PlatformDebugger Architecture - The Java Debugger: http://java.sun.com/javase/

Java PlatformDebugger Architecture - Connecting with JDB: http://java.sun.com/

ToSet the Server toAutomatically Start UpinDebug

The NetBeans Profler on page 41

The HPROF Profler on page 42

The JProbe Profler on page 43

ToUse HPROF ProflingonUNIX