Sun GlassFish Enterprise Server
2.1 Administration Guide
Sun Microsystems, Inc.
4150 Network Circle
Santa Clara, CA 95054
U.S.A.
Part No: 820–4335–10
December 2008
Copyright 2008 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.
Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without
limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries.
U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions
of the FAR and its supplements.
This distribution may include materials developed by third parties.
Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other
countries, exclusively licensed through X/Open Company, Ltd.
Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coee Cup logo, docs.sun.com, Java, and Solaris are trademarks or registered trademarks of Sun
Microsystems, Inc. or its subsidiaries in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of
SPARC International, Inc. in the U.S. and other countries. Products bearing SPARCtrademarks are based upon an architecture developed by Sun Microsystems, Inc.
The OPEN LOOK and Sun
TM
Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering eorts
of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to
the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license
agreements.
Products covered by and information contained in this publication are controlled by U.S. Export Controllaws and may be subject to the export or import laws in
other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export
or reexport to countries subject to U.S. embargo or to entities identied on U.S. export exclusion lists, including, but not limited to, the denied persons and specially
designated nationals lists is strictly prohibited.
DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO
THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
Copyright 2008 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés.
Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier,
et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis
et dans d'autres pays.
Cette distribution peut comprendre des composants développés par des tierces personnes.
Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l'Université de Californie. UNIX est une marque déposée aux
Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd.
Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coee Cup, docs.sun.com, Java et Solaris sont des marques de fabrique ou des marques déposées de
Sun Microsystems, Inc., ou ses liales, aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou
des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture
développée par Sun Microsystems, Inc.
L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les eorts de
pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient
une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface
d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.
Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et
peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Lesutilisations nales, ou utilisateurs naux, pour des armes nucléaires,
des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou
réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités gurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière
non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui
sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spéciquement designés, sont rigoureusement interdites.
LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRESCONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES
SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PARLA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE
IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIEREOU A L'ABSENCE DE CONTREFACON.
090122@21808
Contents
Preface ...................................................................................................................................................19
1 Enterprise ServerOverview ...............................................................................................................23
Enterprise Server Overview and Concepts ....................................................................................... 23
Enterprise Server Overview ........................................................................................................23
Tools for Administration ............................................................................................................ 24
Enterprise Server Concepts ................................................................................................................ 26
Domain ......................................................................................................................................... 26
Domain Administration Server (DAS) ..................................................................................... 26
Usage Proles ............................................................................................................................... 27
Cluster ........................................................................................................................................... 28
Node Agent ................................................................................................................................... 28
Server Instance ............................................................................................................................. 29
Basic Enterprise Server Commands .................................................................................................. 31
Creating a Domain ....................................................................................................................... 31
Deleting a Domain ....................................................................................................................... 32
Listing Domains ........................................................................................................................... 32
Starting the Domain .................................................................................................................... 32
Starting the Default Domain on Windows ............................................................................... 33
Stopping the Domain .................................................................................................................. 33
Stopping the Default Domain on Windows ............................................................................. 33
Restarting the Domain ................................................................................................................ 33
Creating a Cluster ........................................................................................................................ 33
Starting a Cluster .......................................................................................................................... 34
Stopping a Cluster ........................................................................................................................ 34
Creating a Node Agent ................................................................................................................ 34
Starting a Node Agent .................................................................................................................. 34
Stopping a Node Agent ................................................................................................................ 35
3
Starting an Instance ..................................................................................................................... 35
Stopping an Instance ................................................................................................................... 35
Restarting an Instance ................................................................................................................. 35
Recreating the Domain Administration Server ........................................................................ 36
2 Java Business Integration .................................................................................................................. 39
JBI Environment .................................................................................................................................. 39
JBI Components ........................................................................................................................... 39
Service Assemblies ....................................................................................................................... 41
Shared Libraries ........................................................................................................................... 42
JBI Descriptors ............................................................................................................................. 42
3 JDBC Resources ....................................................................................................................................43
JDBC Resources ................................................................................................................................... 43
JDBC Connection Pools ..................................................................................................................... 44
How JDBC Resources and Connection Pools Work Together ...................................................... 44
Setting Up Database Access ................................................................................................................ 45
Working with JDBC Connection Pools ............................................................................................ 46
Creating a JDBC Connection Pool ............................................................................................. 46
Editing a JDBC Connection Pool ............................................................................................... 48
Editing JDBC Connection Pool Advanced Attributes ............................................................. 50
Congurations for Specic JDBC Drivers ........................................................................................ 52
Java DB Type 4 Driver ................................................................................................................. 53
Sun GlassFish JDBC Driver for DB2 Databases ....................................................................... 54
Sun GlassFish JDBC Driver for Oracle 8.1.7 and 9.x Databases ............................................. 54
Sun GlassFish JDBC Driver for Microsoft SQL Server Databases ......................................... 55
Sun GlassFish JDBC Driver for Sybase Databases ................................................................... 55
IBM DB2 8.1 Type 2 Driver ........................................................................................................ 56
JConnect Type 4 Driver for Sybase ASE 12.5 Databases ......................................................... 56
MySQL Type 4 Driver .................................................................................................................. 57
Inet Oraxo JDBC Driver for Oracle 8.1.7 and 9.x Databases .................................................. 57
Inet Merlia JDBC Driver for Microsoft SQL Server Databases .............................................. 58
Inet Sybelux JDBC Driver for Sybase Databases ...................................................................... 59
Oracle Thin Type 4 Driver for Oracle 8.1.7 and 9.x Databases ............................................... 59
OCI Oracle Type 2 Driver for Oracle 8.1.7 and 9.x Databases ............................................... 60
Contents
Sun GlassFish Enterprise Server 2.1 Administration Guide • December20084
IBM Informix Type 4 Driver ...................................................................................................... 61
CloudScape 5.1 Type 4 Driver .................................................................................................... 61
4 Conguring Java Message Service Resources ................................................................................ 63
JMS Resources ...................................................................................................................................... 63
The Relationship Between JMS Resources and Connector Resources ......................................... 64
JMS Connection Factories .................................................................................................................. 65
JMS Destination Resources ................................................................................................................ 65
JMS Physical Destinations .................................................................................................................. 65
Conguring JMS Provider Properties ............................................................................................... 66
Accessing Remote Servers ........................................................................................................... 67
Foreign JMS Providers ........................................................................................................................ 67
Conguring the Generic Resource Adapter for JMS ............................................................... 67
Resource Adapter Properties ...................................................................................................... 68
ManagedConnectionFactory Properties .................................................................................. 71
Administered Object Resource Properties ................................................................................ 72
Activation Spec Properties .......................................................................................................... 72
5 Conguring JavaMail Resources .......................................................................................................75
Creating a JavaMail Session ................................................................................................................ 75
6 JNDI Resources .....................................................................................................................................77
Java EE Naming Services .................................................................................................................... 77
Naming References and Binding Information ................................................................................. 78
Using Custom Resources .................................................................................................................... 79
Using External JNDI Repositories and Resources ........................................................................... 79
7 Connector Resources ..........................................................................................................................81
An Overview of Connectors ............................................................................................................... 81
Managing Connector Connection Pools .......................................................................................... 82
▼ To Create a Connector Connection Pool .................................................................................. 82
▼ To Edit a Connector Connection Pool ...................................................................................... 83
▼ To Edit Connector Connection Pool Advanced Attributes .................................................... 85
▼ To Edit Connection Pool Properties .......................................................................................... 87
Contents
5
Managing Security Maps ............................................................................................................. 87
▼ To Delete a Connector Connection Pool .................................................................................. 87
▼ To Set Up EIS Access ................................................................................................................... 88
Managing Connector Resources ....................................................................................................... 88
▼ To Create a Connector Resource ............................................................................................... 88
▼ To Edit a Connector Resource .................................................................................................... 89
▼ To Delete a Connector Resource ................................................................................................ 89
▼ To Congure the Connector Service ......................................................................................... 90
Managing Administered Object Resources ...................................................................................... 90
▼ To Create an Administered Object Resource ........................................................................... 91
▼ To Edit an Administered Object Resource ............................................................................... 92
▼ To Delete an Administered Object Resource ........................................................................... 92
8 Weband EJB Containers .....................................................................................................................93
The SIP Servlet Container .................................................................................................................. 93
Editing the Properties of the SIP Container .............................................................................. 94
The Web Container ............................................................................................................................. 95
The EJB Container .............................................................................................................................. 95
9 Conguring Security ...........................................................................................................................97
Understanding Application and System Security ............................................................................ 97
Tools for Managing Security .............................................................................................................. 98
Managing Security of Passwords ....................................................................................................... 99
Encrypting a Password in the domain.xml File ........................................................................ 99
Protecting Files with Encoded Passwords ............................................................................... 100
Changing the Master Password ................................................................................................ 100
Working with the Master Password and Keystores ............................................................... 101
Changing the Admin Password ................................................................................................ 101
About Authentication and Authorization ...................................................................................... 102
Authenticating Entities ............................................................................................................. 102
Authorizing Users ...................................................................................................................... 103
Specifying JACC Providers ....................................................................................................... 103
Auditing Authentication and Authorization Decisions ........................................................ 103
Conguring Message Security .................................................................................................. 104
Understanding Users, Groups, Roles, and Realms ........................................................................ 104
Contents
Sun GlassFish Enterprise Server 2.1 Administration Guide • December20086
Users ............................................................................................................................................ 105
Groups ......................................................................................................................................... 105
Roles ............................................................................................................................................ 106
Realms ......................................................................................................................................... 106
Introduction to Certicates and SSL ............................................................................................... 108
About Digital Certicates ......................................................................................................... 108
About Secure Sockets Layer ...................................................................................................... 109
About Firewalls .................................................................................................................................. 111
About Certicate Files ....................................................................................................................... 111
Changing the Location of Certicate Files .............................................................................. 112
Using Java Secure Socket Extension (JSSE) Tools ......................................................................... 112
Using the keytool Utility ........................................................................................................... 112
Generating a Certicate Using the keytool Utility ............................................................... 114
Signing a Digital Certicate Using the keytool Utility ......................................................... 115
Deleting a Certicate Using the keytool Utility .................................................................... 115
Using Network Security Services (NSS) Tools ............................................................................... 116
Using the certutil Utility ....................................................................................................... 117
Importing and Exporting Certicates Using the pk12util Utility ...................................... 118
Adding and Deleting PKCS11 Modules using modutil ........................................................ 119
Using Hardware Crypto Accelerator With Enterprise Server ..................................................... 120
About Conguring Hardware Crypto Accelerators .............................................................. 120
Conguring PKCS#11 Tokens ................................................................................................. 121
Managing Keys And Certicates .............................................................................................. 122
Conguring J2SE 5.0 PKCS#11 Providers .............................................................................. 124
10 Conguring Message Security ........................................................................................................127
Overview of Message Security .......................................................................................................... 127
Understanding Message Security in the Enterprise Server .......................................................... 128
Assigning Message Security Responsibilities .......................................................................... 128
About Security Tokens and Security Mechanisms ................................................................. 129
Glossary of Message Security Terminology ............................................................................ 131
Securing a Web Service ..................................................................................................................... 132
Conguring Application-Specic Web Services Security ..................................................... 133
Securing the Sample Application ..................................................................................................... 133
Conguring the Enterprise Server for MessageSecurity .............................................................. 133
Contents
7
Actions of Request and Response Policy Congurations ...................................................... 134
Conguring Other Security Facilities ...................................................................................... 135
Conguring a JCE Provider ...................................................................................................... 135
Message Security Setup ..................................................................................................................... 137
Enabling Providers for Message Security ................................................................................ 137
Conguring the Message Security Provider ........................................................................... 138
Creating a Message Security Provider ..................................................................................... 139
Enabling Message Security for Application Clients ............................................................... 139
Setting the Request and Response Policy for the Application Client Conguration ......... 139
Further Information .................................................................................................................. 140
11 Conguring the Diagnostic Service ................................................................................................141
What is the Diagnostic Framework? ............................................................................................... 141
Diagnostic Service Framework ........................................................................................................ 141
Generating a Diagnostic Report ............................................................................................... 142
12 Transactions ...................................................................................................................................... 143
About Transactions ........................................................................................................................... 143
What is a Transaction? .............................................................................................................. 143
Transactions in Java EE Technology ....................................................................................... 144
Workarounds for Specic Databases ....................................................................................... 145
Admin Console Tasks for Transactions ......................................................................................... 145
Conguring Transactions ......................................................................................................... 145
13 Conguring the HTTP Service .........................................................................................................149
Virtual Servers ................................................................................................................................... 149
HTTP Listeners .................................................................................................................................. 150
14 Managing Web Services ...................................................................................................................153
Overview of Web Services ................................................................................................................ 153
Web Services Standards ............................................................................................................ 154
Java EE Web Service Standards ................................................................................................ 154
Deploying and Testing Web Services .............................................................................................. 155
Deploying Web Services ............................................................................................................ 155
Contents
Sun GlassFish Enterprise Server 2.1 Administration Guide • December20088
Viewing Deployed Web Services ............................................................................................. 156
Testing Web Services ................................................................................................................. 156
Web Services Security ................................................................................................................ 156
Using Web Services Registries ......................................................................................................... 156
Adding a Registry ....................................................................................................................... 157
Publishing a Web Service to a Registry .................................................................................... 157
Transforming Messages with XSLT Filters ..................................................................................... 158
Monitoring Web Services ................................................................................................................. 158
Viewing Web Service Statistics ................................................................................................. 159
Monitoring Web Service Messages .......................................................................................... 159
15 Conguring the Object Request Broker ........................................................................................161
An Overview of the Object Request Broker ................................................................................... 161
CORBA ........................................................................................................................................ 161
What is the ORB? ....................................................................................................................... 162
IIOP Listeners ............................................................................................................................. 162
Conguring the ORB ........................................................................................................................ 162
Managing IIOP Listeners .................................................................................................................. 162
16 Thread Pools .......................................................................................................................................163
Working with Thread Pools ............................................................................................................. 164
17 Conguring Logging .........................................................................................................................165
About Logging ................................................................................................................................... 165
Log Records ................................................................................................................................ 165
The Logger Namespace Hierarchy ........................................................................................... 166
Conguring Logging ......................................................................................................................... 168
Conguring General Logging Settings .................................................................................... 168
Conguring Log Levels ............................................................................................................. 168
Viewing Server Logs .................................................................................................................. 169
18 Monitoring Components and Services ..........................................................................................171
About Monitoring ............................................................................................................................. 171
Monitoring in the Enterprise Server ........................................................................................ 171
Contents
9
Overview of Monitoring ........................................................................................................... 172
About the Tree Structure of Monitorable Objects ................................................................. 172
About Statistics for Monitored Components and Services ................................................... 175
Enabling and Disabling Monitoring ............................................................................................... 191
Conguring Monitoring Levels Using the Admin Console ................................................. 192
▼ To Congure Monitoring Levels Using asadmin .................................................................. 192
Viewing Monitoring Data ................................................................................................................ 193
Viewing Monitoring Data in the Admin Console .................................................................. 193
Viewing Monitoring Data With the asadmin Tool ................................................................ 193
Using JConsole .................................................................................................................................. 209
Securing JConsole to Application Server Connection ........................................................... 210
Prerequisites for Connecting JConsole to Application Server ............................................. 211
▼ Connecting JConsole to Application Server ........................................................................... 211
▼ Connecting JConsole Securely to Application Server ........................................................... 212
19 Conguring Management Rules .....................................................................................................215
About Management Rules ................................................................................................................ 215
Conguring Management Rules ..................................................................................................... 216
20 JavaVirtual Machine and Advanced Settings .............................................................................. 219
Tuning the JVM Settings .................................................................................................................. 219
Conguring Advanced Settings ....................................................................................................... 220
A Automatically Restarting a Domain or Node Agent .................................................................... 221
Restarting Automatically on Solaris 10 ........................................................................................... 221
Restarting Automatically Using inittab on Solaris 9 and Linux Platforms ................................. 223
Restarting Automatically on the Microsoft Windows Platform .................................................. 223
Creating a Windows Service ..................................................................................................... 223
Preventing the Service From Shutting Down When a User Logs Out ................................. 225
Security for Automatic Restarts ....................................................................................................... 225
B Dotted Name Attributes for domain.xml ......................................................................................227
Top Level Elements ........................................................................................................................... 227
Elements Not Aliased ........................................................................................................................ 229
Contents
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200810
CTheasadmin Utility ............................................................................................................................231
The asadmin Utility ........................................................................................................................... 232
Common Options for Remote Commands ................................................................................... 234
The Multimode Command .............................................................................................................. 235
The Get, Set, and List Commands ................................................................................................... 236
Server Lifecycle Commands ............................................................................................................. 237
List and Status Commands ............................................................................................................... 238
Deployment Commands .................................................................................................................. 239
Version Commands .......................................................................................................................... 240
Message Queue Administration Commands ................................................................................. 240
Resource Management Commands ................................................................................................ 241
Conguration Commands ............................................................................................................... 243
HTTP and IIOP Listener Commands ..................................................................................... 243
Lifecycle and Audit Module Commands ................................................................................ 243
Proler and SSL Commands ..................................................................................................... 244
JVM Options and Virtual Server Commands ........................................................................ 244
Threadpool and Auth-Realm Commands .............................................................................. 245
Transaction and Timer Commands ........................................................................................ 245
Registry Commands .................................................................................................................. 246
User Management Commands ........................................................................................................ 246
Rules and Monitoring Commands .................................................................................................. 247
Database Commands ........................................................................................................................ 247
Diagnostic and Logging Commands .............................................................................................. 248
Web Service Commands .................................................................................................................. 248
Security Service Commands ............................................................................................................ 249
Password Commands ....................................................................................................................... 250
Verify Command ............................................................................................................................... 251
Custom MBean Commands ............................................................................................................ 251
Service Command ............................................................................................................................. 251
Property Command .......................................................................................................................... 252
Index ................................................................................................................................................... 253
Contents
11
12
Figures
FIGURE 1–1 Enterprise Server Instance ........................................................................................ 29
FIGURE 9–1 Role Mapping ........................................................................................................... 105
13
14
Tables
TABLE 1–1 Features Available for Each Prole .......................................................................... 27
TABLE 1–2 Enterprise Server Listeners that Use Ports ............................................................. 30
TABLE 6–1 JNDI Lookups and Their Associated References ................................................... 79
TABLE 9–1 Enterprise Server Authentication Methods .......................................................... 102
TABLE 10–1 Messageprotection policy to WS-Security SOAP message security operation
mapping ................................................................................................................... 134
TABLE 17–1 EnterpriseServer Logger Namespaces .................................................................. 166
TABLE 18–1 EJB Statistics .............................................................................................................176
TABLE 18–2 EJB Method Statistics .............................................................................................. 177
TABLE 18–3 EJB Session Store Statistics .....................................................................................177
TABLE 18–4 EJB PoolStatistics .................................................................................................... 179
TABLE 18–5 EJB Cache Statistics .................................................................................................179
TABLE 18–6 Timer Statistics ........................................................................................................ 180
TABLE 18–7 Web Container (Servlet) Statistics ........................................................................ 180
TABLE 18–8 Web Container (Web Module) Statistics .............................................................181
TABLE 18–9 HTTP Service Statistics (Developer Prole) ........................................................ 182
TABLE 18–10 JDBC Connection Pool Statistics ........................................................................... 183
TABLE 18–11 Connector Connection Pool Statistics .................................................................. 184
TABLE 18–12 Connector Work Management Statistics ............................................................. 185
TABLE 18–13 Connection Manager (in an ORB) Statistics ........................................................ 185
TABLE 18–14 Thread Pool Statistics .............................................................................................. 186
TABLE 18–15 Transaction Service Statistics .................................................................................186
TABLE 18–16 JVMStatistics ...........................................................................................................187
TABLE 18–17 JVM Statistics for Java SE- Class Loading ............................................................. 187
TABLE 18–18 JVM Statistics for Java SE- Compilation ............................................................... 188
TABLE 18–19 JVM Statistics for Java SE- GarbageCollection ................................................... 188
TABLE 18–20 JVM Statistics for Java SE- Memory ...................................................................... 188
TABLE 18–21 JVM Statistics for Java SE - Operating System ..................................................... 189
TABLE 18–22 JVM Statistics for Java SE -Runtime .....................................................................189
15
TABLE 18–23 JVM Statistics for Java SE - Thread Info ............................................................... 190
TABLE 18–24 JVM Statistics for Java SE -Threads ...................................................................... 191
TABLE 18–25 TopLevel ..................................................................................................................203
TABLE 18–26 Applications Level ...................................................................................................203
TABLE 18–27 Applications - Enterprise Applications and Standalone Modules ..................... 204
TABLE 18–28 HTTP-Service Level ................................................................................................ 207
TABLE 18–29 Thread-PoolsLevel .................................................................................................. 207
TABLE 18–30 ResourcesLevel ........................................................................................................ 208
TABLE 18–31 Transaction-ServiceLevel ...................................................................................... 208
TABLE 18–32 ORBLevel .................................................................................................................208
TABLE 18–33 JVMLevel .................................................................................................................209
TABLE C–1 Remote Commands Required Options ................................................................ 234
TABLE C–2 ServerLifecycle Commands ................................................................................... 237
TABLE C–3 List and Status Commands .....................................................................................238
TABLE C–4 DeploymentCommands ........................................................................................ 239
TABLE C–5 VersionCommands ................................................................................................240
TABLE C–6 Message Queue Commands ...................................................................................240
TABLE C–7 ResourceManagement Commands ...................................................................... 241
TABLE C–8 IIOPListener Commands ...................................................................................... 243
TABLE C–9 LifecycleModule Commands ................................................................................244
TABLE C–10 Proler and SSL Commands ..................................................................................244
TABLE C–11 JVM Options and Virtual Server Commands ......................................................245
TABLE C–12 Threadpool and Auth-Realm Commands ...........................................................245
TABLE C–13 TransactionCommands .........................................................................................246
TABLE C–14 TransactionCommands .........................................................................................246
TABLE C–15 User Management Commands ..............................................................................246
TABLE C–16 Rules and Monitoring Commands ........................................................................247
TABLE C–17 Database Commands .............................................................................................. 248
TABLE C–18 Diagnostic and LoggingCommands ....................................................................248
TABLE C–19 Web Service Commands ........................................................................................248
TABLE C–20 SecurityCommands ................................................................................................249
TABLE C–21 PasswordCommands .............................................................................................250
TABLE C–22 VerifyCommand ..................................................................................................... 251
TABLE C–23 Custom MBean Commands .................................................................................. 251
TABLE C–24 ServiceCommand ...................................................................................................251
TABLE C–25 PropertyCommand ................................................................................................252
Tables
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200816
Examples
EXAMPLE 18–1 ApplicationsNode Tree Structure .........................................................................173
EXAMPLE 18–2 HTTPService Schematic (DeveloperProle Version) ........................................173
EXAMPLE 18–3 HTTPService Schematic (Cluster and Enterprise Prole Version) ..................174
EXAMPLE 18–4 ResourcesSchematic ...............................................................................................174
EXAMPLE 18–5 Connector Service Schematic ................................................................................174
EXAMPLE 18–6 JMS Service Schematic ............................................................................................175
EXAMPLE 18–7 ORBSchematic ........................................................................................................ 175
EXAMPLE 18–8 Thread Pool Schematic ........................................................................................... 175
EXAMPLE C–1 Passwordlecontents .............................................................................................. 233
17
18
Preface
The Administration guide describes the administrative tasks of the Enterprise Server.
This preface contains information about and conventions for the entire Sun GlassFish
TM
Enterprise Server documentation set.
Sun GlassFish Enterprise Server Documentation Set
TABLE P–1 Books in the Enterprise Server Documentation Set
Book Title Description
Documentation Center Enterprise Server documentation topics organized by task and subject.
Release Notes Late-breaking information about the software and the documentation. Includes a
comprehensive, table-based summary of the supported hardware, operating system, Java
TM
Development Kit (JDKTM), and database drivers.
Quick Start Guide How to get started with the Enterprise Server product.
Installation Guide Installing the software and its components.
Application Deployment Guide Deployment of applications and application components to the Enterprise Server. Includes
information about deployment descriptors.
Developer’s Guide Creating and implementing Java Platform, Enterprise Edition (Java EE platform) applications
intended to run on the Enterprise Server that follow the open Java standards model for Java
EE components and APIs. Includes information about developer tools, security, debugging,
and creating lifecycle modules.
Java EE 5 Tutorial Using Java EE 5 platform technologies and APIs to develop Java EE applications.
Java WSIT Tutorial Developing web applications using the Web Service Interoperability Technologies (WSIT).
Describes how, when, and why to use the WSIT technologies and the features and options
that each technology supports.
Administration Guide System administration for the Enterprise Server, including conguration, monitoring,
security, resource management, and web services management.
19
TABLE P–1 Books in the Enterprise Server Documentation Set (Continued)
Book Title Description
High Availability Administration
Guide
Setting up clusters, working with node agents, and using load balancers.
Administration Reference Editing the Enterprise Server conguration le, domain.xml.
Performance Tuning Guide Tuning the Enterprise Server to improve performance.
Reference Manual Utility commands available with the Enterprise Server; written in man page style. Includes
the asadmin command line interface.
Default Paths and File Names
The following table describes the default paths and le names that are used in this book.
TABLE P–2 Default Paths and File Names
Placeholder Description Default Value
as-install Represents the base installation directory for
Enterprise Server.
SolarisTMand Linux installations, non-root user:
user’s-home-directory/SUNWappserver
Solaris and Linux installations, root user:
/opt/SUNWappserver
Windows, all installations:
SystemDrive:\Sun\AppServer
domain-root-dir Represents the directory containing all
domains.
All installations:
as-install/domains/
domain-dir Represents the directory for a domain.
In conguration les, you might see
domain-dir represented as follows:
${com.sun.aas.instanceRoot}
domain-root-dir/domain-dir
instance-dir Represents the directory for a server instance. domain-dir/instance-dir
samples-dir Represents the directory containing sample
applications.
as-install/samples
docs-dir Represents the directory containing
documentation.
as-install/docs
Preface
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200820
Typographic Conventions
The following table describes the typographic changes that are used in this book.
TABLE P–3 TypographicConventions
Typeface Meaning Example
AaBbCc123 The names of commands, les, and
directories, and onscreen computer
output
Edit your .login le.
Use ls -a to list all les.
machine_name% you have mail.
AaBbCc123 What you type, contrasted with onscreen
computer output
machine_name% su
Password:
AaBbCc123 A placeholder to be replaced with a real
name or value
The command to remove a le is rm lename.
AaBbCc123 Book titles, new terms, and terms to be
emphasized (note that some emphasized
items appear bold online)
Read Chapter 6 in the User's Guide.
A cache is a copy that is stored locally.
Do not save the le.
Symbol Conventions
The following table explains symbols that might be used in this book.
TABLE P–4 SymbolConventions
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 A key.
+ Joins consecutive multiple
keystrokes.
Ctrl+A+N Press the Control key, release it, and
then press the subsequent keys.
Preface
21
TABLE P–4 SymbolConventions (Continued)
Symbol Description Example Meaning
→ Indicates menu item
selection in a graphical user
interface.
File → New → Templates From the File menu, choose New.
From the New submenu, choose
Templates.
Documentation, Support, and Training
The Sun web site provides information about the following additional resources:
■
Documentation (http://www.sun.com/documentation/)
■
Support (http://www.sun.com/support/)
■
Training (http://www.sun.com/training/)
Third-Party Web Site References
Third-party URLs are referenced in this document and provide additional, related information.
Note – Sun is not responsible for the availability of third-party web sites mentioned in this
document. Sun does not endorse and is not responsible or liable for any content, advertising,
products, or other materials that are available on or through such sites or resources. Sun will not
be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by
or in connection with use of or reliance on any such content, goods, or services that are available
on or through such sites or resources.
Sun WelcomesYour Comments
Sun is interested in improving its documentation and welcomes your comments and
suggestions.
To share your comments, go to
http://docs.sun.com and click Feedback. In the online form,
provide the document title and part number. The part number is a seven-digit or nine-digit
number that can be found on the title page of the book or at the top of the document.
Preface
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200822
Enterprise Server Overview
Sun GlassFish Enterprise Server administration includes many tasks such as deploying
applications, creating and conguring domains, server instances and resources; controlling
(starting and stopping) domains and server instances, managing proles and clusters,
monitoring and managing performance, and diagnosing and troubleshooting problems.
Enterprise Server provides a Java EE compatible server for the development and deployment of
Java EE applications and JavaWeb Services. Key features include scalable transaction
management, container-managed persistence runtime, performant web services, clustering,
high availability, security, and integration capabilities.
Enterprise Server Overview and Concepts
This section contains the following topics:
■
“Enterprise Server Overview” on page 23
■
“Tools for Administration” on page 24
Enterprise Server Overview
You can congure and monitor Enterprise Server instances and clusters securely and remotely,
from a web-based central administration console. The command line interface (CLI) can be
used to script and automate processes. A stable JMX API is made available to programmatically
monitor the server, query conguration and change conguration data. Monitoring is
supported through JMX and SNMP interfaces. Monitoring level may be varied dynamically
from OFF to LOW and high, changing the amount of information that is collected.
You can congure and optimize Enterprise Server for a particular type of use by specifying the
appropriate prole when you create the application server domain.
1
CHAPTER 1
23
Enterprise Server includes the Metro web services stack (http://metro.dev.java.net). Metro
implements important WS-* standards and WS-I standardized interoperability proles in
order to assure interoperability between Java and .NET web services.
Enterprise Server includes the implementation of Java Business Integration (JBI) specications.
JBI is a Java standard for structuring business systems according to a Service-Oriented
Architecture (SOA).
Tools for Administration
The Enterprise Server provides the following administration tools and APIs:
■
“Admin Console” on page 24
■
“Command-line Interface (asadmin Utility)” on page 25
■
“JConsole” on page 25
Admin Console
The Admin Console is a browser-based tool that features an easy-to-navigate interface and
online help. The administration server (also called the Domain Administration Server or DAS)
must be running to use the Admin Console. To, launch the Administration Console, you must
know the administration server hostname and port number. When the Enterprise Server was
installed, you chose a port number for the server, or used the default port of 4848. You also
specied a user name and master password.
To start the Admin Console, in a web browser type:
http://hostname:port
For example:
http://kindness.sun.com:4848
If the Admin Console is running on the machine on which the Enterprise Server was installed,
specify localhost for the host name.
On Windows, start the Enterprise Server Admin Console from the Start menu.
The installation program creates the default administrative domain (named domain1) with the
default port number 4848, as well as an instance separate from the domain administration
server (DAS). After installation, additional administration domains can be created. Each
domain has its own domain administration server, which has a unique port number. When
specifying the URL for the Admin Console, be sure to use the port number for the domain to be
administered.
Enterprise Server Overview and Concepts
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200824
If your conguration includes remote server instances, create node agents to manage and
facilitate remote server instances. It is the responsibility of the node agent to create, start, stop,
and delete a server instance. Use the command line interface (CLI) commands to set up node
agents.
Command-line Interface (asadmin Utility)
The asadmin utility is a command-line interface for the Sun GlassFish Enterprise Server. Use
the asadmin utility and the commands associated with it to perform the same set of
administrative tasks oered by the Admin Console. The default installation root directory on
Solaris is /opt/SUNWappserver.
To start the asadmin utility, go to the as-install/bin directory and enter:
$ ./asadmin
To list the commands available within asadmin:
asadmin> help
It is also possible to issue an asadmin command at the shell’s command prompt:
$ asadmin help
To view a command’s syntax and examples, type help followed by the command name. For
example:
asadmin> help create-jdbc-resource
The asadmin help information for a given command displays the UNIX man page of the
command. These man pages are also available in HTML and PDF format in the
Sun GlassFish
Enterprise Server 2.1 Reference Manual
.
JConsole
JConsole is used to monitor the Sun GlassFish Enterprise Server. You can use either the
JConsole remote tab, or the advanced tab to connect to the Enterprise Server.
■
Remote Tab: identify the username, password, administration server host, and JMS port
number (8686 by default), and select Connect.
■
Advanced Tab: identify the JMXServiceURL as
service:jmx:rmi:///jndi/rmi://host:jms-port/jmxrmi and select Connect. The
JMXServerURL is printed in the server.log le as well as output in the command window of
the domain creation command.
Enterprise Server Overview and Concepts
Chapter 1 • EnterpriseServer Overview 25
Enterprise Server Concepts
The Enterprise Server consists of one or more domains. A domain is an administrative
boundary or context. Each domain has an administration server (also called Domain
Administration Server or DAS) associated with it and consists of zero or more standalone
instances and/or clusters. Each cluster has one or more homogeneous server instances. A server
instance is a single Java Virtual Machine (JVM) that runs the Application Server on a single
physical machine. Server instances (whether standalone or clustered) in a domain can run on
dierent physical hosts.
This section contains the following topics:
■
“Domain” on page 26
■
“Domain Administration Server (DAS)” on page 26
■
“Usage Proles” on page 27
■
“Cluster” on page 28
■
“Node Agent” on page 28
■
“Server Instance” on page 29
Domain
A domain is a group of instances that are administered together. However, an application server
instance can belong to just one domain. In addition to the administration boundary, a domain
provides the basic security structure whereby dierent administrators can administer specic
groups (domains) of application server instances. By grouping the server instances into separate
domains, dierent organizations and administrators can share a single Enterprise Server
installation. Each domain has its own conguration, log les, and application deployment areas
that are independent of other domains. If the conguration is changed for one domain, the
congurations of other domains are not aected.
The Sun GlassFish Enterprise Server installer creates the default administrative domain (named
domain1). It also creates an associated domain administration server (named server). You
must provide the administration server port number. The default administration server port is
4848. The installer also queries for the administration username and master password. After
installation, additional administration domains can be created.
Domain Administration Server (DAS)
Each domain has its own Domain Administration Server (DAS) with a unique port number.
The Admin Console communicates with a specic DAS to administer the associated domain.
Each Admin Console session allows you to congure and manage the specic domain.
The Domain Administration Server (DAS), is a specially-designated application server instance
that hosts the administrative applications. The DAS authenticates the administrator, accepts
requests from administration tools, and communicates with server instances in the domain to
Enterprise Server Concepts
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200826
carry out the requests. The DAS is sometimes referred to as the admin server or default server. It
is referred to as the default server because it is the only server instance that gets created on Sun
GlassFish Enterprise Server installation and can be used for deployments. The DAS is simply a
server instance with additional administration capabilities.
Each Admin Console session allows you to congure and manage a single domain. If you
created multiple domains, you must start an additional Admin Console session to manage the
other domains. When specifying the URL for the Admin Console, be sure to use the port
number of the DAS associated with the domain to be administered.
Usage Proles
Every administrative domain is associated with a usage prole, which identies the capabilities
of that domain. Enterprise Server provides the following proles:
■
Developer: Use this prole if you are running your domain in a development environment
and if your applications do not need the NSS keystore or clustering features, such as load
balancing, and session persistence.
■
Cluster: Use this prole if you need to create clusters but do not require the high-availability
database (HADB) or the NSS keystore.
■
Enterprise:: Use this prole if you need HADB and NSS. This prole is usable only if you
install HADB and NSS separately or if you install Enterprise Server as part of enterprise
oerings, such as Java Enterprise System (JES). For information on how you can use the
enterprise prole with Enterprise Server, see Using the Enterprise Prole
The domain provides a precongured runtime for the user applications. Usage proles
facilitates the distinction between the Application Server binaries and the runtime
conguration. Proles enable you to use the same installation of Enterprise Server to create
dierent domains with proles that suit specic needs. For example, a developer may want to
use the Enterprise Server to get to know the latest JavaEE specications. This developer does
not need stringent security settings. Another user who wants to deploy applications in a
production environment needs an inherently secure environment.
Table 1–1 lists the features available with each prole:
TABLE 1–1 Features Available for Each Prole
Feature Developer Prole Cluster Prole
Enterprise Prole (not
available with Sun GlassFish
Communications Server)
Security store JKS JKS NSS
Clustering/Standalone instances Notavailable Available Available
Enterprise Server Concepts
Chapter 1 • EnterpriseServer Overview 27
TABLE 1–1 Features Available for Each Prole (Continued)
Feature Developer Prole Cluster Prole
Enterprise Prole (not
available with Sun GlassFish
Communications Server)
Security Manager Disabled Enabled Enabled
HADB Not available Not available Available
Load balancing Not available Available Available
Node agents Not available Available Available
Cluster
A cluster is a named collection of server instances sharing the same set of applications,
resources, and conguration information. A server instance can belong to exactly one cluster. A
cluster facilitates server instance load-balancing through distribution of a load across multiple
machines. A cluster facilitates high availability through instance-level failover. From an
administrative perspective, a cluster represents a virtualized entity in which operations on a
cluster (e.g. deployment of an application) act on all instances that make up the cluster.
Horizontal scaling is achieved by adding Enterprise Server instances to a cluster, thereby
increasing the capacity of the system. It is possible to add Enterprise Server instances to a cluster
without disrupting service. The HTTP, RMI/IIOP, and JMS load balancing systems distribute
requests to healthy Enterprise Server instances in the cluster.
High Availability - Availability allows for failover protection of Enterprise Server instances in a
cluster. If one application server instance goes down, another Enterprise Server instance takes
over the sessions that were assigned to the unavailable server. Session information is stored
using the session replication feature or by using the high-availability database (HADB). HADB
supports the persistence of HTTP sessions and stateful session beans.
Node Agent
A lightweight agent (e.g. hosting a JMX runtime only) is required on each node in the domain
to facilitate remote lifecycle management of instances. Its primary purpose is to start, stop, and
create server instances as instructed by the DAS. The Node Agent also acts as a watchdog and
restarts failed processes. Like the DAS, the Node Agent should only be required for certain
administrative operations and should not be expected to be highly available. However, the Node
Agent is an “always on” component, and must be congured to be started by the native O/S
node bootstrap (e.g. Solaris/Linux inetd, or as a Windows service). A Node Agent is not
required for the DAS.
Enterprise Server Concepts
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200828
Server Instance
The server instance is a single Java EE compatible Java Virtual Machine hosting an Enterprise
Server on a single node. Each server instance has a unique name in the domain. A clustered
server instance is a member of a cluster and receives all of its applications, resources, and
conguration from its parent cluster; ensuring that all instances in the cluster are
homogeneous. An unclustered server instance does not belong to a cluster and as such has an
independent set of applications, resources, and conguration. The following gure shows an
application server instance in detail. The application server instance is a building block in the
clustering, load balancing, and session persistence features of the Enterprise Server.
The Sun GlassFish Enterprise Server creates one application server instance, called server,at
the time of installation. For many users, one application server instance meets their needs.
However, depending upon your environment, you might want to create one or more additional
application server instances. For example, in a development environment you can use dierent
application server instances to test dierent Enterprise Server congurations, or to compare
and test dierent application deployments. Because you can easily add or delete an application
server instance, you can use them to create temporary sandbox area for experimentation
purposes.
In addition, for each application server instance, you can also create virtual servers. Within a
single installed application server instance you can oer companies or individuals domain
FIGURE 1–1 Enterprise Server Instance
Enterprise Server Concepts
Chapter 1 • EnterpriseServer Overview 29
names, IP Addresses, and some administration capabilities. For the users, it is almost as if they
have their own web server, without the hardware and basic server maintenance. These virtual
servers do not span application server instances. For more information about virtual servers,
see
Chapter 13, “Conguring the HTTP Service.”
In operational deployments, for many purposes you can use virtual servers instead of multiple
application server instances. However, if virtual servers do not meet your needs, you can also
use multiple application server instances. On stopping, application server instance stops
accepting new connections, then waits for all outstanding connections to complete. If your
machine crashes or is taken oine, the server quits and any requests it was servicing may be
lost.
Ports in the Enterprise Server
The following table describes the port listeners of the Enterprise Server.
TABLE 1–2 Enterprise Server Listeners that Use Ports
Listener Default Port Number Description
Administrative
server
4848 A domain’s administrative server is accessed by the Admin Console and the asadmin utility.
For the Admin Console, specify the port number in the URL of the browser. When
executing an asadmin command remotely, specify the port number with the --port option.
HTTP 8080 The server listens for HTTP requests on a port. To access deployed Web applications and
services, clients connect to this port.
HTTPS 8181 Web applications congured for secure communications listen on a separate port.
IIOP 3700 Remote clients of enterprise beans (EJB components) access the beans through the IIOP
listener.
IIOP, SSL 3820 Another port is used by the IIOP listener congured for secure communications.
IIOP, SSL and
mutual
authentication
3920 Another port is used by the IIOP listener congured for mutual (client and server)
authentication.
SIP 5060 The server listens for SIP requests on a port.
SIPS 5061 SIP/converged applications congured for secure communications listen on a separate port.
JMX_ADMIN 8686
JMS 7676
Enterprise Server Concepts
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200830
Basic Enterprise Server Commands
Administration of the Enterprise Server includes tasks such as creation, conguration, control
and management of domains, clusters, node agents, and server instances. This section contains
the following topics:
■
“Creating a Domain” on page 31
■
“Deleting a Domain” on page 32
■
“Listing Domains” on page 32
■
“Starting the Domain” on page 32
■
“Starting the Default Domain on Windows” on page 33
■
“Stopping the Domain” on page 33
■
“Stopping the Default Domain on Windows” on page 33
■
“Restarting the Domain” on page 33
■
“Creating a Cluster” on page 33
■
“Starting a Cluster” on page 34
■
“Stopping a Cluster” on page 34
■
“Creating a Node Agent” on page 34
■
“Starting a Node Agent” on page 34
■
“Stopping a Node Agent” on page 35
■
“Starting an Instance” on page 35
■
“Stopping an Instance” on page 35
■
“Restarting an Instance” on page 35
■
“Recreating the Domain Administration Server” on page 36
Creating a Domain
Domains are created using the create-domain command. The following example command
creates a domain named mydomain. The administration server listens on port 5000 and the
administrative user name is admin. The command prompts for the administrative and master
passwords.
$ asadmin create-domain --adminport 5000 --adminuser admin mydomain
To start the Admin Console for mydomain domain, in a browser, enter the following URL:
http://hostname:5000
In Enterprise Server 9.1, every domain has a prole associated with it. For information on
proles, see
“Usage Proles” on page 27. You can choose the prole of a domain only during
creation. Use the --profile option with the create-domain command to specify a prole for
the domain. If you do not use the --profile option to explicitly specify a prole, the default
prole is associated with the domain. The AS_ADMIN_PROFILE variable in the asadminenv.conf
le denes the default prole.
Basic Enterprise ServerCommands
Chapter 1 • EnterpriseServer Overview 31
Caution – Do not create an enterprise domain unless you have HADB and the Network Security
Services (NSS) keystore. You will not be able to start an enterprise domain unless you have
HADB and NSS.
For the preceding create-domain example, the domain’s log les, conguration les, and
deployed applications now reside in the following directory:
domain-root-dir/mydomain
To create the domain’s directory in another location, specify the --domaindir option. For the
full syntax of the command, type asadmin help create-domain or the
create-domain(1).
Deleting a Domain
Domains are deleted using the asadmin delete-domain command. Only the operating system
user (or root) who can administer the domain can execute this command successfully. To delete
a domain named mydomain , for example, type the following command:
$ asadmin delete-domain mydomain
Listing Domains
The domains created on a machine can be found using the asadmin list-domains command.
To list the domains in the default domain-root-dir directory, type this command:
$ asadmin list-domains
To list domains that were created in other directories, specify the --domaindir option.
Starting the Domain
When starting a domain, the administration server and application server instance are started.
Once the application server instance is started it runs constantly, listening for and accepting
requests. Each domain must be started separately.
To start a domain, type the asadmin start-domain command and specify the domain name.
For example, to start the default domain (domain1), type the following:
$ asadmin start-domain --user admin domain1
If there is only one domain, omit the domain name. For the full command syntax, type asadmin
help start-domain. If the password data is omitted, you are prompted to supply it.
Basic Enterprise ServerCommands
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200832
Starting the Default Domain on Windows
From the Windows Start Menu, select Programs -> Sun Microsystems -> Enterprise Server ->
Start Admin Server.
Stopping the Domain
Stopping a domain shuts down its administration server and application server instance. When
stopping a domain, the server instance stops accepting new connections and then waits for all
outstanding connections to complete. This process takes a few seconds because the server
instance must complete its shutdown process. While the domain is stopped, the Admin Console
or most asadmin commands cannot be used.
To stop a domain, type the asadmin stop-domain command and specify the domain name. For
example, to stop the default domain (domain1), type the following:
$ asadmin stop-domain domain1
If there is only one domain, then the domain name is optional. For the full syntax, type asadmin
help stop-domain .
Consult the Admin Console online help to stop the domain through the Admin Console.
Stopping the Default Domain onWindows
From the Start menu select Programs -> Sun Microsystems -> Enterprise Server-> Stop Admin
Server.
Restarting the Domain
Restarting the server is the same as restarting the domain. To restart the domain or server, stop
and start the domain.
Creating a Cluster
A cluster is created using the create-cluster command. The following example creates a
cluster named mycluster. The administration server host is myhost, the server port is 1234, and
the administrative username is admin. The command prompts for the administrative
passwords.
$ asadmin create-cluster --host myhost --port 1234 --user admin mycluster
Basic Enterprise ServerCommands
Chapter 1 • EnterpriseServer Overview 33
For the full syntax, type asadmin help create-cluster.
Starting a Cluster
A cluster is started using the start-cluster command. The following example starts the
cluster named mycluster. The command prompts for the administrative passwords.
$ asadmin start-cluster --host myhost --port 1234 --user admin mycluster
For the full syntax, type asadmin help start-cluster.
Stopping a Cluster
A cluster is stopped using the stop-cluster command. The following example stops the cluster
named mycluster. The command prompts for the administrative passwords.
$ asadmin stop-cluster --host myhost --port 1234 --user admin mycluster
myhost is the administrative server host, 1234 is the administrative port, admin is the
administrative username.
For the full syntax, type asadmin help stop-cluster. When a cluster is stopped, all the server
instances in the cluster get stopped. A cluster without instances cannot be stopped.
Creating a Node Agent
A node agent is created using the create-node-agent command. The following example
creates node agent named mynodeagent. The administration server host is myhost, the
administration server port is 1234, and the administrative username is admin. The command
normally prompts for the administrative passwords; however, if the --savemasterpassword
option is not specied or false, the command does not prompt for the administrative
passwords.
$ asadmin create-node-agent --host myhost --port 1234 --user admin mynodeagent
For the full syntax, type asadmin help create-node-agent.
Starting a Node Agent
A node agent is started using the start-node-agent command and specifying the node agent
name. For example, to start the node agent mynodeagent , type the following:
$ asadmin start-node-agent --user admin mynodeagent
Basic Enterprise ServerCommands
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200834
For the full syntax, type asadmin help start-node-agent.
Stopping a Node Agent
A node agent is stopped using the stop-node-agent command and specifying the node agent
name. For example, to stop the node agent mynodeagent , type the following:
$ asadmin stop-node-agent mynodeagent
For the full syntax, type asadmin help stop-node-agent.
Starting an Instance
A server instance is started using the start-instance command. The following example starts
the server instance named myinstance. The command prompts for the administrative
passwords.
$ asadmin start-instance --host myhost --port 1234 --user admin myinstance
The administrative server host is myhost, the administrative port is 1234, the administrative
username is admin. The server instance myinstance can be clustered or standalone.
For the full syntax, type asadmin help start-instance.
Stopping an Instance
A server instance is started using the stop-instance command. The following example stops
the server instance named myinstance. The command prompts for the administrative
passwords.
$ asadmin stop-instance --host myhost --port 1234 --user admin myinstance
The administrative server host is myhost, the administrative port is 1234, the administrative
username is admin. The server instance myinstance can be clustered or standalone.
For the full syntax, type asadmin help stop-instance.
Restarting an Instance
To restart server instance, stop and start the instance.
Basic Enterprise ServerCommands
Chapter 1 • EnterpriseServer Overview 35
Recreating the Domain Administration Server
For mirroring purposes, and to provide a working copy of the Domain Administration Server
(DAS), you must have:
■
One machine (machine1) that contains the original DAS.
■
A second machine (machine2) that contains a cluster with server instances running
applications and catering to clients. The cluster is congured using the DAS on the rst
machine.
■
A third backup machine (machine3) where the DAS needs to be recreated in case the rst
machine crashes.
Note – You must maintain a backup of the DAS from the rst machine. Use asadmin
backup-domain to backup the current domain.
▼
To migrate the DAS
The following steps are required to migrate the Domain Administration Server from the rst
machine (machine1) to the third machine (machine3).
Install the application server on the third machine just as it is installed on the rst machine.
This is required so that the DAS can be properly restored on the third machine and there are no
path conicts.
a. Installthe application serveradministration package using the command-line (interactive)
mode.To activatethe interactive command-line mode, invokethe installation program
using the console option:
./bundle-lename -console
You must have root permission to install using the command-line interface.
b. Deselect the option to install default domain.
Restoration of backed up domains is only supported on two machines with same
architecture and exactly the same installation paths (use same as-install and
domain-root-dir on both machines).
Copy the backup ZIP le from the rst machine into the domain-root-dir on the third machine.
You can also FTP the le.
Execute asadmin restore-domain command to restore the ZIP le onto the third machine:
asadmin restore-domain --filename domain-root-dir/sjsas_backup_v00001.zip domain1
You can backup any domain. However, while recreating the domain, the domain name should
be same as the original.
1
2
3
Basic Enterprise ServerCommands
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200836
Change domain-root-dir/domain1/generated/tmp directory permissions on the third machine
to match the permissions of the same directoryon rst machine.
The default permissions of this directory are: ?drwx------? (or 700).
For example:
chmod 700 domain-root-dir/domain1/generated/tmp
The example above assumes you are backing up domain1. If you are backing up a domain by
another name, you should replace domain1 above with the name of the domain being backed
up.
Change the host values for the propertiesin the domain.xml le for the third machine:
Update the domain-root-dir/domain1/config/domain.xml on the third machine.
For example, search for machine1 and replace it with machine3. So, you can change:
<jmx-connector><property name=client-hostname value=machine1/>...
to:
<jmx-connector><property name=client-hostname value=machine3/>...
Change:
<jms-service... host=machine1.../>
to:
<jms-service... host=machine3.../>
Start the restored domain on machine3:
asadmin start-domain --user admin-user --password admin-password domain1
Change the DAS host values for properties under node agent on machine2.
Change agent.das.host property value in
as-install/nodeagents/nodeagent/agent/config/das.properties on machine2.
Restart the node agent on machine2.
Note – Start the cluster instances using the asadmin start-instance command to allow them
to synchronize with the restored domain.
4
5
6
7
8
9
10
11
Basic Enterprise ServerCommands
Chapter 1 • EnterpriseServer Overview 37
38
Java Business Integration
Java Business Integration (JBI) is an implementation of the JSR 208 specication
(http://www.jcp.org/en/jsr/detail?id=208)
for Java Business Integration, a standard
developed under the Java Community Process (JCP) as an approach to implementing a
service-oriented architecture (SOA).
JBI denes an environment for plug-in components that interact using a services model based
directly on Web Services Description Language (WSDL) 2.0. The plug-in components function
as service providers, service consumers, or both.
For detailed information on managing the key components of the JBI runtime environment and
their lifecycle states, see the Admin Console Online Help. For information about using the JBI
commands, see
Sun GlassFish Enterprise Server 2.1 Reference Manual.
JBI Environment
The key components of the JBI environment are covered in the following sections.
■
“JBI Components” on page 39
■
“Service Assemblies” on page 41
■
“Shared Libraries” on page 42
■
“JBI Descriptors” on page 42
JBI Components
Service Engines
Service Engines are components that provide local services (that is, services within the JBI
environment) and consume local or remote services.
2
CHAPTER 2
39
Binding Components
Binding Components are proxies for consumers or providers that are outside the JBI
environment. Binding components typically are based on a standard communications protocol,
such as FTP, JMS, or SMTP, or a call to an external service, such as SAP or WebSphere MQ.
JBI components have the following lifecyle states:
■
Started
■
Stopped
■
Shutdown
The JBI Runtime persists the life cycle states of JBI Components. When the server shuts down
and then restarts, JBI Components revert to their state at the time the Enterprise Server shut
down.
Note – The JBI runtime attempts to revert to the "desired" state of a JBI component. For
example, suppose you tried to start a JBI component but it did not start due to an error in the
component. If you restart the Enterprise Server, the JBI runtime attempts to start the
component again.
You can do the following operations on the JBI components. For detailed steps, log on to the
Admin Console, navigate to the JBI node, click Components and then click Online Help.
■
View JBI components by their specic lifestyle states.
■
Install JBI components.
■
Uninstall JBI components.
■
Manage the lifecycle states of the JBI Components.
■
View the general properties of a JBI Component.
■
View the conguration information for a JBI Component.
■
View the descriptor for a JBI Component.
■
Manage JBI Component Loggers.
JBI Component Loggers
Using the Admin Console, you can manage the log levels for JBI Components. Some JBI
Components provide several loggers while other components might not provide any. However,
there will always be a logger level displayed for the entire component. But the logger level
setting will only have an eect if a component implements its loggers based on the default name.
The provider of a JBI Component might provide additional documentation on specifying
logging levels.
JBI Environment
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200840
Note – The logging levels for JBI Components are often inherited from a parent logger such as
the JBI logger. To view and set parent logging levels, in the Admin Console, select Common
Tasks and then Application Server. Then, in the Enterprise Server panel, select Logging and
then Log Levels. Look for the drop-down list for the JBI module to view and set the parent JBI
logging level.
Service Assemblies
A Service Assembly is a collection of Service Units that provision target components that
together provide or consume specic services for an application. Service Assemblies are
typically created in a development tools environment, such as that provided by NetBeans
Enterprise Pack.
A Service Assembly has the following lifecyle states:
■
Started
■
Shutdown
■
Stopped
The JBI Runtime persists the lifecycle states of Service Assemblies. When the Enterprise Server
shuts down and then restarts, Service Assemblies revert to their state at the time the Enterprise
Server shut down.
Note – The JBI runtime attempts to revert to the "desired" state of a Service Assembly. For
example, suppose you tried to start a Service Assembly but it did not start due to an error in the
Service Assembly. If you restart the Application Server, the JBI runtime attempts to start the
Service Assembly again.
You can do the following operations on Service Assemblies. For detailed steps, log on to the
Admin Console, navigate to the JBI node, click Service Assemblies and then click Online Help.
■
View all the Service Assemblies, with support for sorting and for ltering by lifecycle state.
■
Deploy a Service Assembly.
■
Undeploy a Service Assembly.
■
Manage the lifecyle of a Service Assembly.
■
View the general properties of a Service Assembly.
■
View the descriptor for a Service Assembly.
JBI Environment
Chapter 2 • JavaBusiness Integration 41
Shared Libraries
A Shared Library provides Java classes that are not private to a single component and is typically
shared by more than one JBI Component. For example, the Java EE Service Engine requires the
WSDL Shared Library.
You can do the following operations on Shared Libraries. For detailed steps, log on to the
Admin Console, navigate to the JBI node, click Shared Libraries and then click Online Help.
■
View all Shared Libraries.
■
Install Shared Libraries.
■
View General Properties of a Shared Library.
■
View the descriptor for a Shared Library.
■
Uninstall a Shared Library.
JBI Descriptors
The descriptor le (jbi.xml) for Service Assemblies, JBI Components, and Shared Libraries
provides the following information:
■
Service Assemblies: Lists the Service Units contained in the Service Assembly and the target
for each Service Unit. Some Service Units may also show information on connection
endpoints.
■
JBI Components: Lists the type of the JBI Component (Binding Component or Service
Engine), a description of the component, information about relevant classpaths for the
component, and the name of any Shared Library upon which it depends.
■
Shared Libraries: Lists the name of the shared library, and the names of the archive les
(.jar les) or class le subdirectories it contains.
JBI Environment
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200842
JDBC Resources
This chapter explains how to congure JDBC resources, which are required by applications that
access databases. This chapter contains the following sections:
■
“JDBC Resources” on page 43
■
“JDBC Connection Pools” on page 44
■
“How JDBC Resources and Connection Pools Work Together” on page 44
■
“Setting Up Database Access” on page 45
■
“Working with JDBC Connection Pools” on page 46
■
“Congurations for Specic JDBC Drivers” on page 52
JDBC Resources
To store, organize, and retrieve data, most applications use relational databases. Java EE
applications access relational databases through the JDBC API.
A JDBC resource (data source) provides applications with a means of connecting to a database.
Typically, the administrator creates a JDBC resource for each database accessed by the
applications deployed in a domain. (However, more than one JDBC resource can be created for
a database.)
To create a JDBC resource, specify a unique JNDI name that identies the resource. (See the
section JNDI Names and Resources.) Expect to nd the JNDI name of a JDBC resource in
java:comp/env/jdbc subcontext. For example, the JNDI name for the resource of a payroll
database could be java:comp/env/jdbc/payrolldb. Because all resource JNDI names are in
the java:comp/env subcontext, when specifying the JNDI name of a JDBC resource in the
Admin Console, enter only jdbc/name. For example, for a payroll database specify
jdbc/payrolldb.
A JDBC resource (data source) provides applications with a means of connecting to a database.
Before creating a JDBC resource, rst create a JDBC connection pool.
3
CHAPTER 3
43
When creating a JDBC resource, you must identify:
1. The JNDI Name. By convention, the name begins with the jdbc/ string. For example:
jdbc/payrolldb. Don’t forget the forward slash.
2. Select a connection pool to be associated with the new JDBC resource.
3. Specify the settings for the resource.
4. Identify the targets (clusters and standalone server instance) on which the resource is
available.
JDBC Connection Pools
To create a JDBC resource, specify the connection pool with which it is associated. Multiple
JDBC resources can specify a single connection pool.
A JDBC connection pool is a group of reusable connections for a particular database. Because
creating each new physical connection is time consuming, the server maintains a pool of
available connections to increase performance. When an application requests a connection, it
obtains one from the pool. When an application closes a connection, the connection is returned
to the pool.
The properties of connection pools can vary with dierent database vendors. Some common
properties are the database’s name (URL), user name, and password.
See Also:
■
“JDBC Resources” on page 43
■
“How JDBC Resources and Connection Pools Work Together” on page 44
■
“Editing a JDBC Connection Pool” on page 48
How JDBC Resources and Connection PoolsWorkTogether
To store, organize, and retrieve data, most applications use relational databases. Java EE
applications access relational databases through the JDBC API. Before an application can access
a database, it must get a connection.
At runtime, here’s what happens when an application connects to a database:
1. The application gets the JDBC resource (data source) associated with the database by
making a call through the JNDI API.
Given the resource’s JNDI name, the naming and directory service locates the JDBC
resource. Each JDBC resource species a connection pool.
2. Via the JDBC resource, the application gets a database connection.
JDBC Connection Pools
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200844
Behind the scenes, the application server retrieves a physical connection from the
connection pool that corresponds to the database. The pool denes connection attributes
such as the database name (URL), user name, and password.
3. Now that it is connected to the database, the application can read, modify, and add data to
the database.
The applications access the database by making calls to the JDBC API. The JDBC driver
translates the application’sJDBC calls into the protocol of the database server.
4. When it is nished accessing the database, the application closes the connection.
The application server returns the connection to the connection pool. Once it’s back in the
pool, the connection is available for the next application.
Setting Up Database Access
To setup a database access:
1. Install a supported database product.
For a list of database products supported by the Enterprise Server, see the Release Notes.
2. Install a JDBC driver for the database product.
3. Make the driver’s JAR le accessible to the domain’s server instance.
4. Create the database.
Usually, the application provider delivers scripts for creating and populating the database.
5. Create a connection pool for the database.
6. Create a JDBC resource that points to the connection pool.
Now to integrate the JDBC driver into an administrative domain, do either of the following:
1. Make the driver accessible to the common class loader.
Copy the driver’s JAR and ZIP les into the domain-dir/lib directory or copy its class les
into the domain-dir/lib/ext directory.
2. Restart the domain.
3. Identify the fully-qualied path name for the driver's JAR le.
Setting Up Database Access
Chapter 3 • JDBCResources 45
Working with JDBC Connection Pools
A JDBC connection pool is a group of reusable connections for a particular database. When
creating the pool with the Admin Console, the Administrator is actually dening the aspects of
a connection to a specic database.
Before creating the pool, you must rst install and integrate the JDBC driver. When building
the Create Connection Pool pages, certain data specic to the JDBC driver and the database
vendor must be entered. Before proceeding, gather the following information:
■
Database vendor name
■
Resource type, such as javax.sql.DataSource (local transactions only)
javax.sql.XADataSource (global transactions)
■
Data source class name
■
Required properties, such as the database name (URL), user name, and password
Creating a JDBC Connection Pool
You can use the Admin Console for creating the JDBC connection pool.
▼
Creating a JDBC Connection Pool and JDBC Resource Using the Admin
Console
Copy the JDBC driver for database connectivity to as-install/domains/domain_name/lib/ext.
Alternatively, add the path to the JDBC driver to classpath-prefix and restartthe server.
In the Admin Console, click Create JDBC Connection Pool in the Common Tasks page.
Provide a name for the connection pool, select the resource type, select the database vendor.
Click Next.
The Admin Console lists the default pool settings and the properties of datasource class
provided by the vendor.
Click the Ping button to test the JDBC connection pool.
In the left-hand pane of the Admin Console, click Resources > JDBC Resources.
Click New.
In the New JDBC Resource page, provide the JNDI name for the resource and the JDBC
comnnection pool with which the JDBC resource needs to be associated.
1
2
3
4
5
6
7
8
Working with JDBC Connection Pools
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200846
Click OK.
▼
Creating a JDBC Connection Pool and JDBC Resource Using the CLI
Use the asadmin create-jdbc-connection-pool command to create a JDBC connection pool.
Sample command to create a JDBC connection pool:
asadmin create-jdbc-connection-pool --datasourceclassname
oracle.jdbc.pool.OracleDataSource --restype javax.sql.DataSource --property
user=dbuser:password=dbpassword:url="jdbc:oracle\:thin\:@localhost\:1521\:ORCL"
myjdbc_oracle-pool
Use the asadmin create-jdbc-resource command to create a JDBC resource assicated with
this connectionpool.
Sample command to create a JDBC resource:
asadmin create-jdbc-connection-pool --connectionpoolid myjdbc_oracle-pool
jdbc/oracle-resource
Test the connection settings are correct by pinging the connection pool using the asadmin
ping-connection-pool command.
asadmin ping-connection-pool myjdbc_oracle-pool
To edit JDBC connection pool properties, use the asadmin list, get, and set commands.
Sample list command to list a JDBC connection pool:
asadmin list myjdbc_oracle-pool
The sample output of this command:
domain.resources.jdbc-connection-pool.oracle-pool
Sample get command to list all properties of a JDBC connection pool:
asadmin list myjdbc_oracle-pool
Sample get command to get all properties of a JDBC connection pool:
asadmin get domain.resources.jdbc-connection-pool.myjdbc_oracle-pool
Sample get command to set a properties of a JDBC connection pool:
asadmin set
domain.resources.jdbc-connection-pool.myjdbc_oracle-pool.steady-pool-size=20
9
1
2
3
4
Working with JDBC Connection Pools
Chapter 3 • JDBCResources 47
Editing a JDBC Connection Pool
The Edit JDBC Connection Pool page provides the means to change all of the settings for an
existing pool except its name.
1. Change general settings.
The values of the general settings depend on the specic JDBC driver that is installed. These
settings are the names of classes or interfaces in the Javaprogramming language.
Parameter Description
DataSource Class Name The vendor-specic class name that implements the DataSource and/or
XADataSource APIs. This class is in the JDBC driver.
Resource Type Choices include javax.sql.DataSource (local transactions only),
javax.sql.XADataSource (global transactions), and
java.sql.ConnectionPoolDataSource (local transactions, possible
performance improvements).
2. Change pool settings.
A set of physical database connections reside in the pool. When an application requests a
connection, the connection is removed from the pool, and when the application releases the
connection, it is returned to the pool.
Parameter Description
Initial and Minimum Pool Size The minimum number of connections in the pool. This value also
determines the number of connections placed in the pool when the pool is
rst created.
Maximum Pool Size The maximum number of connections in the pool.
Pool Resize Quantity When the pool scales up and scales down towards the maximum and
minimum pool sizes respectively, it is resized in batches. This value
determines the number of connections in the batch. Making this value too
large delays connection creation and recycling; making it too small will be
less ecient.
Idle Timeout The maximum time in seconds that a connection can remain idle in the
pool. After this time expires, the connection is removed from the pool.
Max Wait Time The amount of time the application requesting a connection will wait before
getting a connection timeout. Because the default wait time is long, the
application might appear to hang indenitely.
3. Change connection validation settings.
Working with JDBC Connection Pools
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200848
Optionally, the application server can validate connections before they are passed to
applications. This validation allows the application server to automatically reestablish
database connections if the database becomes unavailable due to network failure or database
server crash. Validation of connections incurs additional overhead and slightly reduces
performance.
Parameter Description
Connection Validation Select the Required checkbox to enable connection validation.
Validation Method The application server can validate database connections in three ways:
auto-commit, metadata, and table.
auto-commit and metadata - The application server validates a connection
by calling the con.getAutoCommit() and con.getMetaData() methods.
Auto-commit validation makes use of two methods for validating the
connection.getAutoCommit() is used to retrieve the current state of
auto-commit and setAutoCommit() to change the state of auto-commit.
This allows actual contact with the database to take place.
getAutomCommit()might or might not contact the database, depending on
the implementation. Actual physical connection will be wrapped for
dierent purposes, such as a connection pool.
Note – Because many JDBC drivers cache the results of these calls, they do
not always provide reliable validations. Check with the driver vendor to
determine whether these calls are cached or not.
table - The application queries a database table that are specied. The table
must exist and be accessible, but it doesn't require any rows. Do not use an
existing table that has a large number of rows or a table that is already
frequently accessed.
Table Name If you selected table from the Validation Method combo box, then specify
the name of the database table here.
On Any Failure If you select the checkbox labelled Close All Connections, if a single
connection fails, then the application server closes all connections in the
pool and then reestablish them. If you do not select the checkbox, then
individual connections are reestablished only when they are used.
Allow Non Component Callers Click this check box if you want to enable the pool for use by
non-component callers such as Servlet Filters and Lifecycle modules.
4. Change transaction isolation settings.
Because a database is usually accessed by many users concurrently, one transaction might
update data while another attempts to read the same data. The isolation level of a
transaction denes the degree to which the data being updated is visible to other
transactions. For details on isolation levels, refer to the documentation of the database
vendor.
Working with JDBC Connection Pools
Chapter 3 • JDBCResources 49
Parameter Description
Non-transactional Connections Click the check box if you want Application Server to return all
non-transactional connections.
Transaction Isolation Makes it possible to select the transaction isolation level for the connections
of this pool. If left unspecied, the connections operate with default
isolation levels provided by the JDBC driver.
Guaranteed Isolation Level Only applicable if the isolation level has been specied. If you select the
Guaranteed checkbox, then all connections taken from the pool have the
same isolation level. For example, if the isolation level for the connection is
changed programmatically (with con.setTransactionIsolation) when
last used, this mechanism changes the status back to the specied isolation
level.
5. Change properties.
In the Additional Properties table, it is possible to specify properties, such as the database
name (URL), user name, and password. Because the properties vary with database vendor,
consult the vendor’sdocumentation for details.
Editing JDBC Connection Pool Advanced Attributes
To help diagnose connection leaks and improve ease-of–use, Application Server 9.1 provides
several new attributes to congure a connection pool at the time of its creation.
1. Open the Advanced tab and specify the following attributes.
Attribute Description
Name Name of the JDBC connection pool whose
properties you want to edit. You cannot change the
pool name, however.
Statement Timeout Time in seconds after which abnormally long
running queries will be terminated. Application
Server will set "QueryTimeout" on the statements
created. The default value of -1 implies that the
attribute is not enabled.
Wrap JDBC Objects When set to true, application will get wrapped jdbc
objects for Statement, PreparedStatement,
CallableStatement, ResultSet, DatabaseMetaData.
The default value is false.
2. Specify the Connection Settings as explained in the following table.
Working with JDBC Connection Pools
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200850
Attribute Description
Validate Atmost Once Amount of time, in seconds, after which a
connection is validated at most once. This will help
reduce the number of validation requests by a
connection. The default value 0 implies that
connection validation is not enabled.
Leak Timeout Amount of time, in seconds, to trace connection
leaks in a connection pool. The default value 0
means that connection leak tracing is disabled. If
connection leak tracing is enabled, you can get
statistics on the number of connection leaks in the
Monitoring Resources tab. To view this tab, go to
Application Server > Monitoring > Resources.
Leak Reclaim If this option is enabled, leaked connections will be
restored to the pool after leak connection tracing is
complete.
Creation Retry Attempts Number of attempts that will be made if there is a
failure in creating a new connection. The default
value of 0 implies that no attempts will be made to
create the connection again.
Retry Interval Specify the interval, in seconds, between two
attempts to create a connection. The default value is
10 seconds. This attribute is used only if the value of
Creation Retry Attempts is greater than 0.
Lazy Connection Enlistment Enable this option to enlist a resource to the
transaction only when it is actually used in a
method.
Lazy Association Connections are lazily associated when an operation
is performed on them. Also, they are disassociated
when the transaction is completed and a component
method ends, which helps reuse of the physical
connections. Default value is false.
Associate with Thread Enable this option to associate a connection with the
thread such that when the same thread is in need of
a connection, it can reuse the connection already
associated with that thread, thereby not incurring
the overhead of getting a connection from the pool.
Default value is false.
Working with JDBC Connection Pools
Chapter 3 • JDBCResources 51
Match Connections Use this option to switch on/o connection
matching for the pool. It can be set to false if the
administrator knows that the connections in the
pool will always be homogeneous and hence a
connection picked from the pool need not be
matched by the resource adapter. Default value is
false.
Max Connection Usage Specify the number of times a connection should be
reused by the pool. Once a connection is reused for
the specied number of times, it will be closed. This
is useful, for instance, to avoid statement-leaks. The
default value of 0 implies that no connections will be
reused.
Congurations for Specic JDBC Drivers
Enterprise Server is designed to support connectivity to any database management system with
a corresponding JDBC driver. The following JDBC driver and database combinations are
supported. These combinations have been tested with Enterprise Server and are found to be
Java EE compatible.
■
“Java DB Type 4 Driver” on page 53
■
“Sun GlassFish JDBC Driver for DB2 Databases” on page 54
■
“Sun GlassFish JDBC Driver for Oracle 8.1.7 and 9.x Databases” on page 54
■
“Sun GlassFish JDBC Driver for Microsoft SQL Server Databases” on page 55
■
“Sun GlassFish JDBC Driver for Sybase Databases” on page 55
■
“IBM DB2 8.1 Type 2 Driver” on page 56
■
“JConnect Type 4 Driver for Sybase ASE 12.5 Databases” on page 56
■
“MySQL Type 4 Driver ” on page 57
Other JDBC drivers can be used with Enterprise Server , but Java EE compliance tests have not
been completed with these drivers. Although Sun oers no product support for these drivers,
Sun oers limited support of the use of these drivers with Enterprise Server .
■
“Inet Oraxo JDBC Driver for Oracle 8.1.7 and 9.x Databases” on page 57
■
“Inet Merlia JDBC Driver for Microsoft SQL Server Databases” on page 58
■
“Inet Sybelux JDBC Driver for Sybase Databases” on page 59
■
“Oracle Thin Type 4 Driver for Oracle 8.1.7 and 9.x Databases” on page 59
■
“OCI Oracle Type 2 Driver for Oracle 8.1.7 and 9.x Databases” on page 60
■
“IBM Informix Type 4 Driver” on page 61
■
“CloudScape 5.1 Type 4 Driver” on page 61
For details about how to integrate a JDBC driver and how to use the Administration Console or
the command line interface to implement the conguration, see the
Sun GlassFish Enterprise
Server 2.1 Administration Guide.
Congurations for Specic JDBC Drivers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200852
Note – 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. For information about capture-schema, see
Sun GlassFish
Enterprise Server 2.1 Reference Manual
.
Java DBType 4 Driver
The Java DB JDBC driver is included with the Enterprise Server by default, except for the Solaris
bundled installation, which does not include Java DB. Therefore, unless you have the Solaris
bundled installation, you do not need to integrate this JDBC driver with the Enterprise Server.
The JAR le for the Java DB driver is derbyclient.jar.
Congure the connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Java DB
■
DataSource Classname: Specify one of the following:
org.apache.derby.jdbc.ClientDataSource
org.apache.derby.jdbc.ClientXADataSource
■
Properties:
■
user - Specify the database user.
This is only necessary if Java DB is congured to use authentication. JavaDB does not
use authentication by default. When the user is provided, it is the name of the schema
where the tables reside.
■
password - Specify the database password.
This is only necessary if Java DB is congured to use authentication.
■
databaseName - Specify the name of the database.
■
serverName - Specify the host name or IP address of the database server.
■
portNumber - Specify the port number of the database server if it is dierent from the
default.
■
URL: jdbc:javadb://serverName:portNumber/databaseName;create=true
Include the ;create=true part only if you want the database to be created if it does not exist.
Congurations for Specic JDBC Drivers
Chapter 3 • JDBCResources 53
Sun GlassFish JDBC Driver for DB2 Databases
The JAR les for this driver are smbase.jar, smdb2.jar, and smutil.jar. Congure the
connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: DB2
■
DataSource Classname: com.sun.sql.jdbcx.db2.DB2DataSource
■
Properties:
■
serverName - Specify the host name or IP address of the database server.
■
portNumber - Specify the port number of the database server.
■
databaseName - Set as appropriate.
■
user - Set as appropriate.
■
password - Set as appropriate.
■
URL: jdbc:sun:db2://serverName:portNumber;databaseName=databaseName
Sun GlassFish JDBC Driver for Oracle 8.1.7 and 9.x
Databases
The JAR les for this driver are smbase.jar, smoracle.jar, and smutil.jar. Congure the
connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Oracle
■
DataSource Classname: com.sun.sql.jdbcx.oracle.OracleDataSource
■
Properties:
■
serverName - Specify the host name or IP address of the database server.
■
portNumber - Specify the port number of the database server.
■
SID - Set as appropriate.
■
user - Set as appropriate.
■
password - Set as appropriate.
■
URL: jdbc:sun:oracle://serverName[:portNumber][;SID=databaseName]
Congurations for Specic JDBC Drivers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200854
Sun GlassFish JDBC Driver for Microsoft SQL Server
Databases
The JAR les for this driver are smbase.jar, smsqlserver.jar, and smutil.jar. Congure the
connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: mssql
■
DataSource Classname: com.sun.sql.jdbcx.sqlserver.SQLServerDataSource
■
Properties:
■
serverName - Specify the host name or IP address and the port of the database server.
■
portNumber - Specify the port number of the database server.
■
user - Set as appropriate.
■
password - Set as appropriate.
■
selectMethod - Set to cursor.
■
URL: jdbc:sun:sqlserver://serverName[:portNumber]
Sun GlassFish JDBC Driver for Sybase Databases
The JAR les for this driver are smbase.jar, smsybase.jar, and smutil.jar. Congure the
connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Sybase
■
DataSource Classname: com.sun.sql.jdbcx.sybase.SybaseDataSource
■
Properties:
■
serverName - Specify the host name or IP address of the database server.
■
portNumber - Specify the port number of the database server.
■
databaseName - Set as appropriate. This is optional.
■
user - Set as appropriate.
■
password - Set as appropriate.
■
URL: jdbc:sun:sybase://serverName[:portNumber]
Congurations for Specic JDBC Drivers
Chapter 3 • JDBCResources 55
IBM DB2 8.1Type 2 Driver
The JAR les for the DB2 driver are db2jcc.jar, db2jcc_license_cu.jar, and db2java.zip.
Set environment variables as follows:
LD_LIBRARY_PATH=/usr/db2user/sqllib/lib:${Java EE.home}/lib
DB2DIR=/opt/IBM/db2/V8.1
DB2INSTANCE=db2user
INSTHOME=/usr/db2user
VWSPATH=/usr/db2user/sqllib
THREADS_FLAG=native
Congure the connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: DB2
■
DataSource Classname: com.ibm.db2.jcc.DB2SimpleDataSource
■
Properties:
■
user - Set as appropriate.
■
password - Set as appropriate.
■
databaseName - Set as appropriate.
■
driverType - Set to 2.
■
deferPrepares - Set to false.
JConnect Type 4 Driver for Sybase ASE 12.5 Databases
The JAR le for the Sybase driver is jconn2.jar. Congure the connection pool using the
following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Sybase
■
DataSource Classname:Specify one of the following:
com.sybase.jdbc2.jdbc.SybDataSource
com.sybase.jdbc2.jdbc.SybXADataSource
■
Properties:
■
serverName - Specify the host name or IP address of the database server.
■
portNumber - Specify the port number of the database server.
■
user - Set as appropriate.
Congurations for Specic JDBC Drivers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200856
■
password - Set as appropriate.
■
databaseName - Set as appropriate. Do not specify the complete URL, only the database
name.
■
BE_AS_JDBC_COMPLIANT_AS_POSSIBLE - Set to true.
■
FAKE_METADATA - Set to true.
MySQL Type 4 Driver
The JAR le for the MySQL driver is mysql-connector-java-version-bin-g.jar, for example,
mysql-connector-java-5.0.5-bin-g.jar. Congure the connection pool using the following
settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: mysql
■
DataSource Classname: Specify one of the following:
com.mysql.jdbc.jdbc2.optional.MysqlDataSource
■
Properties:
■
serverName - Specify the host name or IP address of the database server.
■
port - Specify the port number of the database server.
■
user - Set as appropriate.
■
password - Set as appropriate.
■
databaseName - Set as appropriate.
■
URL - If you are using global transactions, you can set this property instead of
serverName, port, and databaseName.
jdbc:mysql://host:port/database
Inet Oraxo JDBC Driver for Oracle 8.1.7 and 9.x
Databases
The JAR le for the Inet Oracle driver is Oranxo.jar. Congure the connection pool using the
following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Oracle
Congurations for Specic JDBC Drivers
Chapter 3 • JDBCResources 57
■
DataSource Classname: com.inet.ora.OraDataSource
■
Properties:
■
user - Specify the database user.
■
password - Specify the database password.
■
serviceName - Specify the URL of the database. The syntax is as follows:
jdbc:inetora:server:port:dbname
For example:
jdbc:inetora:localhost:1521:payrolldb
In this example,localhost is the host name of the machine running the Oracle server,
1521 is the Oracle server’sport number, and payrolldb is the SID of the database. For
more information about the syntax of the database URL, see the Oracle documentation.
■
serverName - Specify the host name or IP address of the database server.
■
port - Specify the port number of the database server.
■
streamstolob - If the size of BLOB or CLOB data types exceeds 4 KB and this driver is
used for CMP, this property must be set to true.
■
xa-driver-does-not-support-non-tx-operations - Set to the value true . Optional:
only needed if both non-XA and XA connections are retrieved from the same
connection pool. Might degrade performance.
As an alternative to setting this property, you can create two connection pools, one for
non-XA connections and one for XA connections.
Inet Merlia JDBC Driver for Microsoft SQL Server
Databases
The JAR le for the Inet Microsoft SQL Server driver is Merlia.jar. Congure the connection
pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: mssql
■
DataSource Classname: com.inet.tds.TdsDataSource
■
Properties:
■
serverName - Specify the host name or IP address and the port of the database server.
■
port - Specify the port number of the database server.
■
user - Set as appropriate.
Congurations for Specic JDBC Drivers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200858
■
password - Set as appropriate.
Inet Sybelux JDBC Driver for Sybase Databases
The JAR le for the Inet Sybase driver is Sybelux.jar. Congure the connection pool using the
following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Sybase
■
DataSource Classname: com.inet.syb.SybDataSource
■
Properties:
■
serverName - Specify the host name or IP address of the database server.
■
portNumber - Specify the port number of the database server.
■
user - Set as appropriate.
■
password - Set as appropriate.
■
databaseName - Set as appropriate. Do not specify the complete URL, only the database
name.
OracleThin Type 4 Driver for Oracle 8.1.7 and 9.x
Databases
The JAR le for the Oracle driver is ojdbc14.jar. Congure the connection pool using the
following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Oracle
■
DataSource Classname:Specify one of the following:
oracle.jdbc.pool.OracleDataSource
oracle.jdbc.xa.client.OracleXADataSource
■
Properties:
■
user - Set as appropriate.
■
password - Set as appropriate.
■
URL - Specify the complete database URL using the following syntax:
jdbc:oracle:thin:[user/password]@host[:port]/service
Congurations for Specic JDBC Drivers
Chapter 3 • JDBCResources 59
For example:
jdbc:oracle:thin:@localhost:1521:customer_db
■
xa-driver-does-not-support-non-tx-operations - Set to the value true . Optional:
only needed if both non-XA and XA connections are retrieved from the same
connection pool. Might degrade performance.
As an alternative to setting this property, you can create two connection pools, one for
non-XA connections and one for XA connections.
Note – You must set the oracle-xa-recovery-workaround property in the Transaction
Service for recovery of global transactions to work correctly. For details, see
“Workarounds
for Specic Databases” on page 145
.
When using this driver, it is not possible to insert more than 2000 bytes of data into a
column. To circumvent this problem, use the OCI driver (JDBC type 2).
OCI OracleType 2 Driver for Oracle 8.1.7 and 9.x
Databases
The JAR le for the OCI Oracle driver is ojdbc14.jar. Make sure that the shared library is
available through LD_LIBRARY_PATH and that the ORACLE_HOME property is set.
Congure the connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Oracle
■
DataSource Classname:Specify one of the following:
oracle.jdbc.pool.OracleDataSource
oracle.jdbc.xa.client.OracleXADataSource
■
Properties:
■
user - Set as appropriate.
■
password - Set as appropriate.
■
URL - Specify the complete database URL using the following syntax:
jdbc:oracle:oci:[user/password]@host[:port]/service
For example:
jdbc:oracle:oci:@localhost:1521:customer_db
Congurations for Specic JDBC Drivers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200860
■
xa-driver-does-not-support-non-tx-operations - Set to the value true . Optional:
only needed if both non-XA and XA connections are retrieved from the same
connection pool. Might degrade performance.
As an alternative to setting this property, you can create two connection pools, one for
non-XA connections and one for XA connections.
IBM InformixType 4 Driver
Congure the connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Informix
■
DataSource Classname:Specify one of the following:
com.informix.jdbcx.IfxDataSource
com.informix.jdbcx.IfxXADataSource
■
Properties:
■
serverName - Specify the Informix database server name.
■
portNumber - Specify the port number of the database server.
■
user - Set as appropriate.
■
password - Set as appropriate.
■
databaseName - Set as appropriate. This is optional.
■
IfxIFXHost - Specify the host name or IP address of the database server.
CloudScape 5.1 Type 4 Driver
The JAR les for the CloudScape driver are db2j.jar, db2jtools.jar, db2jcview.jar, jh.jar,
db2jcc.jar, and db2jnet.jar. Congure the connection pool using the following settings:
■
Name: Use this name when you congure the JDBC resource later.
■
Resource Type: Specify the appropriate value.
■
Database Vendor: Cloudscape
■
DataSource Classname: com.ibm.db2.jcc.DB2DataSource
■
Properties:
■
user - Set as appropriate.
■
password - Set as appropriate.
■
databaseName - Set as appropriate.
Congurations for Specic JDBC Drivers
Chapter 3 • JDBCResources 61
62
Conguring Java Message Service Resources
The Enterprise Server implements the Java Message Service (JMS) API by integrating the
Message Queue software into the Enterprise Server. For basic JMS API administration tasks, use
the Enterprise Server Admin Console. For advanced tasks, including administering a Message
Queue cluster, use the tools provided in the MQ-as-install/imq/bin directory. Fordetails about
administering Message Queue, see the Message Queue Administration Guide.
This chapter describes how to congure resources for applications that use the JavaMessage
Service (JMS) API. It contains the following sections:
JMS Resources
The Java Message Service (JMS) API uses two kinds of administered objects:
■
Connection factories, objects that allow an application to create other JMS objects
programmatically
■
Destinations, which serve as the repositories for messages
These objects are created administratively, and how they are created is specic to each
implementation of JMS. In the Enterprise Server, perform the following tasks:
■
Create a connection factory by creating a connection factory resource
■
Create a destination by creating two objects:
■
A physical destination
■
A destination resource that refers to the physical destination
JMS applications use the JNDI API to access the connection factory and destination resources.
A JMS application normally uses at least one connection factory and at least one destination. To
learn what resources to create, study the application or consult with the application developer.
There are three types of connection factories:
■
QueueConnectionFactory objects, used for point-to-point communication
4
CHAPTER 4
63
■
TopicConnectionFactory objects, used for publish-subscribe communication
■
ConnectionFactory objects, which can be used for both point-to-point and
publish-subscribe communications; these are recommended for new applications
There are two kinds of destinations:
■
Queue objects, used for point-to-point communication
■
Topic objects, used for publish-subscribe communication
The chapters on JMS in the Java EE 5 Tutorial provide details on these two types of
communication and other aspects of JMS (see
http://java.sun.com/javaee/5/docs/tutorial/doc/index.html).
The order in which the resources are created does not matter.
For a Java EE application, specify connection factory and destination resources in the
Enterprise Server deployment descriptors as follows:
■
Specify a connection factory JNDI name in a resource-ref or an
mdb-connection-factory element.
■
Specify a destination resource JNDI name in the ejb element for a message-driven bean and
in the message-destination element.
■
Specify a physical destination name in a message-destination-link element, within either
a message-driven element of an enterprise bean deployment descriptor or a
message-destination-ref element. In addition, specify it in the message-destination
element. (The message-destination-ref element replaces the resource-env-ref
element, which is deprecated in new applications.) In the message-destination element of
an Enterprise Server deployment descriptor, link the physical destination name with the
destination resource name.
The Relationship Between JMS Resources and Connector
Resources
The Enterprise Server implements JMS by using a system resource adapter named jmsra. When
a user creates JMS resources, the Enterprise Server automatically creates connector resources
that appear under the Connectors node in the Admin Console’s tree view.
For each JMS connection factory that a user creates, the Enterprise Server creates a connector
connection pool and connector resource. For each JMS destination a user creates, the
Enterprise Server creates an admin object resource. When the user deletes the JMS resources,
the Enterprise Server automatically deletes the connector resources.
It is possible to create connector resources for the JMS system resource adapter by using the
Connectors node of the Admin Console instead of the JMS Resources node. See
Chapter 7,
“Connector Resources,” for details.
The Relationship Between JMS Resources and Connector Resources
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200864
JMS Connection Factories
JMS connection factories are objects that allow an application to create other JMS objects
programmatically. These administered objects implement the ConnectionFactory,
QueueConnectionFactory, and TopicConnectionFactory interfaces. Using the Enterprise
Server Admin Console, you can create, edit, or delete a JMS Connection Factory. The creation
of a new JMS connection factory also creates a connector connection pool for the factory and a
connector resource.
To manage JMS connection factories using the command-line utility, use
create-jms-resource, list-jms-resources,ordelete-jms-resource command.
JMS Destination Resources
JMS destinations serve as the repositories for messages. Using the Admin Console, you can
create, modify or delete JMS Destination Resources. To create a new JMS Destination Resource,
select Resources >JMS Resources >Destination Resources. In the Destination Resources page,
you can specify the following:
■
JNDI Name for the resource. It is a recommended practice to use the naming subcontext
prex jms/ for JMS resources. For example: jms/Queue.
■
The resource type, which can be javax.jms. Topic or javax.jms.Queue.
■
Additional properties for the destination resource. For more details about all these settings
and the additional properties, refer to the Admin Console Online Help.
To manage JMS destinations using the command-line utility, use create-jms-resource,or
delete-jms-resource command.
Tip – To specify the addresslist property (in the format
host:mqport,host2:mqport,host3:mqport) for asadmin create-jms-resource command,
escape the : by using \\. For example, host1\\:mqport,host2\\:mqport,host3\\:mpqport.
For more information on using escape characters, see the asadmin(8) man page.
JMS Physical Destinations
For production purposes, always create physical destinations. During the development and
testing phase, however, this step is not required. The rst time that an application accesses a
destination resource, Message Queue automatically creates the physical destination specied by
the Name property of the destination resource. The physical destination is temporary and
expires after a period specied by a Message Queue conguration property.
JMS Physical Destinations
Chapter 4 • ConguringJavaMessage Service Resources 65
To create a physical destination from the Admin Console, select Conguration >Physical
Destinations. In the Create Physical Destinations page, specify a name for the physical
destination and choose the type of destination, which can be topic or queue. For more details
about the elds and properties in the Physical Destinations page, refer the Admin Console
Online Help.
For production purposes, always create physical destinations. During the development and
testing phase, however, this step is not required. The rst time an application accesses a
destination resource, Message Queue automatically creates the physical destination specied by
the Name property of the destination resource. The physical destination is temporary and
expires after a period specied by a Message Queue conguration property.
To manage JMS physical destinations using the command-line utility, use create-jmsdest,
flush-jmsdest,ordelete-jmsdest command.
Conguring JMS Provider Properties
Use the JMS Service page in the Admin Console to congure properties to be used by all JMS
connections. In the Admin Console, select Congurations >Java Message Service. In the JMS
Service page, you can control the following general JMS settings.
■
Select Startup Timeout interval, which indicates the time that Enterprise Server waits for the
JMS service to start before aborting the startup.
■
Select JMS Service type, which decides whether you manage a JMS Service on a local or a
remote host.
■
Specify Start Arguments to customize the JMS service startup.
■
Select Reconnect checkbox to specify whether the JMS service attempts to reconnect to a
message server (or the list of addresses in the AddressList ) when a connection is lost.
■
Specify Reconnect Interval in terms of number of seconds. This applies for attempts on each
address in the AddressList and for successive addresses in the list. If it is too short, this time
interval does not give a broker time to recover. If it is too long, the reconnect might
represent an unacceptable delay.
■
Specify the number of reconnect attempts. In the eld, type the number of attempts to
connect (or reconnect) for each address in the AddressList before the client runtime tries
the next address in the list.
■
Choose the default JMS host.
■
In the Address List Behavior drop-down list, choose whether connection attempts are in the
order of addresses in the AddressList (priority) or in a random order (random).
■
In the Address List Iterations eld, type the number of times the JMS service iterates
through the AddressList in an eort to establish (or reestablish) a connection.
Conguring JMS Provider Properties
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200866
■
In the MQ Scheme and MQ Service elds, type the Message Queue address scheme name
and the Message Queue connection service name if a non-default scheme or service is to be
used.
Values of all these properties can be updated at run time too. However, only those connection
factories that are created after the properties are updated, will get the updated values. The
existing connection factories will continue to have the original property values.
To manage JMS providers using the command-line utility, use the set or jms-ping commands.
Accessing Remote Servers
Changing the provider and host to a remote system causes all JMS applications to run on the
remote server. To use both the local server and one or more remote servers, create a connection
factory resource with the AddressList property to create connections that access remote servers.
Foreign JMS Providers
Generic Resource Adapter 1.5 for JMS is a Java EE Connector 1.5 resource adapter that can
wrap the JMS client library of external JMS providers such as IBM Websphere MQ, Tibco EMS,
and Sonic MQ among others, and thus integrate any JMS provider with a Java EE application
server. The adapter is a.rar archive that can be deployed and congured using a Enterprise
Server administration tools.
Conguring the Generic Resource Adapter for JMS
Enterprise Server's administration tools can be used to deploy and congure the generic
resource adapter for JMS. This section explains how to congure Generic Resource Adapter for
JMS with Enterprise Server.
Overall, the Resource Adapter can be congured to indicate whether the JMS provider supports
XA or not. It is also possible to indicate what mode of integration is possible with the JMS
provider. Two modes of integration are supported by the resource adapter. The rst one uses
JNDI as the means of integration. In this case, administered objects are set up in the JMS
provider's JNDI tree and will be looked up for use by the generic resource adapter. If that mode
is not suitable for integration, it is also possible to use the Javareection of JMS administered
object javabean classes as the mode of integration.
You can use the Admin Console or the command-line to congure the resource adapter. This is
not dierent from conguring any other resource adapter.
Foreign JMS Providers
Chapter 4 • ConguringJavaMessage Service Resources 67
Conguring the Generic Resource Adapter
Prior to deploying the resource adapter, JMS client libraries should be made available to the
Enterprise Server. For some JMS providers, client libraries may also include native libraries. In
such cases, these native libraries should also be made available to the JVM(s).
1. Deploy the generic resource adapter the same way you would deploy a connector module.
2. Create a connector connection pool.
3. Create a connector resource.
4. Create an administered object resource.
5. Make the following changes to the security policy in the Enterprise Server:
■
Modify sjsas_home/domains/domain1/config/server.policy to add
java.util.logging.LoggingPermission "control"
■
Modify sjsas_home/lib/appclient/client.policy to add permission
javax.security.auth.PrivateCredentialPermission
"javax.resource.spi.security.PasswordCredential ^ \"^\"","read":
Resource Adapter Properties
The following table presents the properties to be used while creating the resource adapter.
Property Name ValidValues DefaultValue Description
ProviderIntegration
Mode
javabean/jndi javabean Decides the mode of integration
between the resource adapter and the
JMS client.
ConnectionFactory
ClassName
Name of the class available
in the application server
classpath, for example:
com.sun.messaging.
ConnectionFactory
None Class name of
javax.jms.ConnectionFactory
implementation of the JMS client.
Used if ProviderIntegrationMode is
javabean.
QueueConnection
FactoryClassName
Name of the class available
in the application server
classpath, for example:
com.sun.messaging.
QueueConnectionFactory
None Class name of
javax.jms.QueueConnectionFactory
implementation of the JMS client.
Used if ProviderIntegrationMode is
javabean.
Foreign JMS Providers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200868
Property Name ValidValues DefaultValue Description
TopicConnectionFactory
ClassName
Name of the class available
in the application server
classpath , for example:
com.sun.messaging.
TopicConnectionFactory
None Class name of
javax.jms.TopicConnectionFactory
implementation of the JMS client.
Used if ProviderIntegrationMode is
specied as javabean.
XAConnectionFactory
ClassName
Name of the class available
in application server
classpath , for example:
com.sun.messaging.
XAConnectionFactory
None Class name of
javax.jms.ConnectionFactory
implementation of the JMS client.
Used if ProviderIntegrationMode is
specied as javabean.
XAQueueConnection
FactoryClassName
Name of the class available
in application server
classpath , for example:
com.sun.messaging.
XAQueueConnectionFactory
None Class name of javax.jms.
XAQueueConnectionFactory
implementation of the JMS client.
Used if ProviderIntegrationMode is
specied as javabean.
XATopicConnection
FactoryClassName
Name of the class available
in application server
classpath , for example:
com.sun.messaging.
XATopicConnectionFactory
None Class name of javax.jms.
XATopicConnectionFactory
implementation of the JMS client.
Used if ProviderIntegrationMode is
javabean.
TopicClassName Name of the class available
in application server
classpath , for example:
com.sun.messaging.Topic
None Class Name of javax.jms.Topic
implementation of the JMS client.
Used if ProviderIntegrationMode is
javabean.
QueueClassName Name of the class available
in application server
classpath , for example:
com.sun.messaging.Queue
None Class Name of javax.jms.Queue
implementation of the JMS client.
Used if ProviderIntegrationMode is
specied as a javabean.
SupportsXA True/false FALSE Species whether the JMS client
supports XA or not.
ConnectionFactory
Properties
Name value pairs separated
by comma
None Species the javabean property
names and values of the
ConnectionFactory of the JMS client.
Required only if
ProviderIntegrationMode is
javabean.
Foreign JMS Providers
Chapter 4 • ConguringJavaMessage Service Resources 69
Property Name ValidValues DefaultValue Description
JndiProperties Name value pairs separated
by comma
None Species the JNDI provider properties
to be used for connecting to the JMS
provider's JNDI. Used only if
ProviderIntegrationMode is jndi.
CommonSetter
MethodName
Method name None Species the common setter method
name that some JMS vendors use to
set the properties on their
administered objects. Used only if
ProviderIntegrationMode is
javabean. In the case of Sun Java
System Message Queue, this property
is named setProperty.
UserName Name of the JMS user None User name to connect to the JMS
Provider.
Password Password for the JMS user None Password to connect to the JMS
provider.
Foreign JMS Providers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200870
Property Name ValidValues DefaultValue Description
RMPolicy ProviderManaged or
OnePerPhysicalConnection
Provider
Managed
The isSameRM method on an
XAResource is used by the
Transaction Manager to determine if
the Resource Manager instance
represented by two XAResources are
the same. When RMPolicy is set to
ProviderManaged (the default value),
the JMS provider is responsible for
determining the RMPolicy and the
XAResource wrappers in the Generic
Resource Adapter merely delegate the
isSameRM call to the message queue
provider's XA resource
implementations. This should ideally
work for most message queue
products.
Some XAResource implementations
such as IBM MQ Series rely on a
resource manager per physical
connection and this causes issues
when there is inbound and outbound
communication to the same queue
manager in a single transaction (for
example, when an MDB sends a
response to a destination). When
RMPolicy is set to
OnePerPhysicalConnection, the
XAResource wrapper
implementation's isSameRM in
Generic Resource Adapter would
check if both the XAResources use the
same physical connection, before
delegating to the wrapped objects.
ManagedConnectionFactory Properties
ManagedConnectionFactory properties are specied when a connector-connection-pool is
created. All the properties specied while creating the resource adapter can be overridden in a
ManagedConnectionFactory. Additional properties available only in
ManagedConnectionFactory are given below.
Foreign JMS Providers
Chapter 4 • ConguringJavaMessage Service Resources 71
Property Name ValidValue Default Value Description
ClientId A valid client ID None ClientID as specied by JMS 1.1
specication.
ConnectionFactory
JndiName
JNDI Name None JNDI name of the connection factory
bound in the JNDI tree of the JMS
provider. The administrator should
provide all connection factory properties
(except clientID) in the JMS provider
itself. This property name will be used only
if ProviderIntegratinMode is jndi.
ConnectionValidation
Enabled
true/false FALSE If set to true, the resource adapter will use
an exception listener to catch any
connection exception and will send a
CONNECTION_ERROR_OCCURED event to
application server.
Administered Object Resource Properties
Properties in this section are specied when an administered object resource is created. All the
resource adapter properties can be overridden in an administered resource object. Additional
properties available only in the administered object resource are given below.
Property Name Valid Value Default Value Description
DestinationJndiName JNDI Name None JNDI name of the destination bound in
the JNDI tree of the JMS provider. The
Administrator should provide all
properties in the JMS provider itself.
This property name will be used only if
ProviderIntegrationMode is jndi.
DestinationProperties Name value pairs
separated by comma
None Species the javabean property names
and values of the destination of the JMS
client. Required only if
ProviderIntegrationMode is
javabean.
Activation Spec Properties
Properties in this section are specied in the Sun-specic deployment descriptor of MDB as
activation-config-properties. All the resource adapter properties can be overridden in an
Activation Spec. Additional properties available only in ActivationSpec are given below.
Foreign JMS Providers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200872
Property Name ValidValue Default Value Description
MaxPoolSize An integer 8 Maximum size of server session pool
internally created by the resource
adapter for achieving concurrent
message delivery. This should be equal
to the maximum pool size of MDB
objects.
MaxWaitTime An integer 3 The resource adapter will wait for the
time in seconds specied by this
property to obtain a server session
from its internal pool. If this limit is
exceeded, message delivery will fail.
Subscription
Durability
Durable or Non-Durable Non-Durable SubscriptionDurability as specied
by JMS 1.1 specication.
SubscriptionName None SubscriptionName as specied by
JMS 1.1 specication.
MessageSelector A valid message selector None MessageSelector as specied by JMS
1.1 specication.
ClientID A valid client ID None ClientID as specied by JMS 1.1
specication.
ConnectionFactory
JndiName
A valid JNDI Name None JNDI name of connection factory
created in JMS provider. This
connection factory will be used by
resource adapter to create a
connection to receive messages. Used
only if ProviderIntegrationMode is
congured as jndi.
DestinationJndiName A valid JNDI Name None JNDI name of destination created in
JMS provider. This destination will be
used by resource adapter to create a
connection to receive messages from.
Used only if
ProviderIntegrationMode is
congured as jndi.
DestinationType javax.jms.Queue or
javax.jms.Topic
Null Type of the destination the MDB will
listen to.
Destination
Properties
Name-value pairs separated
by comma
None Species the javabean property
names and values of the destination of
the JMS client. Required only if
ProviderIntegrationMode is
javabean.
Foreign JMS Providers
Chapter 4 • ConguringJavaMessage Service Resources 73
Property Name ValidValue Default Value Description
RedeliveryAttempts integer Number of times a message will be
delivered if a message causes a
runtime exception in the MDB.
RedeliveryInterval time in seconds Interval between repeated deliveries, if
a message causes a runtime exception
in the MDB.
SendBadMessages
ToDMD
true/false False Indicateswhether the resource
adapter should send the messages to a
dead message destination, if the
number of delivery attempts is
exceeded.
DeadMessage
Destination
JndiName
a valid JNDI name. None JNDI name of the destination created
in the JMS provider. This is the target
destination for dead messages. This is
used only if
ProviderIntegrationMode is jndi.
DeadMessage
Destination
ClassName
class name of destination
object.
None Used if ProviderIntegrationMode is
javabean.
DeadMessage
Destination
Properties
Name Value Pairs
separated by comma
None Species the javabean property
names and values of the destination of
the JMS client. This is required only if
ProviderIntegrationMode is
javabean.
ReconnectAttempts integer Numberof times a reconnect will be
attempted in case exception listener
catches an error on connection.
ReconnectInterval time in seconds Interval between reconnects.
Foreign JMS Providers
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200874
Conguring JavaMail Resources
The Enterprise Server includes the JavaMail API. The JavaMail API is a set of abstract APIs that
model a mail system. The API provides a platform-independent and protocol-independent
framework to build mail and messaging applications. The JavaMail API provides facilities for
reading and sending electronic messages. Service providers implement particular protocols.
Using the JavaMail API you can add email capabilities to your applications. JavaMail provides
access from Java applications to Internet Message Access Protocol (IMAP) and Simple Mail
Transfer Protocol (SMTP) capable mail servers on your network or the Internet. It does not
provide mail server functionality; you must have access to a mail server to use JavaMail.
The JavaMail API is implemented as a Java platform optional package and is also available as
part of the J2EE platform.
The Enterprise Server includes the JavaMail API along with JavaMail service providers that
allow an application component to send email notications over the Internet and to read email
from IMAP and POP3 mail servers.
To learn more about the JavaMail API, consult the JavaMail web site at
http://java.sun.com/products/javamail/.
This section contains the following topic:
Creating a JavaMail Session
To congure JavaMail for use in Enterprise Server, create a Mail Session in the Enterprise Server
Admin Console. This allows server-side components and applications to access JavaMail
services with JNDI, using the Session properties you assign for them. When creating a Mail
Session, you can designate the mail hosts, transport and store protocols, and the default mail
user in the Admin Console so that components that use JavaMail do not have to set these
properties. Applications that are heavy email users benet because the Application Server
creates a single Session object and makes it available via JNDI to any component that needs it.
5
CHAPTER 5
75
To create a JavaMail session using the Admin Console, select Resources —> JavaMail Sessions.
Specify the JavaMail settings as follows:
■
JNDI Name: The unique name for the mail session. Use the naming sub-context prex mail/
for JavaMail resources. For example: mail/MySession.
■
Mail Host: The host name of the default mail server. The connect methods of the Store and
Transport objects use this value if a protocol-specic host property is not supplied. The
name must be resolvable to an actual host name.
■
Default User: The user name to provide when connecting to a mail server. The connect
methods of the Store and Transport objects use this value if a protocol-specic username
property is not supplied.
■
Default Return Address: The email address of the default user, in the form:
username@host.domain.
■
Description: Provide a descriptive statement for the component.
■
Session: Deselect the Enabled checkbox if you do not want to enable the mail session at this
time.
Additionally, dene the following Advanced settings only if the mail provider has been
re-congured to use a non-default store or transport protocol:
■
Store Protocol: Denes the Store object communication method to be used. By default, the
Store Protocol is imap.
■
Store Protocol Class: Provides the Store communication method class that implements the
desired Store protocol. By default, the Store Protocol Class is
com.sun.mail.imap.IMAPStore.
■
Transport Protocol: Identies the transport communication method. By default, the
Transport Protocol is smtp.
■
Transport Protocol Class: Denes the communication method for the transport class. By
default, the Transport Protocol Class is com.sun.mail.smtp.SMTPTransport.
■
Debug: Select this checkbox to enable extra debugging output, including a protocol trace,
for this mail session. If the JavaMail log level is set to FINE or ner, the debugging output is
generated and is included in the system log le.
■
Additional Properties: Create properties required by applications, such as a
protocol-specic host or username property. Ensure that every property name you dene
start with a mail- prex. If the name of the property does not start withmail-, the property
is ignored.
Creating a JavaMail Session
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200876
JNDI Resources
The Java Naming and Directory Interface (JNDI) is an application programming interface
(API) for accessing dierent kinds of naming and directory services. Java EE components locate
objects by invoking the JNDI lookup method.
JNDI is the acronym for the Java Naming and Directory Interface API. By making calls to this
API, applications locate resources and other program objects. A resource is a program object
that provides connections to systems, such as database servers and messaging systems. (A JDBC
resource is sometimes referred to as a data source.) Each resource object is identied by a
unique, people-friendly name, called the JNDI name. A resource object and its JNDI name are
bound together by the naming and directory service, which is included with the Enterprise
Server. To create a new resource, a new name-object binding is entered into the JNDI.
This section covers the following topics:
■
“Java EE Naming Services” on page 77
■
“Naming References and Binding Information” on page 78
■
“Using Custom Resources” on page 79
■
“Using External JNDI Repositories and Resources” on page 79
Java EE Naming Services
A JNDI name is a people-friendly name for an object. These names are bound to their objects by
the naming and directory service that is provided by a JavaEE server. Because Java EE
components access this service through the JNDI API, the object usually uses its JNDI name.
When it starts up, the Enterprise Server reads information from the conguration le and
automatically adds JNDI database names to the name space.
Java EE application clients, enterprise beans, and web components are required to have access
to a JNDI naming environment.
The application component's naming environment is a mechanism that allows customization
of the application component's business logic during deployment or assembly. Use of the
6
CHAPTER 6
77
application component's environment allows the application component to be customized
without the need to access or change the application component's source code.
A Java EE container implements the application component's environment, and provides it to
the application component instance as a JNDI naming context. The application component's
environment is used as follows:
■
The application component's business methods access the environment using the JNDI
interfaces. The application component provider declares in the deployment descriptor all
the environment entries that the application component expects to be provided in its
environment at runtime.
■
The container provides an implementation of the JNDI naming context that stores the
application component environment. The container also provides the tools that allow the
deployer to create and manage the environment of each application component.
■
A deployer uses the tools provided by the container to initialize the environment entries that
are declared in the application component's deployment descriptor. The deployer sets and
modies the values of the environment entries.
■
The container makes the environment naming context available to the application
component instances at runtime. The application component's instances use the JNDI
interfaces to obtain the values of the environment entries.
Each application component denes its own set of environment entries. All instances of an
application component within the same container share the same environment entries.
Application component instances are not allowed to modify the environment at runtime.
Naming References and Binding Information
A resource reference is an element in a deployment descriptor that identies the component’s
coded name for the resource. More specically, the coded name references a connection factory
for the resource. In the example given in the following section, the resource reference name is
jdbc/SavingsAccountDB.
The JNDI name of a resource and the name of the resource reference are not the same. This
approach to naming requires that you map the two names before deployment, but it also
decouples components from resources. Because of this de-coupling, if at a later time the
component needs to access a dierent resource, the name does not need to change. This
exibility also makes it easier for you to assemble J2EE applications from preexisting
components.
The following table lists JNDI lookups and their associated references for the J2EE resources
used by the Enterprise Server.
Naming References and Binding Information
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200878
TABLE 6–1 JNDI Lookups and Their Associated References
JNDI Lookup Name Associated Reference
java:comp/env Application environment entries
java:comp/env/jdbc JDBC DataSource resource manager connection factories
java:comp/env/ejb EJB References
java:comp/UserTransaction UserTransaction references
java:comp/env/mail JavaMail Session Connection Factories
java:comp/env/url URL Connection Factories
java:comp/env/jms JMS Connection Factories and Destinations
java:comp/ORB ORB instance shared across application components
Using Custom Resources
A custom resource accesses a local JNDI repository and an external resource accesses an
external JNDI repository. Both types of resources need user-specied factory class elements,
JNDI name attributes, etc. In this section, we will discuss how to congure JNDI connection
factory resources, for J2EE resources, and how to access these resources.
Within the Enterprise Server, you can create, delete, and list resources, as well as
list-jndi-entities.
Using External JNDI Repositories and Resources
Often applications running on the Enterprise Server require access to resources stored in an
external JNDI repository. For example, generic Java objects could be stored in an LDAP server
as per the Java schema. External JNDI resource elements let users congure such external
resource repositories. The external JNDI factory must implement
javax.naming.spi.InitialContextFactory interface.
An example of the use of an external JNDI resource is:
<resources>
<!-- external-jndi-resource element specifies how to access J2EE resources
-- stored in an external JNDI repository. The following example
-- illustrates how to access a java object stored in LDAP.
-- factory-class element specifies the JNDI InitialContext factory that
-- needs to be used to access the resource factory. property element
-- corresponds to the environment applicable to the external JNDI context
Using External JNDI Repositories and Resources
Chapter 6 • JNDIResources 79
-- and jndi-lookup-name refers to the JNDI name to lookup to fetch the
-- designated (in this case the java) object.
-->
<external-jndi-resource jndi-name="test/myBean"
jndi-lookup-name="cn=myBean"
res-type="test.myBean"
factory-class="com.sun.jndi.ldap.LdapCtxFactory">
<property name="PROVIDER-URL" value="ldap://ldapserver:389/o=myObjects" />
<property name="SECURITY_AUTHENTICATION" value="simple" />
<property name="SECURITY_PRINCIPAL", value="cn=joeSmith, o=Engineering" />
<property name="SECURITY_CREDENTIALS" value="changeit" />
</external-jndi-resource>
</resources>
Using External JNDI Repositories and Resources
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200880
Connector Resources
This chapter explains how to congure connectors, which are used to access enterprise
information systems (EISs). This chapter contains the following sections:
■
“An Overview of Connectors” on page 81
■
“Managing Connector Connection Pools” on page 82
■
“Managing Connector Resources” on page 88
■
“Managing Administered Object Resources” on page 90
An Overview of Connectors
Also called a resource adapter, a connector module is a JavaEE component that enables
applications to interact with enterprise information systems (EISs). EIS software includes
various types of systems: enterprise resource planning (ERP), mainframe transaction
processing, and non-relational databases, among others. Like other Java EE modules, to install a
connector module you deploy it.
A connector connection pool is a group of reusable connections for a particular EIS. To create a
connector connection pool, specify the connector module (resource adapter) that is associated
with the pool.
A connector resource is a program object that provides an application with a connection to an
EIS. To create a connector resource, specify its JNDI name and its associated connection pool.
Multiple connector resources can specify a single connection pool. The application locates the
resource by looking up its JNDI name. (For more information on JNDI, see the section JNDI
Names and Resources.) The JNDI name of a connector resource for an EIS is usually in the
java:comp/env/eis-specic subcontext.
The Enterprise Server implements JMS by using a connector module (resource adapter). See the
section, The Relationship Between JMS Resources and Connector Resources.
7
CHAPTER 7
81
Managing Connector Connection Pools
■
“To Create a Connector Connection Pool” on page 82
■
“To Edit a Connector Connection Pool” on page 83
■
“To Edit Connector Connection Pool Advanced Attributes” on page 85
■
“To Edit Connection Pool Properties” on page 87
▼
To Create a Connector Connection Pool
Before creating the pool, deploy the connector module (resource adapter) associated with the
pool. The values that are specied for the new pool depend on the connector module that is
deployed.
In the tree component, expand the Resource node and then the Connectors node. Select the
Connector Connection Pools node. On the Connector Connection Pools page, click New.
On the rst Create Connector Connection Pool page, specify the following settings:
a. Inthe Name eld, enter a logical name for the pool.
Specify this name when creating a connector resource.
b. Select an entry from the Resource Adapter combo box.
The combo box displays a list of deployed resource adapters (connector modules).
Select a value from the Connection Denition combo box.
The choices in the combo box depend on the resource adapter you selected. The Connection
Denition attribute identies a resource adapter's connection-definition element in
thera.xml le.
Click Next.
On the next Create Connector Connection Pool page, performthese tasks:
a. Inthe General Settings section verify that the values are correct.
b. For the elds in the Pool Settings section, the default values can be retained.
These settings can be changed at a later time. See
“To Edit a Connector Connection Pool” on
page 83
.
BeforeYou Begin
1
2
3
4
5
Managing Connector Connection Pools
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200882
c. In the Additional Properties table, add any required properties.
In the previous Create Connector Connection Pool page, you selected a class in the
Connection Denition combo box. If this class is in the server’s classpath, then the
Additional Properties table displays default properties.
Click Finish.
Equivalent asadmin command
create-connector-connection-pool
▼
To Edit a Connector Connection Pool
In the tree component, expand the Resources node and then the Connectors node. Expand the
Connector Connection Pools node and selectthe connector connection pool you want to edit.
On the Edit Connector Connection Pool page, you can change the settings of this connection
pool. (Optional) Under General Settings, modify the description for the connection pool.
Under Pool Settings, you can specify the parameter values as explained in the following table.
Parameter Description
Initial and Minimum Pool Size The minimum number of connections in the pool.
This value also determines the number of connections
placed in the pool when the pool is rst created or
when application server starts.
Maximum Pool Size The maximum number of connections in the pool.
Pool Resize Quantity When the pool scales up and scales down towards the
maximum and minimum pool size respectively, it is
resized in batches. This value determines the number
of connections in the batch. Making this value too
large will delay connection creation and recycling;
making it too small will make it less ecient.
Idle Timeout The maximum time in seconds that a connection can
remain idle in the pool. After this time expires, the
connection is removed from the pool.
Max Wait Time The amount of time the application requesting a
connection will wait before getting a connection
timeout.
6
More Information
1
2
3
Managing Connector Connection Pools
Chapter 7 • ConnectorResources 83
On Any Failure If you select the checkbox labelled Close All
Connections, if a single connection fails, then the
application server will close all connections in the
pool and then reestablish them. If you do not select
the checkbox, then individual connections will be
reestablished only when they are used.
Transaction Support Use the Transaction Support list to select the type of
transaction support for the connection pool. The
chosen transaction support overrides the transaction
support attribute in the resource adapter associated
with this connection pool in a downward compatible
way. In other words, it can support a lower transaction
level than that specied in the resource adapter or the
same transaction level as that specied in resource
adapter, but it cannot specify a higher level. The
transaction support options include the following.
The None selection from the Transaction Support
menu indicates that the resource adapter does not
support resource manager local or JTA transactions
and does not implement XAResource or
LocalTransaction interfaces. For JAXR resource
adapters, you need to choose None from the
Transaction Support menu. JAXR resource adapters
do not support local or JTA transactions. Local
transaction support means that the resource adapter
supports local transactions by implementing the
LocalTransaction interface. Local transactions are
managed internal to a resource manager and involve
no external transaction managers. XA transaction
support means that the resource adapter supports
resource manager local and JTA transactions by
implementing the LocalTransaction and
XAResourceinterfaces. XA transactions are controlled
and coordinated by a transaction manager external to
a resource manager. Local transactions are managed
internal to a resource manager and involve no
external transaction managers.
Connection Validation Select the Required checkbox to enable connection
validation.
Click Save.
Click Load Defaults if you want to restore the default values of all the settings.
4
5
Managing Connector Connection Pools
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200884
Using the asadmin commands to change connection pool properties.
You can use the asadmin get and set commands to view and change the values of the
connection pool properties.
To list all the connector connection pools in the server:
asadmin list domain.resources.connector-connection-pool.*
To view the properties of the connector connection pool, you can use the following command:
asadmin get domain.resources.connector-connection-pool.conectionpoolname.*
To set a property of the connector connection pool, you can use the following command:
asadmin set
domain.resources.connector-connection-pool.conectionpoolname.pool-resize-quantity=3
▼
To Edit Connector Connection Pool Advanced
Attributes
Use the Advanced tab to edit the advanced attributes for a connector connectionpool.
Parameter Description
Validate Atmost Once Amount of time, in seconds, after which a connection is validated at most once.
This will help reduce the number of validation requests by a connection. The
default value 0 implies that connection validation is not enabled.
Leak Timeout Amount of time, in seconds, to trace connection leaks in a connection pool. The
default value 0 means that connection leak tracing is disabled. If connection leak
tracing is enabled, you can get statistics on the number of connection leaks in the
Monitoring Resources tab. To view this tab, go to Application Server > Monitoring
> Resources.
Leak Reclaim If this option is enabled, leaked connections will be restored to the pool after leak
connection tracing is complete.
Creation Retry Attempts Number of attempts that will be made if there is a failure in creating a new
connection. The default value of 0 implies that no attempts will be made to create
the connection again.
Retry Interval Specify the interval, in seconds, between two attempts to create a connection. The
default value is 10 seconds. This attribute is used only if the value of Creation
Retry Attempts is greater than 0.
More Information
1
Managing Connector Connection Pools
Chapter 7 • ConnectorResources 85
Lazy Association Connections are lazily associated when an operation is performed on them. Also,
they are disassociated when the transaction is completed and a component
method ends, which helps reuse of the physical connections. Default value is false.
Lazy Connection
Enlistment
Enable this option to enlist a resource to the transaction only when it is actually
used in a method.
Associate with Thread Enable this option to associate a connection with the thread such that when the
same thread is in need of a connection, it can reuse the connection already
associated with it, thereby not incurring the overhead of getting a connection from
the pool. Default value is false.
Match Connections Use this option to switch on/o connection matching for the pool. It can be set to
false if the administrator knows that the connections in the pool will always be
homogeneous and hence a connection picked from the pool need not be matched
by the resource adapter. Default value is false.
Max Connection Usage Specify the number of times a connection should be reused by the pool. Once a
connection is reused for the specied number of times, it will be closed. This is
useful, for instance, to avoid statement-leaks. The default value of 0 implies that
this attribute is not enabled.
Click Save for the changes to take eect.
Click Load Defaults if you want to restore the default values of all the settings.
Using the asadmin commands to change connection pool properties.
You can use the asadmin get and set commands to view and change the values of the
connection pool properties.
To list all the connector connection pools in the server:
asadmin list domain.resources.connector-connection-pool.*
To view the properties of the connector connection pool, you can use the following command:
asadmin get domain.resources.connector-connection-pool.conectionpoolname.*
To set a property of the connector connection pool, you can use the following command:
asadmin set
domain.resources.connector-connection-pool.conectionpoolname.validate-atmost-once-period-in-seconds=3
2
3
More Information
Managing Connector Connection Pools
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200886
▼
To Edit Connection Pool Properties
Use the Additional Properties tab to modify the properties of an existing pool.
The properties specied depend on the resource adapter used by this pool. The name-value
pairs specied by the deployer using this table can be used to override the default values for the
properties dened by the resource-adapter vendor.
Click Save for the changes to take eect.
Managing Security Maps
You can create, edit, and delete security maps associated with connector connection pools.
▼
To create security maps for connector connection pools
In the Edit Connector Connection Pool page, click the SecurityMaps tabbed pane.
Click New to create a new security map.
In the New Security Map page, provide a name for the securitymap, a user name, and password.
Click OK.
▼
To Edit Security Maps for Connector Connection Pools
In the Edit Connector Connection Pool page, click the SecurityMaps tabbed pane.
From the list of security maps, click the name of the security map that you want to edit.
Modify the values as desired, and click Save.
▼
To Delete a Connector Connection Pool
In the tree component, expand the Resources node and then the Connectors node.
Select the Connector Connection Pools node.
On the Connector Connection Pools page, select the checkbox for the pool to be deleted.
Click Delete.
1
2
1
2
3
4
1
2
3
1
2
3
4
Managing Connector Connection Pools
Chapter 7 • ConnectorResources 87
Equivalent asadmin command
delete-connector-connection-pool
▼
To Set Up EIS Access
Deploy (install) a connector.
Create a connection pool for the connector.
Create a connector resource that is associated with the connection pool.
Managing Connector Resources
■
“To Create a Connector Resource” on page 88
■
“To Edit a Connector Resource” on page 89
■
“To Delete a Connector Resource” on page 89
■
“To Congure the Connector Service” on page 90
▼
To Create a Connector Resource
A connector resource (data source) provides applications with a connection to an EIS.
Before creating a connector resource, rst create a connector connection pool.
In the tree component, expand the Resources node and then the Connectors node.
Expand the Connector Resources node.
On the Connector Resources page, click New.
On the Create Connector Resources page, specify the resource’s settings:
a. Inthe JNDI Name eld, type a unique name, for example: eis/myERP.
b. From the Pool Name combo box, choose the connection pool to which the new connector
resource belongs.
c. Tochange the resource to be unavailable, deselect the Status checkbox.
By default, the resource is available (enabled) when it is created.
More Information
1
2
3
BeforeYou Begin
1
2
3
4
Managing Connector Resources
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200888
d. Do one of the following:
■
If you are using the cluster prole, you will see the Targets section of the page. in the
Targets sectionof the page, select the domain, cluster,or server instances where the
connector resource will reside, from the Available eld and click Add. If you do not want
to deploy the connector resource to one of the domains, clusters, or server instances
listed in the Selected eld, select it from the eld and click Remove.
■
If you are running a domain with developer prole, skip to step 5.
Click OK.
Equivalent asadmin command
create-connector-resource
▼
To Edit a Connector Resource
In the tree component, expand the Resources node and then the Connectors node.
Expand the Connector Resources node.
Select the node for the connector resource that you want to edit. On the Edit Connector
Resources page, you can change the settings of this connection.
Do one of the following:
■
If you are using the cluster prole or enterprise prole, you will see the Targets tabbed pane.
On the Targets tabbed pane, you can enable or disable the connector resource on individual
targets.You can change the targets on which the connector resource is deployed by clicking
Manage Targets.
■
If you are using developer prole, skip to next step.
Click Save to apply the edits.
▼
To Delete a Connector Resource
In the tree component, expand the Resources node and then the Connectors node.
Select the Connector Resources node.
5
More Information
1
2
3
4
5
1
2
Managing Connector Resources
Chapter 7 • ConnectorResources 89
On the Connector Resources page, select the checkbox for the resource to be deleted.
Click Delete.
Equivalent asadmin command
delete-connector-resource
▼
To Congure the Connector Service
Use the Connector Service screen to congure the connector container for all resource adapters
deployed to this cluster or server instance.
Select Congurations from the tree.
If you are using the cluster prole, select the instance to congure:
■
To congure a particular instance, select the instance’s cong node. For example, for the
default instance, server, select the server-cong node.
■
To congure the default settings for future instances that use a copy of default-cong,select
the default-congnode.
Select the Connector Service node.
Specify the shutdown timeout in seconds in the Shutdown Timeout eld.
Enter an integer representing the number of seconds that the application server waits to allow
the ResourceAdapter.stop method of the connector module’s instance to complete. Resource
adapters that take longer than the specied shutdown timeout are ignored by the application
server and the shutdown procedure continues. The default shutdown timeout is 30 seconds.
Click Load Defaults to select the default shutdown timeout for the resource adapters deployed
to this cluster or server instance.
Managing Administered Object Resources
Packaged within a resource adapter (connector module), an administered object provides
specialized functionality for an application. For example, an administered object might provide
access to a parser that is specic to the resource adapter and its associated EIS. The object can be
administered; that is, it can be congured by an administrator. To congure the object, add
name-value property pairs in the Create or Edit Admin Object Resource pages. When creating
an administered object resource, associate the administered object to a JNDI name.
3
4
More Information
1
2
3
4
Managing Administered Object Resources
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200890
To create, edit, and delete Connector Connection Pools, click Resources —> Administered
Object Resources in the Admin Console. Consult the Admin Console Online Help for detailed
instructions on managing connector connection pools.
■
“To Create an Administered Object Resource” on page 91
■
“To Edit an Administered Object Resource” on page 92
■
“To Delete an Administered Object Resource” on page 92
▼
To Create an Administered Object Resource
Packaged within a resource adapter (connector module), an administered object provides
specialized functionality for an application. For example, an administered object might provide
access to a parser that is specic to the resource adapter and its associated EIS. The object can be
administered; that is, it can be congured by an administrator. To congure the object, add
name-value property pairs in the Create or Edit Admin Object Resource pages. When creating
an administered object resource, associate the administered object to a JNDI name.
The Enterprise Server implements JMS by using resource adapter. For each JMS destination
created, the Enterprise Server automatically creates an administered object resource.
In the tree component, expand the Resources node and then the Connectors node.
Expand the Admin Object Resources node.
On the Admin Object Resources page, click New.
On the Admin Object Resources page, specify the following settings:
a. Inthe JNDI Name eld, type a unique name that identies the resource.
b. In the Resource Type eld, enter the Java type for the resource.
c. From the Resource Adapter combo box, select the resource adapter that contains the
administered object.
d. Select or deselect the Status checkbox to enable or disable the resource.
e. To congure the administered objectwith name-value property pairs, click Add Property.
f. Ifyou are using cluster prole, in the Targets section of the page, select the domain, cluster,
or serverinstances where the administered object will reside, from the Available eld and
click Add.
To undeploy the administered object to one of the domains, clusters, or server instances
listed in the Selected eld, select it from the eld and click Remove.
1
2
3
4
Managing Administered Object Resources
Chapter 7 • ConnectorResources 91
g. Click Finish.
Equivalent asadmin command
create-admin-object
▼
To Edit an Administered Object Resource
In the tree component, expand the Resource node and then the Connectors node.
Expand the Administered Object Resources node.
Select the node for the administered object resource to be edited.
On the Edit Administered Object Resources page, modify values specied in Creating an
Administered Object Resource.
If you are using cluster prole, on the Targetstabbed pane, edit the targets on which the
administered object is deployed by clicking Manage Targets.
Click Save to apply the edits.
▼
To Delete an Administered Object Resource
In the tree component, expand the Resources node and then the Connectors node.
Select the Administered Object Resources node.
On the Administered Object Resources page, select the checkbox for the resource to be deleted.
Click Delete.
Equivalent asadmin command
delete-admin-object
More Information
1
2
3
4
5
6
1
2
3
4
More Information
Managing Administered Object Resources
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200892
Web and EJB Containers
Containers provide runtime support for application components. Application components use
the protocols and methods of the container to access other application components and services
provided by the server. The Enterprise Server provides an application client container, an
applet container, a Web container, and an EJB container. For a diagram that shows the
containers, see the section
“Enterprise Server Overview” on page 23.
This chapter describes the following containers:
■
“The SIP Servlet Container” on page 93
■
“The Web Container” on page 95
■
“The EJB Container” on page 95
The SIP Servlet Container
Enterprise Server provides the SIP Servlet container that hosts SIP-compliant applications.
Features of this container include the following:
■
Provides a network end point to listen to SIP requests.
■
Provides an environment to host and manage the lifecycle of SIP Servlets.
■
Decides what applications to host in which order.
■
Supports the Secure SIP protocol, SIPS over the transport layer protocol TLS.
■
Uses Grizzly NIO framework for server side socket listeners.
■
Implements Digest Authentication for security.
■
Supports Call Flow. Call Flow is the feature that allows application developers and
Application Server administrators to monitor the behavior of the deployed applications.
8
CHAPTER 8
93
Editing the Properties of the SIP Container
The sub-elements of the SIP container are session-managerand session-properties.
store-properties, manager-properties are sub-elements of session-manager.
For a complete list of SIP container properties, see TBDlink.
To change the properties of the SIP container using the Admin Console, select the
Conguration node, select the conguration name, and the SIP Container node. Use the
General, Session Timeout, SIP Container Manager, or SIP Container Store tabs to view and
change SIP container properties.
You can use the following CLI commands to list and view the sub-elements and attributes of the
SIP container.
To view the sub-elements of the SIP container, use the following command: list
server.sip-container.*
To view the attributes of the SIP container, use the following command: get
server.sip-container.*
Editing SIP ContainerGeneral Attributes
To view the attributes of the SIP container, use the following command: get
server.sip-container.*
■
External Address
■
SIP Port
■
Secure SIP Port
To get the attributes of the SIP container, use the get and set commands:
get server.sip-container.external-sip-port
set server.sip-container.external-sip-port=5060
Editing SIP ContainerSession Properties
To view the attributes of the SIP container session properties, use the following command: get
server.sip-container.session-config.session-properties.*
To set the attributes of the SIP container session properties, use the get and set commands:
get server.sip-container.session-config.session-properties.*
set
server.sip-container.session-config.session-properties.timeout-in-seconds=0
The SIP ServletContainer
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200894
Editing SIP ContainerSession Manager Properties
To view the sub-elements of the SIP container session manager properties, use the following
command: list server.sip-container.session-config.session-manager.*
The two sub-elements are store-properties, manager-properties.
To view the attributes of store-properties, use the following command: get
server.sip-container.session-config.session-manager.store-properties.*
To view the attributes of manager-properties, use the following command: get
server.sip-container.session-config.session-manager.manager-properties.*
To set the attributes of the SIP container session manager properties, use the get and set
commands:
get
server.sip-container.session-manager.manager-properties.reap-interval-in-seconds
set
server.sip-container.session-manager.manager-properties.reap-interval-in-seconds=2
For a complete list of SIP container properties, see the TBDlink,
TheWeb Container
The Web Container is a J2EE container that hosts web applications. The web container extends
the web server functionality by providing developers the environment to run servlets and
JavaServer Pages (JSP les).
The EJB Container
Enterprise beans (EJB components) are Java programming language server components that
contain business logic. The EJB container provides local and remote access to enterprise beans.
There are three types of enterprise beans: session beans, entity beans, and message-driven
beans. Session beans represent transient objects and processes and typically are used by a single
client. Entity beans represent persistent data, typically maintained in a database.
Message-driven beans are used to pass messages asynchronously to application modules and
services.
The container is responsible for creating the enterprise bean, binding the enterprise bean to the
naming service so other application components can access the enterprise bean, ensuring only
authorized clients have access to the enterprise bean’s methods, saving the bean’s state to
persistent storage, caching the state of the bean, and activating or passivating the bean when
necessary.
The EJB Container
Chapter 8 • Web and EJB Containers 95
96
Conguring Security
Security is about protecting data: how to prevent unauthorized access or damage to it in storage
or transit. The Enterprise Server; has a dynamic, extensible security architecture based on the
Java EE standard. Built in security features include cryptography, authentication and
authorization, and public key infrastructure. The Enterprise Server is built on the Javasecurity
model, which uses a sandbox where applications can run safely, without potential risk to
systems or users. The following topics are discussed:
■
“Understanding Application and System Security” on page 97
■
“Tools for Managing Security” on page 98
■
“Managing Security of Passwords” on page 99
■
“About Authentication and Authorization” on page 102
■
“Understanding Users, Groups, Roles, and Realms” on page 104
■
“Introduction to Certicates and SSL” on page 108
■
“About Firewalls” on page 111
■
“About Certicate Files” on page 111
■
“Using Java Secure Socket Extension (JSSE) Tools” on page 112
■
“Using Network Security Services (NSS) Tools” on page 116
■
“Using Hardware Crypto Accelerator With Enterprise Server” on page 120
Understanding Application and System Security
Broadly, there are two kinds of application security:
■
In programmatic security, application code written by the developer handles security chores.
As an administrator, you don't have any control over this mechanism. Generally,
programmatic security is discouraged since it hard-codes security congurations in the
application instead of managing it through the Java EE containers.
9
CHAPTER 9
97
■
In declarative security, the container (the Enterprise Server) handles security through an
application's deployment descriptors. You can control declarative security by editing
deployment descriptors directly or with a tool such as deploytool . Because deployment
descriptors can change after an application is developed, declarative security allows for
more exibility.
In addition to application security, there is also system security, which aects all the applications
on an Enterprise Server system.
Programmatic security is controlled by the application developer, so this document does not
discuss it; declarative security is somewhat less so, and this document touches on it
occasionally. This document is intended primarily for system administrators, and so focuses on
system security.
Tools for Managing Security
The Enterprise Server provides the following tools for managing security:
■
Admin Console, a browser-based tool used to congure security for the entire server, to
manage users, groups, and realms, and to perform other system-wide security tasks. For a
general introduction to the Admin Console, see
“Tools for Administration” on page 24.For
an overview of the security tasks consult the Admin Console online help.
■
asadmin, a command-line tool that performs many of the same tasks as the Admin Console.
You may be able to do some things with asadmin that you cannot do with Admin Console.
You perform asadmin commands from either a command prompt or from a script, to
automate repetitive tasks. For a general introduction to asadmin, see
“Tools for
Administration” on page 24
.
The Java Platform, Standard Edition (Java SE) provides two tools for managing security:
■
keytool, a command-line utility for managing digital certicates and key pairs. Use
keytool to manage users in the certificate realm.
■
policytool, a graphical utility for managing system-wide Java security policies. As an
administrator, you will rarely need to use policytool .
For more information on using keytool, policytool, and other Java security tools, see JDK
Tools and Utilities at
http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security.
In the Enterprise Prole, two other tools that implement Network Security Services (NSS) are
available for managing security. For more information on NSS, go to
http://www.mozilla.org/projects/security/pki/nss/. The tools for managing security
include the following:
■
certutil, a command-line utility for managing certicates and key databases.
■
pk12util, a command-line utility used to import and export keys and certicates between
the certicate/key databases and les in PKCS12 format.
ToolsforManaging Security
Sun GlassFish Enterprise Server 2.1 Administration Guide • December200898
For more information on using certutil, pk12util, and other NSS security tools, see NSS
Security Tools at
http://www.mozilla.org/projects/security/pki/nss/tools.
Managing Security of Passwords
In the Enterprise Server, the le domain.xml, which contains the specications for a particular
domain, initially contains the password of the Message Queue broker in clear text. The element
in the domain.xml le that contains this password is the admin-password attribute of the
jms-host element. Because this password is not changeable at installation time, it is not a
signicant security impact.
However, use the Admin Console to add users and resources and assign passwords to these
users and resources. Some of these passwords are written to the domain.xml le in clear text, for
example, passwords for accessing a database. Having these passwords in clear text in the
domain.xml le can present a security hazard. You can encrypt any password in domain.xml,
including the admin-password attribute or a database password. Instructions for managing the
security passwords is included in the following topics:
■
“Encrypting a Password in the domain.xml File” on page 99
■
“Protecting Files with Encoded Passwords” on page 100
■
“Changing the Master Password” on page 100
■
“Working with the Master Password and Keystores” on page 101
■
“Changing the Admin Password” on page 101
Encrypting a Password in the domain.xml File
To encrypt a password in the domain.xml le. Follow these steps:
1. From the directory where the domain.xml le resides (domain-dir/config by default), run
the following asadmin command:
asadmin create-password-alias --user admin alias-name
For example,
asadmin create-password-alias --user admin jms-password
A password prompt appears (admin in this case). Refer to the man pages for the
create-password-alias, list-password-aliases, delete-password-alias commands
for more information.
2. Remove and replace the password in domain.xml. This is accomplished using the asadmin
set command. An example of using the set command for this purpose is as follows:
asadmin set --user admin server.jms-service.jms-host.
default_JMS_host.admin-password=’${ALIAS=jms-password}’
Managing Security of Passwords
Chapter 9 • ConguringSecurity 99
Note – Enclose the alias password in single quotes as shown in the example.
3. Restart the Enterprise Server for the relevant domain.
Protecting Files with Encoded Passwords
Some les contain encoded passwords that need protecting using le system permissions. These
les include the following:
■
domain-dir/master-password
This le contains the encoded master password and should be protected with le system
permissions 600.
■
Any password le created to pass as an argument using the --passwordfile argument to
asadmin should be protected with le system permissions 600.
Changing the Master Password
The master password (MP) is an overall shared password. It is never used for authentication
and is never transmitted over the network. This password is the central point for overall
security; the user can choose to enter it manually when required, or obscure it in a le. It is the
most sensitive piece of data in the system. The user can force prompting for the master
password by removing this le. When the master password is changed, it is re-saved in the
master-password keystore, which is a Java JCEKS type keystore.
To change the master password, follow these steps:
1. Stop the Enterprise Server for the domain. Use the asadmin change-master-password
command, which prompts for the old and new passwords, then re-encrypts all dependent
items. For example:
asadmin change-master-password>
Please enter the master password>
Please enter the new master password>
Please enter the the new master password again>
2. Restart the Enterprise Server.
Managing Security of Passwords
Sun GlassFish Enterprise Server 2.1 Administration Guide • December2008100
Loading...