WebSphere Application Server Network Deployment, Version 6

򔻐򗗠򙳰

Administering applications and their environment

 Note
Before using this information, be sure to read the general information under “Notices” on page 2305.

Compilation date: January 20, 2005

© Copyright International Business Machines Corporation 2004. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
How to send your comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1. Overview and new features for administering applications and their environments .
. 1
Overview of administering applications and their environments . . . . . . . . . . . . . . .
. 2
Getting started with WebSphere Application Server . . . . . . . . . . . . . . . . . . .
. 3
Introduction: System administration . . . . . . . . . . . . . . . . . . . . . . . . .
. 3
Introduction: Administrative console . . . . . . . . . . . . . . . . . . . . . . . .
. 4
Introduction: Administrative scripting (wsadmin) . . . . . . . . . . . . . . . . . . . .
. 4
Introduction: Administrative commands . . . . . . . . . . . . . . . . . . . . . . .
. 5
Introduction: Administrative programs. . . . . . . . . . . . . . . . . . . . . . . .
. 5
Introduction: Administrative configuration data . . . . . . . . . . . . . . . . . . . .
. 6
Welcome to basic administrative architecture . . . . . . . . . . . . . . . . . . . . .
. 6
Introduction: Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 7
Introduction: Application servers . . . . . . . . . . . . . . . . . . . . . . . . .
. 8
Introduction: Web servers . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 9
Introduction: Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Introduction: Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Introduction: Cell-wide settings. . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 2. How do I administer applications and their environments? . . . . . . . . . . . 13

Chapter 3. Setting up the application serving environment . . . . . . . . . . . . . . . .21

Planning the installation (diagrams) . . . . . . . . . . . . . . . . . . . . . . . . . .21
Planning to install Network Deployment . . . . . . . . . . . . . . . . . . . . . . .23
Planning to install Web server plug-ins . . . . . . . . . . . . . . . . . . . . . . .31
Planning to install WebSphere Application Server Clients . . . . . . . . . . . . . . . . .38
Planning to create application server environments . . . . . . . . . . . . . . . . . . .39
Example: Choosing a topology for better performance . . . . . . . . . . . . . . . . . .42
Queuing network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Configuring the product after installation . . . . . . . . . . . . . . . . . . . . . . . .47
firststeps command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Using the Profile creation wizard . . . . . . . . . . . . . . . . . . . . . . . . . .54
wasprofile command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Using the installation verification test . . . . . . . . . . . . . . . . . . . . . . . . 110
Configuring ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Port number settings in WebSphere Application Server versions . . . . . . . . . . . . . . 113
Communicating with Web servers . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Web server plug-in properties settings . . . . . . . . . . . . . . . . . . . . . . . 118
Web server plug-in custom properties . . . . . . . . . . . . . . . . . . . . . . . 126
Web server plug-in configuration service properties settings . . . . . . . . . . . . . . . 127
Application Server property settings for a Web server plug-in . . . . . . . . . . . . . . . 127
Web server plug-in configuration properties . . . . . . . . . . . . . . . . . . . . . 129
Web server plug-in connections . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Web server plug-in remote user information processing . . . . . . . . . . . . . . . . . 132
Web server plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Checking your IBM HTTP Server version . . . . . . . . . . . . . . . . . . . . . . 132
Web server tuning parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Gskit install images files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Plug-ins: Resources for learning . . . . . . . . . . . . . . . . . . . . . . . . . 137
Web server plug-in tuning tips . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Tuning Web servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Setting up the administrative architecture . . . . . . . . . . . . . . . . . . . . . . . 139
Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

© Copyright IBM Corp. 2004 iii

 Configuring cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Deployment managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Configuring deployment managers . . . . . . . . . . . . . . . . . . . . . . . . . 145
Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Managing nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Node group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Managing node groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Managing node group members . . . . . . . . . . . . . . . . . . . . . . . . . 159
Administration service settings . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Node agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Managing node agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Remote file services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Configuring remote file services . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Administrative agents: Resources for learning . . . . . . . . . . . . . . . . . . . . 173
Configuring the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Virtual hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Configuring virtual hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Configuring WebSphere variables . . . . . . . . . . . . . . . . . . . . . . . . . 181
Shared library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Managing shared libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Environment: Resources for learning . . . . . . . . . . . . . . . . . . . . . . . . 191
Working with server configuration files . . . . . . . . . . . . . . . . . . . . . . . . 191
Configuration documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Configuration document descriptions . . . . . . . . . . . . . . . . . . . . . . . . 193
Object names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Configuration repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Handling temporary configuration files resulting from session timeout . . . . . . . . . . . . 196
Changing the location of temporary configuration files . . . . . . . . . . . . . . . . . 196
Changing the location of backed-up configuration files . . . . . . . . . . . . . . . . . 197
Changing the location of temporary workspace files . . . . . . . . . . . . . . . . . . 197
Backing up and restoring administrative configurations . . . . . . . . . . . . . . . . . 197
Transformation of configuration files . . . . . . . . . . . . . . . . . . . . . . . . 198
Server configuration files: Resources for learning . . . . . . . . . . . . . . . . . . . 198
Administering application servers . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Creating application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Managing application servers . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Creating generic servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Configuring transport chains . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Custom services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Developing custom services . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Process definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Defining application server processes . . . . . . . . . . . . . . . . . . . . . . . 240
Java virtual machines (JVMs) . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Using the JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Preparing to host applications . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Java memory tuning tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Configuring multiple network interface card support . . . . . . . . . . . . . . . . . . 264
Tuning application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Web services client to Web container optimized communication . . . . . . . . . . . . . . 266
Application servers: Resources for learning . . . . . . . . . . . . . . . . . . . . . 267
Balancing workloads with clusters . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Clusters and workload management . . . . . . . . . . . . . . . . . . . . . . . . 268
Clusters and node groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Workload management (WLM) for distributed platforms . . . . . . . . . . . . . . . . . 270

iv IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Creating clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Creating cluster members . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Creating backup clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Starting clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Stopping clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Replicating data across application servers in a cluster . . . . . . . . . . . . . . . . . 283
Deleting clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Deleting cluster members . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Tuning a workload management configuration . . . . . . . . . . . . . . . . . . . . 296
Workload management run-time exceptions . . . . . . . . . . . . . . . . . . . . . 297
Clustering and workload management: Resources for learning . . . . . . . . . . . . . . 297
Setting up a high availability environment . . . . . . . . . . . . . . . . . . . . . . . 298
High availability manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
High availability network components . . . . . . . . . . . . . . . . . . . . . . . . 301
Transport protocol for a high availability manager . . . . . . . . . . . . . . . . . . . 302
Creating a new core group . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Changing a core group’s configuration . . . . . . . . . . . . . . . . . . . . . . . 311
Changing the configuration of a high availability group . . . . . . . . . . . . . . . . . 313
Creating a policy for a high availability group . . . . . . . . . . . . . . . . . . . . . 316
Changing the policy of a high availability group . . . . . . . . . . . . . . . . . . . . 323
Adding members to a core group . . . . . . . . . . . . . . . . . . . . . . . . . 324
Routing high availability group work to a different server . . . . . . . . . . . . . . . . . 326
Configuring the core group bridge service . . . . . . . . . . . . . . . . . . . . . . 328

Chapter 4. Using the administrative clients . . . . . . . . . . . . . . . . . . . . . 349

Using the administrative console . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Starting and stopping the administrative console . . . . . . . . . . . . . . . . . . . 349
Setting the session timeout for the administrative console . . . . . . . . . . . . . . . . 352
Administrative console areas . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Specifying console preferences . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Accessing help and product information from the administrative console . . . . . . . . . . . 362
Administrative console: Resources for learning . . . . . . . . . . . . . . . . . . . . 363
Using scripting (wsadmin) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Getting started with scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Deploying applications using scripting . . . . . . . . . . . . . . . . . . . . . . . 433
Managing deployed applications using scripting . . . . . . . . . . . . . . . . . . . . 435
Configuring servers with scripting . . . . . . . . . . . . . . . . . . . . . . . . . 462
Configuring connections to Webservers with scripting . . . . . . . . . . . . . . . . . . 479
Managing servers with scripting . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Clustering servers with scripting. . . . . . . . . . . . . . . . . . . . . . . . . . 489
Configuring security with scripting . . . . . . . . . . . . . . . . . . . . . . . . . 493
Configuring data access with scripting . . . . . . . . . . . . . . . . . . . . . . . 495
Configuring messaging with scripting . . . . . . . . . . . . . . . . . . . . . . . . 511
Configuring mail, URLs, and resource environment entries with scripting . . . . . . . . . . . 524
Troubleshooting with scripting . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Scripting reference material . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Using Ant to automate tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
ws_ant command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
Ant tasks for deployment and server operation . . . . . . . . . . . . . . . . . . . . 810
Ant tasks for building application code . . . . . . . . . . . . . . . . . . . . . . . 810
Using administrative programs (JMX) . . . . . . . . . . . . . . . . . . . . . . . . . 810
Creating a custom Java administrative client program using WebSphere Application Server
administrative Java APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
Extending the WebSphere Application Server administrative system with custom MBeans . . . . 816
Developing administrative programs for multiple Java 2 Platform, Enterprise Edition application
servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821

Contents v
 Deploying and managing a custom Java administrative client program with multiple Java 2
Platform, Enterprise Edition application servers . . . . . . . . . . . . . . . . . . . 824
Migrating Java Management Extensions V1.0 to Java Management Extensions V1.2 . . . . . . 825
Java Management Extensions interoperability . . . . . . . . . . . . . . . . . . . . 825
Managed object metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
Managing applications through programming . . . . . . . . . . . . . . . . . . . . . 827
Using command line tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
Example: Security and the command line tools . . . . . . . . . . . . . . . . . . . . 853
startServer command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
stopServer command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
startManager command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
stopManager command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
startNode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
stopNode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
addNode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
serverStatus command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
removeNode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
cleanupNode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
syncNode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
backupConfig command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
restoreConfig command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
EARExpander command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
GenPluginCfg command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872

Chapter 5. Starting and stopping quick reference . . . . . . . . . . . . . . . . . . . 875

Chapter 6. Class loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877

Class loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
Configuring class loaders of a server . . . . . . . . . . . . . . . . . . . . . . . . . 881
Class loader collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
Class loader ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
Class loader mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
Class loader settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
Configuring application class loaders . . . . . . . . . . . . . . . . . . . . . . . . . 883
Configuring Web module class loaders . . . . . . . . . . . . . . . . . . . . . . . . 884
Configuring class preloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
Class loading: Resources for learning . . . . . . . . . . . . . . . . . . . . . . . . 886

Chapter 7. Deploying and administering applications . . . . . . . . . . . . . . . . . 889

Enterprise (J2EE) applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
System applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
Installing application files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
Installable module versions . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
Ways to install applications or modules . . . . . . . . . . . . . . . . . . . . . . . 892
Installing application files with the console . . . . . . . . . . . . . . . . . . . . . . 893
Example: Installing an EAR file using the default bindings . . . . . . . . . . . . . . . . 903
Installing J2EE modules with JSR-88 . . . . . . . . . . . . . . . . . . . . . . . . 904
Customizing modules using DConfigBeans . . . . . . . . . . . . . . . . . . . . . 905
Enterprise application collection . . . . . . . . . . . . . . . . . . . . . . . . . . . 906
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907
Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907
Enterprise application settings . . . . . . . . . . . . . . . . . . . . . . . . . . 908
Configuring an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
Application bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
Mapping modules to servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 917
Starting and stopping applications . . . . . . . . . . . . . . . . . . . . . . . . . . 918

vi IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Disabling automatic starting of applications . . . . . . . . . . . . . . . . . . . . . 919
Target mapping collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
Exporting applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
Exporting DDL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
Updating applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
Ways to update application files . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Preparing for application update settings . . . . . . . . . . . . . . . . . . . . . . 925
Hot deployment and dynamic reloading . . . . . . . . . . . . . . . . . . . . . . . 929
Uninstalling applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
Removing a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
Deploying and administering applications: Resources for learning . . . . . . . . . . . . . . 938

Chapter 8. Developing WebSphere applications . . . . . . . . . . . . . . . . . . . . 941

Web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
Task overview: Developing and deploying Web applications . . . . . . . . . . . . . . . 941
Task overview: Managing HTTP sessions . . . . . . . . . . . . . . . . . . . . . . 978
Modifying the default Web container configuration . . . . . . . . . . . . . . . . . . . 993
Configuring session management by level . . . . . . . . . . . . . . . . . . . . . . 998
Configuring session tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
Configuring session tracking for Wireless Application Protocol (WAP) devices . . . . . . . . 1004
Configuring for database session persistence . . . . . . . . . . . . . . . . . . . . 1004
Configuring memory-to-memory replication for the peer-to-peer mode (default memory-to-memory
replication) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
Configuring memory-to-memory replication for the client/server mode . . . . . . . . . . . 1008
EJB applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
Task overview: Using enterprise beans in applications . . . . . . . . . . . . . . . . . 1010
Using access intent policies . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
Managing EJB containers . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
Deploying EJB modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036
Client applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
Using application clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
Running application clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Installing Application Client for WebSphere Application Server . . . . . . . . . . . . . . 1068
Deploying J2EE application clients on workstation platforms . . . . . . . . . . . . . . . 1073
Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
Implementing Web services applications . . . . . . . . . . . . . . . . . . . . . . 1151
Deploying Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163
Configuring Web service client bindings . . . . . . . . . . . . . . . . . . . . . . 1165
Configuring the scope of a Web service port. . . . . . . . . . . . . . . . . . . . . 1168
Web Services Invocation Framework (WSIF): Enabling Web services . . . . . . . . . . . 1170
Getting started with UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . 1174
Planning to use Web services . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
Setting up and deploying a new UDDI Registry. . . . . . . . . . . . . . . . . . . . 1180
Publishing WSDL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191
Configuring endpoint URL information for JMS bindings . . . . . . . . . . . . . . . . 1194
Configuring Web services applications with the wsadmin tool . . . . . . . . . . . . . . 1196
WSIF system management and administration . . . . . . . . . . . . . . . . . . . . 1196
Using the UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203
Removing and reinstalling UDDI Registry . . . . . . . . . . . . . . . . . . . . . . 1307
Configuring the UDDI Registry Application . . . . . . . . . . . . . . . . . . . . . 1309
Managing the UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
Data access resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
Task overview: Accessing data from applications . . . . . . . . . . . . . . . . . . . 1325
Deploying data access applications . . . . . . . . . . . . . . . . . . . . . . . . 1355
Messaging resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443
Learning about messaging with WebSphere Application Server . . . . . . . . . . . . . . 1443

Contents vii
 Installing and configuring a JMS provider . . . . . . . . . . . . . . . . . . . . . . 1454
Using asynchronous messaging . . . . . . . . . . . . . . . . . . . . . . . . . 1456
Using JMS resources of WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . 1456
Using JMS resources of a generic provider . . . . . . . . . . . . . . . . . . . . . 1524
Maintaining Version 5 default messaging resources . . . . . . . . . . . . . . . . . . 1532
Administering support for message-driven beans . . . . . . . . . . . . . . . . . . . 1565
Mail, URLs, and other J2EE resources . . . . . . . . . . . . . . . . . . . . . . . . 1581
Using mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1581
Using URL resources within an application . . . . . . . . . . . . . . . . . . . . . 1585
Resource environment entries . . . . . . . . . . . . . . . . . . . . . . . . . . 1588
Configuring mail providers and sessions . . . . . . . . . . . . . . . . . . . . . . 1592
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1598
Securing applications and their environments . . . . . . . . . . . . . . . . . . . . 1598
Planning to secure your environment . . . . . . . . . . . . . . . . . . . . . . . 1599
Implementing security considerations at installation time . . . . . . . . . . . . . . . . 1611
Integrating IBM WebSphere Application Server security with existing security systems . . . . . 1616
Administering security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
Deploying secured applications . . . . . . . . . . . . . . . . . . . . . . . . . 1984
Naming and directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
Using naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
Configuring name servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006
Configuring and viewing name space bindings . . . . . . . . . . . . . . . . . . . . 2006
Developing applications that use JNDI . . . . . . . . . . . . . . . . . . . . . . . 2010
Developing applications that use CosNaming (CORBA Naming interface) . . . . . . . . . . 2025
Object Request Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
Managing Object Request Brokers . . . . . . . . . . . . . . . . . . . . . . . . 2030
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047
Configuring transaction properties for an application server . . . . . . . . . . . . . . . 2047
Configuring transaction properties for peer recovery . . . . . . . . . . . . . . . . . . 2056
Using the transaction service . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
Managing active and prepared transactions . . . . . . . . . . . . . . . . . . . . . 2070
Managing transaction logging for optimum server availability . . . . . . . . . . . . . . . 2071
Interoperating transactionally between application servers. . . . . . . . . . . . . . . . 2074
Using one-phase and two-phase commit resources in the same transaction . . . . . . . . . 2075
WebSphere programming extensions . . . . . . . . . . . . . . . . . . . . . . . . 2078
ActivitySessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
Application profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
Asynchronous beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
Dynamic cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2122
Dynamic query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2172
Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2201
Object pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217
Startup beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
Work area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2243

Chapter 9. Troubleshooting deployment . . . . . . . . . . . . . . . . . . . . . . 2269

Errors or problems deploying, installing, or promoting applications . . . . . . . . . . . . . 2269
Troubleshooting testing and first time run problems . . . . . . . . . . . . . . . . . . . 2273
Errors starting an application . . . . . . . . . . . . . . . . . . . . . . . . . . . 2274
The application does not start or starts with errors . . . . . . . . . . . . . . . . . . . 2278
A web resource does not display . . . . . . . . . . . . . . . . . . . . . . . . . . 2279
Cannot uninstall an application or remove a node or application server . . . . . . . . . . . . 2281

Chapter 10. Troubleshooting administration . . . . . . . . . . . . . . . . . . . . . 2283

Administration and administrative console troubleshooting tips . . . . . . . . . . . . . . . 2283

viii IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Installation completes but the administrative console does not start . . . . . . . . . . . . . 2285
Errors connecting to the administrative console from a browser . . . . . . . . . . . . . . 2286
When a single user that uses multiple instances of the Mozilla browser logs into the
administrative console, the first user ID that logs into the administrative console is the current
user. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286
A user on Mozilla browser Version 1.4 selects a check box on a collection table, presses Enter,
and receives an error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287
A user on Mozilla browser Version 1.4 enters an invalid ID or password, presses Enter, and
receives an error message . . . . . . . . . . . . . . . . . . . . . . . . . . 2287
Web server plug-in troubleshooting tips . . . . . . . . . . . . . . . . . . . . . . . 2287
The server process does not start or starts with errors . . . . . . . . . . . . . . . . . . 2289
The stopServer.sh or administrative console stop server commandhangs and creates a Java core
dump (Red Hat Linux) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
Errors setting up multiserver environments . . . . . . . . . . . . . . . . . . . . . . 2291
Workload management component troubleshooting tips . . . . . . . . . . . . . . . . . 2293
Workload is not getting distributed . . . . . . . . . . . . . . . . . . . . . . . . . 2297
Problems starting or using the wsadmin command . . . . . . . . . . . . . . . . . . . 2300
Problems using tracing, logging or other troubleshooting features . . . . . . . . . . . . . . 2304

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305

Trademarks and service marks . . . . . . . . . . . . . . . . . . . . . . . . . . 2307

Contents ix
x IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
How to send your comments
Your feedback is important in helping to provide the most accurate and highest quality information.
v To send comments on articles in the WebSphere Application Server Information Center
1. Display the article in your Web browser and scroll to the end of the article.
2. Click on the Feedback link at the bottom of the article, and a separate window containing an e-mail
form appears.
3. Fill out the e-mail form as instructed, and click on Submit feedback .
v To send comments on PDF books, you can e-mail your comments to: [email protected] or fax
them to 919-254-0206.
Be sure to include the document name and number, the WebSphere Application Server version you are
using, and, if applicable, the specific page, table, or figure number on which you are commenting.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information
in any way it believes appropriate without incurring any obligation to you.

© Copyright IBM Corp. 2004 xi

xii IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 1. Overview and new features for administering
applications and their environments
This topic summarizes the contents and organization of the administration documentation, including links
to conceptual overviews and descriptions of new features.
v Overview of administering applications and their environments
v What is new for administrators

Sections in the administration documentation:

Chapter 3, “Setting up the application serving environment,” on page 21
This section is for the administrator who is responsible for integrating application serving
capabilities into an existing network environment. It looks at the product as part of a larger system,
typically a production environment or realistic test environment. This section reiterates some
installation and customization activities, including topology planning and creating product
configurations. It carries the focus into the administrative realm, discussing port configuration and
other network concerns. See also ″Overview and new features for installing an application serving
environment″ in the information center.
This information expands the topology planning discussion by describing how to set up and
maintain logical administrative domains of cells and nodes, and how to balance workload through
clustering and high availability configurations.
Chapter 4, “Using the administrative clients,” on page 349
This section describes the many options available for administering your applications and the
servers to which the applications are deployed. Options include the graphical administrative
console; scripting with the wsadmin tool; programmatic administration using Java Management
Extensions (JMX) and MBeans; and a wide array of command-line tools, including ANT.
Chapter 5, “Starting and stopping quick reference,” on page 875
This section summarizes what can be started and stopped, including applications and the
application servers on which these applications are deployed.
Chapter 6, “Class loading,” on page 877
This section describes how to configure class loaders. It includes both configuration that is
performed during application assembly (packaging) and configuration performed at the server. The
product run-time environment uses class loaders to find and load new classes for an application.
Class loaders are part of the Java virtual machine (JVM) code and are responsible for finding and
loading class files.
Chapter 7, “Deploying and administering applications,” on page 889
This section describes how to deploy applications onto application servers, and then how to
administer the deployed applications. It includes installing applications, starting applications,
exporting application files, updating applications, removing applications, and other common tasks.
Administer WebSphere applications
This section provides administrative instructions that are specific to the various types of
applications. For example, you can focus on administering your Web applications in their Web
container; or aspects of Web services support; or the messaging or security subsystems.
Chapter 9, “Troubleshooting deployment,” on page 2269
This section describes how to identify and handle a variety of problems encountered during
development, assembly, and deployment activities.
Chapter 10, “Troubleshooting administration,” on page 2283
This section describes how to identify and handle a variety of problems encountered during
administrative activities.

© Copyright IBM Corp. 2004 1

Overview of administering applications and their environments
This topic provides links to conceptual overviews of administering your applications and application serving
environment.
What is new for administrators
This topic provides an overview of new and changed features of system administration.
“Introduction: System administration” on page 3
This topic describes the administration of WebSphere Application Server, Version 6 products and
the applications that run on them.
Presentations from Education on Demand
The following presentations provide a quick overview:
v System management architecture
v Administrative security
v Administrative clients overview
– Start, stop, and monitor processes
– Other commands
– Browser-based administrative console
– Scripting - wsadmin
– Custom Java administrative client (JMX)
v Topologies and logical administrative domains
– Resource scoping
– Cells, deployment managers, and node agents
– Build cells - Add and remove nodes
– Manage node groups
v Applications and application resources
– Application management overview
– JDBC
– Installing and uninstalling applications
– Managed application resources - Enhanced EAR files
– Fine grained application updates
v Servers
– Server templates
– Custom services
– Manage Web server nodes
– Application servers and cluster members
– Creating cluster members
v Configuration management
– Configuration repository
– Configuration archives
– File synchronization

2 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Getting started with WebSphere Application Server

Note: If you prefer to browse PDF versions of this documentation using Adobe Reader, see the
Getting Started PDF files that are available from
www.ibm.com/software/webservers/appserv/infocenter.html.

IBM WebSphere Application Server products provide a next-generation application server on an

industry-standard foundation. Each product addresses a distinct set of scenarios and needs. WebSphere
Application Server, Version 6 product offerings are described in ″Packaging″ in the information center.

Planning

See ″Task overview: Installing″ in the information center for a description of typical scenarios for each
WebSphere Application Server product.

Installing

See ″Task overview: Installing″ for a description of installing the WebSphere Application Server product
and other installable components on the product disc.

Configuring

See “Using the Profile creation wizard” on page 54 for a description of installing profiles that define a
deployment manager, a managed node, or a stand-alone Application Server.

Migrating

See ″Migration and coexistence overview″ and ″Migrating and coexisting″ in the information center for a
description of how to migrate applications and configuration data from a previous version of WebSphere
Application Server.

Using the Samples Gallery

See ″Accessing the Samples (Samples Gallery)″ in the information center for a description of the set of
Samples that ship with each product. The Samples demonstrate common Web application tasks.

Deploying applications

The information center describes a way to sample WebSphere Application Server functionality by quickly
deploying Web components, such as servlets and JSP files. The method is not recommended as an
official development method. See ″Fast paths for WebSphere Application Server″ in the information center
to get started.

Introduction: System administration

A variety of tools are provided for administering the WebSphere Application Server product:
v Console
The administrative console is a graphical interface that provides many features to guide you through
deployment and systems administration tasks. Use it to explore available management options.
For more information, refer to “Introduction: Administrative console” on page 4.
v Administrative agents

Chapter 1. Overview and new features for administering applications and their environments 3
 Servers, nodes and node agents, cells and the deployment manager are fundamental concepts in the
administrative universe of the product. It is also important to understand the various processes in the
administrative topology and the operating environment in which they apply.
For more information, refer to “Welcome to basic administrative architecture” on page 6.
v Scripting
The WebSphere administrative (wsadmin) scripting program is a powerful, non-graphical command
interpreter environment enabling you to run administrative operations in a scripting language. You can
also submit scripting language programs to run. The wsadmin tool is intended for production
environments and unattended operations.
For more information, refer to “Introduction: Administrative scripting (wsadmin).”
v Commands
Command-line tools are simple programs that you run from an operating system command-line prompt
to perform specific tasks, as opposed to general purpose administration. Using the tools, you can start
and stop application servers, check server status, add or remove nodes, and complete similar tasks.
For more information, refer to “Introduction: Administrative commands” on page 5.
v Programming
The product supports a Java programming interface for developing administrative programs. All of the
administrative tools supplied with the product are written according to the API, which is based on the
industry standard Java Management Extensions (JMX) specification.
For more information, refer to “Introduction: Administrative programs” on page 5.
v Data
Product configuration data resides in XML files that are manipulated by the previously-mentioned
administrative tools.
For more information, refer to “Introduction: Administrative configuration data” on page 6.

Introduction: Administrative console

The administrative console is a graphical interface for performing deployment and system administration
tasks. It runs in your Web browser. Your actions in the console modify a set of XML configuration files.

You can use the console to perform tasks such as:

v Add, delete, start, and stop application servers
v Deploy new applications to a server
v Start and stop existing applications, and modify certain configurations
v Add and delete Java 2 Platform, Enterprise Edition (J2EE) resource providers for applications that
require data access, mail, URLs, and so on
v Manage variables, shared libraries, and other configurations that can span multiple application servers
v Configure product security, including access to the administrative console
v Collect data for performance and troubleshooting purposes
v Find the product version information. It is located on the front page of the console.

See the Using the administrative clients PDF for information on how you begin using the console. See also
the Reference > Administrator > Settings section of the Information Center navigation. It lists the
settings or properties you can configure.

Introduction: Administrative scripting (wsadmin)

The WebSphere administrative (wsadmin) scripting program is a powerful, non-graphical command
interpreter environment enabling you to run administrative operations in a scripting language. The wsadmin
tool is intended for production environments and unattended operations. You can use the wsadmin tool to
perform the same tasks that you can perform using the administrative console.

4 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The following list highlights the topics and tasks available with scripting. See the Administering applications
and their environment PDF for more information on how to perform these tasks.
v Getting started with scripting Provides an introduction to WebSphere Application Server scripting and
information about using the wsadmin tool. Topics include information about the scripting languages and
the scripting objects, and instructions for starting the wsadmin tool.
v Deploying applications Provides instructions for deploying and uninstalling applications. For example,
stand-alone Java archive files and Web archive files, the administrative console, remote enterprise
archive (EAR) files, file transfer applications, and so on.
v Managing deployed applications Includes tasks that you perform after the application is deployed. For
example, starting and stopping applications, checking status, modifying listener address ports, querying
application state, configuring a shared library, and so on.
v Configuring servers Provides instructions for configuring servers, such as creating a server, modifying
and restarting the server, configuring the Java virtual machine, disabling a component, disabling a
service, and so on.
v Configuring connections to Web servers Includes topics such as regenerating the plug-in, creating new
virtual host templates, modifying virtual hosts, and so on.
v Managing servers Includes tasks that you use to manage servers. For example, stopping nodes,
starting and stopping servers, querying a server state, starting a listener port, and so on.
v Clustering servers Includes topics about clusters, such as creating clusters, creating cluster members,
querying a cluster state, removing clusters, and so on.
v Configuring security Includes security tasks, for example, enabling and disabling global security,
enabling and disabling Java 2 security, and so on.
v Configuring data access Includes topics such as configuring a Java DataBase Connectivity (JDBC)
provider, defining a data source, configuring connection pools, and so on.
v Configuring messaging Includes topics about messaging, such as Java Message Service (JMS)
connection, JMS provider, WebSphere queue connection factory, MQ topics, and so on.
v Configuring mail, URLs, and resource environment entries Includes topics such as mail providers, mail
sessions, protocols, resource environment providers, reference tables, URL providers, URLs, and so on.
v Dynamic caching Includes caching topics, for example, creating, viewing and modifying a cache
instance.
v Troubleshooting Provides information about how to troubleshoot using scripting. For example, tracing,
thread dumps, profiles, and so on.
v Obtaining product information Includes tasks such as querying the product identification.
v Scripting reference material Includes all of the reference material related to scripting. Topics include the
syntax for the wsadmin tool and for the administrative command framework, explanations and examples
for all of the scripting object commands, the scripting properties, and so on.

Introduction: Administrative commands

Command-line tools are simple programs that you run from an operating system command-line prompt to
perform specific tasks, as opposed to general purpose administration. Using the tools, you can start and
stop application servers, check server status, add or remove nodes, and complete similar tasks.

See Reference > Commands in the information center navigation for the names and syntax of all the
commands that are available with the product. A subset of these commands are particular to system
administration purposes.

Introduction: Administrative programs

The product supports a Java programming interface for developing administrative programs. All of the
administrative tools supplied with the product are written according to the API, which is based on the
industry standard Java Management Extensions (JMX) specification. You can write a Java program that

Chapter 1. Overview and new features for administering applications and their environments 5
performs any of the administrative features of the WebSphere Application Server administrative tools. You
can also extend the basic WebSphere Application Server administrative system to include your own
managed resources.

Introduction: Administrative configuration data

Administrative tasks typically involve defining new configurations of the product or performing operations
on managed resources within the environment. IBM WebSphere Application Server configuration data is
kept in files. Because all product configuration involves changing the content of those files, it is useful to
know the structure and content of the configuration files.

The WebSphere Application Server product includes an implementation of the Java Management
Extension (JMX) specification. All operations on managed resources in the product go through JMX
functions. This setup means a more standard framework underlying your administrative operations as well
as the ability to tap into the systems management infrastructure programmatically.

Welcome to basic administrative architecture

This article discusses basic concepts in the administrative architecture to help you understand system
administration in a WebSphere Application Server environment. The fundamental concepts for WebSphere
Application Server administration include software processes called servers, topological units referenced
as nodes and cells, and the configuration repository used for storing configuration information.

Servers perform the actual running of the code. Several types of servers exist depending on the
configuration. Each server runs in its own Java virtual machine (JVM). The application server is the
primary run-time component in all WebSphere Application Server configurations. All WebSphere
Application Server configurations can have one or more application servers. In some configurations, each
application server functions as a separate entity. No workload distribution or common administration
among application servers exists. In other configurations, workload can be distributed between servers and
administration can be done from a central point.

A node is a logical group of WebSphere Application Server-managed server processes that share a
common configuration repository. A node is associated with a single WebSphere Application Server profile.
A WebSphere Application Server node does not necessarily have a one-to-one association with a system.
One computer can host arbitrarily many nodes, but a node cannot span multiple computer systems. A
node can contain zero or more application servers.

The configuration repository holds copies of the individual component configuration documents that define
the configuration of a WebSphere Application Server environment. All configuration information is stored in
.xml files.

A cell is a grouping of nodes into a single administrative domain. A cell can consist of multiple nodes, all
administered from a deployment manager server. When a node becomes part of a cell (a federated node),
a node agent server is installed on the node to work with the deployment manager server to manage the
WebSphere Application Server environment on that node.

When a node is a standalone node, not part of a cell, the configuration repository is fully contained on the
node. When a node is part of a cell, the configuration and application files for all nodes in the cell are
centralized into a cell master configuration repository. This centralized repository is managed by the
deployment manager server and synchronized to local copies that are held on each node. The local copy
of the repository that is given to each node contains just the configuration information needed by that
node, not the full configuration that is maintained by the deployment manager.

WebSphere Application Server types

This section discusses the three server types that interact to perform system administration.

6 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Application Server: A WebSphere Application Server provides the functions that are required to support
and host user applications. An application server runs on only one node, but one node can support many
application servers.

Node agent: When a node is federated, a node agent is created and installed on that node. The node
agent works with the deployment manager to perform administrative activities on the node.

Deployment manager: With the deployment manager, you can administer multiple application servers
from one centralized manager. The deployment manager works with the node agent on each node to
manage all the servers in a distributed topology.

The following diagram depicts the concepts that are discussed in this article.
IBM WebSphere Application Server Network Deployment package

Node
Cell
Deployment
manager

Adding a node to a cell

Node
WebSphere Application Server

Application Server
Enterprise Edition Node
lkdsjfkenroierithtrj
a;lkjdfoidicnvcnv
aodsfiidididid
agent
Node a;osidjfpapoidjuff

Application Server slkdjflkdj;lakjdf;lkjaslkdfgfgfdgfdgfdgfdg

sdlkfj;slkajflskjdf;lskdflkjfj;alkjfd ;lkjfd sd;jfdfgfdgf
jsafjs df;lskjfd ;lskjf sfksdf kjsdf ;slkdfg
as;dlfkj lkdsjf ;sjd;fk ja;lkjd f;lk

Node
agent
WebSphere Application Server
Enterprise Edition
Application Server

lkdsjfkenroierithtrj
a;lkjdfoidicnvcnv
aodsfiidididid
a;osidjfpapoidjuff

Application Server slkdjflkdj;lakjdf;lkjaslkdfgfgfdgfdgfdgfdg

WebSphere Application Server sdlkfj;slkajflskjdf;lskdflkjfj;alkjfd ;lkjfd sd;jfdfgfdgf

Enterprise Edition jsafjs df;lskjfd ;lskjf sfksdf kjsdf ;slkdfg

Application Server as;dlfkj lkdsjf ;sjd;fk ja;lkjd f;lk

lkdsjfkenroierithtrj
a;lkjdfoidicnvcnv
aodsfiidididid
a;osidjfpapoidjuff

Application Server slkdjflkdj;lakjdf;lkjaslkdfgfgfdgfdgfdgfdg

sdlkfj;slkajflskjdf;lskdflkjfj;alkjfd ;lkjfd sd;jfdfgfdgf
Node
jsafjs df;lskjfd ;lskjf sfksdf kjsdf ;slkdfg
as;dlfkj lkdsjf ;sjd;fk ja;lkjd f;lk

Node WebSphere Application Server

Enterprise Edition

= Network Deployment package is installed

Application Server

lkdsjfkenroierithtrj

agent
a;lkjdfoidicnvcnv
aodsfiidididid
a;osidjfpapoidjuff

Application Server slkdjflkdj;lakjdf;lkjaslkdfgfgfdgfdgfdgfdg

sdlkfj;slkajflskjdf;lskdflkjfj;alkjfd ;lkjfd sd;jfdfgfdgf
jsafjs df;lskjfd ;lskjf sfksdf kjsdf ;slkdfg
as;dlfkj lkdsjf ;sjd;fk ja;lkjd f;lk

= Application servers
WebSphere Application Server
Enterprise Edition
Application Server

lkdsjfkenroierithtrj
a;lkjdfoidicnvcnv
aodsfiidididid
a;osidjfpapoidjuff

Application Server slkdjflkdj;lakjdf;lkjaslkdfgfgfdgfdgfdgfdg

sdlkfj;slkajflskjdf;lskdflkjfj;alkjfd ;lkjfd sd;jfdfgfdgf
jsafjs df;lskjfd ;lskjf sfksdf kjsdf ;slkdfg
as;dlfkj lkdsjf ;sjd;fk ja;lkjd f;lk

The concepts that are discussed in this article form the basis of WebSphere Application Server
administration. More detailed descriptions can be found in other sections.

Introduction: Servers
Application servers

Application servers provide the core functionality of the WebSphere Application Server product family. They
extend the ability of a Web server to handle Web application requests, and much more. An application
server enables a server to generate a dynamic, customized response to a client request.

For additional overview, refer to “Introduction: Application servers” on page 8.

Clusters

Workload management optimizes the distribution of client processing tasks. Incoming work requests are
distributed to the application servers that can most effectively process the requests. Workload
management also provides failover when servers are not available, improving application availability.

Chapter 1. Overview and new features for administering applications and their environments 7
Clusters are sets of application servers that are managed together and participate in workload
management. The servers that are members of a cluster can be on different host machines, as opposed to
the servers that are part of the same node and must be located on the same host machine.

For additional overview, refer to “Introduction: Clusters” on page 10.

Introduction: Application servers

Overview

An application server is a Java Virtual Machine (JVM) that is running user applications. The application
server collaborates with the Web server to return a dynamic, customized response to a client request.
Application code, including servlets, JavaServer Pages (JSP) files, enterprise beans and their supporting
classes, runs in an application server. Conforming to the Java 2 platform, Enterprise Edition (J2EE)
component architecture, servlets and JSP files run in a Web container, and enterprise beans run in an
Enterprise JavaBeans (EJB) container.

To begin creating and managing an application server, see “Administering application servers” on page
198.

You can define multiple application servers, each running its own JVM. Enhance the operation of an
application server by using the following options:
v Configure transport chains to provide networking services to such functions as the service integration
bus component of IBM service integration technologies, WebSphere Secure Caching Proxy, and the
high availability manager core group bridge service. See “Configuring transport chains” on page 221 for
more information.
v Plug into an application server to define a hook point that runs when the server starts and shuts down.
See “Custom services” on page 237 for more information.
v Define command-line information that passes to a server when it starts or initializes. See the Using the
administrative clients PDF for more information.
v “Tuning application servers” on page 265
v Enhance the performance of the application server JVM. See “Using the JVM” on page 252 for more
information.
v Use an Object Request Broker (ORB) for RMI/IIOP communication. See the Developing and deploying
applications PDF for more information.

Asynchronous messaging

The product supports asynchronous messaging based on the Java Messaging Service (JMS) of a JMS
provider that conforms to the JMS specification version 1.1.

The JMS functions of the default messaging provider in WebSphere Application Server are served by one
or more messaging engines (in a service integration bus) that runs within application servers.

In a deployment manager cell, there can be WebSphere Application Server version 5 nodes. If a version 5
node is configured to use V5 Default Messaging (the version 5 Embedded Messaging), there can be at
most one JMS server on that node.

Generic Servers

In distributed platforms, the Generic Servers feature allows you create a generic server as an application
server instance within the WebSphere Application Server administration, and associate it with a
non-WebSphere server or process. The generic server can be associated with any server or process
necessary to support the application server environment, including:
v A Java server
v A C or C++ server or process

8 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v A CORBA server
v A Remote Method Invocation (RMI) server

After you define a generic server, you can use the Application Server administrative console to start, stop,
and monitor the associated non-WebSphere server or process when stopping or starting the applications
that rely on them.

For more information, refer to “Creating generic servers” on page 219.

Introduction: Web servers

In the WebSphere Application Server product, an application server works with a Web server to handle
requests for dynamic content, such as servlets, from Web applications. Go to
http://www.ibm.com/software/webservers/appserv/doc/latest/prereq.html for the most current information
about supported Web servers.

The application server and Web server communicate using “Web server plug-ins” on page 132.
“Communicating with Web servers” on page 116 describes how to set up your Web server and Web server
plug-in environment and how to create a Web server definition. The Web server definition associates a
Web server with a previously defined managed or unmanaged node. After you define the Web server to a
node, you can use the administrative console to perform the following functions for that Web server.

If the Web server is defined to a managed node, you can:

v Check the status of the Web server
v Generate a plug-in configuration file for that Web server.
v Propagate the plug-in configuration file after it is generated.

If the Web server is an IBM HTTP Server (IHS) and the IHS Administration server is installed and properly
configured, you can also:
v Display the IBM HTTP Server Error log (error.log) and Access log (access.log) files.
v Start and stop the server.
v Display and edit the IBM HTTP Server configuration file (httpd.conf).

If the Web server it is defined to an unmanaged node, you can:

v Check the status of the Web server
v Generate a plug-in configuration file for that Web server.

If the Web server is an IBM HTTP Server (IHS) and the IHS Administration server is installed and properly
configured, you can also:
v Display the IBM HTTP Server Error log (error.log) and Access log (access.log) files.
v Start and stop the server.
v Display and edit the IBM HTTP Server configuration file (httpd.conf).
v Propagate the plug-in configuration file after it is generated.

You can not propagate an updated plug-in configuration file to a non-IHS Web server that is defined to an
unmanaged node. You must manually install an updated plug-in configuration file to a Web server that is
defined to an unmanaged node. Web servers defined to an unmanaged node are typically remote Web
servers. Remote Web servers are Web servers that are not located on the same machine as the
WebSphere Application Server.

After you set up your Web server and Web server plug-in, whenever you deploy a Web application, you
must specify a Web server as the deployment target that serves as a router for requests to the Web
application. The configuration settings in the plug-in configuration file (plugin-cfg.xml) for each Web server

Chapter 1. Overview and new features for administering applications and their environments 9
are based on the applications that are routed through that Web server. If the Web server plug-in
configuration service is enabled, a Web server plug-in’s configuration file is automatically regenerated
whenever a new application is associated with that Web server.

Note: Before starting the Web server, make sure you are authorized to run any Application Response
Measurement (ARM) agent associated with that Web server.

Refer to your Web server documentation for information on how to administer that Web server. For tips on
tuning your Web server plug-in, see “Web server plug-in tuning tips” on page 137.

Introduction: Clusters
Clusters are groups of servers that are managed together and participate in workload management. A
cluster can contain nodes or individual application servers. A node is usually a physical computer system
with a distinct host IP address that is running one or more application servers. Clusters can be grouped
under the configuration of a cell, which logically associates many servers and clusters with different
configurations and applications with one another depending on the discretion of the administrator and what
makes sense in their organizational environments.

Clusters are responsible for balancing workload among servers. Servers that are a part of a cluster are
called cluster members. When you install an application on a cluster, the application is automatically
installed on each cluster member.

Because each cluster member contains the same applications, you can distribute client tasks in distributed
platforms according to the capacities of the different machines by assigning weights to each server.

In distributed platforms, assigning weights to the servers in a cluster improves performance and failover.
Tasks are assigned to servers that have the capacity to perform the task operations. If one server is
unavailable to perform the task, it is assigned to another cluster member. This reassignment capability has
obvious advantages over running a single application server that can become overloaded if too many
requests are made.

Node groups bound clusters. All cluster members of a given cluster must be members of the same node
group. For more information about clusters and node groups, see “Clusters and node groups” on page
269.

To learn more about clusters, see “Clusters and workload management” on page 268 and “Balancing
workloads with clusters” on page 268 for more information.

Core groups

A group of clusters can be defined as a core group. All of the application servers defined as a member of
one of the clusters included in a core group are automatically members of that core group. Individual
application servers that are not members of a cluster can also be defined as a member of a core group.
The use of core groups enables WebSphere Application Server to provide high availability for applications
that must always be available to end users. You can also configure core groups to communicate with each
other using the core group bridge. The core groups can communicate within the same cell or across cells.

To learn more about core groups, see “Setting up a high availability environment” on page 298.

Introduction: Environment
The environment of the product applies to the configuring of Web server plug-ins, variables, and objects
that you want consistent throughout a cell.

10 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Web servers

In the WebSphere Application Server product, an application server works with a Web server to handle
requests for Web applications. The application Server and Web server communicate using a WebSphere
HTTP plug-in for the Web server.

For more information, refer to “Introduction: Web servers” on page 9.

Cell-wide settings

Cell-wide settings are sets of configuration data that are stored in files in the cell directory. These
configuration files are replicated to every node in the cell. Several different configuration settings apply to
the entire cell. These settings include the definition of virtual hosts, shared libraries, and any variables that
must be consistent throughout the entire cell.

For more information, refer to “Introduction: Cell-wide settings.”

Variables

A variable is a configuration property that can be used to provide a parameter for any value in the system.
A variable has a name and a value to use in place of that name wherever the variable name is located
within the system.

For more information, refer to “Configuring WebSphere variables” on page 181.

Introduction: Cell-wide settings

The configuration data for WebSphere Application Server is stored in XML files. The XML files exist in one
of several directories in the configuration repository tree.

The directory in which a configuration file exists determines its scope, or how broadly or narrowly that data
applies. Files in an individual server directory apply to that specific server only. Files in a node-level
directory apply to every server on that node. Files in the cell directory apply to every server on every node
within the entire cell.

Cell-wide settings are configuration files in the cell directory. The files are replicated to every node in the
cell. Several different configuration settings apply to the entire cell. These settings include the definition of
virtual hosts, shared libraries, and any variables that you want consistent throughout the entire cell.

Chapter 1. Overview and new features for administering applications and their environments 11
12 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 2. How do I administer applications and their
environments?
v Establish the application serving environment
v Secure the application serving environment - see Security
v Set up Web access for applications
v Set up resources for applications to use
v Configure class loaders - see development and deployment
v Deploy and administer applications
v Use the administrative clients
v Troubleshoot deployment and administration

Legend for ″How do I?...″ links

Documentation Show me Tell me Guide me Teach me

Refer to the detailed Watch a brief View the presentation Be led through the Perform the tutorial
steps and reference multimedia for an overview console pages with sample code
demonstration
Approximate time: Approximate time: 3 Approximate time: Approximate time: Approximate time: 1
Varies to 5 minutes 10 minutes+ 1/2 hour+ hour+

Establish the application serving environment

The following tasks involve establishing application serving capability in your network environment,
whether you use single or clustered application servers. Servers can be grouped into administrative
domains known as nodes and cells.

See also the overview:

v Version 6 topology and terminology

--------------------------------------------------------------------------
Create WebSphere profiles
Profiles are the files that define a stand-alone Application Server node, a managed node, or a
deployment manager node. A profile also includes all of the files that the node can change.

Documentation Show me: Tell me

v Standalone node
v Deployment
manager
v Managed node

--------------------------------------------------------------------------
Administer nodes
A node is a grouping of managed servers. Use this task to view information about and manage
nodes.

© Copyright IBM Corp. 2004 13

Documentation Show me Tell me:
v Add and remove
nodes
v Manage node
groups
v Cell, deployment
managers, nodes,
and node agents

--------------------------------------------------------------------------
Administer node agents
Node agents are administrative agents that represent a node to your system and manage the
servers on that node. Node agents monitor application servers on a host system and route
administrative requests to servers. A node agent is created automatically when a node is added to
a cell.

Documentation Show me Tell me

--------------------------------------------------------------------------
Administer cells
When you installed the WebSphere Application Server Network Deployment product, a cell was
created. A cell provides a way to group one or more nodes of your Network Deployment product.
You probably will not need to reconfigure the cell. Use this task to view information about and
manage a cell.

Documentation Show me Tell me

--------------------------------------------------------------------------
Administer configurations
Application server configuration files define the available application servers, their configurations,
and their contents. You should periodically save changes to your administrative configuration. You
can change the default locations of configuration files, as needed.

Documentation Tell me:

v Repository
v Archives

--------------------------------------------------------------------------
Configure remote file services
Configuration data for the WebSphere Application Server product resides in files. Two services
help you reconfigure and otherwise manage these files: the file transfer service and file
synchronization service. By default, the file transfer service is always configured and enabled at a
node agent, so you do not need to take additional steps to configure this service. However, you
might need to configure the file synchronization service.

Documentation Tell me

--------------------------------------------------------------------------
Administer application servers

14 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Create, configure, and operate application server processes. An application server configuration
provides settings that control how an application server provides services for running enterprise
applications and their components.

Documentation: Show me Tell me

v Console
v Scripting -
configure
v Scripting -
administer

--------------------------------------------------------------------------
Administer other server types
One step in the process of creating an application server is to specify a template. A server
template is used to define the configuration settings of the new server. You have the option of
specifying the default server template or choosing a template that is based on a server that
already exists. The default template will be used if you do not specify a different template when
you create the server.
You can create other types of servers, to represent Web servers in your topology, or for other
purposes. There are two types of generic servers: (1) Non-Java applications or processes, or (2)
Java applications or processes. A custom service provides the ability to plug into a WebSphere
application server to define a hook point that runs when the server starts and shuts down.

Documentation: Tell me: Guide me (Web

v Generic servers v Generic servers servers)
v Server templates v Templates
v Custom services v Custom services

--------------------------------------------------------------------------
Balance workloads by clustering application servers
To monitor application servers and manage the workloads of servers, use server clusters and
cluster members provided by the Network Deployment product.

Documentation: Show me Tell me:

v Console v Server, cluster
v Scripting members
v Creating cluster
members
v WLM details
v Data replication
service

--------------------------------------------------------------------------
Establishing high availability (HA) for failover
Planning ahead for high availability support is important in order to avoid the risk of a failure
without failover coverage. The application server runtime of the infrastructure managed by a high
availability manager includes such entities as cells and clusters. These components relate closely
to core groups, high availability groups, and the policy that defines the high availability
infrastructure. In a properly configured high availability environment, a high availability manager
can reassess the environment it is managing and accept new components as they are added to
the environment.

Chapter 2. How do I administer applications and their environments? 15

Documentation Tell me:
v Overview
v Details, core
groups

--------------------------------------------------------------------------
Administer the UDDI registry
The UDDI Registry is supplied as a J2EE application file, uddi.ear. Change its configuration
properties using the assembly tools. You can use either the WebSphere Application Server
administrative console or the Java Management Extensions (JMX) management interface to
manage UDDI Registries.

Documentation: Show me Tell me Teach me

v Configure
v Administer

--------------------------------------------------------------------------

Set up Web access for applications

These tasks involve enabling HTTP requests for applications on the application server.

--------------------------------------------------------------------------
Administer communication with Web servers (plug-ins)
The product provides plug-ins for supported Web servers, to enable the Web servers to pass
requests to the application server, for applications running on the application server. See also the
Web server related tasks in How do I install an application serving environment?.

Documentation: Show me Tell me Guide me

v Console
v Scripting

--------------------------------------------------------------------------
Administer HTTP sessions
Configure the service that the product provides for managing HTTP sessions: Session Manager.

Documentation: Show me
v Console
v Scripting

--------------------------------------------------------------------------
Administer IBM HTTP Server Version 6.x
The product provides a complementary Web server with its own documentation that can be
installed into the information center.
--------------------------------------------------------------------------

16 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Set up resources for applications to use

Make a variety of resources available to your applications that are deployed on the application server.

--------------------------------------------------------------------------
Provide access to naming and directory resources (JNDI)
Configure naming. Naming is used by clients of WebSphere Application Server applications to
obtain references to objects related to those applications, such as Enterprise JavaBeans (EJB)
homes. These objects are bound into a mostly hierarchical structure, referred to as a name space.
The name space structure consists of a set of name bindings, each consisting of a name relative
to a specific context and the object bound with that name.

Documentation: Show me Tell me

v Name server
v Bindings

--------------------------------------------------------------------------
Provide access to relational databases (JDBC resources)
Configure data sources that applications use to access the data from databases.

Documentation: Show me: Tell me Guide me

v Console v Cloudscape
v Scripting v DB2
v Oracle

--------------------------------------------------------------------------
Provide access to messaging resources (default messaging provider)
Use one of various ways to implement a messaging provider for use with WebSphere Application
Server. A messaging provider enables use of the Java Messaging Service (JMS) and other
message resources in the product.

Documentation: Show me Tell me Teach me

v Console
v Scripting

--------------------------------------------------------------------------
Use IBM service integration technologies

Tell me: Teach me

v Overview
v Architecture
v Mediation

--------------------------------------------------------------------------
Establish workload balancing and high availability (HA) of messaging engines

Tell me

--------------------------------------------------------------------------

Chapter 2. How do I administer applications and their environments? 17

Access Service Integration (SI) bus resources

Show me Tell me:

v Service integration
bus resources
v JMS resources for
service integration
bus

--------------------------------------------------------------------------

Deploy and administer applications

These tasks involve deploying applications onto the application server, then administering the applications.

--------------------------------------------------------------------------
Install applications
Installable modules include enterprise archive (EAR), enterprise bean (EJB), Web archive (WAR),
resource adapter (connector or RAR), and application client files.

Documentation Show me Tell me

v Console
v Scripting

--------------------------------------------------------------------------
Start and stop applications
You can start an application that is not running (has a status of Stopped) or stop an application
that is running (has a status of Started).

Documentation: Show me Tell me

v Console
v Scripting

--------------------------------------------------------------------------
Update applications
Update deployed applications or modules using the administrative console or wsadmin scripting.
Learn which changes are candidates for hot deployment and dynamic reloading, in which you can
make various changes to applications and their modules without having to stop the server and
start it again.

Documentation: Tell me Teach me

v Console
v Scripting

--------------------------------------------------------------------------
Deploy applications rapidly (WebSphere Rapid Deployment)
Take advantage of new rapid deployment capabilities. WebSphere rapid deployment offers the
following advantages: You do not need to assemble your J2EE application files prior to
deployment. You do not need to use other installation tools mentioned in this table to deploy the
files. Refer to the Rapid deployment tools documentation in the information center.

18 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 --------------------------------------------------------------------------
Enhanced EAR files

Tell me Teach me

--------------------------------------------------------------------------
Deploy and administer Web services applications
To deploy Web services that are based on the Web Services for Java 2 platform, Enterprise
Edition (J2EE) specification, you need an enterprise application, also known as an enterprise
archive (EAR) file that has been configured and enabled for Web services. You can use either the
administrative console or the wsadmin scripting interface to deploy an EAR file.

Documentation Show me Tell me Teach me

--------------------------------------------------------------------------

Use the administrative clients

A variety of tools are provided for administering the product.

--------------------------------------------------------------------------
Choose an administrative client
Learn about and decide among the available administrative clients, including a graphical console,
scripting (wsadmin), command line tools, and Java Management Extensions (JMX) programs.

Documentation Tell me

--------------------------------------------------------------------------
Use the administrative console
The administrative console is a Web-based tool that you use to administer the product. The
administrative console supports a full range of product administrative activities.

Documentation Show me Tell me

--------------------------------------------------------------------------
Use scripting (wsadmin)
Scripting is a non-graphical alternative that you can use to configure and manage WebSphere
Application Server. The WebSphere Application Server wsadmin tool provides the ability to run
scripts. The tool supports a full range of product administrative activities.

Documentation Tell me

--------------------------------------------------------------------------

See also:
v Start, stop, monitor processes
v Other administrative commands
v Custom Java administrative clients (JMX)

Chapter 2. How do I administer applications and their environments? 19

Troubleshoot deployment and administration

Troubleshoot problems that occur when you are deploying applications onto the application server, or
when you are administering an established application serving environment.

--------------------------------------------------------------------------
Troubleshoot deployment
Troubleshoot problems that occur either during deployment or shortly afterwards, when you try to
access an application that you just deployed for the first time.

Documentation

--------------------------------------------------------------------------
Troubleshoot administration
Review some possible causes, based on the error you are seeing.

Documentation

--------------------------------------------------------------------------

20 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 3. Setting up the application serving environment
This topic summarizes the contents of the documentation that helps you set up your application serving
environment. This information is for administrators, particularly those performing installation, customization,
and maintenance of topologies.
“Planning the installation (diagrams)”
In preparation for installation, this topic describes common product topologies that you can install
with WebSphere Application Server, Version 6 products.
“Configuring the product after installation” on page 47
This topic describes what to do after installing the product.
If you are using Network Deployment, you must configure a profile.
You can display the First Steps tool, an easy way to get started with the product.
“Configuring ports” on page 113
This topic provides information about port number settings for Version 6 and previous versions, for
use in coexistence and interoperability situations.
“Communicating with Web servers” on page 116
This topic describes how to install and configure WebSphere plug-ins for Web servers, enabling
communication between Web servers and application servers.
“Setting up the administrative architecture” on page 139
This topic describes how to set up logical administrative domains, including cells and nodes.
“Configuring the environment” on page 174
This topic describes how to configure cell-wide settings for virtual hosts, variables and shared
libraries to assist in handling requests among Web applications, Web containers, and application
servers.
“Working with server configuration files” on page 191
This topic describes how to change the default locations of configuration files, as needed.
Application server configuration files define the available application servers, their configurations,
and their contents.
“Administering application servers” on page 198
This topic describes how to configure individual application servers to provides services for running
enterprise applications and their components.
“Balancing workloads with clusters” on page 268
This topic describes how to configure clusters, which are sets of servers that are managed
together and participate in workload management.
“Setting up a high availability environment” on page 298
This topic describes planning ahead for high availability support, which is important in order to
avoid the risk of a failure without failover coverage. In a properly setup high availability
environment, a high availability manager can reassess the environment it is managing and accept
new components as they are added to the environment.

Planning the installation (diagrams)

This topic describes common product topologies that you can install with the product.

© Copyright IBM Corp. 2004 21

Use this topic to understand the capabilities of your product package. Knowing what you can do with the
product might influence how you install the product and other installable components on the product disc.

This topic describes topology diagrams and shows you how to create the topologies by showing what
components to install for each topology.

Phased installation roadmap

To install a Version 6 production environment, you install the following components:

v The WebSphere Application Server product on your product CD
v A supported Web server, such as the IBM HTTP Server V6 on the product CD
v A binary plug-in module for your Web server from the product CD

You can also use the product CD to install an application client environment on a client machine. Running
Java 2 Platform, Enterprise Edition (J2EE) and thin application clients that communicate with WebSphere
Application Server requires that elements of the Application Server are installed on the machine on which
the client runs. However, if the machine does not have the Application Server installed, you can install
Application Server clients to provide a stand-alone client run-time environment for your client applications.

You can use the Application Server Toolkit CD in the primary packet of discs to install a development
environment. Or you can use the Rational Application Developer Trial CD in the supplemental packet of
discs to install a fully integrated development environment that includes an exact replica of the Application
Server for development testing.

Installation features

Installation features in V6 include:

Feature Description
The Network Deployment product You can use the Profile creation wizard to create deployment manager profiles,
includes Application Server and Application Server profiles, and custom profiles after installing the WebSphere
managed nodes. Application Server Network Deployment product. You do not have to install
another set of binary files to install an Application Server. All profiles on a
machine share the core product files of the Profile creation wizard. (If you install
again to create another set of core product files, there are two Profile creation
wizards. One for each set of core product files.)
The product CD includes all of the You can use the product CD to install the IBM HTTP Server, the Web server
installable components that are plug-ins, and the WebSphere Application Server Clients. You do not have to use
required to create an e-business separate CDs. Separate installation programs exist within component directories
environment. on the product CD.
Each installable component has its You can use the V6 launchpad to install any installable component on the
own installation program. product CD. Or you can install each component directly using the install
command in each component directory.
The launchpad can install any The launchpad can also install the Application Server Toolkit on Windows 2000
installable product in the primary and Linux (Intel) systems. The Application Server Toolkit is on a separate disc,
packet of compact discs. which requires you to change discs to launch the installation.

Review topology diagrams for each of the following installable components to determine which topology
best fits your needs. The diagrams and their accompanying procedures can serve as a roadmap for
installing a similar topology.

This topic describes installation scenarios for the following installable components:
v WebSphere Application Server Network Deployment
v Web server plug-ins

22 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Application clients

In addition to product installation diagrams for the installable components, this topic also links to a
roadmap for using the Profile creation wizard, which is new for Version 6. The Profile creation wizard lets
you create run-time environments for application server processes.

Each of the following installation scenarios includes topology diagrams and associated installation steps.
Each step links to a specific procedure for installing a component or to a description of a command or tool.
1. Review the installation scenarios for the Network Deployment product, as described in “Planning to
install Network Deployment.”
2. Review the installation scenarios for the WebSphere Application Server plug-ins, as described in
“Planning to install Web server plug-ins” on page 31.
3. Review the installation scenarios for the application clients, as described in “Planning to install
WebSphere Application Server Clients” on page 38.
4. Review the installation scenarios for the Profile creation wizard, as described in “Planning to create
application server environments” on page 39.
5. Optional: Review interoperability and coexistence diagrams to know what is possible with Version 6.
WebSphere Application Server V6 can interoperate with your other e-business systems, including other
versions of WebSphere Application Server. Interoperability provides a communication mechanism for
WebSphere Application Server nodes that are at different versions. Coexistence describes multiple
versions or instances running on the same machine, at the same time.
Interoperability support enhances migration scenarios with more configuration options. It often is
convenient or practical to interoperate during the migration of a configuration from an earlier
WebSphere Application Server version to a later one when some machines are at the earlier version
and some machines are at the later version. The mixed environment of machines and application
components at different software version levels requires interoperability and coexistence.
It is often impractical, or even physically impossible, to migrate all the machines and applications within
an enterprise at the same time. Understanding multiversion interoperability and coexistence is
therefore an essential part of a migration between version levels.
See the following topics for more information:
a. Interoperating
b. Setting up Version 4.0.x and Version 6 coexistence
c. Setting up Version 5 and Version 6 coexistence
d. Setting up Version 6 coexistence
6. Optional: Consider performance when designing your network, as described in “Example: Choosing a
topology for better performance” on page 42 and “Queuing network” on page 43.

You can review installation scenarios to identify the specific steps to follow when installing more than one
component on a single machine or on separate machines.

After determining an appropriate installation scenario, you are ready to install the necessary components
and to configure the products for the system that you selected.

Planning to install Network Deployment

This topic describes common installation scenarios and links to component installation procedures.

In Version 6.0, installing WebSphere Application Server Network Deployment is a two-step process. The
first step is using the installation wizard to install a shared set of core product files. The second step is
using the Profile creation wizard to create a deployment manager profile, an Application server profile, or a
custom profile.

Chapter 3. Setting up the application serving environment 23

A profile is a separate data partition that includes the files that define a run-time environment for an
application server process.

A running application server process, such as a deployment manager, can create, read, update, or delete
the configuration files, data files, and log files in its profile. The application server process has read-only
access to the system files, which include command files and other shared product binary files. System files
are updated only by installing refresh packs or fix packs, or by products that extend WebSphere
Application Server Network Deployment.

Machine A

WebSphere Application Server Network Deployment, Version 6.0

Step 1: Install Product Step 2: Create profiles

Shared product binaries

Profiles
( system files )

Scenarios for installation

The following information describes scenarios for installing the product in various topologies on one or
more machines. Two types of WebSphere Application Server topologies are possible using the Network
Deployment product:
v Topologies for a stand-alone application server
v Topologies for a managed group of application servers

Topologies for a stand-alone application server

Each stand-alone application server has its own administrative console and runs independently of other
application servers.

The following topologies are described in this topic.

v Scenario 1: Single-machine installation of a stand-alone application server
v Scenario 2: Single-machine installation of a stand-alone application server and a Web server
v Scenario 3: Two-machine installation of a stand-alone application server and a Web server
v Scenario 4: Two-machine installation of multiple stand-alone application servers and a Web server

Topologies for a managed group of application servers

A managed group of application servers is called a cell. A cell consists of one deployment manager and
one or more federated application servers, which are called managed nodes.

A node becomes a managed node in either of two ways:

v Federating the node within an Application Server profile into the cell
v Federating the node within a custom profile into the cell

The deployment manager is the single point of administration for all of the managed nodes in the cell. The
deployment manager maintains the configuration files for nodes that it manages and deploys applications
to those managed nodes.

The following topologies for a cell are described in this topic.

24 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Scenario 5: Single-machine installation of a cell of application servers
v Scenario 6: Single-machine installation of a cell of application servers and a Web server
v Scenario 7: Two-machine installation of a cell of application servers and a Web server
v Scenario 8: Three-machine installation of a cell of application servers and a Web server

Each of the following scenarios includes a diagram and a list of detailed installation steps.

Some scenarios are more typical in production environments. For example, Scenario 1 supports a lighter
workload than Scenario 3 or Scenario 4. However, Scenario 1 is a fully functional environment. Scenarios
3 and 4 are typical production environments for a stand-alone application server. Scenario 8 is a typical
production scenario for a cell environment.
v Scenario 1: Install a stand-alone application server on a single machine.
Installing WebSphere Application Server Network Deployment by itself on a single machine lets you
create a stand-alone Application Server profile. Each stand-alone application server profile includes a
server1 application server process. Installing Network Deployment creates the set of system files. The
Profile creation wizard creates the profile for the application server. The profile is a separate data
partition with files that define the stand-alone application server environment.
In this scenario, the application server uses its internal HTTP transport chain for communication, which
is suitable for handling an application with a relatively low request work load. For example, this type of
installation can support a simple test environment or a departmental intranet environment.

Machine A

WebSphere Application Server, Version 6.0

Shared product binaries Profile01

( system files )

1. Install WebSphere Application Server Network Deployment.

2. Create an Application Server profile using the Profile creation wizard.
v Scenario 2: Install a stand-alone application server and a Web server on a single machine.
Installing a Web server, such as IBM HTTP Server, on the same machine as the application server
provides a more robust Web server environment. Installing a Web server plug-in is a requirement for the
Web server to communicate with the application server. This type of installation supports rigorous
testing environments or production environments that do not require a firewall. However, this is not a
typical production environment.

Machine A Data tier, optional

Web client Web server

Application
(browser)
Server
Plug-in
Application
data

1. Install WebSphere Application Server Network Deployment.

2. Create an Application Server profile using the Profile creation wizard.
3. Install IBM HTTP Server or another supported Web server.
4. Install the Web server plug-ins and configure the Web server using the Plug-ins installation wizard.

Chapter 3. Setting up the application serving environment 25

v Scenario 3: Install a stand-alone application server and a Web server on separate machines.
In the typical production environment, the application server on one machine communicates with a Web
server on a separate (remote) machine through the Web server plug-in. Optional firewalls can provide
additional security for the application server machine.
Firewall Firewall

Machine B Machine A Data tier, optional

Web server
Web client Application
(browser) Machine A
Server
Plug-in

Application
data

Internet Intranet

1. Install WebSphere Application Server Network Deployment on Machine A.

2. Create an Application Server profile using the Profile creation wizard on Machine A.
3. Install IBM HTTP Server or another supported Web server on Machine B.
4. Install the Web server plug-ins and configure the Web server using the Plug-ins installation wizard.
5. The Plug-ins installation wizard creates a script named configureWeb_server_name in the
plugins_install_root/bin directory on Machine B. Copy the script to the install_root/bin directory on
Machine A.
6. Run the configureWeb_server_name script to create a Web server definition in the administrative
console. You can then use the administrative console to manage the Web server.
7. Propagate the plugin-cfg.xml file from the application server to the Web server using the
administrative console. Click Servers > Web server > Propagate Plug-in. (Web servers other than
IBM HTTP Server require manual propagation.)
v Scenario 4: Install multiple stand-alone application servers on one machine and a Web server on a
separate machine.
The Profile creation wizard can create a deployment manager profile, an application server profile, or a
custom profile. Each profile is a separate data partition containing the files that define the run-time
environment. After creating a profile and installing a dedicated Web server, use the Plug-ins installation
wizard to install a plug-in and to update the Web server configuration file. The Web server can then
communicate with the application server.
This topology lets each profile have unique applications, configuration settings, data, and log files, while
sharing the same set of system files. Creating multiple profiles creates multiple application server
environments that you can dedicate to different purposes.
For example, each application server on a Web site can serve a different application. In another
example, each application server can be a separate test environment that you assign to a programmer
or a development team.
Updating the core product files
Another feature of having multiple profiles is enhanced serviceability. When a refresh pack or a fix pack
updates the core product files on a machine, all of the application server profiles that were created from
the core product files begin using the updated files. In some situations, you might prefer to not update
all of the application servers on a machine. In such situations, simply install the product a second time
to create a second set of core product files. Create application server profiles from both installations to
manage the product updates incrementally.

26 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Firewall Firewall

Machine B Machine A Data tier, optional

Profile01
Web server
Application
Server 1
Plug-in
application 1
Web client Application
(browser) Machine A data

Profile02
Web server
Application
Application
Server
Server2
Plug-in application 2
Machine A

Internet Intranet

1. Install WebSphere Application Server Network Deployment on Machine A.

2. Create the first Application Server profile using the Profile creation wizard on Machine A.
3. Install IBM HTTP Server or another supported Web server on Machine B.
4. On Machine B, install the Web server plug-ins and configure the first Web server using the
Plug-ins installation wizard.
5. The Plug-ins installation wizard creates a script named configureWeb_server_name in the
plugins_install_root/bin directory on Machine B. Copy the script to the install_root/bin directory on
Machine A.
6. Run the configureWeb_server_name script to create a Web server definition in the administrative
console. You can then use the administrative console to manage the Web server.
7. Propagate the plugin-cfg.xml file from the application server to the Web server using the
administrative console. Click Servers > Web server > Propagate Plug-in. (Web servers other
than IBM HTTP Server require manual propagation.)
8. Create the second Application Server profile using the Profile creation wizard on Machine A. Make
the profile the default profile during the profile creation by selecting the check box on the
appropriate panel.
The script that the Plug-ins installation wizard creates works on the default profile only. So, this
script can only create a Web server definition on the profile that is the default profile at the time
that the script runs.
9. Install a second IBM HTTP Server or another supported Web server on Machine B.
10. On Machine B, install the Web server plug-ins to configure the second Web server using the
Plug-ins installation wizard. Both Web servers share a single installation of the plug-in binaries but
must be configured individually.
11. The Plug-ins installation wizard creates a script named configureWeb_server_name for the second
Web server. The script is in the plugins_install_root/bin directory on Machine B. Copy the script to
the install_root/bin directory on Machine A.
12. Run the configureWeb_server_name script to create a Web server definition in the administrative
console. You can then use the administrative console to manage the Web server.
13. Propagate the plugin-cfg.xml file from the second application server to the Web server using the
administrative console. Click Servers > Web server > Propagate Plug-in. (Web servers other
than IBM HTTP Server require manual propagation.)
v Scenario 5: Install a cell of managed application server nodes on one machine.
WebSphere Application Server Network Deployment can create a cell of managed application servers
on a single machine from one installation of the core product files. The Profile creation wizard creates
the deployment manager. After starting the deployment manager, return to the Profile creation wizard to
create one or more application servers for the cell. Application server profiles have a default application

Chapter 3. Setting up the application serving environment 27

 server, called server1, and default applications. An Application Server node becomes a managed node
after federating the node into the deployment manager cell.
The deployment manager provides the administration for all managed nodes that are in its cell.
Periodically the configuration and application files on a managed node refresh from the master copy of
the files hosted on the deployment manager during synchronization.
In certain secure environments, the Profile creation wizard cannot federate a custom profile into a cell.
Such cases require you to use the addNode command instead. If you have configured the deployment
manager to use a JMX connector type other than the default SOAP connector, use the addNode
command to add the node to the cell.
The deployment manager provides the administration for all managed nodes that are in its cell.
Periodically the deployment manager refreshes the configuration files and application files on the
managed node. Copying the master version of the files hosted on the deployment manager to the
managed nodes is a process called synchronization.
In a cell environment, only the managed nodes serve applications, not the deployment manager. The
managed node in this scenario uses its internal HTTP transport chain for communication, which is
suitable for an application with a relatively low request work load. For example, this type of installation
can support a simple test environment or a departmental intranet environment.
Machine A

Profile02 Profile01

server1 dmgr
( managed Node ( deployment
node ) agent manager )

1. Install WebSphere Application Server Network Deployment.

2. Create a deployment manager profile using the Profile creation wizard.
3. Start the deployment manager using the First steps console or the startManager command.
4. Create an Application Server profile using the Profile creation wizard.
5. Start the application server using the First steps console or the startServer server1 command.
6. Add the application server node to the cell using the administrative console of the deployment
manager. Click System Administration > Nodes to add the node.
v Scenario 6: Install a cell of managed application server nodes and a Web server on one machine.
Installing a Web server, such as IBM HTTP Server, on the same machine as the application server
provides a richer set of configuration options. Installing a Web server plug-in is required for the Web
server to communicate with the server in the managed node. This type of installation can support either
rigorous testing in a cell environment or production environments that do not require a firewall.
Machine A

dmgr
( deployment
manager )

Data tier, optional

Node agent

Web client Web server server1

(browser) ( managed
Plug-in node ) Application
data

1. Install WebSphere Application Server Network Deployment.

28 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 2. Create a deployment manager profile using the Profile creation wizard.
3. Start the deployment manager using the First steps console or the startManager command.
4. Create an Application Server profile using the Profile creation wizard.
5. Start the application server using the First steps console or the startServer server1 command.
6. Add the application server node to the cell using the administrative console of the deployment
manager. Click System Administration > Nodes to add the node.
7. Install IBM HTTP Server or another supported Web server.
8. Install the Web server plug-ins and configure the Web server using the Plug-ins installation wizard.
9. The Plug-ins installation wizard creates a script named configureWeb_server_name in the
plugins_install_root/bin directory. Run the configureWeb_server_name script to create a Web server
definition in the administrative console. You can then use the administrative console to manage the
Web server.
v Scenario 7: Install a cell of managed application server nodes on one machine and a Web server on a
separate machine.
In a typical production environment, a managed node in a cell communicates with a Web server on a
separate (remote) machine through the Web server plug-in. An optional firewall can provide additional
security for the application server machine.

Firewall

Machine A

dmgr
(deployment
manager )

Data tier, optional

Machine B Node agent

Web client Web server

server1
(browser) ( managed
Plug-in Application
node )
data

Internet Intranet

1. Install WebSphere Application Server Network Deployment on Machine A.

2. Create a deployment manager profile using the Profile creation wizard on Machine A.
3. Start the deployment manager using the First steps console or the startManager command on
Machine A.
4. Create the Application Server profile and make this profile the default profile using the Profile
creation wizard on Machine A.
5. Start the application server using the First steps console or the startServer server1 command on
Machine A.
6. Add the application server node to the cell using the administrative console of the deployment
manager on Machine A. Click System Administration > Nodes to add the node.
7. Install IBM HTTP Server or another supported Web server on Machine B.
8. On Machine B, install the Web server plug-ins and configure the Web server using the Plug-ins
installation wizard.
9. The Plug-ins installation wizard creates a script named configureWeb_server_name in the
plugins_install_root/bin directory on Machine B. Copy the script from Machine B to the
install_root/bin directory on Machine A.

Chapter 3. Setting up the application serving environment 29

 You have the option of using the script to create the Web server definition in the configuration of
the deployment manager or using the administrative console of the deployment manager to create
the Web server definition.
10. Run the configureWeb_server_name script on Machine A to create a Web server definition or use
the administrative console of the deployment manager to create the definition. You can then use
the administrative console to manage the Web server.
11. Propagate the plugin-cfg.xml file from the deployment manager on Machine A to the Web server
on Machine B using the administrative console. Click Servers > Web server > Propagate Plug-in.
(Web servers other than IBM HTTP Server require manual propagation.)
v Scenario 8: Install a deployment manager on one machine, multiple managed application server nodes
on a second machine, and a Web server on a third machine.
The primary advantage of a cell over a stand-alone application server is its scalability. Managing a cell
to keep it in proportion with workload levels is possible. In this scenario, managed nodes exist on
Machine C. All of the managed nodes are federated into the same deployment manager. Depending on
your needs, an application server in each managed node could serve the same or different applications.
Having multiple machines and multiple application server profiles lets you use vertical and horizontal
scaling:
– Vertical scaling creates multiple managed nodes on the same physical machine.
– Horizontal scaling creates cell members on multiple physical machines.
The managed nodes in this scenario communicate with the same Web server. However, the preferred
strategy is to have a dedicated Web server for each managed node.

Firewall
Machine A

dmgr
(deployment
manager )

Node Node
agent agent

server1 Data tier, optional

Machine B ( managed
node )

Web client Web server

server1
(browser) ( managed
Plug-in Application
node )
data

Machine C
Internet Intranet

1. Install WebSphere Application Server Network Deployment on Machine A.

2. Create a deployment manager profile using the Profile creation wizard on Machine A.
3. Start the deployment manager using the First steps console or the startManager command on
Machine A.
4. Install WebSphere Application Server Network Deployment on Machine C.
5. Create the first Application Server profile using the Profile creation wizard on Machine C.
6. Start the first application server using the First steps console or the startServer server1 command
on Machine C.
7. Create the second Application Server profile and make this profile the default profile using the
Profile creation wizard on Machine C.
30 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 8. Start the second Application Server using the First steps console or the startServer server1
command on Machine C.
9. Add both application server nodes to the cell using the administrative console of the deployment
manager on Machine A. Click System Administration > Nodes to add the nodes.
10.
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.ihs.doc/info/aes/ae/tihs_install.
or another supported Web server on Machine B.
11. Install the Web server plug-ins and configure the Web server using the Plug-ins installation wizard
on Machine B.
12. The Plug-ins installation wizard creates a script named configureWeb_server_name in the
plugins_install_root/bin directory on Machine B. Copy the script from Machine B to the
install_root/bin directory on Machine A.
You have the option of using the script to create the Web server definition in the configuration of
the deployment manager or using the administrative console of the deployment manager to create
the Web server definition.
13. Run the configureWeb_server_name script on Machine A to create a Web server definition or use
the administrative console of the deployment manager to create the definition. You can then use
the administrative console to manage the Web server.
14. Propagate the plugin-cfg.xml file from the deployment manager on Machine A to the Web server
on Machine B using the administrative console. Click Servers > Web server > Propagate Plug-in.
(Web servers other than IBM HTTP Server require manual propagation.)

You can review common installation scenarios to find a possible match for the topology that you intend to
install. Each product installation diagram provides a high-level procedure for installing the components that
comprise the topology.

After determining a possible topology, follow the steps in the overall procedure. Useful links to the
installation procedures for each installable component are in the list of related topics.

Planning to install Web server plug-ins

This topic describes common installation scenarios and links to component installation procedures for each
scenario.

The primary production configuration is an application server on one machine and a Web server on a
separate machine. This configuration is referred to as a remote configuration. Contrast the remote
configuration to the local configuration, where the application server and the Web server are on the same
machine.

The Plug-ins installation wizard has four main tasks:

v Installs the binary plug-in module on the Web server machine.
v Configures the Web server configuration file on the Web server machine to point to the binary plug-in
module and to the XML configuration file for the binary module.
v Installs a temporary XML configuration file for the binary module (plugin-cfg.xml) on the Web server
machine in remote scenarios.
v Creates the configuration for a Web server definition on the application server machine. The wizard
processes the creation of the Web server definition differently depending on the scenario:
Web server plug-in installation for stand-alone application server environments
– Recommended remote stand-alone Application Server installation:
Creates a configuration script that you run on the application server machine. Install the Web server
and its plug-in on a different machine than the application server. This configuration is recommended
for a production environment.
– Local stand-alone Application Server installation:

Chapter 3. Setting up the application serving environment 31

 Detects the default profile on a local application server machine and creates the Web server
definition for it directly. Install the Web server and its plug-in on the same machine with the
application server. This configuration is for development and test environments.
Web server plug-in installation for distributed environments (cells)
– Recommended remote distributed installation:
Creates a configuration script that you run on the application server machine. Install the Web server
and its plug-in on a different machine than the deployment manager or managed node. This
configuration is recommended for a production environment.
– Local distributed installation:
Creates a configuration script that you run when the deployment manager is running. Install the Web
server and its plug-in on the same machine with the deployment manager or a managed node. This
configuration is for development and test environments.

Select a link to go to the appropriate steps in the following procedure.

v Set up a remote Web server installation.
The remote Web server configuration is recommended for production environments.
The remote installation installs the Web server plug-in on the Web server machine when the application
server is on a separate machine, such as shown in the following graphic:

Firewall
optional

Machine B Machine A

WebSphere
Web server Application
Server

Plug-in

Remote installation scenario

Table 1. Installation and configuration
Step Machine Task
1 A Install your WebSphere Application Server product. See ″Installing the product and
additional software″ in the information center.
2 A Create an application server profile. See “Using the Profile creation wizard” on page 54.
3 B Install IBM HTTP Server or another supported Web server. See ″Installing IBM HTTP
Server″ in the information center.
4 B Install the binary plug-in module using the Plug-ins installation wizard. See ″Configuring
a Web server and an application server on separate machines (remote)″ in the
information center.

The script for creating and configuring the Web server is created under the
plug-ins_install_root/ bin directory.
5 B Copy the configureWeb_server_name script to Machine A. If one machine is running
under Linux or UNIX and the other machine is running under Windows, copy the script
from the plug-ins_install_root/ bin/ crossPlatformScripts directory.
6 A Paste the configureWeb_server_name script from Machine B to the was_install_root/
bin directory on Machine A.
7 A Run the script from a command line.

32 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Table 1. Installation and configuration (continued)
Step Machine Task
8 A Verify that the application server is running. Open the administrative console and save
the changed configuration.
9 B
Run the plug-ins_install_root/setupPluginCfg.sh script for a
Domino Web Server before starting a Domino Web server.Otherwise, start the Web
server.
10 B Run the snoop servlet. See ″Troubleshooting installation″ in the information center.

To verify with your own application, regenerate and propagate the plugin-cfg.xml file
after installing the application.

Regeneration of the plugin-cfg.xml file

During the installation of the plug-ins, the temporary plugin-cfg.xml file is installed on Machine B in the
plug-ins_install_root/ config/ web_server_name directory.
The Web server plug-in configuration service regenerates the plugin-cfg.xml file automatically.
To use the real plugin-cfg.xml file from the application server, propagate the plugin-cfg.xml file as
described in the next section.
Propagation of the plugin-cfg.xml file
The Web server plug-in configuration service propagates the plugin-cfg.xml file automatically for IBM
HTTP Server 6.0 only.
For all other Web servers, propagate the plug-in configuration file manually. Copy the plugin-cfg.xml
file from the profiles_install_root/ config/ cells/ cell_name/ nodes/ Web_server_name_node/
servers/ web_server_name directory on Machine A. Paste the file into the plug-ins_install_root/
config/ web_server_name directory on Machine B.
v Set up a local Web server configuration.
The local Web server configuration is recommended for a development or test environment.
A local installation includes the Web server plug-in, the Web server, and the application server on the
same machine:

Machine A

WebSphere
Web server Application
Server

Plug-in

Local installation scenario

Table 2. Installation and configuration
Step Machine Task
1 A Install your WebSphere Application Server product. See ″Installing the product and
additional software″ in the information center.
2 A Create an application server profile. See “Using the Profile creation wizard” on page 54.
3 A Install IBM HTTP Server or another supported Web server. See ″Installing IBM HTTP
Server″ in the information center.

Chapter 3. Setting up the application serving environment 33

Table 2. Installation and configuration (continued)
Step Machine Task
4 A Install the binary plug-in module using the Plug-ins installation wizard. See See
″Configuring a Web server and an application server on separate machines (remote)″
in the information center.

The Web server definition is automatically created and configured during the installation
of the plug-ins.
5 A Verify that the application server is running. Open the administrative console and save
the changed configuration.
6 B
Run the plug-ins_install_root/setupPluginCfg.sh script for a
Domino Web Server before starting a Domino Web server.Otherwise, start the Web
server.
7 B Run the Snoop servlet.

To verify with your own application, regenerate and propagate the plugin-cfg.xml file
after installing the application.

Regeneration of the plugin-cfg.xml file

The Web server plug-in configuration service regenerates the plugin-cfg.xml file automatically.
The plugin-cfg.xml file is generated in the profiles_install_root/ profile_name/ config/ cells/
cell_name/ nodes/ Web_server_name_node/ servers/ web_server_name directory. The generation occurs
when the Web server definition is created.
Propagation of the plugin-cfg.xml file
The local file does not require propagation.
v Set up a remote Web server installation in a cell.
The remote Web server configuration is recommended for production environments.
The remote installation installs the Web server plug-in on the Web server machine when the application
server is on a separate machine, such as shown in the following graphic:

Firewall
optional

Machine C Machine A

Deployment
Web server Manager

Federate
Plug-in Machine B

WebSphere
Application
Server node

Remote installation scenario

Table 3. Installation and configuration
Step Machine Task
1 A Install WebSphere Application Server Network Deployment. See ″Installing the product
and additional software″ in the information center.

34 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Table 3. Installation and configuration (continued)
Step Machine Task
2 A Create a deployment manager profile. See “Using the Profile creation wizard” on page
54.
3 A Start the deployment manager with the ./profiles_install_root/ profile_name/ bin/
startManager.sh command or its Windows equivalent.
4 B Install WebSphere Application Server Network Deployment. See ″Installing the product
and additional software″ in the information center.
5 B Create an application server profile. See “Using the Profile creation wizard” on page 54.
6 B Federate the node with the ./profiles_install_root/ profile_name/ bin/
addNode.sh dmgrhost 8879 -includeapps command or its Windows equivalent.
7 C Install IBM HTTP Server or another supported Web server. See ″Installing IBM HTTP
Server″ in the information center.
8 C Install the binary plug-in module using the Plug-ins installation wizard. See ″Configuring
a Web server and an application server on separate machines (remote)″ in the
information center.

The script for creating and configuring the Web server is created under the
plug-ins_install_root/ bin directory.
9 C Copy the configureWeb_server_name script to Machine A.

If one machine is running under Linux or UNIX and the other machine is running under
Windows, copy the script from the plug-ins_install_root/ bin/
crossPlatformScripts directory.
10 A Paste the configureWeb_server_name script from Machine C to the was_install_root/
bin directory on Machine A.
11 A Run the script from a command line after verifying that the deployment manager is
running.

If you have enabled security or changed the default JMX connector type, edit the script
and include the appropriate parameters on the wsadmin command.
12 A/B Use the administrative console of the deployment manager on Machine A to start the
application server on Machine B. Wait for synchronization to occur and save the new
configuration.
13 C
Run the plug-ins_install_root/setupPluginCfg.sh script for a
Domino Web Server before starting a Domino Web server.Otherwise, start the Web
server.
14 C Run the Snoop servlet.

To verify with your own application, regenerate and propagate the plugin-cfg.xml file
after installing the application.

Regeneration of the plugin-cfg.xml file

During the installation of the plug-ins, the temporary plugin-cfg.xml file is installed on Machine C in the
plug-ins_install_root/ config/ web_server_name directory.
The Web server plug-in configuration service regenerates the plugin-cfg.xml file automatically.
To use the real plugin-cfg.xml file from the application server, propagate the plugin-cfg.xml file as
described in the next section.
Propagation of the plugin-cfg.xml file
The Web server plug-in configuration service propagates the plugin-cfg.xml file automatically for IBM
HTTP Server 6.0 only.

Chapter 3. Setting up the application serving environment 35

 For all other Web servers, propagate the plug-in configuration file, by manually copying the
plugin-cfg.xml file from the profiles_install_root/ profile_name/ config/ cells/ cell_name/
nodes/ node_name/ servers/ web_server_name directory on Machine A to the plug-ins_install_root/
config/ web_server_name directory on Machine C.
v Set up a local distributed Web server configuration.
The local Web server configuration is recommended for a development or test environment.
A local distributed installation includes the Web server plug-in, the Web server, and the managed
application server on the same machine:

Machine B Machine A

Deployment
Web server Manager

Federate

WebSphere
Plug-in Application
Server node

Local distributed installation scenario

Table 4. Installation and configuration
Step Machine Task
1 A Install WebSphere Application Server Network Deployment. See ″Installing the product
and additional software″ in the information center.
2 A Create a deployment manager profile. See ″Installing the product and additional
software″ in the information center.
3 A Start the deployment manager with the profiles_install_root/ profile_name/ bin/
startManager.sh command or its Windows equivalent.
4 B Install WebSphere Application Server Network Deployment. See ″Installing the product
and additional software″ in the information center.
5 B Create an application server profile. See ″Installing the product and additional software″
in the information center.
6 B Federate the node with the ./profiles_install_root/ profile_name/ bin/addNode.sh
dmgrhost 8879 -includeapps command or its Windows equivalent.
7 B Install IBM HTTP Server or another supported Web server. See ″Installing IBM HTTP
Server″ in the information center.
8 B Install the binary plug-in module using the Plug-ins installation wizard. See ″Configuring
a Web server and an application server on separate machines (remote)″ in the
information center.

The script for creating and configuring the Web server is created in the
plug-ins_install_root/ bin directory.
11 B After verifying that the deployment manager is running on Machine A, run the
configureWeb_server_name script from a command line in the plug-ins_install_root/
bin directory on Machine B.

If you have enabled security or changed the default JMX connector type, edit the script
and include the appropriate parameters.

36 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Table 4. Installation and configuration (continued)
Step Machine Task
12 A/B Use the administrative console of the deployment manager on Machine A to start the
application server on Machine B. Wait for synchronization to occur and save the new
configuration.
13 B
Run the plug-ins_install_root/setupPluginCfg.sh script for a
Domino Web Server before starting a Domino Web server.Otherwise, start the Web
server.
14 B Run the Snoop servlet.

Regeneration of the plugin-cfg.xml file

The Web server plug-in configuration service regenerates the plugin-cfg.xml file automatically.
The plugin-cfg.xml file is generated at the location profiles_install_root/ profile_name/ config/
cells/ cell_name/ nodes/ node_name/ servers/ web_server_name directory, when the Web server
definition is created.
Regenerate the plugin-cfg.xml file in the Web server definition in the application server whenever the
configuration changes. The Web server has immediate access to the file whenever it is regenerated.
When the Web server plug-in configuration service (an administration service) is enabled on Machine A,
the plugin-cfg.xml file is automatically generated for all Web servers.
Propagation of the plugin-cfg.xml file
Node synchronization is used to propagate the plugin-cfg.xml file from Machine A to Machine B.
When the Web server plug-in configuration service (an administration service) is enabled on Machine A,
the plugin-cfg.xml file is automatically propagated for all Web servers.
Alternate configuration
This procedure describes installing the plug-ins on two machines. However, you can perform this
procedure on a single machine as shown in the following graphic. A local distributed installation also
includes the Web server plug-in, the Web server, the Application Server, and the deployment manager
on the same machine:

Client Optional HTTP server Deployment

HTTP manager
Plug-in
requests

Optional Node agent

Application server

You can set up a remote or local Web server by installing Application Server, the Web server, and then the
Web server plug-ins.

See Web server configuration for more information about the files involved in configuring a Web server.

See ″Editing Web server configuration files″ in the information center for details for information about the
logic behind the processing scenarios for the Plug-ins installation wizard.

See Editing Web server configuration files for information about how the Plug-ins installation wizard
configures supported Web servers.

Chapter 3. Setting up the application serving environment 37

See Installing Web server plug-ins for information about other installation scenarios for installing Web
server plug-ins.

Planning to install WebSphere Application Server Clients

This topic helps you examine typical topologies and uses for WebSphere Application Server Clients.

This topic is one in a series of topics described in “Planning the installation (diagrams)” on page 21.
Consider all of the planning scenarios that are mentioned in the parent article to determine the best
approach to installing your e-business network. This topic describes installing and using the WebSphere
Application Server Clients.

In a traditional client server environment, the client requests a service and the server fulfills the request.
Multiple clients use a single server. Clients can also access several different servers. This model persists
for Java clients except that now these requests use a client run-time environment.

In this model, the client application requires a servlet to communicate with the enterprise bean, and the
servlet must reside on the same machine as the WebSphere Application Server.

The Application Client for WebSphere Application Server, Version 6 now consists of the following models:
v ActiveX application client
v Applet client
v J2EE application client
v Pluggable and thin application clients

The following graphic shows a topology for installing the Application Client and using client applications:

38 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The example shows two types of application clients installed in a topology that uses client applications to
access applications and data on Machine A:
v The ActiveX application client on Machine B is a Windows only client that uses the Java Native
Interface (JNI) architecture to programmatically access the Java virtual machine (JVM) API. The JVM
code exists in the same process space as the ActiveX application (Visual Basic, VBScript, or Active
Server Pages (ASP) files) and remains attached to the process until that process terminates.
v The J2EE application client on Machine C is a Java application program that accesses enterprise
beans, Java Database Connectivity (JDBC) APIs, and Java Message Service message queues. The
application program must configure the execution environment of the J2EE application client and use
the Java Naming and Directory Interface (JNDI) name space to access resources.

Use the following procedure as a roadmap for installing the Application Client.
1. Install the WebSphere Application Server product from your product CD on Machine A to establish the
core product files.
2. Use the Profile creation wizard to create both stand-alone application server profiles.
3. Use the administrative console of each application server to deploy any user applications.
4. Use the administrative console of each application server to create a Web server configuration for the
Web server.
5. Use the administrative console of each application server to regenerate each plugin-cfg.xml file in the
local Web server configuration.
6. Install the IBM HTTP Server from the product CD on Machine A.
7. Use the Plug-ins installation wizard to install the plug-in for IBM HTTP Server on Machine A.
The wizard automatically configures the HTTP Server to communicate with the first application server.
8. Install the Application Client from your product CD on Machine B.
a. Select the Custom install type.
b. Select the ActiveX to EJB Bridge feature.
c. Select to add the Java run time to the system path.
d. Select the Java run time as the default JRE, which adds the Java run time path to the beginning of
the system path.
9. Install the Application Client from your product CD on Machine C.
a. Select the Custom install type.
b. Select the J2EE application client feature.

This topic can help you plan run-time environments for client applications.

See “Application Client for WebSphere Application Server” on page 1038 for information about creating
client applications.

Planning to create application server environments

Application server profiles are the run-time environments for application server processes. This topic
describes common scenarios for creating application server profiles and provides links to profile creation
procedures for each scenario.

Install the core product files for a WebSphere Application Server product before using the Profile creation
wizard to create additional application server run-time environments.

This topic describes how to use the Profile creation wizard to install deployment managers, managed
nodes, and stand-alone application servers. Each profile for a deployment manager or an application
server is a run-time environment, with data files, configuration files, applications, and an administrative
console. The profile for a managed node is a special case that is dependent on the deployment manager
profile that owns the managed node.

Chapter 3. Setting up the application serving environment 39

1. Create a deployment manager, as described in “Using the Profile creation wizard to create a
deployment manager” on page 58.

The installation procedure gives you the option of creating a deployment manager during installation.
However, you can use the Profile creation wizard to create a deployment manager when one was not
created during installation. Or, you can create another deployment manager on a machine where a
deployment manager already exists.
2. Create a managed node, as described in “Using the Profile creation wizard to create a custom profile”
on page 70.
The installation procedure gives you the option of creating a managed node during installation.
However, you can use the Profile creation wizard to create a managed node when one was not
created during installation. Or, you can use the wizard to create more managed nodes on a machine
where a managed node already exists.
The first part of the process is to install the Network Deployment product to create the core product
files. Then you can use the Profile creation wizard to create a managed profile.

The next part of the process is to federate the managed profile into the deployment manager cell. This
changes the managed profile into a managed node.

40 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
A managed node has a nodeagent process but does not have Sample applications or an application
server process in contrast to a stand-alone application server, which has a server1 process and
applications, but does not have a nodeagent process.

Chapter 3. Setting up the application serving environment 41

 Start the nodeagent process to allow the administrative console of the deployment manager to create
server processes on the managed node.
3. Create a stand-alone application server, as described in “Using the Profile creation wizard to create an
application server” on page 84.

The installation procedure gives you the option of creating a stand-alone application server during
installation. However, you can use the Profile creation wizard to create a stand-alone application server
when one was not created during installation. Or, you can use the wizard to create more stand-alone
application servers on a machine where an application server already exists.
4. Create a deployment manager and a managed node on the same machine.
The installation procedure gives you the option of creating a deployment manager and managed node
on the same machine during installation. However, you can also use the Profile creation wizard to
create a deployment manager and a managed node at any time after installation of the core product
files. Or, you can use the wizard to create a managed node on a machine where a deployment
manager already exists.
Any time that you create two or more application server processes on one machine, verify that the
machine is capable of hosting both processes. See the hardware prerequisites on the IBM WebSphere
Application Server supported hardware, software, and APIs Web site.
a. Create a deployment manager, as described in “Using the Profile creation wizard to create a
deployment manager” on page 58.
b. Create a managed node, as described in “Using the Profile creation wizard to create a custom
profile” on page 70.

Use the Profile creation wizard after installing the core product files to create:
v A stand-alone application server environment
v A deployment manager environment
v Managed nodes for the deployment manager cell

After installing the core product files and using the Profile creation wizard to create your e-business
environment, you are ready to deploy applications to test the environment.

Example: Choosing a topology for better performance

WebSphere Application Server provides various Workload Management (WLM) topologies. Two topologies
were compared to show how the type of topology you choose can affect performance.

In this comparison, Topology A contains a Web server and a WebSphere Application Server plug-in in front
of a cluster of WebSphere Application Servers. Each cluster member contains a Web container and an
Enterprise JavaBeans (EJB) container. Topology B includes a Web server, a plug-in, and a Web container
in front of a cluster of EJB containers. In both topologies, Object Request Broker (ORB) pass by reference
is selected and the backend database is on a dedicated machine.

42 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Result: Topology A had 10% to 20% higher throughput than Topology B when running the Java 2 Platform,
Enterprise Edition Benchmark sample for WebSphere (Trade).

Note: You can download the Benchmark sample for WebSphere (Trade) from the following Web site:

http://www-306.ibm.com/software/webservers/appserv/was/performance.html

Topology A has an advantage because the Web container and EJB container are running in a single Java
virtual machine (JVM). In Topology B, the ORB pass by reference option is ignored between the Web
container cluster member and the EJB container member. In Topology A, the EJB container uses the same
thread passed from the Web container. The request does not have to be passed from one thread in one
JVM to another thread in another JVM.

In this test environment, Topology A had the advantage. However, many factors related to the application
and environment can influence your results.

Queuing network
WebSphere Application Server contains interrelated components that must be harmoniously tuned to
support the custom needs of your end-to-end e-business application. These adjustments help the system
achieve maximum throughput while maintaining the overall stability of the system. This group of
interconnected components is known as a queuing network. These queues or components include the
network, Web server, Web container, EJB container, data source, and possibly a connection manager to a
custom back-end system. Each of these resources represents a queue of requests waiting to use that
resource. Various queue settings include:
v IBM HTTP Server: MaxClients for UNIX and ThreadsPerChild for Windows NT and Windows 2000
systems described in “Web server tuning parameters” on page 133.
v Web container: Maximum size described in “Thread pool settings” on page 209,
MaxKeepAliveConnections and MaxKeepAliveRequests described in “HTTP transport custom
properties” on page 227.
v Tuning Object Request Brokers explained in “Tuning application servers” on page 265.
v Data source connection pooling and statement cache size are explained in the Developing and
deploying applications PDF.

Clients
Network

Web Servlet EJB Data

server engine container source

Database

Figure Reference 1: WebSphere queuing network

Most of the queues that make up the queuing network are closed queues. A closed queue places a limit
on the maximum number of requests present in the queue, while an open queue has no limit. A closed
queue supports tight management of system resources. For example, the Web container thread pool
setting controls the size of the Web container queue. If the average servlet running in a Web container
creates 10MB of objects during each request, a value of 100 for thread pools limits the memory consumed
by the Web container to 1GB.

Chapter 3. Setting up the application serving environment 43

In a closed queue, requests can be active or waiting. An active request is doing work or waiting for a
response from a downstream queue. For example, an active request in the Web server is doing work,
such as retrieving static HTML, or waiting for a request to complete in the Web container. A waiting
request is waiting to become active. The request remains in the waiting state until one of the active
requests leaves the queue.

All Web servers supported by WebSphere Application Server are closed queues, as are WebSphere
Application Server data sources. You can configure Web containers as open or closed queues. In general,
it is best to make them closed queues. EJB containers are open queues. If there are no threads available
in the pool, a new one is created for the duration of the request.

If enterprise beans are called by servlets, the Web container limits the number of total concurrent requests
into an EJB container, because the Web container also has a limit. The Web container limits the number of
total concurrent requests only if enterprise beans are called from the servlet thread of execution. Nothing
prevents you from creating threads and bombarding the EJB container with requests. Therefore, servlets
should not create their own work threads.

Queuing and clustering

Cloning application servers can be a valuable asset in configuring highly-scalable production
environments, especially when the application is experiencing bottlenecks that are preventing full CPU
utilization of symmetric multiprocessing (SMP) servers. When adjusting the WebSphere Application Server
system queues in clustered configurations, remember that when a server is added to a cluster, the server
downstream receives twice the load.

Clients
Network
Servlet
engine
Web Data
server source

Servlet
engine

Database

Figure Reference 1: Clustering and queuing

Two servlet engines are located between a Web server and a data source. It is assumed that the Web
server, servlet engines and data source, but not the database, are all running on a single SMP server.
Given these constraints, the following queue considerations must be made:
v Double the Web server queue settings to ensure ample work is distributed to each Web container.
v Reduce the Web container thread pools to avoid saturating a system resource like CPU or another
resource that the servlets are using.
v Reduce the data source to avoid saturating the database server.
v Reduce Java heap parameters for each instance of the application server. For versions of the Java
virtual machine (JVM) shipped with WebSphere Application Server, it is crucial that the heap from all
JVMs remain in physical memory. For example, if a cluster of four JVMs is running on a system,
enough physical memory must be available for all four heaps.

44 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Queue configuration tips
The following section outlines a methodology for configuring the WebSphere Application Server queues.
Moving the database server onto another machine or providing more powerful resources, for example a
faster set of CPUs with more memory, can dramatically change the dynamics of your system.

There are four tips for queuing:

v Minimize the number of requests in WebSphere Application Server queues.
In general, requests wait in the network in front of the Web server, rather than waiting in WebSphere
Application Server. This configuration only supports those requests that are ready for processing to
enter the queuing network. Specify that the queues furthest upstream or closest to the client are slightly
larger, and queues further downstream or furthest from the client are progressively smaller.

Clients
Network Arriving requests Arriving requests
200 75 50

Web Servlet Data

25
server engine source
(N=75) (N=50) (N=25)

125 25 25
Waiting requests Waiting requests Waiting requests
Database

Figure Reference 1: Upstream queuing network

Queues in the queuing network become progressively smaller as work flows downstream. When 200
client requests arrive at the Web server, 125 requests remain queued in the network because the Web
server is set to handle 75 concurrent clients. As the 75 requests pass from the Web server to the Web
container, 25 requests remain queued in the Web server and the remaining 50 are handled by the Web
container. This process progresses through the data source until 25 user requests arrive at the final
destination, the database server. Because there is work waiting to enter a component at each point
upstream, no component in this system must wait for work to arrive. The bulk of the requests wait in the
network, outside of WebSphere Application Server. This type of configuration adds stability, because no
component is overloaded.
You can then use the Edge Server to direct waiting users to other servers in a WebSphere Application
Server cluster.
v Draw throughput curves to determine when the system capabilities are maximized.
You can use a test case that represents the full spirit of the production application by either exercising
all meaningful code paths or using the production application. Run a set of experiments to determine
when the system capabilities are fully stressed or when it has reached the saturation point. Conduct
these tests after most of the bottlenecks are removed from the application. The goal of these tests is to
drive CPUs to near 100% utilization. For maximum concurrency through the system, start the initial
baseline experiment with large queues. For example, start the first experiment with a queue size of 100
at each of the servers in the queuing network: Web server, Web container and data source. Begin a
series of experiments to plot a throughput curve, increasing the concurrent user load after each
experiment. For example, perform experiments with one user, two users, five, 10, 25, 50, 100, 150 and
200 users. After each run, record the throughput requests per second, and response times in seconds
per request. The curve resulting from the baseline experiments resembles the following typical
throughput curve shown as follows:

Chapter 3. Setting up the application serving environment 45

 Throughput curve
Saturation point
60
Throughput requests per second

50

40

30

20

10
A B C
0
Light load zone Heavy load zone Buckle zone

Concurrent users
The WebSphere Application Server throughput is a function of the number of concurrent requests
present in the total system. Section A, the light load zone, shows that the number of concurrent user
requests increases, the throughput increases almost linearly with the number of requests. At light loads,
concurrent requests face very little congestion within the WebSphere Application Server system queues.
At some point, congestion starts to develop and throughput increases at a much lower rate until it
reaches a saturation point that represents the maximum throughput value, as determined by some
bottleneck in the WebSphere Application Server system. The most manageable type of bottleneck
occurs when the WebSphere Application Server machine CPUs become fully utilized because adding
CPUs or more powerful CPUs fixes the bottleneck.
In the heavy load zone or Section B, as the concurrent client load increases, throughput remains
relatively constant. However, the response time increases proportionally to the user load. That is, if the
user load is doubled in the heavy load zone, the response time doubles. At some point, represented by
Section C, the buckle zone, one of the system components becomes exhausted. At this point,
throughput starts to degrade. For example, the system might enter the buckle zone when the network
connections at the Web server exhaust the limits of the network adapter or if the requests exceed
operating system limits for file handles.
If the saturation point is reached by driving CPU utilization close to 100%, you can move on to the next
step. If the saturation CPU occurs before system utilization reaches 100%, it is likely that another
bottleneck is being aggravated by the application. For example, the application might be creating Java
objects causing excessive garbage collection bottlenecks in the Java code.
There are two ways to manage application bottlenecks: remove the bottleneck or clone the bottleneck.
The best way to manage a bottleneck is to remove it. You can use a Java-based application profiler,
such as Rational Application Developer, Performance Trace Data Visualizer (PTDV), Borland’s
Optimizeit, JProbe or Jinsight to examine overall object utilization.
v Decrease queue sizes while moving downstream from the client.
The number of concurrent users at the throughput saturation point represents the maximum
concurrency of the application. For example, if the application saturates WebSphere Application Server
at 50 users, using 48 users might produce the best combination of throughput and response time. This
value is called the Max Application Concurrency value. Max Application Concurrency becomes the
preferred value for adjusting the WebSphere Application Server system queues. Remember, it is
desirable for most users to wait in the network; therefore, queue sizes should increase when moving
downstream farther from the client. For example, given a Max Application Concurrency value of 48, start

46 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 with system queues at the following values: Web server 75, Web container 50, data source 45. Perform
a set of additional experiments adjusting these values slightly higher and lower to find the best settings.
To help determine the number of concurrent users, view the Servlet Engine Thread Pool and
Concurrently Active Threads metric in the Tivoli Performance Viewer.
v Adjust queue settings to correspond to access patterns.
In many cases, only a fraction of the requests passing through one queue enters the next queue
downstream. In a site with many static pages, a number of requests are fulfilled at the Web server and
are not passed to the Web container. In this circumstance, the Web server queue can be significantly
larger than the Web container queue. In the previous example, the Web server queue was set to 75,
rather than closer to the value of Max Application Concurrency. You can make similar adjustments when
different components have different execution times.
For example, in an application that spends 90% of its time in a complex servlet and only 10% of its time
making a short JDBC query, on average 10% of the servlets are using database connections at any
time, so the database connection queue can be significantly smaller than the Web container queue.
Conversely, if the majority of servlet execution time is spent making a complex query to a database,
consider increasing the queue values at both the Web container and the data source. Always monitor
the CPU and memory utilization for both the WebSphere Application Server and the database servers to
verify that the CPU or memory are not saturating.

Configuring the product after installation

This topic summarizes how to configure the application serving environment.

Use the First steps console to configure and test the WebSphere Application Server environment after
installation.

This procedure starts the second and final step of Network Deployment installation. This second step
creates and configures server processes by creating profiles.
1. At the end of product installation, select the Launch the Profile creation wizard check box to create
a deployment manager profile.
This step creates the deployment manager and the cell. Later steps in this procedure create an
Application Server profile and optionally, a custom profile.
See “Using the Profile creation wizard to create a deployment manager” on page 58.
2. Start the First steps console by selecting the check box on the last panel of the wizard.
The First steps console for the deployment manager profile can start automatically at the end of profile
creation. Select the check box on the last panel of the Profile creation wizard.
The First steps console is an easy way to start using the product. The console provides one-stop
access to the administrative console, Samples Gallery, Profile creation wizard, installation verification
test, Migration wizard, and other activities.
See the description of the “firststeps command” on page 48 for more information.
3. Click Installation verification on the First steps console.
The installation verification test starts the deployment manager process named dmgr and runs several
tests to verify that the dmgr process can start without error.
See “Using the installation verification test” on page 110 for more information.
4. Click Profile creation wizard on the First steps console to create an Application Server profile.
See “Using the Profile creation wizard to create an application server” on page 84.
5. Start the First steps console by selecting the check box on the last panel of the Profile creation wizard.
This First steps console belongs to the Application Server profile that you just created. Each profile has
its own First steps console.
6. Click Installation verification on the First steps console.

Chapter 3. Setting up the application serving environment 47

 The installation verification test starts the new Application Server process named server1 and runs
several tests to verify that the server1 process can start without error.
7. Federate the Application Server into the deployment manager cell.
If both server processes are running, use the administrative console of the deployment manager to add
the Application Server node into the cell.
Point your browser at http://localhost:9060/ibm/console for example, to start the administrative console.
Or start it from the First steps console of the deployment manager profile.
Log in and click System administration > Nodes > Add Node and follow the wizard to add the node
into the cell. You can use localhost for the Host field if both processes are on the same machine. The
SOAP port for the Application Server node is 8880 unless you changed the port during profile creation.
If the deployment manager is running, you can use the addNode command instead. See ″addNode
command″ in the information center.
8. Optional: Click Profile creation wizard on the First steps console to create a custom profile.
Verify that the deployment manager is running. The Profile creation wizard can federate the custom
node for you if the deployment manger is running.
Supply the host name and the SOAP port for the deployment manager while creating the custom
profile.
Choose to federate the custom node into the deployment manager cell. A custom profile must be part
of a cell.
Use the deployment manager to customize the node at your leisure. Add servers, add clusters, and
install applications on the node, for example.
See “Using the Profile creation wizard to create a custom profile” on page 70.

This procedure results in configuring and testing the Application Server environment.

See “Planning to install Network Deployment” on page 23 for diagrams of topologies that you can create
using the First steps console and the Profile creation wizard.

firststeps command
The firststeps command starts the First steps console.

The First steps console

The First steps console is a post-installation ease-of-use tool for directing WebSphere Application Server
elements from one place. Options display dynamically on the First steps console, depending on features
you install. With all of the options present, you can use the First steps console to start or stop the
application server, verify the installation, access the information center, access the administrative console,
launch the Migration wizard, or access the Samples gallery.

The First steps console for the Network Deployment product has several forms. A First steps console
exists for the product itself before the creation of any profiles. This version lets you start the Profile
creation wizard to get started defining a deployment manager and application servers for the cell. You can
also define stand-alone application servers. Each stand-alone application server has its own First steps
console. Each deployment manager has its own First steps console.

A prompt to launch the First steps console displays on the last panel of the Profile creation wizard.

You can also start the First steps console from the command line as described later.

The First steps console for the Network Deployment product has several forms. A console exists for the
product itself before the creation of any profiles. Options that display on the First steps console in the core
product files of the Network Deployment product include the following entries:

48 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Profile creation wizard
This option starts the Profile creation wizard. The wizard lets you create a deployment manager
profile, an application server profile, or a custom profile. A profile consists of files that define the
run-time environment for the deployment manager or the application server. Each environment has
its own administrative interface. A custom profile is an exception. A custom profile is an empty
node that you can federate into a deployment manager cell and customize. No default server
processes or applications are created for a custom profile.
Each deployment manager or application server profile has its own First steps console. The
location of the command to launch the First steps console is within the set of files in the profile. A
prompt to launch the First steps console that is associated with a profile displays on the last panel
of the Profile creation wizard.
Information center for WebSphere Application Server
This option links you to the online information center at the
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp IBM Web address.
Migration wizard
This option starts the Migration wizard. The Migration wizard is a new graphical interface to the
migration tools. The migration tools are described in ″WASPreUpgrade command″ and
″WASPostUpgrade command″ in the information center.
See ″Using the Migration wizard″ in the information center for more information about the
Migration wizard.
Exit This option closes the First steps console.

In addition to the generic First steps console for the Network Deployment product, other First steps
consoles exist for the deployment manager profile and the application server profile that the Network
Deployment product can create. Options that display on the First steps console for a deployment manager
include the following entries:
Installation verification
This option starts the installation verification test. The test consists of starting and monitoring the
deployment manager during its start up.
If this is the first time that you have used the First steps console since creating a deployment
manager profile, click Installation verification to verify that all is well with your installation. The
verification process starts the deployment manager.
If you select the Installation verification option, the Start the deployment manager option is
grayed out while the IVT is running.
The IVT provides the following useful information about the deployment manager:
v The deployment manager server name: dmgr
v The name of the profile
v The profile file path
v The type of profile: dmgr
v The cell name
v The node name
v The current encoding
v The port number for the administrative console
v Various informational messages that include the location of the SystemOut.log file and how
many errors are listed within the file
v A completion message

Chapter 3. Setting up the application serving environment 49

Start the deployment manager
This option displays when you use the Profile creation wizard to create a deployment manager.
This option toggles to Stop the deployment manager when the deployment manager is running.
After selecting the Start the deployment manager option, an output screen displays with status
messages. The success message informs you that the deployment manager is open for
e-business. Then the menu item changes to Stop the deployment manager.
If you select the Start the deployment manager option, the Installation verification option is
grayed out while the deployment manager is running.
Administrative console
This option is grayed out until the application server is running.
The administrative console is a configuration editor that runs in a Web browser. The administrative
console lets you work with XML configuration files for the deployment manager and all of the
application servers that are in the cell. To launch the administrative console, click Administrative
console. You can also point your browser to http://localhost:9060/ibm/console to start the
administrative console. Substitute your own host name in the address if the localhost variable does
not resolve correctly. As the administrative console opens, it prompts you for a login name. This is
not a security item, but merely a tag to identify configuration changes that you make during the
session. Secure signon is also available.
Profile creation wizard
This option starts the Profile creation wizard. The wizard lets you create a deployment manager
profile, an application server profile, or a custom profile. A profile consists of files that define the
run-time environment for the deployment manager or the application server. Each environment has
its own administrative interface. A custom profile is an exception. A custom profile is an empty
node that you can federate into a deployment manager cell and customize. No default server
processes or applications are created for a custom profile.
Each deployment manager profile has its own First steps console. The location of the command to
launch the First steps console is within the set of files in the profile. A prompt to launch the First
steps console that is associated with a profile displays on the last panel of the Profile creation
wizard.
Information center for WebSphere Application Server
This option links you to the online information center at the
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp IBM Web address.
Migration wizard
This option starts the Migration wizard. The Migration wizard is a new graphical interface to the
migration tools. The migration tools are described in ″WASPreUpgrade command″ and
″WASPostUpgrade command″ in the information center.
See ″Using the Migration wizard″ in the information center for more information about the
Migration wizard.
Exit This option closes the First steps console.

In addition to the generic First steps console and the First steps console for the deployment manager,
another First steps console exists for stand-alone application servers that you create with the Profile
creation wizard. Options that display on the First steps console for an application server profile include the
following entries:
Installation verification
This option starts the installation verification test. The test consists of starting and monitoring the
application server during its start up.
If this is the first time that you have used the First steps console since creating an application
server profile, click Installation verification to verify that all is well with your installation. The
verification process starts the application server.

50 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 If you select the Installation verification option, the Start the server option is grayed out while
the IVT is running.
The IVT provides the following useful information about the application server:
v The server name: server1
v The name of the profile
v The profile file path
v The type of profile: default
v The cell name
v The node name
v The current encoding
v The port number for the administrative console
v Various informational messages that include the location of the SystemOut.log file and how
many errors are listed within the file
v A completion message
Start the server
This option toggles to Stop the server when the application server is running.
After selecting the Start the server option, an output screen displays with status messages. The
success message informs you that the server is open for e-business. Then the menu item
changes to Stop the server.
If you select the Start the server option, the Installation verification option is grayed out while
the application server is running.
Administrative console
This option is grayed out until the application server is running.
The administrative console is a configuration editor that runs in a Web browser. The administrative
console lets you work with XML configuration files for the deployment manager and all of the
application servers that are in the cell. To launch the administrative console, click Administrative
console. You can also point your browser to http://localhost:9060/ibm/console to start the
administrative console. Substitute your own host name in the address if the localhost variable does
not resolve correctly. As the administrative console opens, it prompts you for a login name. This is
not a security item, but merely a tag to identify configuration changes that you make during the
session. Secure signon is also available.
Profile creation wizard
This option starts the Profile creation wizard. The wizard lets you create a deployment manager
profile, an application server profile, or a custom profile. A profile consists of files that define the
run-time environment for the deployment manager or the application server. Each environment has
its own administrative interface. A custom profile is an exception. A custom profile is an empty
node that you can federate into a deployment manager cell and customize. No default server
processes or applications are created for a custom profile.
Each application server profile has its own First steps console. The location of the command to
launch the First steps console is within the set of files in the profile. A prompt to launch the First
steps console that is associated with a profile displays on the last panel of the Profile creation
wizard.
Samples gallery
This option starts the Samples gallery. The option is grayed out until you start the application
server. The option displays when you have installed the Samples during installation.
From the First steps console, click Samples gallery to explore the application Samples.
Alternatively you can point your browser directly to http://localhost:9080/WSsamples. Substitute

Chapter 3. Setting up the application serving environment 51

 your own host name in the address if the localhost variable does not resolve correctly. The Web
address is case sensitive. Substitute your own host name in the address.
Information center for WebSphere Application Server
This option links you to the online information center at the
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp IBM Web address.
Migration wizard
This option starts the Migration wizard. The Migration wizard is a new graphical interface to the
migration tools. The migration tools are described in ″WASPreUpgrade command″ and
″WASPostUpgrade command″ in the information center.
See ″Using the Migration wizard″ in the information center for more information about the
Migration wizard.
Exit This option closes the First steps console.

The First steps console for a managed node has the same options as the generic First steps console for
the Network Deployment product.

Location of the command file

The location of the firststeps.sh or firststeps.bat script for any profile is:
v install_root/profiles/profile_name/firststeps/firststeps.sh
v install_root\profiles\profile_name\firststeps\firststeps.bat

The location of the firststeps command for the generic First steps console for the Network Deployment
product is:
v install_root/firststeps/firststeps.sh
v install_root\firststeps\firststeps.bat

Parameters

No parameters are associated with this command.

Syntax for the firststeps command

Use the following syntax for the command:

v ./firststeps.sh

v firststeps.bat

Usage tips

The following links exist on one of the First steps consoles for the Network Deployment product. Not all
links display on each First steps console. For example, the First steps console for the deployment
manager does not have the Samples Gallery option or the Start the server option.

Option Link
Installation verification Calls the ivt command.

The location of the installation verification test varies per platform:

v install_root/profiles/profile_name/bin/ivt.sh

v install_root\profiles\profile_name\bin\ivt.bat

52 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Option Link
Start the server Calls the startServer command.

The location of the startServer command varies per platform:

server1 install_root/profiles/profile_name/bin/startServer.sh

v install_root\profiles\profile_name\bin\startServer.bat
server1

When you have more than one application server on the same machine, the
command starts the same application server that is associated with the First
steps console.
Stop the server Calls the stopServer command.

The location of the stopServer command varies per platform:

server1 install_root/profiles/profile_name/bin/stopServer.sh

v install_root\profiles\profile_name\bin\stopServer.bat
server1
Start the deployment manager Calls the startManager command.

The location of the startManager command varies per platform:

install_root/profiles/profile_name/bin/startManager.sh
v install_root\profiles\profile_name\bin\startManager.bat

When you have more than one deployment manager on the same machine,
the command starts the same deployment manager that is associated with
the First steps console.
Stop the deployment manager Calls the stopManager command.

The location of the stopManager command varies per platform:

install_root/profiles/profile_name/bin/stopManager.sh
v install_root\profiles\profile_name\bin\stopManager.bat
Administrative console Opens the default browser to the http://localhost:9060/ibm/console Web
address.

When you have more than one application server on the same machine, the
port varies. The First steps console starts the administrative console that is
associated with the First steps console.

Chapter 3. Setting up the application serving environment 53

Option Link
Profile creation wizard Calls the pctplatform command.

The command is in the install_root/bin/ProfileCreator directory. The name

of the command varies per platform:

v pctAIX.bin

v pctHPUX.bin

v 64-bit platforms: pctHPUXIA64.bin

v pctLinux.bin

v 64-bit platforms: pct.bin S/390 platforms: pctLinux390.bin

v Power platforms: pctLinuxPPC.bin

v pctSolaris.bin

v pctWindows.exe

v 64-bit platforms: pctWindowsIA64.exe

Samples Gallery Opens the default browser to the http://localhost:9080/WSsamples Web
address.

If you do not install Samples, the option does not appear on the First steps
console. If you do not install the Samples during the initial installation of the
product, the option does not display on the First steps console. You can
perform an incremental installation to add the Samples feature. After adding
the Samples, the options displays on the First steps console.

When you have more than one profile on the same machine, the port
varies. The First steps console starts the Samples gallery that is associated
with the First steps console.
Information center for WebSphere Opens the default browser to the online information center at the
Application Server products http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp Web address.
Migration wizard Calls the migration command.

The location of the migration command is:

v install_root/bin/migration.sh

v install_root\bin\migration.bat

The migration tools are also in the /migration folder on the product disc.

Using the Profile creation wizard

This topic describes how to create run-time environments for WebSphere Application Server. Each
run-time environment is created within a profile. A profile is the set of files that define the run-time
environment. The Profile creation wizard creates the profile for each run-time environment.

Before using the Profile creation wizard, install the core product files.

The Profile creation wizard is the wizard interface to the profile creation tool, wasprofile. See the
description of the “wasprofile command” on page 96 for more information.

54 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
An error can occur when you have not provided enough system temporary space to create a profile. Verify
that you have a minimum of 40 MB of temp space available before creating a profile.

You must have 200 MB of available disk space in the directory where you create an Application Server
profile.

Important:

You must have 30 MB of available disk space in the directory where you create a deployment
manager profile.

You must have 10 MB of available disk space in the directory where you create a custom
profile.

Manually verify that the required space for creating a profile is available on AIX. A known
problem in the underlying InstallShield for Multiplatforms (ISMP) code prevents proper space checking on
AIX systems at the time that the product disc was created.

Important: Concurrent profile creation is not supported at this time for one set of core product files.
Concurrent attempts to create profiles result in a warning about a profile creation already in
progress.

The installation procedure for the Network Deployment product does not create a run-time environment by
default because three possibilities exist. After installing the core product files for the Network Deployment
product, use the Profile creation wizard to create any combination of the following three profiles to have an
operational run-time environment:
v A deployment manager profile.
See “Using the Profile creation wizard to create a deployment manager” on page 58. Create this
run-time environment first, to create the administrative node for a multinode, multimachine group of
application server nodes that you create later. This logical group of application server processes is
known as a cell.
v An application server profile.
See “Using the Profile creation wizard to create an application server” on page 84.
When you create the application server profile, a default server1 process is created. The process has all
of the Sample applications and its own administrative console. You can federate the server1 node into
the deployment manager cell with the addNode command or from the administrative console of the
deployment manager. The server1 process must be running to begin the federation from the deployment
manager.
If you include all of the applications from the application server, the act of federation installs the
applications on the deployment manager where they can be redeployed.
Optionally, you can create stand-alone application servers by creating an application server profile and
not federating the node. If you remove a federated application server node from a deployment manager,
the application server returns to its original configuration, which is a stand-alone application server.
v A custom profile.
See “Using the Profile creation wizard to create a custom profile” on page 70. A custom profile is an
empty node that you can customize through the deployment manager to include application servers,
clusters, or other Java processes, such as a messaging server. Create a custom profile on a distributed
machine and add the node into the deployment manager cell to get started customizing the node.

Each use of the Profile creation wizard or the wasprofile command line tool creates one profile.
1. Install the product to create the core product files.
2. Start the Profile creation wizard to create a new run-time environment.

Chapter 3. Setting up the application serving environment 55

 Several ways exist to start the wizard. The initial way to start the wizard is at the end of installation by
selecting the check box to launch the Profile creation wizard.
One way to start the wizard is to issue the command directly from a command line.
The command is in the install_root/bin/ProfileCreator directory. The name of the command varies
per platform:

v pctAIX.bin

v pctHPUX.bin

v 64-bit platforms: pctHPUXIA64.bin

v pctLinux.bin

v 64-bit platforms: pct.bin S/390 platforms: pctLinux390.bin

v Power platforms: pctLinuxPPC.bin

v pctSolaris.bin

v pctWindows.exe

v 64-bit platforms: pctWindowsIA64.exe

Another way to start the Profile creation wizard is to select the wizard from the First steps console.
a. Open a command window.
b. Change directories to the firststeps directory in the installation root directory:
The installation root varies by platform:

v /usr/IBM/WebSphere/AppServer/firststeps

v /opt/IBM/WebSphere/AppServer/firststeps

v C:\Program Files\IBM\WebSphere\AppServer\firststeps
c. Issue the firststeps command to start the console:

v ./firststeps.sh

v firststeps.bat
d. Select the Profile creation wizard option on the console.
The Profile creation wizard is an InstallShield for Multiplatforms application. The wizard loads the
Java 2 SDK and then displays its Welcome panel.
See the description of the “firststeps command” on page 48 for more information.
3. Create a profile.
You can create profiles in any order. However, to create a functioning cell in the shortest possible time,
create a deployment manager profile first. Then create an application server profile and add it to the
deployment manager cell. You now have a functioning cell with a managed node that you can manage
from the administrative console of the deployment manager.
A custom profile requires a greater amount of customization. When you create a custom profile, you
must use the addNode command to federate it into the deployment manager cell. In contrast to an
application server profile, a custom profile does not have a default application server on its node. The
server1 application server does not exist by default on the custom node. Nor are there any default
applications on the custom node. Use the administrative console of the deployment manager to
customize the empty node for production or other uses. You can create application servers or clusters
on the node, for example.
Create any of the following profiles:
v Create a deployment manager.

56 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 See “Using the Profile creation wizard to create a deployment manager” on page 58.
Create a deployment manager to establish a cell. Although you can create an application server
profile and use it as a stand-alone application server, you must have a deployment manager to use
a custom profile. So there is no point in creating a custom profile until you have created a
deployment manager.
v Create an application server profile, as described in “Using the Profile creation wizard to create an
application server” on page 84.
Federate the application server into the deployment manager cell to create a federated server1
application server. A stand-alone application server has default applications. You can include the
applications as you federate the application server to install the default applications on the
deployment manager.
Two methods exist for federating application servers into a deployment manager cell:
– Start the deployment manager and the application server and use the administrative console of
the deployment manager to federate the node. Click System administration > Nodes > Add
node > Managed node > Next and identify the host name and the SOAP port of the machine
where you created the application server.
– Start the deployment manager. Go to the install_root/profiles/profile_name/bin directory of the
application server and issue the addNode command. See ″addNode command″ in the
information center for more information.
v Create a custom profile, as described in “Using the Profile creation wizard to create a custom
profile” on page 70.
The first part of the process is to install the Network Deployment product to create the core product
files. Then you can use the Profile creation wizard to create a managed profile.
The next part of the process is to federate the managed profile into the deployment manager cell.
This changes the custom profile into a managed node.
After federation, a custom profile has a nodeagent process but does not have an application server
process. Contrast this situation to an application server profile that has a server1 process, but does
not have a nodeagent process until you federate the node.
Start the nodeagent process to allow the administrative console of the deployment manager to
create server processes on the managed node.
Two methods exist for federating a custom node into a deployment manager cell:
– Federate the custom node during custom profile creation, either with the wizard or as the wizard
runs in silent mode.
The deployment manager must be running and accessible at the host address you supply. The
deployment manager must also use the default JMX connector type, which is SOAP. The
deployment manager must not have security enabled. If any of these conditions are not met, do
not federate the custom profile as you create it, but federate it later with the addNode command.
Otherwise, you create a faulty profile that you must move or delete from the profiles repository
directory before creating another profile.
– Use the addNode command to federate the custom node after you create the custom profile.
a. Start the deployment manager.
b. Go to the install_root/profiles/profile_name/bin directory of the custom profile and issue
the addNode command.
c. Within the same directory, issue the startNode command. See ″startNode command″ in the
information center for more information.
After federation, go to the administrative console of the deployment manager to customize the
empty node.
v Create a deployment manager and a managed node on the same machine:
a. Create a deployment manager, as described in “Using the Profile creation wizard to create a
deployment manager” on page 58.

Chapter 3. Setting up the application serving environment 57

 b. Start the deployment manager with the startManager command. See ″startManager command″
in the information center for more information.
c. Create an application server profile, as described in “Using the Profile creation wizard to create
an application server” on page 84.
d. Start the application server with the startServer command. See ″startServer command″ in the
information center for more information.
e. Use the administrative console of the deployment manager to add the application server node
into the deployment manager cell. Click System administration > Nodes > Add node >
Managed node > Next and identify the host name of the machine and the SOAP port of the
application server.
The SOAP port is identified in the
install_root/profiles/profile_name/config/cells/cell_name/nodes/node_name/serverindex.xml
file. You can also use the administrative console of the application server to view its SOAP port
setting. Click Servers > Application servers > server1 > Ports. The SOAP port is usually the
second port in the list.
Select the check box to include applications that are installed on the application server. The
default application has the snoop servlet and the hitcount servlet, which are useful for testing.
Adding the stand-alone application server node to the deployment manager node changes the
server1 process into a managed node. Use the administrative console of the deployment
manager to configure the server1 process.
You can also create a custom profile and federate the node during profile creation, or use the
addNode command to federate the empty node into the cell after the custom profile exists. A
managed node created from a custom profile requires customization to create an application
server and install applications. Use the administrative console of the deployment manager to
configure the custom node.

See the description of the “wasprofile command” on page 96 to learn more about the command-line
alternative method of creating a profile, and to see examples of using the command.

See “Planning the installation (diagrams)” on page 21 for examples of configurations that you can create
by creating profiles.

Using the Profile creation wizard to create a deployment manager

This topic describes creating a run-time environment for a deployment manager.

Before using the Profile creation wizard, install the core product files.

The Profile creation wizard is the wizard interface to the profile creation tool, wasprofile. See the
description of the “wasprofile command” on page 96 for more information.

An error can occur when you have not provided enough system temporary space to create a profile. Verify
that you have a minimum of 40 MB of temp space available before creating a profile.

You must have 200 MB of available disk space in the directory where you create an Application Server
profile.

You must have 30 MB of available disk space in the directory where you create a deployment manager
profile.

You must have 10 MB of available disk space in the directory where you create a custom profile.

Manually verify that the required space for creating a profile is available on AIX. A known
problem in the underlying InstallShield for Multiplatforms (ISMP) code prevents proper space checking on
AIX systems at the time that the product disc was created.

58 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
After installing the core product files, you must create one of the following profiles to have an operational
run-time environment:
v An application server that is described in this topic.
An application server profile has a default server (which is server1), the default application that includes
the snoop servlet and the hitcount servlet, and application Samples. You can federate the application
server or use it as a stand-alone application server.
v A deployment manager.
The deployment manager provides a single administrative interface to a logical group of application
servers on one or more machines.
v A custom profile that you must federate to make operational.
A custom profile is an empty node that you can customize to include application servers, clusters, or
other Java processes, such as a messaging server.

This procedure describes creating a deployment manager profile. The procedure uses the graphical user
interface provided by the Profile creation wizard. You can use the Profile creation wizard in silent mode
with a response file, without the graphical user interface. See “responsefile.pct.NDdmgrProfile.txt” on page
63 for examples of using the Profile creation wizard in silent mode.

You can also use the wasprofile command to create a deployment manager. See the description of the
“wasprofile command” on page 96 for more information.
1. Start the Profile creation wizard to create a new run-time environment.
Several ways exist to start the wizard. The initial way to start the wizard is at the end of installation by
selecting the check box to launch the Profile creation wizard.
One way to start the wizard is to issue the command directly from a command line.
The command is in the install_root/bin/ProfileCreator directory. The name of the command varies
per platform:

v pctAIX.bin

v pctHPUX.bin

v 64-bit platforms: pctHPUXIA64.bin

v pctLinux.bin

v 64-bit platforms: pct.bin S/390 platforms: pctLinux390.bin

v Power platforms: pctLinuxPPC.bin

v pctSolaris.bin

v pctWindows.exe

v 64-bit platforms: pctWindowsIA64.exe

Another way to start the Profile creation wizard is to select the wizard from the First steps console.
a. Open a command window.
b. Change directories to the firststeps directory in the installation root directory:
The installation root varies by platform:

v /usr/IBM/WebSphere/AppServer/firststeps

v /opt/IBM/WebSphere/AppServer/firststeps

v C:\Program Files\IBM\WebSphere\AppServer\firststeps
c. Issue the firststeps command to start the console:

Chapter 3. Setting up the application serving environment 59

 v ./firststeps.sh

v firststeps.bat
d. Select the Profile creation wizard option on the console.
The Profile creation wizard is an InstallShield for Multiplatforms application. The wizard loads the
Java 2 SDK and then displays its Welcome panel.
See the description of the “firststeps command” on page 48 for more information.
2. Click Next on the Welcome panel.
The wizard displays the Profile type selection panel.
3. Select the type of profile to create and click Next. In this example, select the option for creating a
deployment manager and click Next.
The wizard displays the Profile name panel.
4. Specify a name for the profile, then click Next.
Profile naming guidelines: The profile name can be any unique name with the following restrictions.
Do not use any of the following characters when naming your profile:
v Spaces
v Illegal special characters that are not allowed within the name of a directory on your operating
system, such as *&?
v Slashes (/) or (\)
Double-byte characters are allowed.
The default profile
The first profile that you create on a machine is the default profile. The default profile is the default
target for commands issued from the bin directory in the product installation root. When only one
profile exists on a machine, every command works on the only server process in the configuration.
Addressing a profile in a multi-profile environment
When two or more profiles exist on a machine, certain commands require that you specify the profile
to which the command applies. These commands use the -profileName parameter to identify which
profile to address. You might find it easier to use the commands that in the bin directory of each
profile.
A command in the profiles/profile_name/bin directory has two lines. The first line sets the
WAS_USER_SCRIPT environment variable for the command window. The variable sets up the
command environment to address the profile. The second line calls the actual command in the
install_root/bin directory.
The actual command queries the command shell to determine the calling profile and to autonomically
address the command to the calling profile.
The wizard then displays the Profile directory panel.
5. Accept the default directory, specify a non-default location, or click Browse to select a different
location. Click Next.
If you click Back and change the name of the profile, you must manually change the name on this
panel when it displays again.
The wizard displays the Node, host, and cell name panel.
6. Specify a unique node name, the actual host name of the machine, and a unique cell name. Click
Next.
The deployment manager node has the following characteristics.

60 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Field name Default value Constraints Description
Node name The name of your machine, Use a unique name for the The name is used for
or a unique derivation of the deployment manager. administration within the
machine name. deployment manager cell.
See the following note.
Host name The DNS name of your The host name must be Use the actual DNS name or IP
machine. addressable through your address of your machine to
network. enable communication with your
machine. See additional
See the following note. information about the host name
that follows this table.
Cell name The arbitrary name of the Use a unique name for the All federated nodes become
deployment manager cell. deployment manager cell. If you members of the deployment
The cell is a logical grouping plan to migrate a V5 manager cell, which you name
of managed nodes, under the deployment manager cell to this in this panel.
control of the deployment V6 deployment manager, use
manager. the same cell name as the V5
deployment manager.

See the following note.

Reserved names: Avoid using reserved folder names as field values. The use of reserved folder
names can cause unpredictable results. The following words are reserved:
v cells
v nodes
v servers
v clusters
v applications
v deployments
Node and cell name considerations

The profiles directory path must be no longer than 80 characters.

Host name considerations
The host name is the network name for the physical machine on which the node is installed. The host
name must resolve to a physical network node on the server. When multiple network cards exist in
the server, the host name or IP address must resolve to one of the network cards. Remote nodes use
the host name to connect to and to communicate with this node. Selecting a host name that other
machines can reach within your network is extremely important. Do not use the generic localhost
identifier for this value.
If you define coexisting nodes on the same computer with unique IP addresses, define each IP
address in a domain name server (DNS) look-up table. Configuration files for stand-alone Application
Servers do not provide domain name resolution for multiple IP addresses on a machine with a single
network address.
The value that you specify for the host name is used as the value of the hostName property in
configuration documents for the stand-alone Application Server. Specify the host name value in one of
the following formats:
v Fully qualified domain name servers (DNS) host name string, such as
xmachine.manhattan.ibm.com
v The default short DNS host name string, such as xmachine
v Numeric IP address, such as 127.1.255.3
The fully qualified DNS host name has the advantage of being totally unambiguous and also flexible.
You have the flexibility of changing the actual IP address for the host system without having to
change the Application Server configuration. This value for host name is particularly useful if you plan

Chapter 3. Setting up the application serving environment 61

 to change the IP address frequently when using Dynamic Host Configuration Protocol (DHCP) to
assign IP addresses. A format disadvantage is being dependent on DNS. If DNS is not available, then
connectivity is compromised.
The short host name is also dynamically resolvable. A short name format has the added ability of
being redefined in the local hosts file so that the system can run the Application Server even when
disconnected from the network. Define the short name to 127.0.0.1 (local loopback) in the hosts file to
run disconnected. A format disadvantage is being dependent on DNS for remote access. If DNS is
not available, then connectivity is compromised.
A numeric IP address has the advantage of not requiring name resolution through DNS. A remote
node can connect to the node you name with a numeric IP address without DNS being available. A
format disadvantage is that the numeric IP address is fixed. You must change the setting of the
hostName property in Express configuration documents whenever you change the machine IP
address. Therefore, do not use a numeric IP address if you use DHCP, or if you change IP addresses
regularly. Another format disadvantage is that you cannot use the node if the host is disconnected
from the network.
After specifying deployment manager characteristics, the wizard displays the Port value assignment
panel.
7. Verify that the ports specified for the deployment manager are unique and click Next.

The wizard displays the Windows service definition panel.

8. Choose whether to run the dmgr process as a Windows service on a Windows platform
and click Next.
Version 6 attempts to start Windows services for dmgr processes started by a startManager
command. For example, if you configure a deployment manager as a Windows service and issue the
startManager command, the wasservice command attempts to start the defined service.
If you chose to install a local system service, you do not have to specify your user ID or password. If
you create a specified user type of service, you must specify the user ID and the password for the
user who is to run the service. The user must have Log on as a service authority for the service to
run properly.
To perform this installation task, the user ID must not have spaces in its name. The ID must also
belong to the administrator group and must have the advanced user rights Act as part of the
operating system and Log on as a service. The Installation wizard grants the user ID the advanced
user rights if it does not already have them, if the user ID belongs to the administrator group.
You can also create other Windows services after the installation is complete, to start other server
processes. See “Automatically restarting server processes” on page 244 for more information.
The wizard displays the Profile summary panel.
9. Click Next to create the deployment manager or click Back to change the characteristics of the
deployment manager.
The wizard displays a Status panel during the creation of the profile. When the installation is
complete, the wizard displays the Profile creation is complete panel.
10. Click Finish to exit and then click Profile creation wizard on the First steps console to start the
wizard again, if you intend to create an application server profile.

You can create a deployment manager profile. The node within the profile has a deployment manager
named dmgr.

Refer to the description of the “wasprofile command” on page 96 to learn about creating this type of profile
using a command instead of a wizard.

Create an application server profile and add the node into the cell. Then you are ready to deploy an
application.

62 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Deploy an application to get started!

See Fast paths for WebSphere Application Server to get started deploying applications.

responsefile.pct.NDdmgrProfile.txt:

This topic describes the response file for creating a deployment manager profile.

Create a deployment manager profile with an options response file after logging on as root on a Linux or
UNIX platform, or as a user that belongs to the administrator group on a Windows platform. Some steps of
the installation procedure on a Windows platform require the user to belong to the administrator group and
to have the advanced user rights Act as part of the operating system and Log on as a service.

The response file is shipped with default values.

A common use for an options file is to run the Installation wizard in silent mode, which is referred to as
installing silently. The wizard reads the options file to determine responses and does not display the
graphical user interface. Issue the following command to use a copy of the options file named
myresponsefile.txt for a silent installation:
pctWindows.exe -options "myresponsefile.txt" -silent

Avoiding the use of the -silent option within the options response file

A problem occurs when the -silent option exists in the file. The file works with the option during a direct
call to the profile creation wizard, but fails when called from a silent product installation. See ″Customizing
the options response file for Network Deployment″ in the information center for information about creating
a profile silently during a silent product installation.

The option is unnecessary. Avoid using the option to avoid problems.

Response file locations

The example options response files are in two locations.

Example files:
v responsefile.pct.NDdmgrProfile.txt
v responsefile.pct.NDmanagedProfile.txt
v responsefile.pct.NDstandAloneProfile.txt

Location:
Table 5. Option response file locations
Product disc location Installed location
/WAS directory install_root/bin/ProfileCreator directory

Use the file on the product disc to install the Network Deployment product silently and create a profile.

After installing the Network Deployment product, you can use the installed response file with the -options
parameter on the Profile creation wizard command.

Chapter 3. Setting up the application serving environment 63

Required disk space

Profile Required disk space Required temp space

Deployment manager profile 30 MB 40 MB
Custom profile 10 MB 40 MB
Application server profile 200 MB 40 MB

Creating an operational environment during product installation

Version 6 installation of the Network Deployment product is a two-step process:

1. Installing the core product files and feature files.
2. Creating a deployment manager profile, a custom profile, or an application server profile.

The sample options response file, responsefile.nd.txt, controls the first part of the installation and can also
start the second part of the installation. To create a profile as part of installing the core product files, use
the option in the responsefile.nd.txt file that identifies the response file for creating a profile. The profile
response file lets you use the Profile creation wizard silently.

To edit and use the appropriate response file for creating a profile, perform the following procedure:
1. Copy the appropriate file from the WAS directory on the product disc to a place that you can easily
identify on your machine. The example files are:

To create a: Copy the following response file:

Deployment manager profile responsefile.pct.NDdmgrProfile.txt
Custom profile responsefile.pct.NDmanagedProfile.txt
Application server profile responsefile.pct.NDstandAloneProfile.txt

2. Edit the file to customize the values for your installation.

3. Verify that no -silent option exists in the response file for the Profile creation wizard. If the option
exists, the profile is not created.
4. Save the file.
5. Edit the responsefile.nd.txt file to identify the location and name of the profile response file. Change
the value of the -W pctresponsefilelocationqueryactionInstallWizardBean.fileLocation option to identify
the file. For example:
-W pctresponsefilelocationqueryactionInstallWizardBean.fileLocation=
"/opt/IBM/WebSphere/MyOptionFiles/customProfile.txt"
6. Start the installation. For example:
install -options "myresponsefile.txt" -silent
7. After the installation, examine the logs for success.

Creating a profile after installation

Version 6 installation of the Network Deployment product is a two-step process:

1. Installing the core product files and feature files
2. Creating a deployment manager profile, a custom profile, or an application server profile

When the core product files exist, create a profile at any time using the Profile creation wizard. Start the
wizard from the First steps console or directly using the Profile creation wizard command.

64 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
You can also use one of the following sample options response files for profiles to create a profile silently
using the Profile creation wizard in silent mode. To edit and use the appropriate response file for creating a
profile, perform the following procedure:
1. Copy the appropriate file from the install_root/bin/ProfileCreator directory to a place that you can
easily identify on your machine. The example files are:

To create a profile for a: Copy the following response file:

Deployment manager responsefile.pct.NDdmgrProfile.txt
Managed node responsefile.pct.NDmanagedProfile.txt
Stand-alone application server responsefile.pct.NDstandAloneProfile.txt

For example, copy the file as my_options_file.txt

2. Edit the file to customize the values for your installation.
3. Save the file.
4. Start the installation.
For example:

v ./pctAIX.bin -options my_options_file.txt -silent

v ./pctHPUX.bin -options my_options_file.txt -silent

v 64-bit platforms: ./pctHPUXIA64.bin -options my_options_file.txt -silent

v ./pctLinux.bin -options my_options_file.txt -silent

v 64-bit platforms: ./pct.bin -options my_options_file.txt -silent

v Power platforms: ./pctLinuxPPC.bin -options my_options_file.txt -silent

v S/390 platforms: ./pctLinux390.bin -options my_options_file.txt -silent

v ./pctSolaris.bin -options my_options_file.txt -silent

v pctWindows.exe -options my_options_file.txt -silent

v 64-bit platforms: pctWindowsIA64.exe -options my_options_file.txt -silent

5. After using the Profile creation wizard, examine the logs for success.

Logging

The following log files record information about profile creation:

v The install_root/logs/log.txt file records installation status.
v The install_rootprofiles/profile_name/logs/pctLog.txt file records installation events that occur when
creating profiles with the Profile creation wizard.
v The install_root/logs/wasprofile/wasprofile_create_profile_name.log file records installation events
that occur when creating profiles.
v The install_root/logs/wasprofile/wasprofile_delete_profile_name.log file records installation events
that occur when deleting profiles.

See ″Troubleshooting installation″ in the information center for more information.

Usage notes
v The file is not a read-only file.
v Edit this file directly with your flat file editor of choice, such as WordPad on a Windows platform.

Chapter 3. Setting up the application serving environment 65

v The file is updated when you specify the -options parameter when using the Profile creation wizard and
the file does not yet exist.
v The file must exist to perform a silent installation. The installation program reads this file to determine
installation option values when you install silently.
v Save the file in a location that you can identify when you specify the fully qualified path as part of the
profile creation command.

Naming considerations

Consider the following recommendations when supplying names for the profile and other objects.

Naming the profile

Use the following guidelines when supplying a value for the profile name directive:
-W profilenamepanelInstallWizardBean.profileName

Profile naming guidelines: The profile name can be any unique name with the following restrictions. Do
not use any of the following characters when naming your profile:
v Spaces
v Illegal special characters that are not allowed within the name of a directory on your operating system,
such as *&?
v Slashes (/) or (\)

Double-byte characters are allowed.

Avoiding reserved names

Avoid the following reserved folder names as values for the directives in the
responsefile.pct.NDstandAloneProfile.txt file and in the responsefile.pct.NDmanagedProfile.txt file:
-W nodehostnamepanelInstallWizardBean.nodeName=""
-W nodehostnamepanelInstallWizardBean.hostName=""
-W setnondmgrcellnameinglobalconstantsInstallWizardBean.value=""

Avoid the following reserved folder names as values for the directives in the
responsefile.pct.NDdmgrProfile.txt file:
-W nodehostandcellnamepanelInstallWizardBean.nodeName=""
-W nodehostandcellnamepanelInstallWizardBean.hostName=""
-W nodehostandcellnamepanelInstallWizardBean.cellName=

Reserved names: Avoid using reserved folder names as field values. The use of reserved folder names
can cause unpredictable results. The following words are reserved:
v cells
v nodes
v servers
v clusters
v applications
v deployments

Node and cell name considerations

The profiles directory path must be no longer than 80 characters.

Host name considerations

66 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The host name is the network name for the physical machine on which the node is installed. The host
name must resolve to a physical network node on the server. When multiple network cards exist in the
server, the host name or IP address must resolve to one of the network cards. Remote nodes use the host
name to connect to and to communicate with this node. Selecting a host name that other machines can
reach within your network is extremely important. Do not use the generic localhost identifier for this value.

If you define coexisting nodes on the same computer with unique IP addresses, define each IP address in
a domain name server (DNS) look-up table. Configuration files for stand-alone Application Servers do not
provide domain name resolution for multiple IP addresses on a machine with a single network address.

The value that you specify for the host name is used as the value of the hostName property in
configuration documents for the stand-alone Application Server. Specify the host name value in one of the
following formats:
v Fully qualified domain name servers (DNS) host name string, such as xmachine.manhattan.ibm.com
v The default short DNS host name string, such as xmachine
v Numeric IP address, such as 127.1.255.3

The fully qualified DNS host name has the advantage of being totally unambiguous and also flexible. You
have the flexibility of changing the actual IP address for the host system without having to change the
Application Server configuration. This value for host name is particularly useful if you plan to change the IP
address frequently when using Dynamic Host Configuration Protocol (DHCP) to assign IP addresses. A
format disadvantage is being dependent on DNS. If DNS is not available, then connectivity is
compromised.

The short host name is also dynamically resolvable. A short name format has the added ability of being
redefined in the local hosts file so that the system can run the Application Server even when disconnected
from the network. Define the short name to 127.0.0.1 (local loopback) in the hosts file to run disconnected.
A format disadvantage is being dependent on DNS for remote access. If DNS is not available, then
connectivity is compromised.

A numeric IP address has the advantage of not requiring name resolution through DNS. A remote node
can connect to the node you name with a numeric IP address without DNS being available. A format
disadvantage is that the numeric IP address is fixed. You must change the setting of the hostName
property in Express configuration documents whenever you change the machine IP address. Therefore, do
not use a numeric IP address if you use DHCP, or if you change IP addresses regularly. Another format
disadvantage is that you cannot use the node if the host is disconnected from the network.

Example responsefile.pct.NDdmgrProfile.txt file

################################################################################
#
# Response file for Websphere Application Server 6.0 dmgr profile creation
#
# This options file is located in the CD_ROOT\WAS\ directory and in the
# install_root\bin\ProfileCreator directory.
#
# To use the options file under CD_ROOT\WAS\ directory, follow the instructions
# in CD_ROOT\WAS\responsefile.nd.txt. The WebSphere Application Server
# Network Deployment installer locates this file during silent installation
# and automatically runs the silent profile creation at the end of installation.
#
# To use the options file under install_root\bin\ProfileCreator for silent profile
# creation, you must change various values in the file and use the following
# command line arguments:
#
# -options "responsefile.pct.NDdmgrProfile.txt" -silent
#
################################################################################

Chapter 3. Setting up the application serving environment 67

################################################################################
#
# Profile name
#
# Set the profile name for installing a deployment manager profile. The profile
# name must be unique for this WebSphere Application Server installation.
#
-W profilenamepanelInstallWizardBean.profileName="profileDmgr"

################################################################################
# If you want to set this profile to be your default profile, set to "true".
# Otherwise set to "false". If this is the first profile being created, the profile
# automatically is the default.
#
-W profilenamepanelInstallWizardBean.isDefault="false"

################################################################################
#
# Profile location
#
# Specify a directory to contain the files that define the run-time environment,
# such as commands,configuration files, and log files. If the directory contains
# spaces, enclose it in double-quotes as shown in the Windows example below.
#
# Note that spaces in the install location is only supported on Windows
# operating systems.
#
# Default Install Location:
#
# -P installLocation="<WAS_HOME>\profiles\<PROFILE_NAME>"
#
-P installLocation="C:\Program Files\IBM\WebSphere\AppServer\profiles\profileDmgr"

################################################################################
#
# Node name
#
# Please select the node name for the Application Server. Node name under one cell
# has to be unique.
#
# Replace YOUR_NODE_NAME with the actual node name.
#
-W nodehostandcellnamepanelInstallWizardBean.nodeName="YOUR_NODE_NAME"

################################################################################
#
# Host name
#
# Specify the host name for the Application Server. The host name is the domain
# name system (DNS) name (short or long) or the IP address of this computer.
#
# Replace YOUR_HOST_NAME with the actual host name. Comment the line to use
# the default value.
#
-W nodehostandcellnamepanelInstallWizardBean.hostName="YOUR_HOST_NAME"

################################################################################
#
# Cell name
#
# Specify the cell name for the Application Server.
#
# If you plan to migrate a V5 deployment manager cell to this V6 deployment
# manager, specify the same cell name as the V5 cell.

68 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
#
# Replace YOUR_CELL_NAME with the actual cell name.
#
-W nodehostandcellnamepanelInstallWizardBean.cellName="YOUR_CELL_NAME"

################################################################################
#
# Port value assignment
#
# The following entries are used to reset port numbers used in the configuration
#
# They are currently set to the defaults.
# Please check to make sure there are no Port Conflicts.
# Port nubmers for each profile can be found in:
# <profile>/config/cells/<cell name>/nodes/<node name>/serverindex.xml
#
-W pctdmgrprofileportspanelInstallWizardBean.WC_adminhost="9060"
-W pctdmgrprofileportspanelInstallWizardBean.WC_adminhost_secure="9043"
-W pctdmgrprofileportspanelInstallWizardBean.BOOTSTRAP_ADDRESS="9809"
-W pctdmgrprofileportspanelInstallWizardBean.SOAP_CONNECTOR_ADDRESS="8879"
-W pctdmgrprofileportspanelInstallWizardBean.SAS_SSL_SERVERAUTH_LISTENER_ADDRESS="9404"
-W pctdmgrprofileportspanelInstallWizardBean.CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS="9406"
-W pctdmgrprofileportspanelInstallWizardBean.CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS="9405"
-W pctdmgrprofileportspanelInstallWizardBean.ORB_LISTENER_ADDRESS="9101"
-W pctdmgrprofileportspanelInstallWizardBean.CELL_DISCOVERY_ADDRESS="7277"
-W pctdmgrprofileportspanelInstallWizardBean.DCS_UNICAST_ADDRESS="9352"

################################################################################
#
# Windows service
#
# The following directives are to install services for WebSphere Application Server
# on Windows.
# Using Services, you can start and stop services,
# and configure startup and recovery actions.
# Set winServiceQuery="false" will turn off the function on windows system.
# You can ignore these or comment them out for other Operating Systems.
#
-W winservicepanelInstallWizardBean.winServiceQuery="true"

################################################################################
# Specify account type of the service. Legal values are:
#
# localsystem - Indicates that you choose to use Local System account.
# specifieduser - Indicates that you choose to use specified user account.
#
-W winservicepanelInstallWizardBean.accountType="localsystem"

################################################################################
# If you chose to install a service above with the accountType="localsystem",
# the userName and password below can be ignored. If the accountType was set to:
# accountType="specifieduser", then you must specify the User Name and Password
# which are required to install the Services. The current user must be admin or must
# have admin authority to install a Service. Also the username
# which is given here must have "Log On as a Service " authority
# for the service to run properly.
#
# Replace YOUR_USER_NAME with your username.
#
-W winservicepanelInstallWizardBean.userName="YOUR_USER_NAME"

################################################################################
# Replace YOUR_PASSWORD with your valid password.
#
-W winservicepanelInstallWizardBean.password="YOUR_PASSWORD"

Chapter 3. Setting up the application serving environment 69

################################################################################
# Set the startup type of the WebSphere Application Server on Windows.
# Valid values are "automatic", "manual", and "disabled".
#
-W winservicepanelInstallWizardBean.startupType="manual"

################################################################################
# Profile type
#
# Must be set to "dmgr" for installing a deployment manager Profile.
# Do not change this!
#
-W profiletypepanelInstallWizardBean.selection="dmgr"

Using the Profile creation wizard to create a custom profile

This topic describes creating a run-time environment for a custom profile.

Before using the Profile creation wizard, install the core product files.

The Profile creation wizard is the wizard interface to the profile creation tool, wasprofile. See the
description of the “wasprofile command” on page 96 for more information.

An error can occur when you have not provided enough system temporary space to create a profile. Verify
that you have a minimum of 40 MB of temp space available before creating a profile.

You must have 200 MB of available disk space in the directory where you create an Application Server
profile.

Manually verify that the required space for creating a profile is available on AIX. A known
problem in the underlying InstallShield for Multiplatforms (ISMP) code prevents proper space checking on
AIX systems at the time that the product disc was created.

After installing the core product files for the Network Deployment product, you must create one of the
following profiles to have an operational run-time environment:
v A custom profile.
This topic describes creating a custom profile. A custom profile is an empty node that you can
customize to include application servers, clusters, or other Java processes, such as a messaging
server.
You must have 10 MB of available disk space in the directory where you create a custom profile.
v A deployment manager.
See “Using the Profile creation wizard to create a deployment manager” on page 58. The deployment
manager provides a single administrative interface to a logical group of application servers on one or
more machines.
You must have 30 MB of available disk space in the directory where you create a deployment manager
profile.
v An application server profile.
See “Using the Profile creation wizard to create an application server” on page 84. An Application
Server profile has a default server (which is server1), the default application that includes the snoop
servlet and the hitcount servlet, and application Samples. You can federate the Application Server or
use it as a stand-alone Application Server.
You must have 200 MB of available disk space in the directory where you create an Application Server
profile.

70 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This topic describes creating a custom profile using the Profile creation wizard. You can use the Profile
creation wizard in silent mode with a response file instead of the graphical user interface. See
“responsefile.pct.NDmanagedProfile.txt” on page 75 for examples of using the Profile creation wizard in
silent mode.

You can also use the wasprofile command to create a custom profile. See the description of the
“wasprofile command” on page 96 for more information.

After creating a custom profile, you must have access to a running deployment manager to federate the
node. Federating the custom profile makes the node operational. If the custom profile is on a machine that
does not have a deployment manager, the deployment manager must be accessible over the network to
allow the federation of the node.

You can federate the custom node as you create the custom profile, either with the Profile creation wizard
or when using the wasprofile command. If you choose to federate, but the deployment manager is not
running, the custom node is not usable. You must then either delete the profile directory or move the
directory out of the profiles repository (profiles installation root directory) before creating another profile
with the same name.
1. Install the product to create the core product files.
2. Start the Profile creation wizard to create a new run-time environment.
Several ways exist to start the wizard. The initial way to start the wizard is at the end of installation by
selecting the check box to launch the Profile creation wizard.
One way to start the wizard is to issue the command directly from a command line.
The command is in the install_root/bin/ProfileCreator directory. The name of the command varies
per platform:

v pctAIX.bin

v pctHPUX.bin

v 64-bit platforms: pctHPUXIA64.bin

v pctLinux.bin

v 64-bit platforms: pct.bin S/390 platforms: pctLinux390.bin

v Power platforms: pctLinuxPPC.bin

v pctSolaris.bin

v pctWindows.exe

v 64-bit platforms: pctWindowsIA64.exe

Another way to start the Profile creation wizard is to select the wizard from the First steps console.
a. Open a command window.
b. Change directories to the firststeps directory in the installation root directory:
The installation root varies by platform:

v /usr/IBM/WebSphere/AppServer/firststeps

v /opt/IBM/WebSphere/AppServer/firststeps

v C:\Program Files\IBM\WebSphere\AppServer\firststeps
c. Issue the firststeps command to start the console:

v ./firststeps.sh

Chapter 3. Setting up the application serving environment 71

 v firststeps.bat
d. Select the Profile creation wizard option on the console.
The Profile creation wizard is an InstallShield for Multiplatforms application. The wizard loads the
Java 2 SDK and then displays its Welcome panel.
See the description of the “firststeps command” on page 48 for more information.
3. Click Next on the Welcome panel.
The wizard displays the Profile type selection panel.
4. Select Create a custom profile and click Next.
The wizard displays the Custom-profile federation panel.
5. Specify the host name and SOAP port of the deployment manager and click Next.
After federation, the process in the custom profile is the nodeagent process. The nodeagent process
is the agent of the deployment manager for the custom node. The nodeagent responds to commands
from the deployment manager to perform tasks that include the following actions:
v Creating application server processes, clusters, and cluster members
v Starting and stopping application server processes
v Synchronizing configurations between the current edition on the deployment manager and the copy
that exists on the node
v Deleting application server processes
See the system administration section of the information center for more information about node
agents and their tasks.
Should you federate the node?
Federate the custom node at this time if the deployment manager is running. Select the check box to
federate the node at a later time if the deployment manager is not running.
If you are unsure whether the deployment manager is running, do not federate now. Federate the
node later.
If security is enabled on the deployment manager node, you must federate later using the addNode
command to enter a user ID and password on the command.
A possibility exists that the deployment manager is reconfigured to use the non-default remote
method invocation (RMI) as the preferred Java Management Extensions (JMX) connector. (Click
System Administration > Deployment manager > Administrative services in the administrative
console of the deployment manager to verify the preferred connector type.)
If RMI is the preferred JMX connector, you must use the addNode command to federate the custom
profile at a later time. Use the addNode command so that you can specify the JMX connector type
and the RMI port.
If the deployment manager uses the default SOAP JMX connector type, specify the host name and
SOAP port and federate the node now to create a functional node that you can customize.
Federating when the deployment manager is not available
If you federate a custom node when the deployment manager is not running or is not available
because of security being enabled or for other reasons, the installation indicator in the logs is
INSTCONFFAIL to indicate a complete failure. The resulting custom profile is unusable. You must
move the custom profile directory out of the profile repository (the profiles installation root directory)
before creating another custom profile with the same profile name.
Click Next to display the Profile name panel.
6. Specify a name for the profile, then click Next.
Profile naming guidelines: The profile name can be any unique name with the following restrictions.
Do not use any of the following characters when naming your profile:
v Spaces

72 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Illegal special characters that are not allowed within the name of a directory on your operating
system, such as *&?
v Slashes (/) or (\)
Double-byte characters are allowed.
The default profile
The first profile that you create on a machine is the default profile. The default profile is the default
target for commands issued from the bin directory in the product installation root. When only one
profile exists on a machine, every command works on the only server process in the configuration.
Addressing a profile in a multi-profile environment
When two or more profiles exist on a machine, certain commands require that you specify the profile
to which the command applies. These commands use the -profileName parameter to identify which
profile to address. You might find it easier to use the commands that in the bin directory of each
profile.
A command in the profiles/profile_name/bin directory has two lines. The first line sets the
WAS_USER_SCRIPT environment variable for the command window. The variable sets up the
command environment to address the profile. The second line calls the actual command in the
install_root/bin directory.
The actual command queries the command shell to determine the calling profile and to autonomically
address the command to the calling profile.
The wizard then displays the Profile directory panel.
7. Specify a location for the profile and click Next.
If you click Back and change the name of the profile, you must manually change the name on this
panel when it displays again.
The wizard displays the Node and host names panel.
8. Specify the node and host characteristics for the custom profile and click Next.
Migration considerations
If you plan to migrate an installation of V5.x Network Deployment to V6, use the same cell name for
the V6 deployment manager as you used for the V5.x cell.
After migrating the cell, the V5 managed nodes are now managed by the V6 deployment manager in
compatibility mode. You can migrate individual V5 managed nodes in the cell to V6. To do so, you
must create a V6 profile with the same node name as the V5 managed node.
Reserved names: Avoid using reserved folder names as field values. The use of reserved folder
names can cause unpredictable results. The following words are reserved:
v cells
v nodes
v servers
v clusters
v applications
v deployments

Chapter 3. Setting up the application serving environment 73

 The custom profile has the following characteristics:

Field Default value Constraints Description

name
Node The name of Avoid using the reserved The name is used for administration within the deployment
name your machine, words. manager cell to which the custom profile is added. Use a
or a unique unique name within the deployment manager cell.
derivation of the Use a unique name
machine name. within the deployment After migrating a V5 deployment manager cell to a V6
manager cell. deployment manager, you can migrate the V5 custom
profiles that are running in compatibility mode in the V6
If you plan to migrate a deployment manager.
V5 managed node, use
the same node name for
this V6 custom profile.
Host The DNS name The host name must be Use the actual DNS name or IP address of your machine to
name of your addressable through your enable communication with your machine. See additional
machine. network. information about the host name that follows this table.

Node name considerations

The profiles directory path must be no longer than 80 characters.

Host name considerations
The host name is the network name for the physical machine on which the node is installed. The host
name must resolve to a physical network node on the server. When multiple network cards exist in
the server, the host name or IP address must resolve to one of the network cards. Remote nodes use
the host name to connect to and to communicate with this node. Selecting a host name that other
machines can reach within your network is extremely important. Do not use the generic localhost
identifier for this value.
If you define coexisting nodes on the same computer with unique IP addresses, define each IP
address in a domain name server (DNS) look-up table. Configuration files for stand-alone Application
Servers do not provide domain name resolution for multiple IP addresses on a machine with a single
network address.
The value that you specify for the host name is used as the value of the hostName property in
configuration documents for the stand-alone Application Server. Specify the host name value in one of
the following formats:
v Fully qualified domain name servers (DNS) host name string, such as
xmachine.manhattan.ibm.com
v The default short DNS host name string, such as xmachine
v Numeric IP address, such as 127.1.255.3
The fully qualified DNS host name has the advantage of being totally unambiguous and also flexible.
You have the flexibility of changing the actual IP address for the host system without having to
change the Application Server configuration. This value for host name is particularly useful if you plan
to change the IP address frequently when using Dynamic Host Configuration Protocol (DHCP) to
assign IP addresses. A format disadvantage is being dependent on DNS. If DNS is not available, then
connectivity is compromised.
The short host name is also dynamically resolvable. A short name format has the added ability of
being redefined in the local hosts file so that the system can run the Application Server even when
disconnected from the network. Define the short name to 127.0.0.1 (local loopback) in the hosts file to
run disconnected. A format disadvantage is being dependent on DNS for remote access. If DNS is
not available, then connectivity is compromised.
A numeric IP address has the advantage of not requiring name resolution through DNS. A remote
node can connect to the node you name with a numeric IP address without DNS being available. A
format disadvantage is that the numeric IP address is fixed. You must change the setting of the
hostName property in Express configuration documents whenever you change the machine IP
74 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 address. Therefore, do not use a numeric IP address if you use DHCP, or if you change IP addresses
regularly. Another format disadvantage is that you cannot use the node if the host is disconnected
from the network.
After specifying custom profile characteristics, the wizard displays the Port value assignment panel.
9. Specify port assignments that do not conflict for the custom profile and click Next.
When federating a custom profile, the addNode command uses non-conflicting ports. This means
that you can take the default port assignments as you create the profile, and let the addNode
command specify non-conflicting ports as you federate the node. Port assignments must be unique
on a machine. application server processes on different machines can use the same port
assignments without conflict.
After specifying non-conflicting port assignments, the wizard displays the Profile summary panel.
10. Click Next to create the custom profile or click Back to change the characteristics of the custom
profile. The wizard displays a Status panel as the wizard creates the custom profile.
At the end of the installation, the wizard displays the Profile creation is complete panel.
11. Click Finish to exit the Profile creation wizard.

You can create a custom profile. The node within the profile is empty until you federate the node and use
the deployment manager to customize the node.

Refer to the description of the “wasprofile command” on page 96 to learn about creating this type of profile
using a command instead of a wizard.

Federate the node into the deployment manager cell if you have not already done so as you created the
node. Then use the deployment manager to create an application server on the node. Then you are ready
to deploy an application.

Deploy an application to get started!

See Fast paths for WebSphere Application Server to get started deploying applications.

responsefile.pct.NDmanagedProfile.txt:

This topic describes the response file for creating a custom profile. Federate the custom node into a
running deployment manager cell to make the node operational.

Create a custom node using the with an options response file after logging on as root on a Linux or UNIX
platform, or as a user that belongs to the administrator group on a Windows platform. Some steps of the
installation procedure on a Windows platform require the user to belong to the administrator group and to
have the advanced user rights Act as part of the operating system and Log on as a service.

The response file is shipped with default values.

A common use for an options file is to run the Installation wizard in silent mode, which is referred to as
installing silently. The wizard reads the options file to determine responses and does not display the
graphical user interface. Issue the following command to use a copy of the options file named
myresponsefile.txt for a silent installation:
pctWindows.exe -options "myresponsefile.txt" -silent

Federating the custom profile

Several directives in the file provide options for how the custom node is federated into the deployment
manager cell:
v -W pctfederationpanelInstallWizardBean.federateLater

Chapter 3. Setting up the application serving environment 75

 Set this value to true if the deployment manager is not running or is not accessible for any of the
reasons in the following description of federation.
v -W pctfederationpanelInstallWizardBean.hostname
Specify a value that resolves to the system where the deployment manager is running. See the
following description of host name considerations for more information.
v -W pctfederationpanelInstallWizardBean.port
Specify the value of the deployment manager SOAP port. You must specify the correct value. An
incorrect value prevents node federation and results in a total failure with an INSTCONFFAILED
indicator. The default SOAP port for the deployment manager is 8879.

Should you federate the node?

Federate the custom node if you can. However, if any of the parameters that you supply are faulty, you not
only do not federate the node, you create a faulty custom profile. Federate the node at the time that you
perform the silent creation of the node if, and only if, the deployment manager is running and is accessible
at the host name that you specify and over the SOAP port that you specify.

If you are unsure whether the deployment manager is running, do not federate now. Federate the node
later.

If security is enabled on the deployment manager node, you must federate later using the addNode
command to enter a user ID and password on the command.

A possibility exists that the deployment manager is reconfigured to use the non-default remote method
invocation (RMI) as the preferred Java Management Extensions (JMX) connector. (Click System
Administration > Deployment manager > Administrative services in the administrative console of the
deployment manager to verify the preferred connector type.)

If RMI is the preferred JMX connector, you must use the addNode command to federate the custom
profile at a later time. Use the addNode command so that you can specify the JMX connector type and
the RMI port.

If the deployment manager uses the default SOAP JMX connector type, specify the host name and SOAP
port and federate the node now to create a functional node that you can customize.

Federating when the deployment manager is not available

If you federate a custom node when the deployment manager is not running or is not available because of
security being enabled or for other reasons, the installation indicator in the logs is INSTCONFFAIL to
indicate a complete failure. The resulting custom profile is unusable. You must move the custom profile
directory out of the profile repository (the profiles installation root directory) before creating another custom
profile with the same profile name.

Avoiding the use of the -silent option within the options response file

A problem occurs when the -silent option exists in the file. The file works with the option during a direct
call to the profile creation wizard, but fails when called from a silent product installation. See ″Customizing
the options response file for Network Deployment″ in the information center for information about creating
a profile silently during a silent product installation.

The option is unnecessary. Avoid using the option to avoid problems.

76 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Response file locations

The example options response files are in two locations.

Example files:
v responsefile.pct.NDdmgrProfile.txt
v responsefile.pct.NDmanagedProfile.txt
v responsefile.pct.NDstandAloneProfile.txt

Location:
Table 6. Option response file locations
Product disc location Installed location
/WAS directory install_root/bin/ProfileCreator directory

Use the file on the product disc to install the Network Deployment product silently and create a profile.

After installing the Network Deployment product, you can use the installed response file with the -options
parameter on the Profile creation wizard command.

Required disk space

Profile Required disk space Required temp space

Deployment manager profile 30 MB 40 MB
Custom profile 10 MB 40 MB
Application server profile 200 MB 40 MB

Creating an operational environment during product installation

Version 6 installation of the Network Deployment product is a two-step process:

1. Installing the core product files and feature files.
2. Creating a deployment manager profile, a custom profile, or an application server profile.

The sample options response file, responsefile.nd.txt, controls the first part of the installation and can also
start the second part of the installation. To create a profile as part of installing the core product files, use
the option in the responsefile.nd.txt file that identifies the response file for creating a profile. The profile
response file lets you use the Profile creation wizard silently.

To edit and use the appropriate response file for creating a profile, perform the following procedure:
1. Copy the appropriate file from the WAS directory on the product disc to a place that you can easily
identify on your machine. The example files are:

To create a: Copy the following response file:

Deployment manager profile responsefile.pct.NDdmgrProfile.txt
Custom profile responsefile.pct.NDmanagedProfile.txt
Application server profile responsefile.pct.NDstandAloneProfile.txt

2. Edit the file to customize the values for your installation.

3. Verify that no -silent option exists in the response file for the Profile creation wizard. If the option
exists, the profile is not created.

Chapter 3. Setting up the application serving environment 77

4. Save the file.
5. Edit the responsefile.nd.txt file to identify the location and name of the profile response file. Change
the value of the -W pctresponsefilelocationqueryactionInstallWizardBean.fileLocation option to identify
the file. For example:
-W pctresponsefilelocationqueryactionInstallWizardBean.fileLocation=
"/opt/IBM/WebSphere/MyOptionFiles/customProfile.txt"
6. Start the installation. For example:
install -options "myresponsefile.txt" -silent
7. After the installation, examine the logs for success.

Creating a profile after installation

Version 6 installation of the Network Deployment product is a two-step process:

1. Installing the core product files and feature files
2. Creating a deployment manager profile, a custom profile, or an application server profile

When the core product files exist, create a profile at any time using the Profile creation wizard. Start the
wizard from the First steps console or directly using the Profile creation wizard command.

You can also use one of the following sample options response files for profiles to create a profile silently
using the Profile creation wizard in silent mode. To edit and use the appropriate response file for creating a
profile, perform the following procedure:
1. Copy the appropriate file from the install_root/bin/ProfileCreator directory to a place that you can
easily identify on your machine. The example files are:

To create a profile for a: Copy the following response file:

Deployment manager responsefile.pct.NDdmgrProfile.txt
Managed node responsefile.pct.NDmanagedProfile.txt
Stand-alone application server responsefile.pct.NDstandAloneProfile.txt

For example, copy the file as my_options_file.txt

2. Edit the file to customize the values for your installation.
3. Save the file.
4. Start the installation.
For example:

v ./pctAIX.bin -options my_options_file.txt -silent

v ./pctHPUX.bin -options my_options_file.txt -silent

v 64-bit platforms: ./pctHPUXIA64.bin -options my_options_file.txt -silent

v ./pctLinux.bin -options my_options_file.txt -silent

v 64-bit platforms: ./pct.bin -options my_options_file.txt -silent

v Power platforms: ./pctLinuxPPC.bin -options my_options_file.txt -silent

v S/390 platforms: ./pctLinux390.bin -options my_options_file.txt -silent

v ./pctSolaris.bin -options my_options_file.txt -silent

v pctWindows.exe -options my_options_file.txt -silent

v 64-bit platforms: pctWindowsIA64.exe -options my_options_file.txt -silent

78 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
5. After using the Profile creation wizard, examine the logs for success.

Logging

The following log files record information about profile creation:

v The install_root/logs/log.txt file records installation status.
v The install_rootprofiles/profile_name/logs/pctLog.txt file records installation events that occur when
creating profiles with the Profile creation wizard.
v The install_root/logs/wasprofile/wasprofile_create_profile_name.log file records installation events
that occur when creating profiles.
v The install_root/logs/wasprofile/wasprofile_delete_profile_name.log file records installation events
that occur when deleting profiles.

See ″Troubleshooting installation″ in the information center for more information.

Usage notes
v The file is not a read-only file.
v Edit this file directly with your flat file editor of choice, such as WordPad on a Windows platform.
v The file is updated when you specify the -options parameter when using the Profile creation wizard and
the file does not yet exist.
v The file must exist to perform a silent installation. The installation program reads this file to determine
installation option values when you install silently.
v Save the file in a location that you can identify when you specify the fully qualified path as part of the
profile creation command.

Naming considerations

Consider the following recommendations when supplying names for the profile and other objects.

Naming the profile

Use the following guidelines when supplying a value for the profile name directive:
-W profilenamepanelInstallWizardBean.profileName

Specify a name for the profile, then click Next.

Profile naming guidelines: The profile name can be any unique name with the following restrictions. Do
not use any of the following characters when naming your profile:
v Spaces
v Illegal special characters that are not allowed within the name of a directory on your operating system,
such as *&?
v Slashes (/) or (\)

Double-byte characters are allowed.

The default profile

The first profile that you create on a machine is the default profile. The default profile is the default target
for commands issued from the bin directory in the product installation root. When only one profile exists
on a machine, every command works on the only server process in the configuration.

Addressing a profile in a multi-profile environment

Chapter 3. Setting up the application serving environment 79

When two or more profiles exist on a machine, certain commands require that you specify the profile to
which the command applies. These commands use the -profileName parameter to identify which profile to
address. You might find it easier to use the commands that in the bin directory of each profile.

A command in the profiles/profile_name/bin directory has two lines. The first line sets the
WAS_USER_SCRIPT environment variable for the command window. The variable sets up the command
environment to address the profile. The second line calls the actual command in the install_root/bin
directory.

The actual command queries the command shell to determine the calling profile and to autonomically
address the command to the calling profile.

The wizard then displays the Profile directory panel.

Avoiding reserved names

Avoid the following reserved folder names as values for the directives in the
responsefile.pct.NDstandAloneProfile.txt file and in the responsefile.pct.NDmanagedProfile.txt file:
-W nodehostnamepanelInstallWizardBean.nodeName=""
-W nodehostnamepanelInstallWizardBean.hostName=""
-W setnondmgrcellnameinglobalconstantsInstallWizardBean.value=""

Avoid the following reserved folder names as values for the directives in the
responsefile.pct.NDdmgrProfile.txt file:
-W nodehostandcellnamepanelInstallWizardBean.nodeName=""
-W nodehostandcellnamepanelInstallWizardBean.hostName=""
-W nodehostandcellnamepanelInstallWizardBean.cellName=

Reserved names: Avoid using reserved folder names as field values. The use of reserved folder names
can cause unpredictable results. The following words are reserved:
v cells
v nodes
v servers
v clusters
v applications
v deployments

Node and cell name considerations

The profiles directory path must be no longer than 80 characters.

Host name considerations

The host name is the network name for the physical machine on which the node is installed. The host
name must resolve to a physical network node on the server. When multiple network cards exist in the
server, the host name or IP address must resolve to one of the network cards. Remote nodes use the host
name to connect to and to communicate with this node. Selecting a host name that other machines can
reach within your network is extremely important. Do not use the generic localhost identifier for this value.

If you define coexisting nodes on the same computer with unique IP addresses, define each IP address in
a domain name server (DNS) look-up table. Configuration files for stand-alone Application Servers do not
provide domain name resolution for multiple IP addresses on a machine with a single network address.

80 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The value that you specify for the host name is used as the value of the hostName property in
configuration documents for the stand-alone Application Server. Specify the host name value in one of the
following formats:
v Fully qualified domain name servers (DNS) host name string, such as xmachine.manhattan.ibm.com
v The default short DNS host name string, such as xmachine
v Numeric IP address, such as 127.1.255.3

The fully qualified DNS host name has the advantage of being totally unambiguous and also flexible. You
have the flexibility of changing the actual IP address for the host system without having to change the
Application Server configuration. This value for host name is particularly useful if you plan to change the IP
address frequently when using Dynamic Host Configuration Protocol (DHCP) to assign IP addresses. A
format disadvantage is being dependent on DNS. If DNS is not available, then connectivity is
compromised.

The short host name is also dynamically resolvable. A short name format has the added ability of being
redefined in the local hosts file so that the system can run the Application Server even when disconnected
from the network. Define the short name to 127.0.0.1 (local loopback) in the hosts file to run disconnected.
A format disadvantage is being dependent on DNS for remote access. If DNS is not available, then
connectivity is compromised.

A numeric IP address has the advantage of not requiring name resolution through DNS. A remote node
can connect to the node you name with a numeric IP address without DNS being available. A format
disadvantage is that the numeric IP address is fixed. You must change the setting of the hostName
property in Express configuration documents whenever you change the machine IP address. Therefore, do
not use a numeric IP address if you use DHCP, or if you change IP addresses regularly. Another format
disadvantage is that you cannot use the node if the host is disconnected from the network.

Example responsefile.pct.NDmanagedProfile.txt file

Tip: A custom profile must be added into a deployment manager cell to become operational. Because of
this strong dependency on being a managed node, the profile is often referred to as a managed
profile or as a managed node.

Of course, until you federate the node into a cell, the node is not managed. Another thing to keep in
mind is that any federated node is a managed node, including federated nodes within Application
Server profiles.

The following response file refers to the term managed instead of the term custom in many directive
names. Even so, all of the directives in this response file help to define a custom profile.
################################################################################
#
# Response file for WebSphere Application Server v6.0 custom profile creation
#
# This options file is located in the CD_ROOT\WAS\ directory and in the
# install_root\bin\ProfileCreator directory.
#
# To use the options file under CD_ROOT\WAS\ directory, follow the instructions
# in CD_ROOT\WAS\responsefile.nd.txt. The WebSphere Application Server
# Network Deployment installer locates this file during silent installation
# and automatically runs the silent profile creation at the end of installation.
#
# To use the options file under install_root\bin\ProfileCreator for silent profile
# creation, you must change various values in the file and use the following command
# line arguments:
#
# -options "responsefile.pct.NDmanagedProfile.txt" -silent
#
################################################################################

Chapter 3. Setting up the application serving environment 81

################################################################################
#
# Profile name
#
# Set the name for this custom profile. The profile name must be unique for this
# WebSphere Application Server installation.
#
#
-W profilenamepanelInstallWizardBean.profileName="profileManaged"

################################################################################
# If you want to set this profile to be your default profile, set to "true".
# Otherwise set to "false". If this is the first profile being created, the profile
# automatically is the default.
#
-W profilenamepanelInstallWizardBean.isDefault="false"

################################################################################
#
# Profile location
#
# Specify a directory to contain the files that define the run-time environment,
# such as commands,configuration files, and log files. If the directory contains
# spaces, enclose it in double-quotes as shown in the Windows example below.
#
# Note that spaces in the install location is only supported on Windows
# operating systems.
#
# Default Install Location:
#
# -P installLocation="<WAS_HOME>\profiles\<PROFILE_NAME>"
#
-P installLocation="C:\Program Files\IBM\WebSphere\AppServer\profiles\profileManaged"

################################################################################
#
# Node name
#
# Please select the node name for the Application Server. Node name under one cell
# has to be unique.
#
# If you plan to migrate a V5 deployment manager cell, the V5 managed nodes are also
# migrated to the V6 cell. To incrementally migrate an individual V5 managed node
# to V6, you must use the same node name for the V6 Application Server profile.
#
# Replace YOUR_NODE_NAME with the actual node name.
#
-W nodehostnamepanelInstallWizardBean.nodeName="YOUR_NODE_NAME"

################################################################################
#
# Host name
#
# Specify the host name for the Application Server. The host name is the domain
# name system (DNS) name (short or long) or the IP address of this computer.
#
# Replace YOUR_HOST_NAME with the actual host name. Comment the line to use
# the default value.
#
-W nodehostnamepanelInstallWizardBean.hostName="YOUR_HOST_NAME"

82 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
################################################################################
#
# Cell name
#
# You should not Modify this, unless absolutely necessary
#
# The Wizard would set this to short local host name + "Node##Cell" by default.
#
# If you would like to override the resolved cell name value, uncomment the line and
# replace YOUR_CELL_NAME with <YOUR_OWN_VALUE>
#
# -W setnondmgrcellnameinglobalconstantsInstallWizardBean.value="YOUR_CELL_NAME"

################################################################################
#
# Ports value assignment
#
# The following entries are used to reset port numbers used in the configuration
#
# They are currently set to the defaults.
# Please check to make sure there are no port conflicts.
# Port nubmers for each profile can be find in:
# <profile>/config/cells/<cell name>/nodes/<node name>/serverindex.xml
#
# If you specify true for the value of
# the -W pctfederationpanelInstallWizardBean.federateLater
# directive, port numbers are assigned automatically when you federate the
# node with the addNode command. The following port numbers do not apply.
#
-W pctmanagedprofileportspanelInstallWizardBean.BOOTSTRAP_ADDRESS="2809"
-W pctmanagedprofileportspanelInstallWizardBean.SOAP_CONNECTOR_ADDRESS="8878"
-W pctmanagedprofileportspanelInstallWizardBean.SAS_SSL_SERVERAUTH_LISTENER_ADDRESS="9901"
-W pctmanagedprofileportspanelInstallWizardBean.CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS="9201"
-W pctmanagedprofileportspanelInstallWizardBean.CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS="9202"
-W pctmanagedprofileportspanelInstallWizardBean.ORB_LISTENER_ADDRESS="9100"
-W pctmanagedprofileportspanelInstallWizardBean.NODE_DISCOVERY_ADDRESS="7272"
-W pctmanagedprofileportspanelInstallWizardBean.NODE_MULTICAST_DISCOVERY_ADDRESS="5000"
-W pctmanagedprofileportspanelInstallWizardBean.NODE_IPV6_MULTICAST_DISCOVERY_ADDRESS="5001"
-W pctmanagedprofileportspanelInstallWizardBean.DCS_UNICAST_ADDRESS="9353"

################################################################################
#
# Federation
#
# A custom profile contains an empty node that must be federated to a deployment
# manager to become a functional managed node. Identify a running deployment
# manager that will administer the node or choose to federate the node later
# using the addNode command.
#
# Set to "true" if you want to federate this custom node later using the addNode
# command. You must federate this node later if the deployment manager :
# - is not running.
# - has security enabled.
# - has the SOAP connector disabled
#
# If you want to federate it now, set to "" and fill in the entries for the host
# and port of the deployment manager.
#
-W pctfederationpanelInstallWizardBean.federateLater=""

################################################################################
# Specify the host name of the deployment manager for federation.
#
-W pctfederationpanelInstallWizardBean.hostname="YOUR_DEPLOYMENT_MANAGER_HOST_NAME"

Chapter 3. Setting up the application serving environment 83

################################################################################
# Specify the port number where the deployment manager (DMGR) is reachable on the
# above host. The default port value is "8879".
#
-W pctfederationpanelInstallWizardBean.port="YOUR_DEPLOYMENT_MANAGER_PORT_NUMBER"

################################################################################
#
# Profile type
#
# Must be set to "managed" for installing a custom profile. Do not change this!
#
-W profiletypepanelInstallWizardBean.selection="managed"

Using the Profile creation wizard to create an application server

The Profile creation wizard can create an application server profile on any machine where the core product
files exist.

Before using the Profile creation wizard, install the core product files.

The Profile creation wizard is the wizard interface to the profile creation tool, wasprofile. See the
description of the “wasprofile command” on page 96 for more information.

An error can occur when you have not provided enough system temporary space to create a profile. Verify
that you have a minimum of 40 MB of temp space available before creating a profile.

You must have 200 MB of available disk space in the directory where you create an Application Server
profile.

Important:

You must have 30 MB of available disk space in the directory where you create a deployment
manager profile.

You must have 10 MB of available disk space in the directory where you create a custom
profile.

Manually verify that the required space for creating a profile is available on AIX. A known
problem in the underlying InstallShield for Multiplatforms (ISMP) code prevents proper space checking on
AIX systems at the time that the product disc was created.

Important:

After installing the core product files, you must create one of the following profiles to have an
operational run-time environment:
v An application server that is described in this topic.
An application server profile has a default server (which is server1), the default application
that includes the snoop servlet and the hitcount servlet, and application Samples. You can
federate the application server or use it as a stand-alone application server.
v A deployment manager.
See “Using the Profile creation wizard to create a deployment manager” on page 58. The
deployment manager provides a single administrative interface to a logical group of
application servers on one or more machines.

84 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v A custom profile that you must federate to make operational.
See “Using the Profile creation wizard to create a custom profile” on page 70. A custom
profile is an empty node that you can customize to include application servers, clusters, or
other Java processes, such as a messaging server.

This procedure describes creating an application server profile using the graphical user interface provided
by the Profile creation wizard.

You can use the Profile creation wizard in silent mode with a response file instead of a graphical user
interface. See “responsefile.pct.NDstandAloneProfile.txt” on page 88 for examples of using the Profile
creation wizard in silent mode.

You can also use the wasprofile command to create an application server profile. See the description of
the “wasprofile command” on page 96 for more information.
1. Start the Profile creation wizard to create a new run-time environment.
Several ways exist to start the wizard. The initial way to start the wizard is at the end of installation by
selecting the check box to launch the Profile creation wizard.
One way to start the wizard is to issue the command directly from a command line.
The command is in the install_root/bin/ProfileCreator directory. The name of the command varies
per platform:

v pctAIX.bin

v pctHPUX.bin

v 64-bit platforms: pctHPUXIA64.bin

v pctLinux.bin

v 64-bit platforms: pct.bin S/390 platforms: pctLinux390.bin

v Power platforms: pctLinuxPPC.bin

v pctSolaris.bin

v pctWindows.exe

v 64-bit platforms: pctWindowsIA64.exe

Another way to start the Profile creation wizard is to select the wizard from the First steps console.
a. Open a command window.
b. Change directories to the firststeps directory in the installation root directory:
The installation root varies by platform:

v /usr/IBM/WebSphere/AppServer/firststeps

v /opt/IBM/WebSphere/AppServer/firststeps

v C:\Program Files\IBM\WebSphere\AppServer\firststeps
c. Issue the firststeps command to start the console:

v ./firststeps.sh

v firststeps.bat
d. Select the Profile creation wizard option on the console.
The Profile creation wizard is an InstallShield for Multiplatforms application. The wizard loads the
Java 2 SDK and then displays its Welcome panel.

Chapter 3. Setting up the application serving environment 85

 See the description of the “firststeps command” on page 48 for more information.
2. Click Next on the Welcome panel.
The wizard displays the Profile type selection panel.
3. Select the application server profile, then click Next.
The wizard displays the Profile directory panel.
4. Specify a name for the profile, then click Next.
Profile naming guidelines: The profile name can be any unique name with the following restrictions.
Do not use any of the following characters when naming your profile:
v Spaces
v Illegal special characters that are not allowed within the name of a directory on your operating
system, such as *&?
v Slashes (/) or (\)
Double-byte characters are allowed.
The default profile
The first profile that you create on a machine is the default profile. The default profile is the default
target for commands issued from the bin directory in the product installation root. When only one
profile exists on a machine, every command works on the only server process in the configuration.
Addressing a profile in a multi-profile environment
When two or more profiles exist on a machine, certain commands require that you specify the profile
to which the command applies. These commands use the -profileName parameter to identify which
profile to address. You might find it easier to use the commands that in the bin directory of each
profile.
A command in the profiles/profile_name/bin directory has two lines. The first line sets the
WAS_USER_SCRIPT environment variable for the command window. The variable sets up the
command environment to address the profile. The second line calls the actual command in the
install_root/bin directory.
The actual command queries the command shell to determine the calling profile and to autonomically
address the command to the calling profile.
The wizard then displays the Profile directory panel.
5. Accept the default directory or specify a non-default location, then click Next. Or click Browse to
select a different location.
If you click Back and change the name of the profile, you must manually change the name on this
panel when it displays again.
The wizard displays the Node and host name panel.
6. Specify the characteristics for the application server, then click Next.
Use unique names for each application server that you create.
Reserved names: Avoid using reserved folder names as field values. The use of reserved folder
names can cause unpredictable results. The following words are reserved:
v cells
v nodes
v servers
v clusters
v applications
v deployments

86 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Field name Default value Constraints Description
Node name Name of your Avoid using the reserved Pick any name you want. To help organize
machine words. your installation, use a unique name if you
plan to create more than one application
server on the machine.
Host name DNS name of your Addressable through your Use the actual DNS name or IP address of
machine network. your machine to enable communication with
your machine. See additional information
about the host name following this table.

Node name considerations: If you plan to migrate an installation of V5.x Network Deployment to V6
and migrate one of the managed nodes in the cell, use the same node name for the V6 application
server as you used for the V5.x managed node.

The installation directory path must be no longer than 60 characters.

Host name considerations:
The host name is the network name for the physical machine on which the node is installed. The host
name must resolve to a physical network node on the server. When multiple network cards exist in
the server, the host name or IP address must resolve to one of the network cards. Remote nodes use
the host name to connect to and to communicate with this node. Selecting a host name that other
machines can reach within your network is extremely important. Do not use the generic localhost
identifier for this value.
If you define coexisting nodes on the same computer with unique IP addresses, define each IP
address in a domain name server (DNS) look-up table. Configuration files for stand-alone Application
Servers do not provide domain name resolution for multiple IP addresses on a machine with a single
network address.
The value that you specify for the host name is used as the value of the hostName property in
configuration documents for the stand-alone Application Server. Specify the host name value in one of
the following formats:
v Fully qualified domain name servers (DNS) host name string, such as
xmachine.manhattan.ibm.com
v The default short DNS host name string, such as xmachine
v Numeric IP address, such as 127.1.255.3
The fully qualified DNS host name has the advantage of being totally unambiguous and also flexible.
You have the flexibility of changing the actual IP address for the host system without having to
change the Application Server configuration. This value for host name is particularly useful if you plan
to change the IP address frequently when using Dynamic Host Configuration Protocol (DHCP) to
assign IP addresses. A format disadvantage is being dependent on DNS. If DNS is not available, then
connectivity is compromised.
The short host name is also dynamically resolvable. A short name format has the added ability of
being redefined in the local hosts file so that the system can run the Application Server even when
disconnected from the network. Define the short name to 127.0.0.1 (local loopback) in the hosts file to
run disconnected. A format disadvantage is being dependent on DNS for remote access. If DNS is
not available, then connectivity is compromised.
A numeric IP address has the advantage of not requiring name resolution through DNS. A remote
node can connect to the node you name with a numeric IP address without DNS being available. A
format disadvantage is that the numeric IP address is fixed. You must change the setting of the
hostName property in Express configuration documents whenever you change the machine IP
address. Therefore, do not use a numeric IP address if you use DHCP, or if you change IP addresses
regularly. Another format disadvantage is that you cannot use the node if the host is disconnected
from the network.
After specifying application server characteristics, the wizard displays the Port value assignment
panel.

Chapter 3. Setting up the application serving environment 87

 7. Verify that the ports specified for the stand-alone application server are unique, then click Next.

After specifying port assignments, the wizard displays the Windows service definition
panel, if you are installing on a Windows platform.

8. Choose whether to run the application server as a Windows service on a Windows

platform and click Next.
Version 6 attempts to start Windows services for application server processes started by a
startServer command. For example, if you configure an application server as a Windows service and
issue the startServer command, the wasservice command attempts to start the defined service.
If you chose to install a local system service, you do not have to specify your user ID or password. If
you create a specified user type of service, you must specify the user ID and the password for the
user who is to run the service. The user must have Log on as a service authority for the service to
run properly.
To perform this installation task, the user ID must not have spaces in its name. The ID must also
belong to the administrator group and must have the advanced user rights Act as part of the
operating system and Log on as a service. The Installation wizard grants the user ID the advanced
user rights if it does not already have them, if the user ID belongs to the administrator group.
You can also create other Windows services after the installation is complete, to start other server
processes. See “Automatically restarting server processes” on page 244 for more information.
The installation wizard shows which components are selected for installation in a pre-installation
summary panel.
9. Click Next to create the application server or click Back to change the characteristics of the
application server.
The wizard displays the Installation status panel that shows which components are installing.
When the installation is complete, the wizard displays the Profile creation is complete panel.
10. Click Finish to exit, then click Profile creation wizard on the First steps console to start the wizard
again to create other application servers.

You can create an application server profile. The node within the profile has an application server named
server1.

Refer to the description of the “wasprofile command” on page 96 to learn about creating this type of profile
using a command instead of a wizard.

Deploy an application to get started!

See Fast paths for WebSphere Application Server to get started deploying applications.

responsefile.pct.NDstandAloneProfile.txt:

This topic describes the response file for creating a stand-alone application server profile.

Create a stand-alone application server profile with an options response file after logging on as root on a
Linux or UNIX platform, or a user that belongs to the administrator group on a Windows platform. Some
steps of the installation procedure on a Windows platform require the user to belong to the administrator
group and to have the advanced user rights Act as part of the operating system and Log on as a service.

The response file is shipped with default values.

A common use for an options file is to run the Installation wizard in silent mode, which is referred to as
installing silently. The wizard reads the options file to determine responses and does not display the
graphical user interface. Issue the following command to use a copy of the options file named
myresponsefile.txt for a silent installation:

88 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
pctWindows.exe -options "myresponsefile.txt" -silent

Avoiding the use of the -silent option within the options response file

A problem occurs when the -silent option exists in the file. The file works with the option during a direct
call to the profile creation wizard, but fails when called from a silent product installation. See ″Customizing
the options response file for Network Deployment″ in the information center for information about creating
a profile silently during a silent product installation.

The option is unnecessary. Avoid using the option to avoid problems.

Response file locations

The example options response files are in two locations.

Example files:
v responsefile.pct.NDdmgrProfile.txt
v responsefile.pct.NDmanagedProfile.txt
v responsefile.pct.NDstandAloneProfile.txt

Location:
Table 7. Option response file locations
Product disc location Installed location
/WAS directory install_root/bin/ProfileCreator directory

Use the file on the product disc to install the Network Deployment product silently and create a profile.

After installing the Network Deployment product, you can use the installed response file with the -options
parameter on the Profile creation wizard command.

Required disk space

Profile Required disk space Required temp space

Deployment manager profile 30 MB 40 MB
Custom profile 10 MB 40 MB
Application server profile 200 MB 40 MB

Creating an operational environment during product installation

Version 6 installation of the Network Deployment product is a two-step process:

1. Installing the core product files and feature files.
2. Creating a deployment manager profile, a custom profile, or an application server profile.

The sample options response file, responsefile.nd.txt, controls the first part of the installation and can also
start the second part of the installation. To create a profile as part of installing the core product files, use
the option in the responsefile.nd.txt file that identifies the response file for creating a profile. The profile
response file lets you use the Profile creation wizard silently.

To edit and use the appropriate response file for creating a profile, perform the following procedure:
1. Copy the appropriate file from the WAS directory on the product disc to a place that you can easily
identify on your machine. The example files are:

Chapter 3. Setting up the application serving environment 89

To create a: Copy the following response file:
Deployment manager profile responsefile.pct.NDdmgrProfile.txt
Custom profile responsefile.pct.NDmanagedProfile.txt
Application server profile responsefile.pct.NDstandAloneProfile.txt

2. Edit the file to customize the values for your installation.

3. Verify that no -silent option exists in the response file for the Profile creation wizard. If the option
exists, the profile is not created.
4. Save the file.
5. Edit the responsefile.nd.txt file to identify the location and name of the profile response file. Change
the value of the -W pctresponsefilelocationqueryactionInstallWizardBean.fileLocation option to identify
the file. For example:
-W pctresponsefilelocationqueryactionInstallWizardBean.fileLocation=
"/opt/IBM/WebSphere/MyOptionFiles/customProfile.txt"
6. Start the installation. For example:
install -options "myresponsefile.txt" -silent
7. After the installation, examine the logs for success.

Creating a profile after installation

Version 6 installation of the Network Deployment product is a two-step process:

1. Installing the core product files and feature files
2. Creating a deployment manager profile, a custom profile, or an application server profile

When the core product files exist, create a profile at any time using the Profile creation wizard. Start the
wizard from the First steps console or directly using the Profile creation wizard command.

You can also use one of the following sample options response files for profiles to create a profile silently
using the Profile creation wizard in silent mode. To edit and use the appropriate response file for creating a
profile, perform the following procedure:
1. Copy the appropriate file from the install_root/bin/ProfileCreator directory to a place that you can
easily identify on your machine. The example files are:

To create a profile for a: Copy the following response file:

Deployment manager responsefile.pct.NDdmgrProfile.txt
Managed node responsefile.pct.NDmanagedProfile.txt
Stand-alone application server responsefile.pct.NDstandAloneProfile.txt

For example, copy the file as my_options_file.txt

2. Edit the file to customize the values for your installation.
3. Save the file.
4. Start the installation.
For example:

v ./pctAIX.bin -options my_options_file.txt -silent

v ./pctHPUX.bin -options my_options_file.txt -silent

v 64-bit platforms: ./pctHPUXIA64.bin -options my_options_file.txt -silent

v ./pctLinux.bin -options my_options_file.txt -silent

90 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v 64-bit platforms: ./pct.bin -options my_options_file.txt -silent

v Power platforms: ./pctLinuxPPC.bin -options my_options_file.txt -silent

v S/390 platforms: ./pctLinux390.bin -options my_options_file.txt -silent

v ./pctSolaris.bin -options my_options_file.txt -silent

v pctWindows.exe -options my_options_file.txt -silent

v 64-bit platforms: pctWindowsIA64.exe -options my_options_file.txt -silent

5. After using the Profile creation wizard, examine the logs for success.

Logging

The following log files record information about profile creation:

v The install_root/logs/log.txt file records installation status.
v The install_rootprofiles/profile_name/logs/pctLog.txt file records installation events that occur when
creating profiles with the Profile creation wizard.
v The install_root/logs/wasprofile/wasprofile_create_profile_name.log file records installation events
that occur when creating profiles.
v The install_root/logs/wasprofile/wasprofile_delete_profile_name.log file records installation events
that occur when deleting profiles.

See ″Troubleshooting installation″ in the information center for more information.

Usage notes
v The file is not a read-only file.
v Edit this file directly with your flat file editor of choice, such as WordPad on a Windows platform.
v The file is updated when you specify the -options parameter when using the Profile creation wizard and
the file does not yet exist.
v The file must exist to perform a silent installation. The installation program reads this file to determine
installation option values when you install silently.
v Save the file in a location that you can identify when you specify the fully qualified path as part of the
profile creation command.

Naming considerations

Consider the following recommendations when supplying names for the profile and other objects.

Naming the profile

Use the following guidelines when supplying a value for the profile name directive:
-W profilenamepanelInstallWizardBean.profileName

Profile naming guidelines: The profile name can be any unique name with the following restrictions. Do
not use any of the following characters when naming your profile:
v Spaces
v Illegal special characters that are not allowed within the name of a directory on your operating system,
such as *&?
v Slashes (/) or (\)

Double-byte characters are allowed.

Avoiding reserved names

Chapter 3. Setting up the application serving environment 91
Avoid the following reserved folder names as values for the directives in the
responsefile.pct.NDstandAloneProfile.txt file and in the responsefile.pct.NDmanagedProfile.txt file:
-W nodehostnamepanelInstallWizardBean.nodeName=""
-W nodehostnamepanelInstallWizardBean.hostName=""
-W setnondmgrcellnameinglobalconstantsInstallWizardBean.value=""

Avoid the following reserved folder names as values for the directives in the
responsefile.pct.NDdmgrProfile.txt file:
-W nodehostandcellnamepanelInstallWizardBean.nodeName=""
-W nodehostandcellnamepanelInstallWizardBean.hostName=""
-W nodehostandcellnamepanelInstallWizardBean.cellName=

Reserved names: Avoid using reserved folder names as field values. The use of reserved folder names
can cause unpredictable results. The following words are reserved:
v cells
v nodes
v servers
v clusters
v applications
v deployments

Node and cell name considerations

The profiles directory path must be no longer than 80 characters.

Host name considerations

The host name is the network name for the physical machine on which the node is installed. The host
name must resolve to a physical network node on the server. When multiple network cards exist in the
server, the host name or IP address must resolve to one of the network cards. Remote nodes use the host
name to connect to and to communicate with this node. Selecting a host name that other machines can
reach within your network is extremely important. Do not use the generic localhost identifier for this value.

If you define coexisting nodes on the same computer with unique IP addresses, define each IP address in
a domain name server (DNS) look-up table. Configuration files for stand-alone Application Servers do not
provide domain name resolution for multiple IP addresses on a machine with a single network address.

The value that you specify for the host name is used as the value of the hostName property in
configuration documents for the stand-alone Application Server. Specify the host name value in one of the
following formats:
v Fully qualified domain name servers (DNS) host name string, such as xmachine.manhattan.ibm.com
v The default short DNS host name string, such as xmachine
v Numeric IP address, such as 127.1.255.3

The fully qualified DNS host name has the advantage of being totally unambiguous and also flexible. You
have the flexibility of changing the actual IP address for the host system without having to change the
Application Server configuration. This value for host name is particularly useful if you plan to change the IP
address frequently when using Dynamic Host Configuration Protocol (DHCP) to assign IP addresses. A
format disadvantage is being dependent on DNS. If DNS is not available, then connectivity is
compromised.

The short host name is also dynamically resolvable. A short name format has the added ability of being
redefined in the local hosts file so that the system can run the Application Server even when disconnected

92 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
from the network. Define the short name to 127.0.0.1 (local loopback) in the hosts file to run disconnected.
A format disadvantage is being dependent on DNS for remote access. If DNS is not available, then
connectivity is compromised.

A numeric IP address has the advantage of not requiring name resolution through DNS. A remote node
can connect to the node you name with a numeric IP address without DNS being available. A format
disadvantage is that the numeric IP address is fixed. You must change the setting of the hostName
property in Express configuration documents whenever you change the machine IP address. Therefore, do
not use a numeric IP address if you use DHCP, or if you change IP addresses regularly. Another format
disadvantage is that you cannot use the node if the host is disconnected from the network.

Example responsefile.pct.NDstandAloneProfile.txt file

################################################################################
#
# Response file for WebSphere Application Server v6.0 stand alone profile
# creation
#
# This options file is located in the CD_ROOT\WAS\ directory and in the
# install_root\bin\ProfileCreator directory.
#
# To use the options file under CD_ROOT\WAS\ directory, follow the instructions
# in CD_ROOT\WAS\responsefile.nd.txt. The WebSphere Application Server
# Network Deployment installer locates this file during silent installation
# and automatically runs the silent profile creation at the end of installation.
#
# To use the options file under install_root\bin\ProfileCreator for silent profile
# creation, you must change various values in the file and use the following
# command line arguments:
#
# -options "responsefile.pct.NDstandAloneProfile.txt" -silent
#
################################################################################

################################################################################
#
# Profile name
#
# Set the profile name for installing a stand alone profile. The profile
# name must be unique for this WebSphere Application Server installation.
#
-W profilenamepanelInstallWizardBean.profileName="profileStandAlone"

################################################################################
# If you want to set this profile to be your default profile, set to "true".
# Otherwise set to "false". If this is the first profile being created, the profile
# automatically is the default.
#
-W profilenamepanelInstallWizardBean.isDefault="false"

################################################################################
#
# Profile location
#
# Specify a directory to contain the files that define the run-time environment,
# such as commands,configuration files, and log files. If the directory contains
# spaces, enclose it in double-quotes as shown in the Windows example below.
#
# Note that spaces in the install location is only supported on Windows
# operating systems.
#
# Default Install Location:
#

Chapter 3. Setting up the application serving environment 93

# -P installLocation="<WAS_HOME>\profiles\<PROFILE_NAME>"
#
-P installLocation="C:\Program Files\IBM\WebSphere\AppServer\profiles\profileStandAlone"

################################################################################
#
# Node name
#
# Please select the node name for the Application Server. Node name under one cell
# has to be unique.
#
# If you plan to migrate a V5 deployment manager cell, the V5 managed nodes are also
# migrated to the V6 cell. To incrementally migrate an individual V5 managed node
# to V6, you must use the same node name for the V6 Application Server profile.
#
# Replace YOUR_NODE_NAME with the actual node name.
#
-W nodehostnamepanelInstallWizardBean.nodeName="YOUR_NODE_NAME"

################################################################################
#
# Host name
#
# Specify the host name for the Application Server. The host name is the domain
# name system (DNS) name (short or long) or the IP address of this computer.
#
# Replace YOUR_HOST_NAME with the actual host name. Comment the line to use
# the default value.
#
-W nodehostnamepanelInstallWizardBean.hostName="YOUR_HOST_NAME"

################################################################################
#
# Cell name
#
# You should not Modify this, unless absolutely necessary.
#
# The Wizard would set this to short local host name + "Node##Cell" by default.
#
# If you would like to override the resolved cell name value, uncomment the line and
# replace YOUR_CELL_NAME with <YOUR_OWN_VALUE>.
#
# -W setnondmgrcellnameinglobalconstantsInstallWizardBean.value="YOUR_CELL_NAME"

################################################################################
#
# Port value assignment
#
# The following entries are used to reset port numbers used in the configuration
#
# They are currently set to the defaults.
# Please check to make sure there are no Port Conflicts.
# Port numbers for each profile can be find in:
# <profile>/config/cells/<cell name>/nodes/<node name>/serverindex.xml
#
-W pctdefaultprofileportspanelInstallWizardBean.WC_defaulthost="9080"
-W pctdefaultprofileportspanelInstallWizardBean.WC_adminhost="9060"
-W pctdefaultprofileportspanelInstallWizardBean.WC_defaulthost_secure="9443"
-W pctdefaultprofileportspanelInstallWizardBean.WC_adminhost_secure="9043"
-W pctdefaultprofileportspanelInstallWizardBean.BOOTSTRAP_ADDRESS="2809"
-W pctdefaultprofileportspanelInstallWizardBean.SOAP_CONNECTOR_ADDRESS="8880"
-W pctdefaultprofileportspanelInstallWizardBean.SAS_SSL_SERVERAUTH_LISTENER_ADDRESS="9401"
-W pctdefaultprofileportspanelInstallWizardBean.CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS="9403"
-W pctdefaultprofileportspanelInstallWizardBean.CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS="9402"

94 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-W pctdefaultprofileportspanelInstallWizardBean.ORB_LISTENER_ADDRESS="9100"
-W pctdefaultprofileportspanelInstallWizardBean.DCS_UNICAST_ADDRESS="9353"
-W pctdefaultprofileportspanelInstallWizardBean.SIB_ENDPOINT_ADDRESS="7276"
-W pctdefaultprofileportspanelInstallWizardBean.SIB_ENDPOINT_SECURE_ADDRESS="7286"
-W pctdefaultprofileportspanelInstallWizardBean.SIB_MQ_ENDPOINT_ADDRESS="5558"
-W pctdefaultprofileportspanelInstallWizardBean.SIB_MQ_ENDPOINT_SECURE_ADDRESS="5578"

################################################################################
#
# Windows service
#
# The following directives are to install services for
# WebSphere Application Server on Windows.
# Using Services, you can start and stop services,
# and configure startup and recovery actions.
# Set winServiceQuery="false" will turn off the function on windows system.
# You can ignore these or comment them out for other Operating Systems.
#
-W winservicepanelInstallWizardBean.winServiceQuery="true"

################################################################################
# Specify account type of the service. Legal values are:
#
# localsystem - Indicates that you choose to use Local System account.
# specifieduser - Indicates that you choose to use specified user account.
#
-W winservicepanelInstallWizardBean.accountType="localsystem"

################################################################################
# If you chose to install a service above with the accountType="localsystem",
# the userName and password below can be ignored. If the accountType was set to:
# accountType="specifieduser", then you must specify the User Name and Password
# which are required to install the Services. The current user must be admin or must
# have admin authority to install a Service. Also the username
# which is given here must have "Log On as a Service " authority
# for the service to run properly.
#
# Replace YOUR_USER_NAME with your username.
#
-W winservicepanelInstallWizardBean.userName="YOUR_USER_NAME"

################################################################################
# Replace YOUR_PASSWORD with your valid password.
#
-W winservicepanelInstallWizardBean.password="YOUR_PASSWORD"

################################################################################
# Set the startup type of the WebSphere Application Server on Windows.
# Valid values are "automatic", "manual", and "disabled".
#
-W winservicepanelInstallWizardBean.startupType="manual"

################################################################################
# Profile type
#
# This must be set to "default" for installing a stand alone profile
# Do not change this!
#
-W profiletypepanelInstallWizardBean.selection="default"

Deleting a profile
This topic describes how to manually delete a profile.

Chapter 3. Setting up the application serving environment 95

Before using the manual procedure to remove a profile, try the wasprofile command with the -delete
option. For example, issue one of the following commands:

./wasprofile.sh -delete
-profileName profile_name | -profilePath profile_path

wasprofile.bat -delete
-profileName profile_name | -profilePath profile_path

See “wasprofile command.”

If the command does not work, use this procedure to delete the profile.

This procedure describes how to manually delete a profile when the wasprofile -delete command results
in the following message:
INSTCONFFAILED: Cannot delete profile
1. Delete the profiles_install_root/profile_name directory.
2. If the install_root/properties/profileRegistry.xml file exists, edit the file in a flat-file editor to delete
the entry for the profile, if the entry is present.
The entry resembles the following example:
<profile isDefault="true"
name="BadProfile"
path="E:\IBM\WebSphere\AppServer\profiles\BadProfile"
template="E:\IBM\WebSphere\AppServer\profileTemplates\default"/>

3. Compare the two batch files, install_root/ properties/ fsdb/

_was_profile_default/ default.sh and install_root/ properties/ fsdb/ bad_profile_name.sh.
If the files are identical, delete the install_root/ properties/ fsdb/ _was_profile_default directory
and the install_root/ properties/ fsdb/ bad_profile_name.sh file.
If the files are not identical, delete only the install_root/ properties/ fsdb/ bad_profile_name.sh file.

4. Compare the two batch files, install_root\ properties\ fsdb\ _was_profile_default\

default.bat and install_root\ properties\ fsdb\ bad_profile_name.bat.
If the files are identical, delete the install_root\ properties\ fsdb\ _was_profile_default directory
and the install_root\ properties\ fsdb\ bad_profile_name.bat file.
If the files are not identical, delete only the install_root\ properties\ fsdb\ bad_profile_name.bat file.

See the description of the “wasprofile command” to learn more about the command-line method of working
with profiles.

See “Using the Profile creation wizard” on page 54 for more information about creating profiles with the
Profile creation wizard.

wasprofile command
The wasprofile command line tool creates all Application Server run-time environments in Version 6. The
command creates a profile, which is the set of files that define the run-time environment for a deployment
manager, a custom profile, or a stand-alone Application Server.

The wasprofile command is also referred to as the profile creation tool.

96 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Introduction to terms that describe Version 6 profiles
The wasprofile command creates the run-time environment for a WebSphere Application Server process
in a set of files called a profile. The profile defines the run-time environment and includes all of the files
that the server processes in the run-time environment can change. The profile creation tool and its
graphical user interface, the Profile creation wizard, are the only ways to create run-time environments in
V6.

The Profile creation wizard is an InstallShield for Multiplatforms (ISMP) application. You can use the wizard
to enter most of the parameters that are described in this topic. Some parameters, however, require you to
use the wasprofile command. You must use the wasprofile command to delete a profile, for instance,
because the Profile creation wizard does not provide a deletion function.

However, the Profile creation wizard also performs tasks that the wasprofile command does not. For
instance, the wizard can create a Windows service for each profile that it creates. It can also assign
non-conflicting ports based on previous Version 6 port assignments.

Core product files: The core product files are the shared product binaries. The binary files are shared
by all profiles.

The directory structure for V6 has two major divisions of files in the installation root directory for the
product:
v The core product files are shared product binary files that do not change unless you install a refresh
pack, a fix pack, or an interim fix. Some log information is also updated.
v The profiles directory is the default directory for creating profiles. The configuration for every defined
Application Server process is within the profiles directory unless you specify a new directory when you
create a profile. These files change as often as you create a new profile, reconfigure an existing profile,
or delete a profile.

All of the folders except for the profiles directory and a few others such as the logs directory and the
properties directory do not change unless you install service fixes. The profiles directory, however,
changes each time you add, change, or delete a profile. The profiles directory is the default repository for
profiles. However, you can put a profile anywhere on the machine provided there is enough available disk
space.

If you put a profile in another existing folder in the installation root directory, a risk exists that the profile
might be affected by the installation of a service fix that applies maintenance to the folder. Use a directory
outside of the installation root directory when using a directory other than the profiles directory for
creating profiles.

WebSphere Application Server profile: The wasprofile command line tool defines each Application
Server instance of a Version 6 product.

You must run the wizard or the command line tool each time that you want to create a stand-alone
Application Server. A need for more than one stand-alone Application Server on a machine is common.

Administration is greatly enhanced when using V6 profiles instead of multiple product installs. Not only is
disk space saved, but updating the product is simplified when you only maintain a single set of product
core files. Also, creating new profiles is faster and less prone to error than full product installs, allowing a
developer to create new disposable profiles of the product for development and testing.

You can run the Profile creation wizard or the profile creation tool to create a new Application Server
environment on the same machine as an existing one. Simply define unique characteristics (such as
profile name and node name) for the new profile. Each profile has its own administrative console and
administrative scripting interface. Each Application Server process shares all run-time scripts, libraries, the
Software Development Kit, and other core product files.

Chapter 3. Setting up the application serving environment 97

Profile types: Templates for each profile are located in the was_home/profileTemplates directory.

Within this directory are the default folder, the dmgr folder, and the managed folder. These are the paths
that you indicate while using the wasprofile command with the -templatePath option.

For example: -templatePath /usr/WebSphere/AppServer/profileTemplates/default

The wasprofile command in the Network Deployment product can create the following types of profiles:
Deployment manager profile
The basic function of the deployment manager is to deploy applications to a cell of Application
Servers, which it manages. Each Application Server that belongs to the cell is referred to as a
managed node.
Application Server profile
The basic function of the Application Server is to serve applications to the Internet or to an
intranet.
An important product feature for the Network Deployment product is the ability to scale up a
stand-alone Application Server profile by adding the Application Server node into a deployment
manager cell. Multiple Application Server processes in a cell can deploy an application that is in
demand. You can also remove an Application Server node from a cell to return the node to the
status of a stand-alone Application Server.
Each stand-alone Application Server has its own administrative console application, which you use
to manage the Application Server. You can also use the wsadmin scripting facility to perform every
function that is available in the administrative console application.
There is no node agent process for a stand-alone Application Server unless you decide to add the
Application Server node to a deployment manager cell. Adding the Application Server to a cell is
known as federation. Federation changes the stand-alone Application Server into a managed
node. At that point, you use the administrative console of the deployment manager to manage the
node. If you remove the node from the deployment manager cell, use the administrative console
and the scripting interface of the stand-alone Application Server to manage the process.
Custom profile
The basic function of this profile that belongs to a deployment manager cell is to serve
applications to the Internet or to an intranet under the management of the deployment manager.
The deployment manager changes a custom profile to a managed node by adding the node into
the cell. This is also true when you add an Application Server into a cell. When either node is
added to a cell, the node becomes a managed node. The nodeagent process is then instantiated
on the managed node. The node agent acts on behalf of the deployment manager to control
Application Server processes on the managed node. The node agent can start or stop Application
Servers, for example.
A deployment manager can create multiple Application Servers on a managed node so long as the
node agent process is running. Processes on the managed node can include cluster members that
the deployment manager uses to balance the work load for heavily used applications.
Use the administrative console of the deployment manger to control all of the nodes that the
deployment manager manages. You can also use the wsadmin scripting facility of the deployment
manager to control any of the managed nodes. A custom profile does not have its own
administrative console or scripting interface. You cannot manage the node directly with the
wsadmin scripting facility. You must use the administrative interface of the deployment manager to
manage a managed node.
A custom profile does not include default applications or a default server as the Application Server
profile does. A custom profile is an empty node. Add the node to the deployment manager cell.
Then you can use the administrative interface of the deployment manager to customize the
managed node by creating clusters and Application Servers.

98 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Installed file set: You decide where to install the files that define a profile. The default location is in the
profiles directory in the installation root directory. But you can change the location on the Profile creation
wizard or in a parameter when using the command line tool. For example, assume that you create two
profiles on a Linux platform with host name devhost1. The profile directories resemble the following
example if you do not relocate them:
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile02

Suppose that you specify a different directory, such as /opt/profiles, for the profile directory field in the
wizard. The profile directories resemble the following example:
/opt/profiles/devhost1Profile01
/opt/profiles/devhost1Profile02

The following directories exist within a profile. This example assumes that a profile named
devhost1Profile01 exists:
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/bin
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/config
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/etc
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/firststeps
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/installableApps
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/installedApps
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/installedConnectors
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/installedFilters
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/logs
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/properties
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/samples
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/temp
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/tranlog
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01/wstemp

The profile repository: The profile repository is the default location of profile-related metadata. The
repository is the default location for new profiles, which is often referred to as the profiles installation root
directory.

However, you can decide where to install a profile. The default location of the profile repository is the
install_root/profiles directory. In the earlier example, creating two profiles on a Linux platform with host
name devhost1 results in the following example directories in the profile repository:
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile01
/opt/IBM/WebSphere/AppServer/profiles/devhost1Profile02

When you specify a directory, such as /opt/profiles, the profiles are no longer in the default repository,
which is not a problem. For example, the following locations are valid:
/opt/profiles/devhost1Profile01
/opt/profiles/devhost1Profile02

Location of the command file

The command file is located in the install_root/bin directory. The command file is a script named
wasprofile.sh for Linux and UNIX platforms or wasprofile.bat for Windows platforms.

The Profile creation wizard is the graphical user interface to the command line tool. The file name of the
command that calls the Profile creation wizard varies per operating system platform. See “Using the Profile
creation wizard” on page 54 for more information.

Chapter 3. Setting up the application serving environment 99

Logging
The wasprofile command creates a log for every profile that it creates. The logs are in the
install_root/logs/wasprofile directory. The files are named in this pattern:
wasprofile_create_profile_name.log.

The command also creates a log for every profile that it deletes. The logs are in the
install_root/logs/wasprofile directory. The files are named in this pattern:
wasprofile_delete_profile_name.log.

Required disk space

Manually verify that the required space for creating a profile is available on AIX. A known
problem in the underlying InstallShield for Multiplatforms (ISMP) code prevents proper space checking on
AIX systems at the time that the product disc was created.

An error can occur when you have not provided enough system temporary space to create a profile. Verify
that you have a minimum of 40 MB of temp space available before creating a profile.

You must have 200 MB of available disk space in the directory where you create an Application Server
profile.

Network Deployment

Tip:

You must have 30 MB of available disk space in the directory where you create a deployment
manager profile.

You must have 10 MB of available disk space in the directory where you create a custom profile.

After installing the core product files, you must create one of the following profiles to have an
operational run-time environment:
v An application server that is described in this topic.
An application server profile has a default server (which is server1), the default application that
includes the snoop servlet and the hitcount servlet, and application Samples. You can federate the
application server or use it as a stand-alone application server.
v A deployment manager.
See ″Using the Profile creation wizard to create a deployment manager″ in the Installation PDF.
The deployment manager provides a single administrative interface to a logical group of
application servers on one or more machines.
v A custom profile that you must federate to make operational.
See ″Using the Profile creation wizard to create a custom profile″ in the Installation PDF. A custom
profile is an empty node that you can customize to include application servers, clusters, or other
Java processes, such as a messaging server.

Concurrent profile creation

Important: Concurrent profile creation is not supported at this time for one set of core product files.
Concurrent attempts to create profiles result in a warning about a profile creation already in
progress.

Entering lengthy commands on more than one line

The length of the wasprofile command can exceed the normal shell window limit for one line of 256
characters. If your command is longer than the limit, issue the command on multiple lines by ending a line
with a backward slash, pressing Enter, and continuing the command on the next line.

100 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
For example, on a Solaris system, the following command requires input on multiple lines:
./wasprofile.sh \
-create -profileName bladetcb6profile \
-profilePath /usr/IBM/WebSphere/AppServer/profiles/bladetcb6profile \
-templatePath /usr/WebSphere/AppServer/profileTemplates/default \
-nodeName bladetcb6node \
-cellName bladetcb6Cell \
-hostName bladetcb6.rtp.raleigh.ibm.com

Omit the line continuation character from the last line to signal the end of the command to the operating
system.

wasprofile.sh command syntax

List existing profiles:
# ./wasprofile.sh -listProfiles
[-debug]

Delete profiles:
# ./wasprofile.sh -delete
-profileName profile_name | -profilePath profile_path
[-debug]

Create new profiles:

wasprofile.sh -create
-profileName profile_name
-profilePath fully_qualified_profile_path
-templatePath template_path
-nodeName node_name
-cellName cell_name
-hostName host_name
-server iSeries_server_name
[-dmgrHost host_name]
[-dmgrPort SOAP port]
[-startingPort starting_port | -portsFile filepath]
-winserviceCheck true | false
-winserviceAccountType specifieduser | localsystem
-winserviceUserName yourusername
-winservicePassword yourpassword
-winserviceStartupType manual | automatic | disabled
[-debug]

Get name of existing profile from path:

# ./wasprofile.sh -getName
-profilePath profile_path
[-debug]

Get path of existing profile from name:

# ./wasprofile.sh -getPath
-profileName profile_name
[-debug]

Check the integrity of the profile registry:

# ./wasprofile.sh -validateRegistry
[-debug]

Check the integrity of the profile registry, removing profiles that are not found:
# ./wasprofile.sh -validateAndUpdateRegistry
[-backup file_name]
[-debug]

Chapter 3. Setting up the application serving environment 101

wasprofile.bat command syntax
List existing profiles:
wasprofile.bat -listProfiles
[-debug]

Delete profiles:
wasprofile.bat -delete
-profileName profile_name | -profilePath profile_path
[-debug]

Create new profiles:

wasprofile.bat -create
-profileName profile_name
-profilePath fully_qualified_profile_path
-templatePath template_path
-nodeName node_name
-cellName cell_name
-hostName host_name
-server iSeries_server_name
[-dmgrHost host_name]
[-dmgrPort SOAP port]
[-startingPort starting_port | -portsFile filepath]
-winserviceCheck true | false
-winserviceAccountType specifieduser | localsystem
-winserviceUserName yourusername
-winservicePassword yourpassword
-winserviceStartupType manual | automatic | disabled
[-debug]

When the -startingPort parameter is not used, the profile creation tool uses the default port settings
specified in the serverindex.xml file.

Get name of existing profile from path:

wasprofile.bat -getName
-profilePath fully_qualified_profile_path
[-debug]

Get path of existing profile from name:

wasprofile.bat -getPath
-profileName profile_name
[-debug]

Check integrity of profile registry:

wasprofile.bat -validateRegistry
[-debug]

Check integrity of profile registry, removing unfound profiles:

wasprofile.bat -validateAndUpdateRegistry
[-backup file_name]
[-debug]

Parameters
Supported arguments include:
-augment
Refreshes or augments the given profile using the template in the templatePath parameter.
-backup file_name
Backs up the profile registry file to a file with the file name specified.

102 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-cellname file_name
Specifies the cell name of the profile.
-create
Creates the profile.
-debug
Turns on the debug function of the Ant utility, which the wasprofile command uses.
-delete
Deletes the profile.
-dmgrHost host_name
Identifies the machine where the deployment manager is running. Specify this parameter and the
dmgrPort parameter to federate a custom profile as it is created.
The host name can be the long or short DNS name or the IP address of the deployment manager
machine.
Specifying this optional parameter directs the wasprofile command to attempt to federate the custom
node into the deployment manager cell as it creates the custom profile. This parameter is ignored
when creating a deployment manager profile or an Application Server profile.
Federating when the deployment manager is not available
If you federate a custom node when the deployment manager is not running or is not available
because of security being enabled or for other reasons, the installation indicator in the logs is
INSTCONFFAIL to indicate a complete failure. The resulting custom profile is unusable. You must
move the custom profile directory out of the profile repository (the profiles installation root directory)
before creating another custom profile with the same profile name.
-dmgrPort port_number
Identifies the SOAP port of the deployment manager. Specify this parameter and the dmgrHost
parameter to federate a custom profile as it is created. The deployment manager must be running and
accessible.
If you have enabled security or changed the default JMX connector type, you cannot federate with the
wasprofile command. Use the addNode command instead.
-getName
Gets the name for a profile registered at a given file system path. Requires the –profilePath parameter.
-getPath
Gets the file system location for a profile of a given name. Requires the –profileName parameter.
-hostName host_name
Specifies the host name where you are creating the profile. This should match the host name that you
specified during installation of the initial product.
-listProfiles
Llists all defined profiles.
-nodeName node_name
Specifies the node name for the node that is created with the new profile. Use a unique value within
the cellor on the machine. Each profile that shares the same set of product binaries must have a
unique node name.
-portsFile file_path
An optional parameter that specifies the path to a file that defines port settings for the new profile.
When omitted, the wasprofile tool looks for the install_root /profileTemplates/profile_type
/actions/portsUpdate/bin/portdef.props file.
Do not use this parameter when using the startingPort parameter.

Chapter 3. Setting up the application serving environment 103

-profileName profile_name
Specifies the name of the profile. Use a unique value when creating a profile. Each profile that shares
the same set of product binaries must have a unique name.
-profilePath profile_path
Specifies the fully qualified path to the profile.

Specify the full path to avoid an ANT scripting limitation that can cause a failure when
federating the profile into a cell. For example:
-profilePath C:\IBM\WebSphere\AppServer\profiles\profile01

If the fully qualified path contains spaces, enclose the value in quotation marks.

Specifies the name of the server on an iSeries platform.

-startingPort startingPort
Specifies the starting port number for generating all ports for the profile. If not specified, the
wasprofile command uses default ports specified in the serverindex.xml file.
-templatePath template_path
Specifies the path to the templates in the shared binaries.
-validateAndUpdateRegistry registry_file backup_file
Checks all of the profiles that are listed in the profile registry to see if the profiles are present on the
file system. Removes any missing profiles from the registry. Returns a list of the missing profiles that
were deleted from the profile.
-validateRegistry registry_file
Checks all of the profiles that are listed in the profile registry to see if the profiles are present on the
file system. Returns a list of missing profiles.

-winserviceAccountType type_of_owner_account
The type of the owner account of the Windows service created for the profile can be either
specifieduser or localsystem. The Windows service can run under the local account of the user who is
creating the profile.

winserviceCheck value
The value can be either true or false. Specify true to create a Windows service for the server process
that is created within the profile. Specify false to not create the Windows service.

-winservicePassword yourpassword
Specify the password for the specified user or the local account that is to own the Windows service.

-winserviceStartupType startup_type
Possible startup_type values are:
v manual
v automatic
v disabled
See ″WASService command″ in the Installation PDF for more information about Windows services.

-winserviceUserName user_ID
Specify your user ID so that Windows can verify you as an ID that is capable of creating a Windows
service. Your user ID must belong to the administrator group and have the following advanced user
rights, Act as part of the operating system and Log on as a service

104 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Use case scenarios
Use cases are a description of common tasks for which the tool is used.

Scenario: Creating a deployment manager profile on a Linux or UNIX platform: To create a

deployment manager profile for user shasti:
wasprofile.sh -create
-profileName shasti
-profilePath ~/shasti/WebSphere
-templatePath /opt/IBM/WebSphere/AppServer/profileTemplates/dmgr
-cellName shaix1
-hostName planetaix
-nodeName dmgr1

On an Express product or a base product installation, the command does not create anything because the
deployment manager template is not present.

On a Network Deployment product installation, the command creates a deployment manager profile
named shasti in a cell named shaix1 in location ~/shasti/WebSphere with a node name of dmgr1.

Scenario: Creating a deployment manager profile on a Windows platform: To create a server

process for user shasti:
wasprofile.sh -create
-profileName shasti
-profilePath G:\shasti\WebSphere
-templatePath C:\IBM\WebSphere\AppServer\profileTemplates\dmgr
-cellName shwindows1
-hostName planetnt
-nodeName dmgr1

On an Express installation or on a base WebSphere Application Server product installation, the command
does not create a deployment manager profile because the dmgr template does not exist in either product.

On a Network Deployment product installation, the command creates a deployment manager profile
named shasti in a cell named shwindows1 in location G:\shasti\WebSphere with a node name of dmgr1.

Scenario: Creating a deployment manager profile in a multiuser environment on a Linux or UNIX

platform: Follow these steps to create a server process for user shasti in a multiuser environment:
1. Create the server process:
wasprofile.sh -create
-profileName shasti
-profilePath ~/shasti/WebSphere
-templatePath /opt/IBM/WebSphere/AppServer/profileTemplates/dmgr
-cellName shaix1
-hostName myhost
-nodeName dmgr1
-startingPort 12000
2. Change the owner of the folder:
chown -R shasti ~shasti2/WebSphere
3. As a convenience, add a call to script ~shasti/WebSphere/bin/setupCmdLine.sh in the profile of user
shasti to set the environment when user shasti logs in.
4. Give these folder permissions to user shasti:
install_root/bin --- rx (read and execute)
install_root/java --- rx
install_root/properties ----r (read)
install_root/deploytool ----r
install_root/config ----r
install_root/lib ----r

Chapter 3. Setting up the application serving environment 105

 install_root/classes ----r
install_root/null ----r
install_root/samples ----r
install_root/Web ----r

Scenario: Deleting a profile: The following command is on more than one line for clarity. Enter the
command on one line to delete the profile named shasti:
wasprofile.sh -delete
-profileName shasti

Scenario: Using predefined port numbers: When you use the wasprofile tool without the -startingPort
parameter, the tool uses the /profileTemplates/profile_type /actions/portsUpdate/bin/portdef.props
file to set the initial ports.

Example of using the -portsFile parameter

Copy the file, edit the port settings, and use your copy by using the -portsFile parameter as shown in the
following example:
wasprofile.bat
-create
-profileName Wow_Profile
-profilePath
C:\ExpressV6\IBM\WebSphere\AppServer\profiles\Wow_Profile
-templatePath
C:\ExpressV6\IBM\WebSphere\AppServer\profileTemplates\default
-nodeName Wow_node
-cellName Wow_cell
-hostName loyAllen
-portsFile C:\temp\ports\portdef.props

Suppose that the portdef.props file has the following values:

WC_defaulthost=39080
WC_adminhost=39060
WC_defaulthost_secure=39443
WC_adminhost_secure=39043
BOOTSTRAP_ADDRESS=32809
SOAP_CONNECTOR_ADDRESS=38880
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS=39401
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS=39403
CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS=39402
ORB_LISTENER_ADDRESS=39100
DCS_UNICAST_ADDRESS=39353
SIB_ENDPOINT_ADDRESS=37276
SIB_ENDPOINT_SECURE_ADDRESS=37286
SIB_MQ_ENDPOINT_ADDRESS=35558
SIB_MQ_ENDPOINT_SECURE_ADDRESS=35578

As you run the command, messages similar to the following appear in the output stream:
replaceRegExpAllInstancesOfGivenTokenWithGivenValueForTheGivenFile:
[echo] File C:\ExpressV6\IBM\WebSphere\AppServer\profiles\
Wow_Profile/config/templates/default/serverentry-template.xml:
setting CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS to 39403

...
replaceRegExpAllInstancesOfGivenTokenWithGivenValueForTheGivenFile:
[echo] File C:\ExpressV6\IBM\WebSphere\AppServer\profiles\
Wow_Profile/config/templates/default/serverentry-template.xml:
setting CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS to 39402
...

The resulting serverindex.xml file looks similar to the following example:

106 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
<?xml version="1.0" encoding="UTF-8"?>
<serverindex:ServerIndex xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"
...
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="BOOTSTRAP_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="IBMmachine" port="32809"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="SOAP_CONNECTOR_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="IBMmachine" port="38880"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="SAS_SSL_SERVERAUTH_LISTENER_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="IBMmachine" port="39401"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="IBMmachine" port="39403"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="IBMmachine" port="39402"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="WC_adminhost">
<endPoint xmi:id="EndPoint_..." host="*" port="39060"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="WC_defaulthost">
<endPoint xmi:id="EndPoint_..." host="*" port="39080"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="DCS_UNICAST_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="IBMmachine" port="39353"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="WC_adminhost_secure">
<endPoint xmi:id="EndPoint_..." host="*" port="39043"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="WC_defaulthost_secure">
<endPoint xmi:id="EndPoint_..." host="*" port="39443"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="SIB_ENDPOINT_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="*" port="37276"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="SIB_ENDPOINT_SECURE_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="*" port="37286"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="SIB_MQ_ENDPOINT_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="*" port="35558"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="SIB_MQ_ENDPOINT_SECURE_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="*" port="35578"/>
</specialEndpoints>
<specialEndpoints xmi:id="NamedEndPoint_..."
endPointName="ORB_LISTENER_ADDRESS">
<endPoint xmi:id="EndPoint_..." host="IBMmachine" port="39100"/>
</specialEndpoints>
</serverEntries>
</serverindex:ServerIndex>

Chapter 3. Setting up the application serving environment 107

The wasprofile command creates a copy of the current portdefs.props file in the
install_root\profiles\profile_name\logs directory.

Do not use the portsFile parameter when using the startingPort parameter. The two parameters are
mutually exclusive.

Scenario: Incrementing default port numbers from a starting point: The wasprofile command can
assign port numbers based on a starting port value that you give on the command line, using the
-startingPort parameter. The tool assigns port numbers sequentially from the starting port number value.

The order of port assignments is arbitrary. Predicting assignments is not possible.

For example, ports created with -startingPort 20002 would appear similar to the following example:

Assigned ports for an Application Server profile

WC_defaulthost=20002
WC_adminhost=20003
WC_defaulthost_secure=20004
WC_adminhost_secure=20005
BOOTSTRAP_ADDRESS=20006
SOAP_CONNECTOR_ADDRESS=20007
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS=20008
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS=20009
CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS=20010
ORB_LISTENER_ADDRESS=20011
DCS_UNICAST_ADDRESS=20012
SIB_ENDPOINT_ADDRESS=20013
SIB_ENDPOINT_SECURE_ADDRESS=20014
SIB_MQ_ENDPOINT_ADDRESS=20015
SIB_MQ_ENDPOINT_SECURE_ADDRESS=20016

Assigned ports for a custom profile

WC_defaulthost=20002
WC_adminhost=20003
WC_defaulthost_secure=20004
WC_adminhost_secure=20005
BOOTSTRAP_ADDRESS=20006
SOAP_CONNECTOR_ADDRESS=20007
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS=20008
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS=20009
CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS=20010
ORB_LISTENER_ADDRESS=20011
CELL_DISCOVERY_ADDRESS=20012
DCS_UNICAST_ADDRESS=20013

Assigned ports for a deployment manager profile

CELL_DISCOVERY_ADDRESS=20010
BOOTSTRAP_ADDRESS=20004
DRS_CLIENT_ADDRESS=7989
SOAP_CONNECTOR_ADDRESS=20005
ORB_LISTENER_ADDRESS=20009
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS=20006
CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS=20008
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS=20007
WC_adminhost=20002
DCS_UNICAST_ADDRESS=20011
WC_adminhost_secure=20003

Example of startingPort parameter use

108 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The following example of using the wasprofile command creates ports from an initial value of 20002, with
the content shown in the previous example:
wasprofile.bat -create
-profileName shasti
-profilePath G:\shasti\WebSphere
-templatePath template_path
-nodeName W2K03
-cellName W2K03_Cell01
-hostName planetnt
-startingPort 20002

Scenario: Setting up and using the profile environment: Most tasks that you perform in a profile are
done using the -profileName attribute on the command line tools that you use. Such a scenario might be:
1. Create the server process using the install_root/bin/wasprofile.sh (or wasprofile.bat) script from the
original installation. Assume that you create the Profile02 profile.
2. In that command window or in another, change directories to the /bin directory of the new server
process.
3. Establish a temporary override for the normal WebSphere Application Server environment by using the
-profileName attribute on a command you issue. In the same window, start server1 by changing
directories to the install_root/bin directory of the original installation and issuing the command.
There is no such command in the /bin directory of the server process:
startServer.sh server1 -profileName Profile02
4. Notice the changes in the environment. Display all of the ports for the machine to see the ports that
you set for the server process. For example, in a Linux bash shell or in the command window on a
Windows platform, type:
netstat -a
5. Open a browser window and point it at the port defined for the HTTP_TRANSPORT_ADMIN port of
the new process. For example, suppose the setting is HTTP_TRANSPORT_ADMIN=20003. Open the
administrative console for server1 by pointing your browser at:
http://hostname_orIP_address:20003/ibm/console/

Scenario: Profile creation for a non-root user: Two methods exist for a non-root user to create a
profile:
v The root user creates the profile and assigns ownership to the non-root user.
v A non-root user creates a profile after getting write permission to the appropriate directories.

Remember: An ease-of-use limitation exists for non-root users who create profiles. Mechanisms within
the Profile creation wizard that suggest unique names and port values are disabled for
non-root users. The non-root user must change the default field values in the Profile creation
wizard for the profile name, node name, cell name, and port assignments. Consider
assigning non-root users a range of values for each of the fields. You can assign
responsibility to the non-root profilers for adhering to their proper value ranges and for
maintaining the integrity of their own definitions.

Root creates the profile and assigns ownership to a non-root user: The root user can create a profile and
assigns ownership of the profile directory to a non-root user.
1. The root user creates the profile with the following command:
./wasprofile.sh -create -profileName profile01 -profilePath install_root/profiles/profile01
2. The root user changes ownership of the directory for the profile to the non-root user with the following
command:
chown -R user1 install_root/profiles/profile01

A non-root user creates the profile (advanced option): The root user can grant write permission to the
appropriate files and directories to a non-root user. The non-root user can then create the profile. You can

Chapter 3. Setting up the application serving environment 109

create a group for users who are authorized to create profiles. Or you can give everyone the ability to
create profiles. The following example shows how to create a group that is authorized to create profiles.
1. Log on to the Application Server system as root.
2. Create the profilers group that you can use to create profiles.
3. Create a user named user1 to create profiles.
4. Add users root and user1 to the profilers group.
5. Log off and back on as root to pick up the new group.
6. As root, use operating system tools to change file permissions.
The following example assumes that the installation root directory is /opt/IBM/WebSphere/AppServer:
mkdir /opt/IBM/WebSphere/AppServer/logs/wasprofile
chgrp profilers /opt/IBM/WebSphere/AppServer/logs/wasprofile
chmod g+wr /opt/IBM/WebSphere/AppServer/logs/wasprofile
chgrp profilers /opt/IBM/WebSphere/AppServer/properties
chmod g+wr /opt/IBM/WebSphere/AppServer/properties
chmod g+wr /opt/IBM/WebSphere/AppServer/properties/profileRegistry.xml
You might have to change the permissions on additional /opt/IBM/WebSphere/AppServer directories if
you encounter permission problems.
7. The non-root user who belongs to the profilers group can then create a profile in any directory to which
the non-root user has write permission.
If the non-root user does not have write access to any directories, it is up to the root user to change
that situation. If the non-root user does not have write access to the /tmp directory, it is up to the root
user to change that as well.
The commands listed in step 6 give users assigned to the profilers group the ability to write to the
/opt/IBM/WebSphere/AppServer/logs/wasprofile directory and to the
/opt/IBM/WebSphere/AppServer/properties directory. It is not necessary to write to any other
directories in the installation root of your WebSphere Application Server product.
Have non-root users create a profiles directory in their own area, not in the installation root directory
of the product.

Using the installation verification test

This topic describes how to use the installation verification test (IVT). The IVT verifies that the installation
of the application server or deployment manager profile was successful. A profile consists of files that
define the run-time environment for a deployment manager or an application server. Each profile has its
own IVT command.

After installing the Network Deployment product and creating a deployment manager or application server
profile, you are ready to use the installation verification test (IVT).

The IVT program scans product log files for errors and verifies core functionality of the product installation.

The Profile creation wizard creates profiles. After creating a profile, the Profile creation wizard displays a
prompt for starting the First steps console. The First steps console is unique for each profile. See
“firststeps command” on page 48 for more information.

Installation verification is the first option on the First steps console.

The IVT program for an application server profile starts and monitors the application server process, which
is the server1 process. The installation verification for a deployment manager profile starts and monitors
the deployment manager process, which is the dmgr process. The IVT works differently for the deployment
manager profile than for a stand-alone application server. On a stand-alone application server, the IVT
queries servlets from the ivtApp application. However, the deployment manager does not have the ivtApp
application, so the IVT looks at log files only.

110 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
1. Start the First steps console and select Installation verification after creating a deployment manager
profile or an application server profile.
No installation verification is possible for a custom profile. After federating the node and using the
deployment manager to create a server, you can start the server process to verify its functionality.
Select the check box to launch the First steps console at the end of profile creation. You can also start
the First steps console from the command line, as described in “firststeps command” on page 48.
You can also start the “ivt command” on page 112 directly from the bin directory of the profile:
v install_root/profiles/profile_name/bin/ivt.sh
v install_root\profiles\profile_name\bin\ivt.bat
If you create profiles in another location, the ivt script location is within the profile_home/bin directory.
2. Observe the results in the First steps status window.
The default log file for installation verification is the install_root/profiles/profile
name/logs/ivtClient.log. If you create profiles in another location, the file path is
profile_home/logs/ivtClient.log.
The IVT provides the following useful information about the application server:
v The application server name
v The name of the profile
v The profile file path
v The type of profile
v The node name
v The current encoding
v The port number for the administrative console
v Various informational messages that include the location of the SystemOut.log file and how many
errors are listed within the file
v A completion message
As the IVT starts the application server on a Windows platform, the IVT attempts to start the Windows
service for the application server, if a Windows service exists. This is true even though the Windows
service might have a manual startup type.
If you federate a stand-alone application server, you can still run the IVT on the server.
The IVT provides the following useful information about the deployment manager:
v The deployment manager server name: dmgr
v The name of the profile
v The profile file path
v The type of profile: dmgr
v The cell name
v The node name
v The current encoding
v The port number for the administrative console
v Various informational messages that include the location of the SystemOut.log file and how many
errors are listed within the file
v A completion message
As the IVT starts the deployment manager on a Windows platform, the IVT attempts to start the
Windows service for the deployment manager if a Windows service exists. This is true even though the
Windows service might have a manual startup type.
See “Automatically restarting server processes” on page 244 for more information.

Chapter 3. Setting up the application serving environment 111

3. If the log shows that errors occurred during the installation verification, correct the errors and run the
IVT again. If necessary, create a new profile after correcting the error, and run the IVT on the new
profile.

The IVT program starts the server process automatically if the server is not running. Once the server
initializes, the IVT runs a series of verification tests. The tool displays pass or fail status in a console
window. The tool also logs results to the profile_home/logs/ivtClient.log file. As the IVT verifies your
system, the tool reports any detectable errors in the SystemOut.log file.

Return to the ″Task overview: Installing″ topic in the information center to continue.

ivt command
The ivt command starts the installation verification test (IVT) program. The IVT verifies that the installation
of the application server or deployment manager profile was successful. A profile consists of files that
define the run-time environment for a deployment manager or an application server. Each profile has its
own IVT command.

The IVT program starts the application server or deployment manager automatically if the server process
is not already running. After the server process initializes, the IVT runs a series of verification tests and
displays pass or fail status in a console window.

The IVT program scans the SystemOut.log file for errors and verifies core functionality of the profile.

You can start the IVT program from the command line or from the First steps console.

Location of the command file

The location of the ivt.sh or ivt.bat script for any profile is:
v install_root/profiles/profile_name/bin/ivt.sh
v install_root\profiles\profile_name\bin\ivt.bat

Parameters

The following parameters are associated with this command.

server_name
Required parameter that identifies the name of the server process, such as server1 or dmgr.
profile_name
Required parameter that identifies the name of the profile that contains the server definition.
-p server_port_number
Optional parameter that identifies the default_host port when the port is not 9080, which is the default.
-host machine_host_name
Optional parameter that identifies the host machine of the profile to test. The default is localhost.

Syntax for the ivt command

Use the following syntax for the command:

v install_root/profiles/profile_name/bin/ivt.sh

v install_root\profiles\profile_name\bin\ivt.bat

Logging

The ivt command logs results to the install_root/profiles/profile name/logs/ivtClient.log file.

112 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Example

The following examples test the server1 process in the profile01 profile on the myhost machine using the
default_host on port 9081.

ivt.bat server1 profile01 -p 9081 -host myhost

ivt.sh server1 profile01 -p 9081 -host myhost

Configuring ports
This topic discusses configuring ports, particularly in coexistence scenarios.
1. Review “Port number settings in WebSphere Application Server versions.”
This topic provides reference information about identifying port numbers in versions of WebSphere
Application Server, as a means of determining port conflicts that might occur when you intend for an
earlier version to coexist with Version 6.
2. You can change port settings on the port assignment panel while using the Profile creation wizard.
See “Using the Profile creation wizard” on page 54 for more information.
3. After installation, edit the
profiles_install_root/profile_name/config/cells/cell_name/nodes/node_name/serverindex.xml file to
change the port settings, or use scripting to change the values.
See the Administering applications and their environment PDF for more information.

Port number settings in WebSphere Application Server versions

This topic provides reference information about identifying port numbers in versions of WebSphere
Application Server, as a means of determining port conflicts that might occur when you intend for an
earlier version to coexist or interoperate with Version 6.

Version 6 port numbers

Table 8. Port definitions for WebSphere Application Server Version 6
WebSphere
Network Deployment
Port name Application Server File
Value
HTTP_TRANSPORT 9080 9080
HTTP Admin Console Port
9060 9060
(HTTP_TRANSPORT_ADMIN)
serverindex.xml and
HTTPS Transport Port virtualhosts.xml
9443 9443
(HTTPS_TRANSPORT)
HTTPS Admin Console Secure Port
9043 9043
(HTTPS_TRANSPORT_ADMIN)

Chapter 3. Setting up the application serving environment 113

Table 8. Port definitions for WebSphere Application Server Version 6 (continued)
WebSphere
Network Deployment
Port name Application Server File
Value
BOOTSTRAP_ADDRESS 2809 9809
SOAP_CONNECTOR-ADDRESS 8880 8879
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS 9401 9401
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS9403 9403
CSIV2_SSL_MULTIAUTH_LISTENER_ADDRESS 9402 9402
ORB_LISTENER_ADDRESS 9100 9100
DCS_UNICAST_ADDRESS 9353 9352
SIB_ENDPOINT_ADDRESS 7276 7276
serverindex.xml
SIB_ENDPOINT_SECURE_ADDRESS 7286 7286
SIB_MQ_ENDPOINT_ADDRESS 5558 5558
SIB_MQ_ENDPOINT_SECURE_ADDRESS 5578 5578
Internal JMS Server
5557 Not applicable
(JMSSERVER_SECURITY_PORT)
IBM HTTP Server Port virtualhosts.xml,

80 Not applicable plugin-cfg.xml,

and IHSinstall_ro
IBM HTTPS Server Admin Port IHSinstall_root/conf/
8008 Not applicable
admin.conf
CELL_DISCOVERY_ADDRESS Not applicable 7277
CELL_MULTICAST_DISCOVERY_ADDRESS Not applicable 7272 serverindex.xml
NODE_MULTICAST_IPV6_DISCOVERY_ADDRESS
5001 5001

When you federate an Application Server node into a deployment manager cell, the deployment manager
instantiates the nodeagent server process on the Application Server node. The nodeagent server uses
these port assignments by default:
Table 9. Port definitions for the V6 nodeagent server process
Port name Value File
BOOTSTRAP_ADDRESS 2809
ORB_LISTENER_ADDRESS 9100
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS 9901
CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS 9202
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS 9201
NODE_DISCOVERY_ADDRESS 7272 serverindex.xml
NODE_MULTICAST_DISCOVERY_ADDRESS 5000
NODE_IPV6_MULTICAST_DISCOVERY_ADDRESS 5001
DCS_UNICAST_ADDRESS 9353
DRS_CLIENT_ADDRESS 7888
SOAP_CONNECTOR_ADDRESS 8878

114 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Version 5.x port numbers
Table 10. Port definitions for WebSphere Application Server Version 5.x
WebSphere
Network Deployment
Port name Application Server File
Value
HTTP_TRANSPORT 9080 Not applicable
HTTPS Transport Port
9443 Not applicable
(HTTPS_TRANSPORT)
server.xml and
HTTP Admin Console Port virtualhosts.xml
9090 9090
(HTTP_TRANSPORT_ADMIN)
HTTPS Admin Console Secure Port
9043 9043
(HTTPS_TRANSPORT_ADMIN)
Internal JMS Server
5557 Not applicable server.xml
(JMSSERVER_SECURITY_PORT)
JMSSERVER_QUEUED_ADDRESS 5558 Not applicable
serverindex.xml
JMSSERVER_DIRECT_ADDRESS 5559 Not applicable
BOOTSTRAP_ADDRESS 2809 9809 serverindex.xml
SOAP_CONNECTOR-ADDRESS 8880 8879 serverindex.xml
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS 0 9401 serverindex.xml
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS 0 9403
serverindex.xml
CSIV2_SSL_MULTIAUTH_LISTENER_ADDRESS 0 9402
IBM HTTP Server Port virtualhosts.xml,
plugin-cfg.xml, and
80 Not applicable
IHSinstall_root/conf/
httpd.conf
IBM HTTPS Server Admin Port IHSinstall_root/conf/
8008 Not applicable
admin.conf
CELL_DISCOVERY_ADDRESS Not applicable 7277
ORB_LISTENER_ADDRESS 9100 9100 serverindex.xml
CELL_MULTICAST_DISCOVERY_ADDRESS Not applicable 7272

When you federate an Application Server node into a deployment manager cell, the deployment manager
instantiates the nodeagent server process on the Application Server node. The nodeagent server uses
these port assignments by default:
Table 11. Port definitions for the V5.x nodeagent server process
Port name Value File
BOOTSTRAP_ADDRESS 2809
ORB_LISTENER_ADDRESS 9900
SAS_SSL_SERVERAUTH_LISTENER_ADDRESS 9901
CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS 9101
CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS 9201 serverindex.xml
NODE_DISCOVERY_ADDRESS 7272
NODE_MULTICAST_DISCOVERY_ADDRESS 5000
DRS_CLIENT_ADDRESS 7888
SOAP_CONNECTOR_ADDRESS 8878

Chapter 3. Setting up the application serving environment 115

Version 4.0.x port numbers

For WebSphere Application Server Advanced Single Server Edition, Version 4.0.x: Inspect the
server-cfg.xml file to find the Web container HTTP transports port values for the configuration.

For WebSphere Application Server Advanced Edition, Version 4.0.x: When the administrative server is
running, use this command to extract the configuration from the database:
xmlConfig -export config.xml -nodeName theNodeName

Look for the Web container HTTP transports port assignments.

Table 12. Port definitions for WebSphere Application Server V4.0.x
IBM WebSphere Advanced Single
Business Integration Server Edition
Advanced Edition
Port name Value Server Foundation
Edition
File
bootstrapPort 900
lsdPort 9000 admin.config admin.config
LSDSSLPort 9001
HTTP transport port 9080
HTTPS transport port 9443 server-cfg.xml

Admin Console HTTP 9090

database database
transport port
ObjectLevelTrace 2102
diagThreadPort 7000

Communicating with Web servers

The WebSphere Application Server works with a Web server to route requests for dynamic content, such
as servlets, from Web applications. The Web servers are necessary for directing traffic from browsers to
the applications that run in WebSphere Application Server. The Web server plug-in uses the XML
configuration file to determine whether a request is from the Web server or the Application Server.

The Web server plug-ins for distributed platform Web servers are provided on a separate CD from the
WebSphere Application Server products. A Web Server Plug-in Installation Wizard is also provided on that
CD. Installing Web server plug-ins describes how to install a Web server plug-in and create a Web server
definition.
1. Install your Web server if it is not already installed. If you want to use an IBM HTTP Server, see
Installing IBM HTTP Server. Otherwise, see the installation information provided with your Web server.
2. Ensure that your Web server is configured to perform operations required by Web applications, such
as GET and POST. Typically, this involves setting a directive in the Web server configuration file (such
as the httpd.conf file for an IBM HTTP Server). Refer to the Web server documentation for instructions.
If an operation is not enabled when a servlet or JSP file requiring the operation is accessed, an error
message displays, such as this one from the IBM HTTP Server:
HTTP method POST is not supported by this URL.
3. Use the Plug-in Installation wizard to install the appropriate plug-in file to your Web server and run the
script configureWeb_server_name created by the wizard to create and configure the Web server

116 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 definition in the WebSphere configuration repository. The following substeps are performed during the
plug-in installation process. See the Plug-in Installation Roadmap for additional information.
a. A node is created. An unmanaged node is created when the Web server is on a different computer
from the Application Server. An unmanaged node is a node that does not have a WebSphere node
agent running on it. Using unmanaged nodes, WebSphere Application Server can represent
servers that are not application servers within its configuration topology. This representation
enables connection information between those servers and application servers to be maintained.
“Managing nodes” on page 149 describes how to create a node.
b. A Web server definitions is created. You can also use either use the administrative console or use
the ConfigureWebServerDefintion.jacl script to create a Web server definition.
If you use the administrative console:
1) Select the node that was created in the preceding step, and in the Server name field, enter the
local name of the Web server for which you are creating a Web server definition.
2) Use the wizard to complete the Web server definition.
c. An application or modules are mapped to a Web server. If an application that you want to use with
this Web server is already installed, the application is automatically mapped to the Web server. If
the application is not installed, select this Web server during the Map modules to servers step of
the application installation process.
d. Master repository is updated and saved.
4. Optional: Configure the plug-in. Use either the administrative console, or issue the “GenPluginCfg
command” on page 872 to create your plugin-cfg.xml file.
When setting up your Web server plug-in, you must decide whether or not to have the configuration
automatically generated in response to a configuration change. When the Web server plug-in
configuration service is enabled and any of the following conditions occur, the plug-in configuration file
is automatically generated:
v When the Web server is created or saved.
v When an application is installed.
v When an application is uninstalled.
v When the virtual host definition is updated
Generating or regenerating the configuration file might take a while to complete. After it finishes, all
objects in the administrative cell use their newest settings, which the Web server can access. If the
Application Server is on the same physical machine as the Web server, the regeneration usually takes
about 30 to 60 seconds to complete. The regeneration takes longer if they are not both on the same
machine.

Important: When the plug-in configuration file is first generated, it does not include admin_host on the
list of virtual hosts. ″Allowing Web servers to access the administrative console″ in the
information center describes how to add it to the list.
To use the administrative console:
a. Select Servers > Web Servers > webserver > plug-in properties.
b. Select Automatically generate plug-in configuration file or click on one or more of the following
topics to manually configure the plugin-cfg.xml file:
v Caching
v Request and response
v Request routing
v Service
Web server plug-in configuration properties maps each property to one of these topics.
c. Click OK.
d. You might need to stop the application server and then start the application server again to enable
the Web server to locate the plugin-cfg.xml file.

Chapter 3. Setting up the application serving environment 117

5. If you want to use Secure-socket layer (SSL) with this configuration, use the plug-in’s installation
wizard to install the appropriate GSKIT installation image file on your workstation. See “Configuring the
Web server plug-in for Secure Sockets Layer” on page 1908 for information on how to configure
GSKIT.
6. If you want to enable the Web server plug-in to use private headers, define an SSL configuration
repertoire that defines a trust file. Then in the administrative console, select Application servers >
server1 > Web Container Settings > Web Container Transport Chains > transport_chain > SSL
Inbound Channel (SSL_2) and specify this repertoire for that transport chain. If you try to use private
headers without setting up an SSL configuration repertoire that does not include a trust file definition,
the private headers will be ignored. If the private headers are ignored, the application server might not
locate the requested application.
After you enable the use of private headers, the transport chain’s SSL inbound channel trusts all
private headers it receives. Therefore, you must ensure that all paths to the transport chain’s SSL
inbound channel are trusted.
7. Tune your Web server with Web server tuning parameters.
8. Propagate the plug-in configuration. The plug-in configuration file (plugin-cfg.xml) is automatically
propagated to the Web server if the Web server plug-in configuration service is enabled, and one of
the following is true:
v The Web server is a local Web server. (It are located on the same machine as an application
server.)
v The Web server is a remote IBM HTTP Server (IHS) Version 6.0 that has a running IHS
Administrative server.
If neither of these conditions is true, the plugin-cfg.xml file must be manually copied to the remote Web
server’s installation location.
The remote Web server installation location is the location you specified when you created the node
for this Web server.

The configuration is complete. To activate the configuration, stop and restart the Web server. If you
encounter problems restarting your Web server, check the http_plugin.log file for information on what
portion of the plugin-cfg.xml file contains an error. The log file states the line number on which the error
occurred along with other details that might help you diagnose why the Web server did not start. You can
then use the administrative console to update the plugin-cfg.xml file.

If applications are infrequently installed or uninstalled, which is usually the situation in a production
environment, or if you can tolerate the performance impact of generating and distributing the plug-in
configuration file each time any of the previously listed actions occur, you should consider enabling this
service.

If you are making a series of simultaneous changes, like installing numerous applications, you might want
the configuration service disabled until after you make the last change. The Web server plug-in
configuration service is enabled by default. To disable this service, in the administrative console click elect
Servers > Application Servers > server_name > Administration Services >Web server plug-in
configuration service and then unselect the Enable automated Web server configuration processing
option.

Tip: If your installation uses a firewall, make sure you configure the Web server plug-in to use a port that
has been opened. (See your security administrator for information on how to obtain an open port.

Web server plug-in properties settings

Use this page to view or change the settings of a Web server plug-in configuration file. The plug-in
configuration file, plugin_cfg.xml, provides properties for establishing communication between the Web
server and the Application Server.

118 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this administrative console page, click Servers > Web Servers >Web_server_name Plug-in
Properties.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.

The Runtime tab is available only when this Web server has accessed applications running on application
servers and there is an http_plugin.log file.

Plug-in log file name

Specifies the fully qualified path to the log file to which the plug-in will write error messages. The default
file path is plugin_install_root/logs/web_server_name/http_plugin.log .

If the file does not exist then it will be created. If the file already exists, it will be opened in append mode
and the previous plug-in log messages will remain.

This field corresponds to the RequestMetrics loggingEnabled element in the plugin-cfg.xml file.

Data type String

Default for Linux and UNIX platforms plugin_install_root/logs/web_server_name/http_plugin.log

Default for Windows platforms plugin_install_root/logs/web_server_name/http_plugin.log

Plug-in installation location

Specifies the fully qualified path to where the plug-in configuration file is installed.

Data type String

Default The default value is the installation root directory.

If you select a Web server plug-in during installation, the installer program configures the Web server to
identify the location of the plugin-cfg.xml file, if possible. The Web server is considered installed on a
local machine if it is on the same machine as the application server. It is considered installed on a remote
machine if the Web server and the application server are on different machines.
v If the Web server is installed on a remote machine, the plug-in configuration file, by default, will be
installed in the plugin_install_root/config/web_server_name directory.
v If the Web server is installed on a local standalone machine, the plug-in configuration file, by default will
be installed in the profile_install_root/config/cells/cell_name/nodes/web_server_name
_node/servers/web_server_name directory.
v If the Web server is installed on a local distributed machine, the plug-in configuration file, by default will
be installed in the
profile_install_root/config/cells/cell_name/nodes/node_name/servers/web_server_name directory.

The installer program adds a directive to the Web server configuration that specifies the location of the
plugin-cfg.xml file.

For remote Web servers, you must copy the file from the local directory where the Application Server is
installed to the remote machine. This is known as propagating the plug-in configuration file. If you are
using an IBM HTTP Server (IHS) V6 for your Web server, WebSphere Application Server can automatically
propagate the plug-in configuration file for you to remote machines provided there is a working HTTP
transport mechanism to propagate the file.

Chapter 3. Setting up the application serving environment 119

Plug-in configuration file name
Specifies the file name of the configuration file for the plug-in. The Application Server generates the
plugin-cfg.xml file by default. The configuration file identifies applications, Application Servers, clusters,
and HTTP ports for the Web server. The Web server uses the file to access deployed applications on
various Application Servers.

Data type String

Default plugin-cfg.xml

If you select a plug-in during installation, the installer program configures the Web server to identify the
location and name of the plugin-cfg.xml file, if possible.

You can change the name of the plug-in configuration file. However, if you do change the file name, you
must also change the Web server configuration to point to the new plug-in configuration file.

Automatically generate plug-in configuration file

To automatically generate a plug-in configuration file to a remote Web server:
v This field must be checked.
v The plug-in configuration service must be enabled

When the plug-in configuration service is enabled, a plug-in configuration file is automatically generated for
a Web server whenever:
v The WebSphere Application Server administrator defines new Web server.
v An application is deployed to an Application Server.
v An application is uninstalled.
v A virtual host definition is updated and saved.

Clear the check box if you want to manually generate a plug-in configuration file for this Web server.

Important: When the plug-in configuration file is generated, it does not include admin_host on the list of
virtual hosts. ″Allowing Web servers to access the administrative console″ in the information
center describes how to add it to the list.

Automatically propagate plug-in configuration file

To automatically propagate a copy of a changed plug-in configuration file to a Web server:
v This field must be checked.
v The plug-in configuration service must be enabled
v A WebSphere Application Server node agent must be on the node that hosts the Web server associated
with the changed plug-in configuration file.

Note: The plug-in configuration file can only be automatically propagated to a remote Web server if that
Web server is an IHS V6.0 Web server and its administration server is running.

Ignore DNS failures during Web server startup

Specifies whether the plug-in ignores DNS failures within a configuration when starting.

This field corresponds to the IgnoreDNSFuilures element in the plugin-cfg.xml file.

When set to true, the plug-in ignores DNS failures within a configuration and starts successfully if at least
one server in each ServerCluster is able to resolve the host name. Any server for which the host name
can not be resolved is marked unavailable for the life of the configuration. No attempts to resolve the host
name are made later on during the routing of requests. If a DNS failure occurs, a log message is written to
the plug-in log file and the plug-in initialization continues rather than causing the Web server not to start.

120 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
When false is specified, DNS failures cause the Web server not to start.

Data type String

Default false

Refresh configuration interval

Specifies the time interval, in seconds, at which the plug-in should check the configuration file to see if
updates or changes have occurred. The plug-in checks the file for any modifications that have occurred
since the last time the plug-in configuration was loaded.

In a development environment in which changes are frequent, a lower setting than the default setting of 60
seconds is preferable. In production, a higher value than the default is preferable because updates to the
configuration will not occur so often. If the plug-in reload fails for some reason, a message is written to the
plug-in log file and the previous configuration is used until the plug-in configuration file successfully
reloads. If you are not seeing the changes you made to your plug-in configuration, check the plug-in log
file for indications of the problem.

Data type Integer

Default 60 seconds.

Plug-in logging
Specifies the location and name of the http_plugin.log file. Also specifies the scope of messages in the
log.

This field corresponds to the RequestMetrics traceLevel element in the plugin-cfg.xml file.

The log describes the location and level of log messages that are written by the plug-in. If a log is not
specified within the configuration file, then, in some cases, log messages are written to the Web server
error log.

On a distributed platform, if the log file does not exist then it will be created. If the log file already exists, it
will be opened in append mode and the previous plug-in log messages will remain.

Log file name - The fully qualified path to the log file to which the plug-in will write error messages.

Data type String

Default plugin_install_root/logs/web_server_name/http_plugin.log

Specify the file path of the http_plugin.log file.

Log level- The level of detail of the log messages that the plug-in should write to the log. You can specify
one of the following values for this attribute:
v Trace. All of the steps in the request process are logged in detail.
v Stats. The server selected for each request and other load balancing information relating to request
handling is logged.
v Warn. All warning and error messages resulting from abnormal request processing are logged.
v Error. Only error messages resulting from abnormal request processing are logged.

If a Log level is not specified, the default value Error is used.

Be careful when setting the level to Trace. A lot of messages are logged at this level which can cause the
disk space/file system to fill up very quickly. A Trace setting should never be used in a normally functioning
environment as it adversely affects performance.

Data type String

Chapter 3. Setting up the application serving environment 121

Default Error

Web server plug-in request and response optimization properties settings

Use this page to view or change the request and response optimization properties for a Web server
plug-in.

To view this administrative console page, click Servers > Web Servers >web_server_name Plug-in
Properties > Request and Response.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.

The Runtime tab is available only when this Web server has accessed applications running on application
servers and there is an http_plugin.log file.

Maximum chunk size used when reading the response body:

Specifies the maximum chunk size the plug-in can use when reading the response body.

This field corresponds to the ResponseChunkSize element in the plugin-cfg.xml file.

The plug-in reads the response body in 64K chunks until all of the response data is read. This approach
causes a performance problem for requests whose response body contains large amounts of data.

If the content length of the response body is unknown, the values specified for this property is used as the
size of the buffer that is allocated. The response body is then read in this size chunks, until the entire body
is read. If the content length is known, then a buffer size of either the content length or the specified size
(whichever is less) is used to read the response body.

Data type Integer

Default 64 kilobytes

Specify the size in kilobytes (1024 byte blocks).

Enable Nagle algorithm for connections to the Application Server:

When checked, the Nagle algorithm is enabled for connections between the plug-in and the Application
Server.

This field corresponds to the ASDisableNagle element in the plugin-cfg.xml file.

The Nagle algorithm is named after engineer John Nagle, who invented this standard part of the
transmission control protocol/internet protocol (TCP/IP). The algorithm reduces network overhead by
adding a transmission delay (usually 20 milliseconds) to a small packet, which lets other small packets
arrive and be included in the transmission. Because communications has an associated cost that is not as
dependent on packet size as it is on frequency of transmission, this algorithm potentially reduces overhead
with a more efficient number of transmissions.

Clear the check box to disable the Nagle algorithm.

Enable Nagle Algorithm for the IIS Web Server:

When checked, the Nagle algorithm is used for connections from the Microsoft Internet Informations
Services (IIS) Web Server to the Application Server.

122 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This field corresponds to the IHSDisableNagle element in the plugin-cfg.xml file. It only appears if you are
using the Microsoft Internet Informations Services (IIS) Web server. Clear the check box to disable the
Nagle algorithm for this connection.

Chunk response to the client:

When checked, responses to the client are broken into chunks if a Transfer-Encoding : Chunked
response header is present in the response.

This field corresponds to the ChunkedResponse element in the plugin-cfg.xml file. It only appears if you
are using a Microsoft Internet Informations Services (IIS) Web Server, a Java System Web server, or a
Domino Web server. The IHS Web server automatically handles breaking the response into chunks to
send to the client.

Clear the check box to if you do not want responses broken into chunks.

Accept content for all requests: This field corresponds to the AcceptAllContent element in the
plugin-cfg.xml file.

When selected, users can include content in POST, PUT, GET, and HEAD requests when a
Content-Length or Transfer-encoding header is contained in the request header.

Virtual host matching:

When selected, virtual host mapping is performed by physically using the port number for which the
request was received.

This field corresponds to the VHostMatchingCompat element in the plugin-cfg.xml file.

If this field is not selected, matching is done logically using the port number contained in the host header.

Use the radio buttons to make your physical or logical port selection.

Application server port preference:

Specifies which port number the Application Server should use to build URI’s for a sendRedirect.

This field corresponds to the AppServerPortPreference element in the plugin-cfg.xml file.

Specify:
v webserverPort if the port number from the host header of the HTTP request coming in is to be used.
v hostHeader if the port number on which the Web server received the request is to be used.

The default is webserverPort.

Priority used by the IIS Web server when loading the plug-in configuration file:

Specifies the priority in which the Microsoft Internet Informations Services (IIS) Web server loads the
WebSphere Web server plug-in.

This field corresponds to the IISPluginPriority element in the plugin-cfg.xml file. It only appears if you are
using the IIS Web server. Because the IIS Web server uses this value during startup, the Web server must
be restarted before a change to this field takes effect.

Select one of the following priorities:

v High

Chapter 3. Setting up the application serving environment 123

v Medium
v Low

The default value of High ensures that all requests are handled by the Web server plug-in before they are
handled by any other filter/extensions. If problems occur while using a priority of Medium or Low, you will
have to rearrange the order or change the priority of the interfering filter/extension.

Web server plug-in caching properties settings

Use this page to view or change the caching properties for a Web server plug-in.

To view this administrative console page, click Servers > Web Servers >Web_server_name Plug-in
Properties > Caching Properties.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.

The Runtime tab is available only when this Web server has accessed applications running on application
servers and there is an http_plugin.log file.

Enable Edge Side Include (ESI) processing to cache the responses:

Specifies whether to enable Edge Side Include processing to cache the responses.

This field corresponds to the esiEnable element in the plugin-cfg.xml file.

When selected, Edge Side Include (ESI) processing is used to cache responses. If ESI processing is
disabled for the plug-in, the other ESI plug-in properties are ignored. Clear the checkbox to disable Edge
Side Include processing.

Enable invalidation monitor to receive notifications:

When checked, the ESI processor receives invalidations from the Application Server.

This field corresponds to the ESIInvalidationMonitor element in the plugin-cfg.xml file. It is ignored if Edge
Side Include (ESI) processing is not enabled for the plug-in.

Maximum cache size:

Specifies, in 1K byte units, the maximum size of the cache. The default maximum size of the cache is
1024K bytes (1 megabyte). If the cache is full, the first entry to be evicted from the cache is the entry that
is closest its expiration time.

This field corresponds to the esiMaxCacheSize element in the plugin-cfg.xml file.

Data type Integer

Default 1024 kilobytes

Specify the size in kilobytes (1024 byte blocks).

Web server plug-in request routing properties settings

Use this page to view or change the request routing properties for a Web server plug-in.

To view this administrative console page, click Servers > Web Servers >Web_server_name Plug-in
Properties > Plug-in server_cluster_name Properties.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.

124 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The Runtime tab is available only when this Web server has accessed applications running on application
servers and there is an http_plugin.log file.

Load balancing option:

Specifies the load balancing option that the plug-in uses in sending requests to the various application
servers associated with that Web server.

This field corresponds to the LoadBalanceWeight element in the plugin-cfg.xml file.

Select the appropriate load balancing option:

v Round robin
v Random

The Round Robin implementation has a random starting point. The first application server is picked
randomly. Round Robin is then used to pick application servers from that point forward. This
implementation ensures that in multiple process based Web servers, all of the processes don’t start up by
sending the first request to the same Application Server.

The default load balancing type is Round Robin.

Retry interval:

Specifies the length of time, in seconds, that should elapse from the time an application server is marked
down to the time that the plug-in retries a connection.

This field corresponds to the ServerWaitforContinue element in the plugin-cfg.xml file.

Data type Integer

Default 60 seconds

Maximum size of request content:

Select whether there is a limit on the size of request content. If limited, this field also specifies the
maximum number of bytes of request content allowed in order for the plug-in to attempt to send the
request to an application server.

This field corresponds to the PostSizeLimit element in the plugin-cfg.xml file.

When a limit is set, the plug-in fails any request that is received that is greater than the specified limit.

Select whether to limit the size of request content:

v No limit
v Set limit

If Set limit is selected, specify a limit size.

Data type Integer

Default -1, which indicates there is no limit for the post size.

Specify the size in kilobytes (1024 byte blocks).

Remove special headers:

Chapter 3. Setting up the application serving environment 125

When checked, the plug-in will remove any headers from incoming requests before adding the headers the
plug-in is supposed to add before forwarding the request to an application server.

This field corresponds to the RemoveSpecialHeaders element in the plugin-cfg.xml file.

The plug-in adds special headers to the request before it is forwarded to the application server. These
headers store information about the request that will need to be used by the application. Not removing the
headers from incoming requests introduces a potential security exposure.

Clear the check box to retain special headers.

Clone separator change:

When checked, the plug-in expects the plus character (+) as the clone separator.

This field corresponds to the ServerCloneID element in the plugin-cfg.xml file.

Some pervasive devices cannot handle the colon character (:) used to separate clone IDs in conjunction
with session affinity. If this field is checked, you must also change the configurations of the associated
application servers such that the application servers separates clone IDs with the plus character as well.

Clear the checkbox to use the colon character to separate clone IDs.

Web server plug-in custom properties

If you are using a Web server plug-in, you can add the following custom property to the configuration
settings for that plug-in.

To add a custom property:

1. In the administrative console, click In the administrative console, click Servers > Web Servers >
Web_server_name > Plug-in properties > Custom properties > New
2. Under General Properties specify the name of the custom property in the Name field and a value for
this property in the Value field. You can also specify a description of this property in the Description
field.
3. Click Apply or OK.
4. Click Save to save your configuration changes.
5. Restart the server.

Following is a list of Web server plug-in custom properties that are provided with the Application Server.
These properties are not shown on the properties settings pages for the plug-in.

StashfileLocation

Use this element to set a value for the stashfile initialization parameter.

Data type String

KeyringLocation

Use this element to set a value for the keyring initialization parameter.

Data type String

126 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Web server plug-in configuration service properties settings
Use this page to view or change the configuration settings for the Web server plug-in configuration service.

To view this administrative console page, click Application Servers >server_name > Administration
Services > Web server plug-in configuration service.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.

Enable automated Web server configuration processing

When selected, the Web server plug-in configuration service automatically generates the plug-in
configuration file whenever the Web server environment changes. For example, the plug-in configuration
file is regenerated whenever one of the following activities occurs:
v A new application is deployed on an associated application server.
v The Web server definition is saved.
v An application is removed from an associated application server.
v A new virtual host is defined.

Application Server property settings for a Web server plug-in

Use this page to view or change application server settings for a Web server plug-in.

To view this administrative console page, click Application Servers >server_name > Web Server Plug-in.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.

The Runtime tab is available only when this Web server has accessed applications running on application
servers and there is an http_plugin.log file.

Server role
Specifies the role this application server is assigned.

Select Primary to add this application server to the list of primary application servers. The plug-in initially
attempts to route requests to the application servers on this list.

Select Backup to add this application server to the list of backup application servers. The plug-in does not
load balance across the backup application servers. A backup server is only used if a primary server is not
available. When the plug-in determines that a backup application server is required, it goes through the list
of backup servers, in order, until no servers are left in the list or until a request is successfully sent and a
response received from one of the servers on this list.

Connect timeout
Specifies whether or not there is a limited amount of time the Application Server will maintain a connection
with the Web server.

You can select either No timeout or Set timeout. If you select Set timeout you, must specify, in seconds,
the length of time a connection with the Web server is to be maintained.

This property enables the plug-in to perform non-blocking connections with the application server.
Non-blocking connections are beneficial when the plug-in is unable to contact the destination to determine
whether or not the port is available. If no value is specified for this property, the plug-in performs a
blocking connect in which the plug-in sits until an operating system times out (which could be as long as 2
minutes depending on the platform) and allows the plug-in to mark the server unavailable.

Chapter 3. Setting up the application serving environment 127

A value of 0 causes the plug-in to perform a blocking connect. A value greater than 0 specifies the number
of seconds you want the plug-in to wait for a successful connection. If a connection does not occur after
that time interval, the plug-in marks the server unavailable and fails over to another application server
defined for the requested application.

Data type Integer

Maximum number of connections that can be handled by the Application Server

Specifies the maximum number of pending connections to an Application Server that can be flowing
through a Web server process at any point in time.

This field corresponds to the ServerMaxConnections element in the plugin-cfg.xml file.

You can select either No limit or Set limit. If you select Set limit you, must specify the maximum number
of connections that can exist between the Web server and the Application Server at any given point in
time.

For example, assuming that:

v The application server is fronted by 5 nodes that are running an IHS Web server.
v Each node starts 2 processes.
v This property is set to 50.

In this example, the application server could potentially get up to 500 connections. (You take the number
of nodes, 5, multiply it by the number of processes, 2, and then multiply that number by the number
specified for this property, 50, for a total of 500 connections.)

If this attribute is set to either zero or -1, there is no limit to the number of pending connections to the
Application Servers.

Data type Integer

Default -1

Use extended handshake to check whether Application Server is running

When selected, the Web server plug-in will use an extended handshake to check whether or not the
Application Server is running.

This field corresponds to the ServerExtendedHandshake element in the plugin-cfg.xml file.

Select this property if a proxy firewall is between the plug-in and the application server.

The plug-in marks a server as down when the connect() fails. However, when a proxy firewall is in
between the plug-in and the application server, the connect() will succeed, even though the back end
application server is down. This causes the plug-in to not failover correctly to other application servers.

If the plug-in performs some handshaking with the application server to ensure that it is started before it
sends a request it can failover to another application server if it detects that the application server with
which it is attempting to perform a handshake is down.

Send the header ″100 Continue″ before sending the request content
This field corresponds to the WaitForContinue element in the plugin-cfg.xml file.

When selected, the Web server plug-in will send the header ″100 Continue″ to the Application Server
before it sends the request content.

128 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Web server plug-in configuration properties
The following table indicates which panel in the administrative console you need to use to manually
configure a Web server plug-in property.
Table 13. Web server plug-in configuration properties
Administrative console panel Field name Configuration property name
In the administrative console, click Refresh configuration interval RefreshInterval
Servers > Web Servers
>Web_server_name > Plug-in
properties
In the administrative console, click Plug-in log file name Log->name
Servers > Web Servers >
Web_server_name > Plug-in
properties
In the administrative console, click Plug-in logging Log->LogLevel
Servers > Web Servers >
Web_server_name > Plug-in
properties
In the administrative console, click Ignore DNS failures during Web IgnoreDNSFailures
Servers > Web Servers > server startup
Web_server_name > Plug-in
properties
In the administrative console, click KeyringLocation Keyring
Servers > Web Servers >
Web_server_name > Plug-in
properties > Custom properties >
New
In the administrative console, click StashfileLocation Stashfile
Servers > Web Servers >
Web_server_name > Plug-in
properties > Custom properties >
New
In the administrative console, click Load balancing option LoadBalance
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request routing
In the administrative console, click Clone separator change CloneSeparatorChange
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request Routing
In the administrative console, click Retry interval RetryInterval
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request Routing
In the administrative console, click Maximum size of request content PostSizeLimit
Servers >Web server_name >
Plug-in properties > Request
routing
In the administrative console, click Remove special headers RemoveSpecialHeaders
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request routing

Chapter 3. Setting up the application serving environment 129

Table 13. Web server plug-in configuration properties (continued)
In the administrative console, click Server role PrimaryServers and BackupServers
Application Servers >server_name > list
Web server plug-in properties
In the administrative console, click Connect timeout Server ConnectTimeout
Application Servers >server_name >
Web server plug-in properties
In the administrative console, click Use extended handshake to check Server Extended Handshake
Application Servers >server_name > whether Application Server is running
Web server plug-in properties
In the administrative console, click Send the header ″100 Continue″ WaitForContinue
Application Servers >server_name > before sending the request content
Web server plug-in properties
In the administrative console, click Maximum number of connections that Server MaxConnections
Application Servers >server_name > can be handled by the Application
Web server plug-in properties Server
In the administrative console, click Application server port preference AppServerPortPreference
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request and
Response
In the administrative console, click Enable Nagle algorithm for ASDisableNagle
Servers > Web Servers > connections to the Application Server
Web_server_name > Plug-in
properties > Request and
Response
In the administrative console, click Enable Nagle Algorithm for the IIS IISDisableNagle
Servers > Web Servers > Web Server
Web_server_name > Plug-in
properties > Request and
Response
In the administrative console, click Virtual host matching VHostMatchingCompat
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request and
Response
In the administrative console, click Maximum chunk size used when ResponseChunkSize
Servers > Web Servers > reading the response body
Web_server_name > Plug-in
properties > Request and
Response
In the administrative console, click Accept content for all requests AcceptAllContent
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request and
Response
In the administrative console, click Chunk response to the client ChunkedResponse
Servers > Web Servers >
Web_server_name > Plug-in
properties > Request and
Response

130 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Table 13. Web server plug-in configuration properties (continued)
In the administrative console, click Priority used by the IIS Web server IISPluginPriority
Servers > Web Servers > when loading the plug-in configuration
Web_server_name > Plug-in file
properties > Request and
Response
In the administrative console, click Enable Edge Side Include (ESI) ESIEnable
Servers > Web Servers > processing to cache the responses
Web_server_name > Plug-in
properties > Caching
In the administrative console, click Maximum cache size ESIMaxCacheSize
Servers > Web Servers >
Web_server_name > Plug-in
properties > Caching
In the administrative console, click Enable invalidation monitor to receive ESIInvalidationMonitor
Servers > Web Servers > notifications
Web_server_name > Plug-in
properties > Caching

Web server plug-in connections

The WebSphere Application Server Web server plug-ins are used to establish and maintain persistent
HTTP and HTTPS connections to Application Servers .

When the plug-in is ready to send a request to the application server, it first checks its connection pool for
existing connections. If an existing connection is available the plug-in checks its connection status. If the
status is still good, the plug-in uses that connection to send the request. If a connection does not exist, the
plug-in creates one. If a connection exists but has been closed by the application server, the plug-in closes
that connection and opens a new one.

After a connection is established between a plug-in and an application server, it will not be closed unless
the application server closes it for one of the following reasons:
v If the Use Keep-Alive property is selected and the time limit specified on the Read timeout or Write
timeout property for the HTTP inbound channel has expired.
v The maximum number of persistent requests which can be processed on an HTTP inbound channel has
been exceeded. (This number is set using the HTTP inbound channel’s Maximum persistent requests
property.)
v The Application Server is shutting down.

Even if the application server closes a connection, the plug-in will not know that it has been closed until it
tries to use it again. The connection will be closed if one of the following events occur:
v The plug-in receives a new HTTP request and tries to reuse the existing connection.
v The number of httpd processes drop because the Web server is not receiving any new HTTP requests.
(For the IHS Web server, the number of httpd processes that are kept alive depends on the value
specified on the Web server’s MinSpareServers directive.)
v The Web server is stopped and all httpd processes are terminated, and their corresponding sockets are
closed.

Note: Sometimes, if a heavy request load is stopped or decreased abruptly on a particular application
server, a lot of the plug-in’s connections to that application server will be in CLOSE_WAIT state.
Because these connections will be closed the first time the plug-in tries to reuse them, having a
large number of connections in CLOSE-WAIT state should not affect performance

Chapter 3. Setting up the application serving environment 131

Web server plug-in remote user information processing
You can configure your Web server with a third-party authentication module and then configure the Web
server plug-in to route requests to the Application Server. If an application calls the getRemoteUser()
method, it relies on a private HTTP header that contains the remote user information and is parsed by the
plug-in. The plug-in sets the private HTTP header value whenever a Web server authentication module
populates the remote user in the Web server data structure. If the private HTTP header value is not set,
the application’s call to getRemoteUser() returns a null value.
v In the case of an Apache and IBM HTTP Server (IHS) Web server, the plug-in builds the private header
from the information contained in the associated request record.
v In the case of a Sun One Web server, the plug-in builds the private header from the information
contained in the auth_user property associated with the request. The private header is usually set to
the name of the local HTTP user of the Web browser, if HTTP access authorization is activated for the
URL.
v In the case of a Domino Web server, the plug-in builds the private header from the information
contained in the REMOTE_USER environment variable. The plug-in sets this variable to anonymous
for users who have not logged in and to the username for users who are logged into the application.
v In the case of an Internet Information Services (IIS) Web server, the plug-in builds the private header
from the information contained in the REMOTE_USER environment variable. The plug-in sets this
variable to the name of the user as it is derived from the authorization header sent by the client.

If the private header is not being set in the Sun One, IIS, or Domino Web server plug-in, make sure the
request record includes information about the user requesting the data.

Note: If an application’s call to getRemoteUser() returns a null value, or if the correct remote user
information is not being added to the Web server plug-in’s data structure, make sure the remote
user parameter within the WebAgent is still set to YES. (Sometimes this parameter gets set to NO
when service is applied.)

Web server plug-ins

Web server plug-ins enable the Web server to communicate requests for dynamic content, such as
servlets, to the application server. A Web server plug-in is associated with each Web server definition. The
configuration file (plugin-cfg.xml) that is generated for each plug-in is based on the applications that are
routed through the associated Web server.

A Web server plug-in is used to forward HTTP requests from a supported Web server to an application
server. Using a Web server plug-in to provide communication between a Web server and an application
server has the following advantages:
v XML-based configuration file
v Standard protocol recognized by firewall products
v Security using HTTPS, replacing proprietary Open Servlet Engine (OSE) over Secure Sockets Layer
(SSL)

Each of the supported distributed platform Web server plug-ins run on a number of operating systems.
See Supported Hardware and Software at
http://www.ibm.com/software/webservers/appserv/doc/latest/prereq.htmlfor the product for the most
current information about supported Web servers.

Checking your IBM HTTP Server version

At times, you might need to determine the version of your IBM HTTP Server installation.
1. Change directory to the installation root of the Web server. For example, this is /opt/IBMIHS on a
Solaris machine.

132 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Find the subdirectory that contains apache.exe (on a Windows platforms) or apachectl (on a
UNIX-based platforms, such as z/OS, Solaris, Linux, and HP-UX)
3. On a Windows platform, issue:
apache.exe -V
4. On a UNIX-based platforms issue:
./apachectl -V 4

The version is shown in the ″Server version:″ field and will looks something like the following:
Server version: IBM_HTTP_Server/2.0.47 Apache/2.0.47
Server built: July 2 2004 20:38:36
Server’s Module Magic Number: 20020903:4.

Web server tuning parameters

WebSphere Application Server provides plug-ins for several Web server brands and versions. Each Web
server operating system combination has specific tuning parameters that affect the application
performance.
v IBM HTTP Server
The IBM HTTP Server V6.0 is a multi-process, multi-threaded server.
– Access logs
- Description: Collects all incoming HTTP requests. Logging degrades performance because IO
operation overhead causes logs to grow significantly in a short time.
- How to view or set:
1. Open the IBM HTTP Server httpd.conf file, located in the directory
IBM_HTTP_Server_root_directory/conf.
2. Search for a line with the text CustomLog.
3. Comment out this line by placing # in front of the line.
4. Save and close the httpd.conf file.
5. Stop and restart the IBM HTTP Server.
- Default value: Logging of every incoming HTTP request is enabled.
- Recommended value: Disable the access logs.
– MaxClients
- Description: The MaxClients directive controls the maximum number of simultaneous connections
or users that the web server can service at any one time. If, at peak usage, your web server
needs to support 200 active users at once, you should set MaxClients to 220 (200 plus an extra
10% for load growth). Setting MaxClients too low could cause some users to believe the web
server is not responding. You should have sufficient RAM in your web server machines to support
each connected client. For IBM HTTP Server V6.0 on UNIX, you should allocate around 1.5MB
MaxClients of RAM for use by the IBM HTTP Server. For IBM HTTP Server V6.0 on Windows,
you should allocate around 300KB MaxClients of RAM for use by the IBM HTTP Server. Some
third party modules can significantly increase the amount of RAM used per connected client.
- How to view or set: Edit the MaxClients directive in the IBM HTTP Server httpd.conf file,
located in the directory IBM_HTTP_Server_root_directory/conf.
- Default value: 150
- Recommended value: The maximum number of users normally simultaneously connected to your
web server, plus an additional 10% for buffer. Note: The KeepAliveTimeout setting can affect how
long a user is connected to the webserver.
– MinSpareServers, MaxSpareServers, and StartServers
- Description: Pre-allocates and maintains the specified number of processes so that few
processes are created and destroyed as the load approaches the specified number of processes.
Specifying similar values reduces the CPU usage for creating and destroying HTTPD processes.
Adjust this parameter if the time waiting for IBM HTTP Server to start more servers, so that it can
handle HTTP requests, is not acceptable.
- How to view or set: Edit the MinSpareServers, MaxSpareServers and StartServers directives in
the httpd.conf file located in the IBM_HTTP_Server_root_directory/conf directory.
- Default value: MinSpareServers 5, MaxSpareServers 10, StartServers 5
Chapter 3. Setting up the application serving environment 133
 - Recommended value: For optimum performance, specify the same value for the
MinSpareServers and the StartServers parameters. If MaxSpareServers is set to less than
MinSpareServers, IBM HTTP Server resets MaxSpareServer=MinSpareServer+1. Setting the
StartServers too high can cause swapping if memory is not sufficient, degrading performance.
– ListenBackLog
- Description: Sets the length of a pending connections queue. When several clients request
connections to the IBM HTTP Server, and all threads used, a queue exists to hold additional client
requests. However, if you use the default Fast Response Cache Accelerator (FRCA) feature of
IBM HTTP Server V6.0 on Windows, the ListenBackLog directive is not used since FRCA has its
own internal queue.
- How to view or set: For non-FRCA: Edit the IBM HTTP Server httpd.conf file. Then, add or
view the ListenBackLog directive.
- Default value: For HTTP Server V6.0: 1024 with FRCA enabled, 511 with FRCA disabled
- Recommended value: Use the defaults.
v IBM HTTP Server - Linux
– MaxRequestsPerChild
- Description: Sets the limit on the number of requests that an individual child server process
handles. After the number of requests reaches the value set for the MaxRequestsPerChild
parameter, the child process dies. Adjust this parameter if destroying and creating child processes
is degrading your Web server performance.
- How to view or set:
1. Edit the IBM HTTP server httpd.conf file located in the IBM_HTTP_Server_root_directory/conf
directory.
2. Change the value of the parameter.
3. Save the changes and restart the IBM HTTP server.
- Default value: 500
- Recommended value: Should normally be set to 0. Non-zero settings can be useful if child
memory usage is observed to steadly increase over time. Memory leaks have occasionally been
observed in third party modules and various OS runtime libraries used by the IBM HTTP Server.
v IBM HTTP Server - Windows 2000 and Windows 2003
– ThreadsPerChild
- Description: Sets the number of concurrent threads running at any one time within the IBM HTTP
Server.
- How to view or set: Edit the IBM HTTP Server file httpd.conf file located in the directory
IBM_HTTP_Server_root_directory/conf. Change the value of the parameter. Save the changes and
restart the IBM HTTP Server.
There are two ways to find how many threads are used under load:
1. Use the Windows 2000 and Windows 2003 Performance Monitor under the desktop Start
menu:
a. Right-click the status bar on your desktop. Click Task Manager.
b. Select the Processes tab.
c. Click View > Select Columns.
d. Select Thread Count.
e. Click OK.
The Processes tab shows the number threads for each process under the column name
Threads, including Apache.
2. Use the IBM HTTP Server server-status (this choice works on all platforms, not just
Windows):
a. Edit the IBM HTTP Server httpd.conf file as follows: Remove the comment character #
from the following lines: #LoadModule status_module, modules/ApacheModuleStatus.dll,
#<Location/server-status>, #SetHandler server-status, and #</Location>.
b. Save the changes and restart the IBM HTTP Server.
c. In a Web browser, go to the URL: http://yourhost/server-status. Alternatively,
d. Click Reload to update status.

134 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 e. (Optional) If the browser supports refresh, go to http://your_host/server-
status?refresh=5 to refresh every five seconds. You will see five requests currently
processing 45 idle servers.
- Default value: 250 for IBM HTTP Server V6.0.
- Recommended value: Set this value to prevent bottlenecks, allowing just enough traffic through
to the application server.
– Web server configuration reload interval
- Description: Tracks a variety of configuration information about WebSphere Application Server
resources. The Web server needs to understand some of this information, such as Uniform
Resource Identifiers (URIs) pointing to WebSphere Application Server resources. This
configuration data is pushed to the Web server through the WebSphere Application Server plug-in
at intervals specified by this parameter. Periodic updates add new servlet definitions without
having to restart any of the WebSphere Application Server servers. However, the dynamic
regeneration of this configuration information is costly in terms of performance. Adjust this
parameter in a stable production environment.
- How to view or set:Use the Refresh configuration interval Web server plug-in property to change
the current setting for this parameter. In the administrative console, click Servers > Web Servers
>Web_server_name > Plug-in properties.
- Default value: The default reload interval is 60 seconds.
- Recommended value: Increase the reload interval to a value that represents an acceptable wait
time between the servlet update and the Web server update.
For more information about the plugin-cfg.xml file see the topic “Web server plug-ins” on page 132.
v Sun Java System Web server, Enterprise Edition (formerly Sun ONE) - Solaris operating
environment
The default configuration of the Sun ONE Web server, Enterprise Edition provides a single-process,
multi-threaded server.
– Active threads
- Description: Specifies the current number of threads active in the server. After the server reaches
the limit set with this parameter, the server stops servicing new connections until it finishes old
connections. If this setting is too low, the server can become throttled, resulting in degraded
response times. To tell if the Web server is being throttled, consult its perfdump statistics. Look at
the following data:
v WaitingThreads count: If WaitingThreads count is getting close to zero, or is zero, the server
is not accepting new connections.
v BusyThreads count: If the WaitingThreads count is close to zero, or is zero, BusyThreads is
probably very close to its limit.
v ActiveThreads count: If ActiveThreads count is close to its limit, the server is probably limiting
itself.
- How to view or set: Use the Maximum number of simultaneous requests parameter in the
Enterprise Server Manager interface to control the number of active threads within Sun ONE Web
server, Enterprise Edition. This setting corresponds to the RqThrottle parameter in the
magnus.conf file.
- Default value: 512
- Recommended value: Increase the thread count until the active threads parameters show
optimum behavior.
v Microsoft Internet Information Server (IIS) - Windows NT and Windows 2000
– IIS permission properties
- Description: The Web server has several properties that dramatically affect the performance of
the application server. The default settings are usually acceptable. However, because other
products can change the default settings without user knowledge, make sure to check the IIS
settings for the Home Directory permissions of the Web server. The permissions should be set to
Script and not to Execute. If the permissions are set to Execute, no error messages are returned,
but the performance of WebSphere Application Server is decreased.
- How to view or set: To check or change these permissions, perform the following procedure in
the Microsoft management console:

Chapter 3. Setting up the application serving environment 135

 1. Select the Web site (usually default Web site).
2. Right-click and select the Properties option.
3. Click the Home Directory tab. To set the permissions of the Home Directory:
a. In the Application settings, select the Script check box in the Permissions list and clear
the Execute check box.
b. (Optional) Check the permissions of the sePlugin:
1) Expand the Web server.
2) Right-click the sePlugin and select Properties.
3) Confirm that the Execute permissions are set to Execute.
- Default value: Script
- Recommended value: Script
– Number of expected hits per day
- Description: Controls the memory that IIS allocates for connections.
- How to view or set: Using the performance window, set the parameter to More than 100000 in
the Web site properties panel of the Microsoft management console.
- Default value: Fewer than 100000
- Recommended value: More than 100000
– ListenBackLog parameter
- Description: Alleviates failed connections under heavy load conditions, if you are using IIS on
Windows NT and Windows 2000. Failure typically occurs when you are using more than 100
clients. ListenBackLog increases the number of requests that IIS keeps in its queue. Consider
raising this value if you see intermittent Unable to locate server errors in the Netscape
browser.
- How to view or set:
1. Use a command prompt to issue the regedit command to access the operating system
registry.
2. In the registry window, locate the parameter in the
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
InetInfo\Parameters\ListenBackLog directory.
3. Right-click the parameter to adjust the setting according to the server load.
- Default value: 25 (decimal)
- Recommended value: You can set the ListenBackLog parameter can be set as high as 200,
without negative impact on performance and with an improvement in load handling.

Modifying the WebSphere plug-in to improve performance

You can improve the performance of IBM HTTP Server V6.0 (with the WebSphere Web server plug-in) by
modifying the plug-in’s RetryInterval configuration. The RetryInterval is the length of time to wait before
trying to connect to a server that has been marked temporarily unavailable. Making this change can help
the IBM HTTP Server V6.0 to scale higher than 400 users.

The plug-in marks a server temporarily unavailable if the connection to the server fails. Although a default
value is 60 seconds, it is recommended that you lower this value in order to increase throughput under
heavy load conditions. Lowering the RetryInterval is important for IBM HTTP Server V6.0 on UNIX
operating systems that have a single thread per process, or for IBM HTTP Server 2.0 if it is configured to
have fewer than 10 threads per process.

How can lowering the RetryInterval affect throughput? If the plug-in attempts to connect to a particular
application server while the application server threads are busy handling other connections, which
happens under heavy load conditions, the connection times out and the plug-in marks the server
temporarily unavailable. If the same plug-in process has other connections open to the same server and a
response is received on one of these connections, the server is marked again. However, when you use
the IBM HTTP Server V6.0 on a UNIX operating system, there is no other connection since there is only
one thread and one concurrent request per plug-in process. Therefore, the plug-in waits for the
RetryInterval before attempting to connect to the server again.

136 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Since the application server is not really down, but is busy, requests are typically completed in a small
amount of time. The application server threads become available to accept more connections. A large
RetryInterval causes application servers that are marked temporarily unavailable, resulting in more
consistent application server CPU utilization and a higher sustained throughput.

Note: Although lowering the RetryInterval can improve performance, if all the application servers are
running, a low value can have an adverse affect when one of the application servers is down. In
this case, each IBM HTTP Server V6.0 process attempts to connect and fail more frequently,
resulting in increased latency and decreased overall throughput.

Gskit install images files

The Global Security Kit (GSKit) installation image files for the WebSphere Web server plug-ins are
packaged on the CD with the Web server plug-in files. You can download the appropriate GSKIT file to the
workstation on which your Web server is running. Use the following table to assist you in selecting the
correct GSKIT installation image file.

Operating system GSKit 7 Installation image file

Windows No image name
AIX gskta.rte
HP-UX gsk7bas
Solaris Operating Environment gsk7bas
Linux gsk7bas_7.0.3.1.i386.rpm
Linux390 gsk7bas-7.0.3.1.s390.rpm
LinuxPPC gsk7bas-7.0.3.1.ppc.rpm

Plug-ins: Resources for learning

See this topic in the V6 Information Center to find links links to relevant supplemental information about
Web server plug-ins. The information resides on IBM and non-IBM Internet sites, whose sponsors control
the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

Web server plug-in tuning tips

Balancing workloads:

During normal operation, the backlog of connections pending to an application server is bound to grow.
Therefore, balancing workloads among application servers in a network fronted by a Web server plug-in
helps improve request response time.

In a distributed environment, you can limit the number of connections that can be handled by an
applications server. To do this:
1. Go to the Servers > Application Servers >server_name.
2. Under Additional Properties, click > Web Server Plug-in properties .
3. Select Set limit for the Minimum number of connections that can be handled by the Application Server
field.
4. Specify in the Connections field the maximum number of connections you want to allow.
5. Then click Apply and Save.

Chapter 3. Setting up the application serving environment 137

When this maximum number of connections is reached, the plug-in, when establishing connections,
automatically skips that application server, and tries the next available application server. If no application
servers are available, an HTTP 503 response code will be returned to the client. This code indicates that
the server is currently unable to handle the request because it is experiencing a temporary overloading or
because maintenance is being performed.

The capacity of the application servers in the network determines the value you specify for the maximum
number of connections. The ideal scenario is for all of the application servers in the network to be
optimally utilized. For example, if you have the following environment:
v There are 10 application servers in a cluster.
v All of these application servers host the same applications (that is, Application_1 and Application_2).
v This cluster of application servers is fronted by five IBM HTTP Servers.
v The IBM HTTP Servers get requests through a load balancer.
v Application_1 takes approximately 60 seconds to respond to a request
v Application_2 takes approximately 1 second to respond to a request.

Depending on the request arrival pattern, all requests to Application_1 might be forwarded to two of the
application servers, say Appsvr_1 and Appsvr_2. If the arrival rate is faster than the processing rate, the
number of pending requests to Appsvr_1 and Appsvr_2 can grow.

Eventually, Appsvr_1 and Appsvr_2 are busy and are not able to respond to future requests. It usually
takes a long time to recover from this overloaded situation.

If you want to maintain 2500 connections, and optimally utilize the Application Servers in this example, set
the number of maximum connections allowed to 50. (This value is arrived at by dividing the number of
connections by the result of multiplying the number of Application Servers by the number of Web servers;
in this example, 2500/(10x5)=50.)

Limiting the number of connections that can be established with an application server works best for Web
servers that follow the threading model instead of the process model, and only one process is started.

The IBM HTTP Server V6.0.x follows the threading model. To prevent the IBM HTTP Server from starting
more than one process, change the following properties in the Web server configuration file (httpd.conf)
to the indicated values:
ServerLimit 1
ThreadLimit 4000
StartServers 1
MaxClients 1024
MinSpareThreads 1
MaxSpareThreads 1024
ThreadsPerChild 1024
MaxRequestsPerChild 0

Improving performance in a high stress environment:

If you use the default settings for a Microsoft Windows operating system, you might encounter Web server
plug-in performance problems if you are running in a high stress environment. To avoid these problems,
consider tuning the the TCP/IP setting for this operating system. Two of the keys setting to tune are
TcpTimedWaitDelay and MaxUserPort.

To tune the TcpTimedWaitDelay setting, change the value of the tcp_time_wait_interval parameter from the
default value of 240 seconds, to 30 seconds:
1. Locate in the Windows Registry:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\tcpip\Parameters\TcpTimedWaitDelay

138 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 If this entry does not exist in your Windows Registry, create it by editing this entry as a new DWORD
item.
2. Specify, in seconds, a value between 30 and 300 inclusive for this entry. (It is recommended that you
specify a value of 30. )

To tune the MaxUserPort setting:

1. Locate in the Windows Registry:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\tcpip\Parameters\MaxUserPort

If this entry does not exist in your Windows Registry, create it by editing this entry as a new DWORD
item.
2. Set the maximum number of ports to a value between 5000 and 65534 ports, inclusive. (It is
recommended that you specify a value of 65534,)

See the Microsoft Web site for more information about these settings.

Tuning Web servers

“Web server tuning parameters” on page 133 lists tuning parameters specific to Web servers. The listed
parameters may not apply to all of the supported Web servers. Check your Web server documentation
before using any of these parameters.

Setting up the administrative architecture

After you install and set up the Network Deployment product, you mainly need to monitor and control
incorporated nodes and the resources on those nodes by using the administrative console or other
administrative tools. Use the following tasks to perform these activities.
1. Use the settings page for an administrative service to configure administrative services.
2. Configure cells.
3. Configure deployment managers.
4. Manage nodes.
5. Manage node agents.
6. Manage node groups.
7. Configure remote file services.

Cells
Cells are logical groupings of one or more nodes in a WebSphere Application Server distributed network.

A cell is a configuration concept, a way for administrators to logically associate nodes with one another.
Administrators define the nodes that make up a cell, according to the specific criteria that make sense in
their organizational environments.

Administrative configuration data is stored in XML files. A cell retains master configuration files for each
server in every node in the cell. Each node and server also have their own local configuration files.
Changes to a local node or to a server configuration file are temporary, if the server belongs to the cell.
While in effect, local changes override cell configurations. Changes to the master server and master node
configuration files made at the cell level replace any temporary changes made at the node when the cell
configuration documents are synchronized to the nodes. Synchronization occurs at designated events,
such as when a server starts.

Chapter 3. Setting up the application serving environment 139

Configuring cells
When you created a deployment manager profile, a cell was created. A cell provides a way to group one
or more nodes of your Network Deployment product. You probably will not need to re-configure the cell. To
view information about and manage a cell, use the settings page for a cell.
1. Access the settings page for a cell. Click System Administration > Cell from the navigation tree of
the administrative console.
2. If the protocol that the cell uses to retrieve information from a network is not appropriate for your
system, select the appropriate protocol. By default, a cell uses Transmission Control Protocol (TCP). If
you want the cell to use User Diagram Protocol, select UDP from the drop-down list for Cell
Discovery Protocol on the settings page for the cell. It is unlikely that you will need to change the
cell’s protocol configuration from TCP.
3. Click Custom Properties and define any name-value pairs needed by your deployment manager.
4. When you installed the WebSphere Application Server Network Deployment product, a node was
added to the cell. You can add additional nodes on the Node page. Click Nodes to access the Node
page, which you use to manage nodes.

Note: Both Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6) are now
supported by WebSphere Application Server, but there are restrictions that apply to using both
IPv4 and IPv6 in the same cell. Note that when you add a node to a cell, the format in which
you specify the host name is based on the version of IP the node will be using. For details, see
“IP version considerations for cells.”

IP version considerations for cells

Internet Protocol Version 4 is no longer viable for many businesses. Because it is based on 32-bit
architecture, there is a growing shortage of Internet Protocol Version 4 (IPv4) addresses. Internet Protocol
Version 6 (IPv6) is based on 128-bit architecture, which allows a far greater number of addresses to be
available for use over the Internet.

In response, WebSphere Application Server Version 6 now includes support for IPv6, in addition to
continued support for IPv4. This means that nodes running WepSphere Application Server Version 6 can
use IPv6. (However, note that nodes running WebSphere Application Server Version 5.x cannot use IPv6.)

WebSphere Application Server Version 6 supports a dual mode environment in which you can have older
legacy applications running on IPv4 and IPv6-enabled applications running on IPv6. Note, however, that
there are restrictions on using IPv4 and IPv6 in the same cell. This article documents those restrictions as
well as outlines the ways in which you can set up your cells, depending on the version of IP that you will
be using.

From an IP perspective, you must adhere to one of the following scenarios:

Dual mode cell

In a dual mode cell, mixed IPv4 and IPv6 communications are supported. By default, a cell is set to dual
mode when it is created. Note, however, that only nodes running WebSphere Application Server Version 6
are valid in a dual mode cell.

IPv4 and IPv6 nodes cannot communicate with each other, so the purpose of the dual mode cell is to
enable this communication, thereby allowing you to use your existing applications, running over IPv4, with
newer applications that have been enabled for IPv6.

The following illustration shows a dual mode cell:

140 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Dual mode cell

Cell (dual mode)

Node A Node B Node C

WebSphere WebSphere WebSphere

IPv6 Application IPv6 Application IPv6 Application
Server v6.0 Server v6.0 Server v6.0

Node D Node E

WebSphere WebSphere
IPv4 Application IPv4 Application
Server v6.0 Server v6.0

IPv4-only cell

In an IPv4-only cell, all nodes must:

v Use IPv4
v Run WebSphere Application Server Version 5.x
v Have host names defined as strings or 32-bit numerical addresses.

IPv4-only cell

Cell (IPv4)

Node A Node B Node C

WebSphere WebSphere WebSphere

IPv4 Application IPv4 Application IPv4 Application
Server V5.x Server V5.x Server V5.x

Node D Node E

WebSphere WebSphere
IPv4 Application IPv4 Application
Server V5.x Server V5.x

Chapter 3. Setting up the application serving environment 141

It is important to note that, by default, a cell is set to dual mode. However, in order to run in an IPv4-only
environment, you will need to explicitly set the cell to IPv4. See the section on JVM settings, in this article,
for more information.

Note: If you want to run a combination of WebSphere Application Server Version 5.x and WebSphere
Application Server Version 6.0 nodes over IPv4, see the section on setting up a mixed node cell,
below.

Mixed node cell

A mixed node cell consists of some nodes running WebSphere Application Server Version 5.x and other
nodes running WebSphere Application Server Version 6. In a mixed node cell, all nodes must use IPv4.
When defining a node that will be used in a mixed node cell, you must specify the host name as a string
or as a 32-bit numerical address, regardless of whether the node is running WebSphere Application Server
Version 5.x or WebSphere Application Server Version 6. 128-bit numerical addresses may not be
specified.

Mixed node cell

Cell (IPv4)

Node A Node B Node C

WebSphere WebSphere WebSphere

IPv4 Application IPv4 Application IPv4 Application
Server V5.x Server V5.x Server V5.x

Node D Node E

WebSphere WebSphere
IPv4 Application IPv4 Application
Server V6.0 Server V6.0

In a mixed node cell, even though the WebSphere Application Server Version 6 nodes will be configured to
use IPv4, the operating system running on them can still support both IPv4 and IPv6. This is true as long
as the WebSphere Application Server Version 6 nodes are configured with string-based host names or
32-bit numerical addresses.

Note also, that you can only add Version 5.x nodes into a mixed node cell through migration. You first
need to migrate from a Version 5.x Deployment Manager to a Version 6.0 Deployment Manager, and then
either keep the Version 5.x nodes or migrate them to Version 6.0 nodes.

IPv6-only cell

In an IPv6-only cell, all nodes must:

v Use IPv6
v Run WebSphere Application Server Version 6
v Have host names defined as strings or 128-bit numerical addresses.
142 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
IPv6-only cell

Cell (IPv6)

Node A Node B Node C

WebSphere WebSphere WebSphere

IPv6 Application IPv6 Application IPv6 Application
Server V6.0 Server V6.0 Server V6.0

Node D Node E

WebSphere WebSphere
IPv6 Application IPv6 Application
Server V6.0 Server V6.0

Specifying host names

During the installation of WebSphere Application Server, you are asked to provide the host name or IP
address of the machine on which the installation is being carried out in the Host Name or IP address field.
The host name or IP address that you specify is used to advertise this installation to all other WebSphere
Application Server installations in the cell configurations. All nodes in the cell will use the host names or IP
addresses that are defined in this way to reach each other. In general, it is best to always use a host
name to identify a WebSphere Application Server installation. By using a host name, you will not have to
be concerned about which IP address is being used (32-bit versus 128-bit), whether it runs on IPv4 or
IPv6, and so on. As long as the DNS service is properly configured, the nodes should all be able to work
together.

However, if you prefer, you can control which IP stack or address is used. To do this, enter the specific IP
address (32-bit for IPv4 or 128-bit for IPv6) into the Host Name or IP Address field. This installation will
then be identified with this IP address and other WebSphere Application Server nodes will use this IP
address to communicate with this node.

When specifying IPv6 addresses, it is good practice to always surround them with protective square
brackets. For example, [fe80::202:57ff:fec4:2334]. The reason for this is that in system internal
processing, IP addresses are often combined with port numbers in the form of <IP address>:<port
number> , and the colons in IPv6 addresses could be confusing in such circumstances. Note that you
cannot use IPv6 addresses, including IPv6 addresses surrounded by square brackets, within the
administrative console or the install wizard.

Note that in scripting, the square brackets might have special meaning, depending on the language
binding used (for example, Jacl). You can work around this problem by using a special escape character in
front of the opening and closing brackets. Using the Jacl binding, for example, the same IPv6 address
cited earlier can be entered as \[fe80::202:57ff:fec4:2334\]

Chapter 3. Setting up the application serving environment 143

Note: While you cannot use square brackets with IPv6 addresses within the administrative console, you
must use square brackets to specify an IPv6 address as part of the adminstrative console’s URL in
a browser. This allows the browser to distinguish the IPv6 address from the port value.

Multicast configuration

WebSphere Application Server uses multicast broadcasting at the node level to allow a node agent to
discover the managed processes in the node. IPv4 and IPv6 addresses are not compatible. Therefore, to
allow a WebSphere Application Server node installation to run out-of-the-box, both IPv4 and IPv6 multicast
addresses are initially defined in the node agent configuration, and when a node agent starts, both
addresses will be tried in sequence. It is a good idea to delete either
NODE_MULTICAST_DISCOVERY_ADDRESS or NODE_IPV6_MULTICAST_DISCOVERY_ADDRESS
after installation. By that time, you should know whether the node is running IPv4 or IPv6, so by limiting
multicast discovery to the known protocol, the node agent runs more efficiently.

To delete one of the multicast ports using the Administrative Console, do the following:
1. Click System Administration --> Node Agents.
2. Select the node agent.
3. On the next panel, under Additional Properties, select Ports. The next panel shows a list of existing
ports.
4. Select either NODE_MULTICAST_DISCOVERY_ADDRESS (to delete IPv4) or
NODE_IPV6_MULTICAST_DISCOVERY_ADDRESS (to delete IPv6).
5. Click Delete.

JVM settings

Two system properties are related to IPv6 support. They are:

v java.net.preferIPv4Stack=<true|false>
v java.net.preferIPv6Addresses=<true|false>

In general, setting these properties is not recommended. In particular, setting java.net.perferIPv4Stack to

true will disable the dual mode support in the JVM which might, in turn, disrupt normal WebSphere
Application Server functions. Therefore, it is important to understand the full implications if you are
contemplating using this setting.

Cell settings
Use this page to set the discovery protocol and address end point for an existing cell. A cell is a
configuration concept, a way for an administrator to logically associate nodes according to whatever
criteria make sense in the administrator’s organizational environment.

To view this administrative console page, click System Administration > Cell.

Name:

Specifies the name of the existing cell.

Short Name:

Specifies the short name of the cell. The name is 1-8 characters, alphanumeric or national language. It
cannot start with a numeric.

The short name property is read only. It was defined during installation and customization.

Cell Discovery Protocol:

144 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies the protocol that the cell follows to retrieve information from a network.

Select one of these protocol options:

UDP User Datagram Protocol (UDP)
TCP Transmission Control Protocol (TCP)

Default TCP

Deployment managers
Deployment managers are administrative agents that provide a centralized management view for all nodes
in a cell, as well as management of clusters and workload balancing of application servers across one or
several nodes in some editions.

A deployment manager hosts the administrative console. A deployment manager provides a single, central
point of administrative control for all elements of the entire WebSphere Application Server distributed cell.
Each cell contains one deployment manager.

Configuring deployment managers

When you created a deployment manager profile, a deployment manager was created. A deployment
manager provides a single, central point of administrative control for all elements in a WebSphere
Application Server distributed cell. You can run the deployment manager with its default settings. However,
you can follow this task to change the deployment manager configuration settings such as the ports the
process uses, custom services, logging and tracing settings, and so on. To view information about and
manage a deployment manager, use the settings page for a deployment manager.
1. Access the settings page for a deployment manager. Click System Administration > Deployment
Manager from the navigation tree of the administrative console.
2. Configure the deployment manager as desired by clicking on a property such as Custom Services
and specifying settings on the resulting pages.

Running the deployment manager with a non-root user ID

This article describes how to run the deployment manager with a non-root user ID on Linux and UNIX
platforms.

If global security is enabled, the user registry must not be Local OS. Using the Local OS user registry
requires the dmgr process to run as root. If you are attempting to run a deployment manager as root in
WebSphere Application Server Version 6 when you previously used a non-root user ID on Linux and UNIX
platforms in Version 5.x, see ″Migrating a previously non-root configuration to root″ in the information
center.

By default, the Network Deployment product on Linux platforms uses the root user to run the deployment
manager, which is the dmgr process. You can use a non-root user to run the deployment manager. You
might want to change to a non-root user ID for security or administrative reasons.

Perform this task to change the permissions for the deployment manager. Restart the deployment
manager for the changes to take effect.

For the steps that follow, assume that:

v wasadmin is the user to run all servers
v wasgroup is the user group
v dmgr is the deployment manager
v the installation root for Network Deployment is install_nd_root, for example
/opt/IBM/WebSphere/AppServer
v you created a run-time environment with a single profile or multiple profiles

Chapter 3. Setting up the application serving environment 145

To configure a user to run the deployment manager, complete the following steps:
1. Log on to the Network Deployment system as root.
2. Create user wasadmin with primary group wasgroup.
3. Start the deployment manager process as root with the startManager.sh script.
Issue the script command:
network deployment installation root/profiles/deployment manager profile name/bin/

./startManager.sh
4. Start the administrative console.
5. Define the dmgr process to run as a wasadmin process.
Click System Administration > Deployment manager > Server Infrastructure > Java and
Process Management > Process Definition > Additional Properties > Process Execution and
change all of these values:

Property Value
Run As User wasadmin
Run As Group wasgroup
UMASK 022

where the value 022 means the files the process creates
are writable by the group and by others as defined on the
Linux or UNIX platforms

6. Save the configuration.

7. Stop the deployment manager with the stopManager.sh script.
Issue the script command from the network deployment installation root/profiles/profile
name/bin directory:
./stopManager.sh
8. As root, use operating system tools to change file permissions on Linux and UNIX-based platforms.
The following example assumes /opt/IBM/WebSphere/AppServer is the installation root:
chgrp wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name
chgrp wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name
chgrp -R wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name/config
chgrp -R wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name/logs
chgrp -R wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name/wstemp
chgrp -R wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name/installedApps
chgrp -R wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name/temp
chgrp -R wasgroup /opt/IBM/WebSphere/AppServer/profiles/profile name/tranlog
chmod g+wr /opt/IBM/WebSphere
chmod g+wr /opt/IBM/WebSphere/AppServer/profiles/profile name
chmod -R g+wr /opt/IBM/WebSphere/AppServer/profiles/profile name/config
chmod -R g+wr /opt/IBM/WebSphere/AppServer/profiles/profile name/logs
chmod -R g+wr /opt/IBM/WebSphere/AppServer/profiles/profile name/wstemp
chmod -R g+wr /opt/IBM/WebSphere/AppServer/profiles/profile name/installedApps
chmod -R g+wr /opt/IBM/WebSphere/AppServer/profiles/profile name/temp
chmod -R g+wr /opt/IBM/WebSphere/AppServer/profiles/profile name/tranlog
9. Log in as wasadmin on the Network Deployment system.
10. Start the deployment manager process with the startManager.sh script.
Issue the script command:
network deployment installation root/profiles/deployment manager profile name/bin/

./startManager.sh

You can start a deployment manager process from a non-root user.

146 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Deployment manager settings
Use this page to stop the deployment manager from running, and to link to other pages which you can use
to define additional properties for the deployment manager. A deployment manager provides a single,
central point of administrative control for all elements of the entire WebSphere Application Server
distributed cell.

To view this administrative console page, click System Administration > Deployment Manager.

Name:

Specifies a logical name for the deployment manager. The name must be unique within the cell.

Data type String

Short name:

Specifies the short name of the deployment manager server.

The server short name must be unique within a cell. The short name identifies the server to the native
facilities of the operating system, such as Workload Manager (WLM), Automatic Restart Manager, SAF (for
example, RACF), started task control, and others.

The name is 1-8 characters, alpha numeric or national language. It cannot start with a numeric.

The system assigns a cell-unique, default short name.

Data type String

Unique Id:

Specifies the unique ID of this deployment manager server.

The unique ID property is read only. The system automatically generates the value.

Data type String

Process ID:

Specifies a string identifying the process.

Data type String

Default None

Cell Name:

Specifies the name of the cell for the deployment manager. The default is the name of the host computer
on which the deployment manager is installed with Cell## appended, where ## is a two-digit number.

Data type String

Default host_nameCell01

Node Name:

Chapter 3. Setting up the application serving environment 147

Specifies the name of the node for the deployment manager. The default is the name of the host computer
on which the deployment manager is installed with CellManager## appended, where ## is a two-digit
number.

Data type String

Default host_nameCellManager01

State:

Indicates the state of the deployment manager. The state is Started when the deployment manager is
running and Stopped when it is not running.

Data type String

Default Started

Node
A node is a logical grouping of managed servers.

A node usually corresponds to a logical or physical computer system with a distinct IP host address.
Nodes cannot span multiple computers. Node names usually are identical to the host name for the
computer.

Nodes in the network deployment topology can be managed or unmanaged. Two types of managed nodes
exist while one type of unmanaged node exists.

One type of managed node has a node agent which manages all servers on a node, whether the servers
are WebSphere Application Servers, Java Message Service (JMS) servers (on Version 5 nodes only), Web
servers, or generic servers. The node agent represents the node in the management cell. A deployment
manager manages this type of managed node. The other type of managed node has no node agent. This
type of managed node is defined on a standalone Application Server. The deployment manager cannot
manage this standalone Application Server. An standalone Application Server can be federated. When it is
federated, a node agent is automatically created. The node becomes a managed node in the cell. The
deployment manager manages this node.

An unmanaged node does not have a node agent to manage its servers. Unmanaged nodes can have
server definitions such as Web servers in the WebSphere Application Server topology. Unmanaged nodes
can never be federated. That is, a node agent can never be added to an unmanaged node.

A supported Web server can be on a managed node or an unmanaged node. You can define only one
Web server to a standalone WebSphere Application Server node. This Web server is defined on an
unmanaged node. You can define Web servers to the deployment manager. These Web servers can be
defined on managed or unmanaged nodes.

WebSphere Application Server supports basic administrative functions for all supported Web servers. For
example, generation of a plug-in configuration can be performed for all Web servers. However,
propagation of a plug-in configuration to remote Web servers is supported only for IBM HTTP Servers that
are defined on an unmanaged node. If the Web server is defined on a managed node, propagation of the
plug-in configuration is done for all the Web servers by using node synchronization. The Web server
plug-in configuration file is created according to the Web server definition and is created based on the list
of applications that are deployed on the Web server. You can also map all supported Web servers as
potential targets for the modules during application deployment.

148 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebSphere Application Server supports some additional administrative console tasks for IBM HTTP
Servers on managed and unmanaged nodes. For instance, you can start IBM HTTP Servers, stop them,
terminate them, display their log files, and edit their configuration files.

You can add managed and unmanaged nodes to a network deployment cell in one of the following ways:
v Administrative console
v Command line (managed nodes only)
v Administrative script
v Java program

Each of these methods for adding a managed node to a network deployment cell includes the option of
specifying a target node group for the managed node to join. If you do not specify a node group, or you do
not have the option of specifying a node group, the default node group of DefaultNodeGroup is the target
node group.

Whether you specify an explicit node group or accept the default, the node group membership rules must
be satisfied. If the node you are adding does not satisfy the node group membership rules for the target
node group, the add node operation fails with an error message.

Managing nodes
This article describes how to add a node, select the discovery protocol for a node, define a custom
property for a node, stop servers on a node, and remove a node.

A node is a grouping of managed or unmanaged servers. You can add both managed and unmanaged
nodes to the WebSphere Application Server topology. If you add a new node for an existing WebSphere
Application Server to the network deployment cell, you add a managed node. If you create a new node in
the topology for managing Web servers or servers other than WebSphere Application Servers, you add an
unmanaged node.

To view information about nodes and manage nodes, use the Nodes page. To access the Nodes page,
click System Administration > Nodes in the console navigation tree.

You can manage nodes on an application server through the wsadmin scripting tool, through the Java
application programming interfaces (APIs), or through the administrative console. Perform the following
tasks to manage nodes on an application server through the administrative console.
v Add a node.
1. Go to the Nodes page and click Add Node. Choose whether you want to add a managed or
unmanaged node, and click Next.
2. For a managed node, verify that an application server is running on the remote host for the node
that you are adding. On the Add Node page, specify a host name, connector type, and port for the
application server at the node you are adding.
3. For a managed node, do one of the following sets of actions in the table:

If the deployment manager is on And the node that you add to the Complete the appropriate set of
cell is on actions:
The distributed platform The distributed platform Optionally specify a node group and a
core group. Click OK.

Chapter 3. Setting up the application serving environment 149

The distributed platform A z/OS system Specify a node group that contains
nodes from the same sysplex as the
node you are now adding. If no such
node group exists, create a node
group and then specify that node
group. Optionally specify a core
group. Click OK.
A z/OS system The distributed platform Specify a node group that contains
distributed nodes. If no such node
group exists, create a node group
and then specify that node group.
Optionally specify a core group. Click
OK.

For the node group option to display, a group other than the default node group must first be
created. Likewise, for the core group option to display, a group other than the default core group
must first be created.
4. For managed nodes, another administrative console panel is displayed if the node to federate is on
a Windows operating system. Specify on the panel whether you want to register the node agent to
run as a Windows service. If security is enabled, you can optionally enter the local operating system
user name and password under which you will run the service. If you do not specify a user name
and password, the service runs under the local system identity. When you run remove the node, the
node agent is de-registered as a Window service.
5. For an unmanaged node, on the Nodes > New page, specify a node name, a host name, and a
platform for the new node. Click OK.
The node is added to the WebSphere Application Server environment and the name of the node is
displayed in the collection on the Nodes page.
Both Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6) are now supported by
WebSphere Application Server, but restrictions do apply when using both IPv4 and IPv6 in the same
cell. When you add a node to a cell, the format in which you specify the name is based on the version
of IP that the node is using. For details, see IP version considerations for cells.
v Select the discovery protocol.
If the discovery protocol that a node uses is not appropriate for the node, select the appropriate
protocol. On the Nodes page, click the node to access the Settings for the node. Select a value for
Discovery Protocol. By default, a node uses Transmission Control Protocol (TCP). You probably not
need to change a node protocol configuration from TCP. However, if you do need to change the
discovery protocol value, some guidelines are provided:
– For a managed process, use multicast. A managed process supports multicast because by using
multicasting, all application servers in one node can listen to one port instead of to one port for each
server. A benefit of using multicast is that you do not have to configure the discovery port for each
application server or prevent port conflicts. A drawback of using multicast is that you must ensure
that your machine is connected to the network when application servers (not including the node
agent) launch because a multicast address is shared by the network and not by the local machine. If
your machine is not connected to the network when application servers launch, the multicast address
is not shared with the application servers.
– For a node agent or a deployment manager, use TCP or UDP. Do not use multicast.
v Define a custom property for a node.
1. On the Nodes page, click the node for which you want to define a custom property.
2. On the Settings for the node, click Custom Properties.
3. On the Property collection page, click New.
4. On the Settings page for a property instance, specify a name-value pair and a description for the
property, and click OK.
v Synchronize the node configuration.

150 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 If you added a managed node or changed a managed node’s configuration, synchronize the node’s
configuration. On the Node Agents page, ensure that the node agent for the node is running. Then, on
the Nodes page, put a check mark in the check box beside the node whose configuration files you want
to synchronize and click Synchronize or Full Resynchronize.
Clicking either button sends a request to the node agent for that node to perform a configuration
synchronization immediately, instead of waiting for the periodic synchronization to occur. This is
important if automatic configuration synchronization is disabled, or if the synchronization interval is set
to a long time, and a configuration change has been made to the cell repository that needs to be
replicated to that node. Settings for automatic synchronization are on the File Synchronization Service
page.
Synchronize requests that a node synchronization operation be performed using the normal
synchronization optimization algorithm. This operation is fast but might not fix problems from manual file
edits that occur on the node. So it is still possible for the node and cell configuration to be out of
synchronization after this operation is performed.
Full Resynchronize clears all synchronization optimization settings and performs configuration
synchronization anew, so there will be no mismatch between node and cell configuration after this
operation is performed. This operation can take longer than the Synchronize operation.
Unmanaged nodes cannot be synchronized.
v Stop servers on a node.
On the Nodes page, put a check mark in the check box beside the managed node whose servers you
want to stop running and click Stop.
v Remove a node.
On the Nodes page, put a check mark in the check box beside the node you want to delete and click
Remove Node. If you cannot remove the node by clicking Remove Node, remove the node from the
configuration by clicking Force Delete.
v View node capabilities.
Review the node capabilities, such as the product version through the administrative console. You can
also query them through the Application Server application programming interface (API) or the wsadmin
tool .

Node collection
Use this page to manage nodes in the WebSphere Application Server environment. Nodes group managed
servers.

To view this administrative console page, click System Administration > Nodes.

Name:

Specifies a name for a node that is unique within the cell.

A node corresponds to a physical computer system with a distinct IP host address. The node name is
usually the same as the host name for the computer.

Both Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6) are now supported by
WebSphere Application Server, but there are restrictions that apply to using both IPv4 and IPv6 in the
same cell. Note that when you add a node to a cell, the format in which you specify the name is based on
the version of IP the node will be using.

Version:

Specifies the product version of the node.

The product version is the version of a WebSphere Application Server for managed nodes. For
unmanaged nodes, on which you can define Web servers, the version displays as unknown.

Chapter 3. Setting up the application serving environment 151

Discovery protocol:

Specifies the protocol that servers use to discover the presence of other servers on this node.

The possible protocol options follow:

UDP User Datagram Protocol (UDP)
TCP Transmission Control Protocol (TCP)
multicast
IP multicast protocol

Status:

Indicates the state of the node.

The state can beStarted, Stopped, Unavailable, Unknown, Partial Start, Partial Stop, Not applicable,
Synchronized, or Not synchronized.

Node settings:

Use this page to view or change the configuration or topology settings for either a managed node instance
or an unmanaged node instance.

A managed node is a node with an Application Server and a node agent that belongs to a cell. An
unmanaged node is a node defined in the cell topology that does not have a node agent running to
manage the process. Unmanaged nodes are typically used to manage Web servers.

To view this administrative console page, click System Administration > Nodes >node_name.

Name:

Specifies a logical name for the node. The name must be unique within the cell.

A node name usually is identical to the host name for the computer. However, you choose the node name.
You can make the node name some name other than the host name.

Data type String

Both Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6) are now supported by
WebSphere Application Server, but there are restrictions that apply to using both IPv4 and IPv6 in the
same cell. Note that when you add a node to a cell, the format in which you specify the name is based on
the version of IP the node will be using.

Short Name:

Specifies the name of a node. The name is 1-8 characters, alphanumeric or national language. It cannot
start with a numeric.

The short name property is read only. It is defined during installation and customization.

Discovery Protocol:

Specifies the protocol that the node follows to retrieve information from a network. The Discovery protocol
setting is only valid for managed nodes.

Select from one of these protocol options:

UDP User Datagram Protocol (UDP)

152 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
TCP Transmission Control Protocol (TCP)
multicast
IP multicast protocol

Data type String

Default TCP
Range Valid values are UDP, TCP, or multicast.

UDP is faster than TCP, but TCP is more reliable than UDP because UDP does not guarantee delivery of
datagrams to the destination. Between these two protocols, the default of TCP is recommended.

Add managed Windows node:

Use this page to run the node agent as a Windows service.

To view this administrative console page, click System Administration > Nodes > Add node > managed
node > Add managed node .

Run the node agent as a Windows service:

Specifies whether to run a node agent as a Windows service.

Default false (cleared)

User name:

Specifies the ID for running the service process for the node agent. The user name and password fields
are only available if security is enabled. If you do not specify the user name, the node agent runs under
the authority of the local system. User name requirements are the requirements that the Windows
operating system imposes for a user ID.

Password:

Specifies the password for the user name that you supply. Password requirements are the requirements
that the Windows operating system imposes for a password.

Confirm password:

Specifies the same password that you typed for Password so that you can verify the correct password.

Add managed nodes

A managed node is a node with an Application Server and a node agent that belongs to a cell. Use this
page to add a managed node to a cell.

To view this administrative console page, click System Administration > Nodes > Add node > Next .

Node connection: Specifies connection information for WebSphere Application Server.

v Host
Specifies the host name or IP address of the node to add to the cell. A WebSphere Application Server
instance must be running on this machine.

Date type String

Default None

v JMX connector type

Chapter 3. Setting up the application serving environment 153

 Specifies the Java Management Extensions (JMX) connectors that communicate with the WebSphere
Application Server when you invoke a scripting process.
Select from one of these JMX connector types:

Simple Object Access Protocol (SOAP)

Use when the Application Server connects to a SOAP server.

Remote Method Invocation (RMI)

Use when the Application Server connects to an RMI server.

v JMX connector port

Specifies the port number of the JMX connector on the instance to add to the cell. The default SOAP
connector port is 8880.

Date type Integer

Default 8880

Options: Select from the following settings to further specify characteristics when adding a managed
node to a cell.
v Include Applications
Copies the applications installed on the remote instance into a cell. If the applications to copy have the
same name as the applications that currently exist in the cell, the Application Server does not copy the
applications.
v Include buses
Specifies whether to move the bus configuration at the node to the deployment manager.
v Starting port
Specifies the port numbers for the node agent process.

Use default Specifies whether to use the default node agent port
numbers.
Specify Allows you to specify the starting port number in the Port
number field. WebSphere Application Server
administration assigns the port numbers in order from the
starting port number. For example, if you specify 9950, the
administration program configures the node agent ports as
9950, 9951, 9952, and so on.

v Core Group
Specifies the group to which you can add a cluster or node agent. By default, clusters or node agents
are added to the DefaultCoreGroup group.
Select from one of the core groups if a list is displayed. The list displays if a core group in addition to
the default core group exists.
v Node group
Specifies the group to which you can add the node. By default, nodes are added to the
DefaultNodeGroup group.
Select from one of the node groups if a list is displayed. The list displays if a node group in addition to
the default node group exists.

Node installation properties

Use this page to view read-only installation properties for this node. These properties provide information
about the capabilities of the node that are collected during product installation time, such as the operating
system name, architecture and version, or WebSphere Application Server product levels that are installed
on the node.

154 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this administrative console page, click System Administration > Nodes > node name > Node
installation properties.

Information about a node, such as operating system platform and product features, is maintained in the
configuration repository in the form of properties. As product features are installed on a node, new property
settings are added.

WebSphere Application Server system management uses the managed object metadata properties as
follows:
v To display the node version in the administrative console
v To ensure that new configuration types or attributes are not created or set on older release nodes
v To ensure that new resource types are not created on old release notes
v To ensure that new applications are not installed on old release nodes because the old run time cannot
support the new applications

For detailed information about the following properties, see the Application Server application programming
interface (API).

com.ibm.websphere.baseProductVersion:

The version of WebSphere Application Server that is installed.

com.ibm.websphere.nodeOperatingSystem:

The operating system platform on which the node runs.

com.ibm.websphere.nodeSysplexName:

The sysplex name on a z/OS operating system.

com.ibm.websphere.deployed.features:

A list of features that extends a profile. An example of a feature is an administrative console plug-in.

Node group
A node group is a collection of managed nodes. Managed nodes are WebSphere Application Server
nodes. A node group defines a boundary for server cluster formation.

Nodes that you organize into a node group should be enough alike in terms of installed software, available
resources, and configuration to enable servers on those nodes to host the same applications as part of a
server cluster. The deployment manager does no validation to guarantee that nodes in a given node group
have anything in common.

Node groups are optional and are established at the discretion of the WebSphere Application Server
administrator. However, a node must be a member of a node group. Initially, all Application Server nodes
are members of the default node group named DefaultNodeGroup.

A node can be a member of more than one node group.

On the z/OS platform, an Application Server node must be a member of a sysplex node group. Nodes in
the same sysplex must be in the same sysplex node group. A node can be in one sysplex node group
only.

A node on a distributed platform and a node on a z/OS platform cannot be members of the same node
group.

Chapter 3. Setting up the application serving environment 155

To delete a node group, the node group must be empty. The default node group cannot be deleted.

Node group membership rules

Nodes can be members of node groups if they meet certain requirements.

Node group membership must adhere to the following rules:

v A node in a node group must be a managed node.
v A managed node must be a member of at least one node group. If the node is on the z/OS platform,
the node group must be a sysplex node group.
v Nodes on a distributed platform and nodes on the z/OS platform must be members of different node
groups.
v Nodes on the z/OS platform that are in different sysplexes must be members of different groups.

Examples: Using node groups

Use node groups to define groups of nodes capable of hosting members of the same cluster. An
application deployed to a cluster must be capable of running on any of the cluster members. This means
that the node that hosts each of the cluster members must be configured with software and settings
necessary to support running of the application.

By organizing nodes that satisfy your application requirements into a node group, you establish an
administrative policy that governs which nodes can be used together to form a cluster. The people who
define the cell configuration and the people who create server clusters can operate with greater
independence from one another, if they are different people.

Example 1

Assume the following information:

v A cell is comprised of nodes 1 to 8.
v Each node is a managed node, which means that each node is configured with an Application Server.
v Nodes 6, 7, and 8 are additionally configured as WebSphere Business Integration Server Foundation
nodes.
v All nodes are either z/OS system nodes from the same sysplex, or distributed platform nodes.
v By default, all the nodes are in the default node group, DefaultNodeGroup.

Applications that exploit WebSphere Business Integration Server Foundation functions can run
successfully only on nodes 6, 7, and 8. Therefore, clusters that host these applications can be formed only
on nodes 6, 7, and 8. To define a clustering policy that guides users of your WebSphere cell into building
clusters that can only span predetermined nodes, create an additional node group called WBINodeGroup,
for example. Add to the node group nodes 6, 7, and 8. If you create a cluster on a node from the
WBINodeGroup node group, the system allows only nodes from the WBINodeGroup node group to be
members of the cluster.

Example 2

Assume the following information:

v A cell is comprised of nodes 1 to 6.
v Each node is a managed node, which means that each node is configured with an Application Server.
v Nodes 1 to 4 are on distributed platforms.
v Nodes 5 and 6 are nodes on the z/OS operating system and are in sysplex PLEX1.
v The deployment manager is on a distributed platform node.
v Nodes 1 to 4 are members of the DefaultNodeGroup node group by default.

156 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v You created empty node group PLEX1NodeGroup to group the z/OS operating system nodes on the
PLEX1 sysplex.
v You joined the nodes on the z/OS operating system to the PLEX1NodeGroup node group when you
added them to the cell. You did this because nodes on the z/OS operating system cannot be in the
same node group as the distributed platform nodes.

Applications that exploit z/OS functions in the PLEX1 sysplex can run successfully only on nodes 5 and 6.
Therefore, clusters that host these applications can be formed only on nodes 5 and 6. The required
separation of distributed platform nodes from z/OS system nodes establishes a natural clustering policy
that guides users of your Application Server cell into building clusters that can only span predetermined
nodes. If you create a cluster on a node from the PLEX1NodeGroup node group, the system allows only
nodes from the PLEX1NodeGroup node group to be members of the cluster.

Managing node groups

Read about Nodes groups if you are unfamiliar with them.

Your WebSphere Application Server environment has a default node group. However, if you need
additional node groups to manage your Application Server environment, you can create and configure
additional node groups.
v View and configure node groups.
1. Click System Administration > Node groups in the console navigation tree.
2. To view additional information about a particular node group or to further configure a node group,
click on the node group name under Name.
v Create a node group.
1. Click System Administration > Node groups in the console navigation tree.
2. Click New.
3. Specify the node group name and description.
The node group is added to the WebSphere Application Server environment . The name of the node
group appears in the name column of the Node group page.

You can now add nodes to the node group.

Node group collection

Use this page to manage node groups. A node group is a collection of WebSphere Application Server
nodes. A node group defines a boundary for server cluster formation.

Nodes that are organized into a node group should be enough alike in terms of installed software,
available resources, and configuration to enable servers on those nodes to host the same applications as
part of a server cluster. The deployment manager does no validation to guarantee that nodes in a given
node group have anything in common.

Node groups are optional and are established at the discretion of the WebSphere administrator. However,
a node must be a member of a node group. Initially, all Application Server nodes are members of the
default node group. The default node group is DefaultNodeGroup.

A node can be a member of more than one node group.

On the z/OS platform, an Application Server node must be a member of a sysplex node group. Nodes in
the same sysplex must be in the same sysplex node group. A node can only be in one sysplex node
group. Sysplex node groups are special node groups that the system manages.

Chapter 3. Setting up the application serving environment 157

A node on a distributed platform and a node on a z/OS platform cannot be members of the same node
group.

To delete a node group, the node group must be empty. The default node group cannot be deleted.

To view this administrative console page, click System Administration > Node groups.

Name:

Specifies a name for a node group that is unique within the cell.

Members:

Specifies the number of members or nodes in the node group.

Description:

Specifies a description that you define for the node group.

Node group settings:

Use this page to view or change the configuration or topology settings for a node group instance.

To view this administrative console page, click System Administration > Node groups >node group
name.

Name:

Specifies a logical name for the node group. The name must be unique within the cell.

Data type String

Maximum length 64 characters

The name must contain alphanumeric or national language characters and cannot start with a number.

Short name:

Specifies the name of a node. The name must contain 1-8 characters, which are either alphanumeric or
national language. It cannot start with a number.

On the z/OS system the short name property is:

v Read-only
v Used only by sysplex node groups
v Defined during installation and customization

Sysplex:

Specifies the name of a node. The name is eight characters, alphanumeric or national language. It cannot
start with a numeric. It is used only by sysplex node groups on the z/OS platform. It is defined during
installation and customization on z/OS platforms only.

The Sysplex property is read only.

Members:

158 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies the number of nodes within the node group.

Data type Integer

Description:

Specifies the description that you define for the node group. The description has no specific maximum
length.

Managing node group members

Read about Nodes groups and Node group membership rules if you are unfamiliar with them.

Group nodes that meet your application requirements into a node group.
v View node groups members.
1. Click System Administration > Node groups > node group name > Nodes > Node group
members in the console navigation tree.
2. To view additional information about a particular node group member for this node group, click on
the node group member name under Name.
v Add a node to a node group.
1. Click System Administration > Node groups > node group name > Nodes > Node group
members in the console navigation tree.
2. Click Add.
3. Select the node from a list. The node group member name is the node name.
The node group member is added to the node group specified on the bread crumb trail. The name of
the node group member appears in the name column of the Node group member page. You can add
additional nodes of similar characteristics to the node group by repeating the steps for adding a node to
a node group.
If the node you add does not satisfy the node group membership rules for the target node group, the
add node operation fails with an error message.
v Remove a node from a node group.
1. Click System Administration > Node groups > node group name > Nodes > Node group
members in the console navigation tree.
2. Select the box next to each node group member that you want to remove from the node group.
3. Click Remove.
Each node group member that you selected is removed from the node group specified on the bread
crumb trail.

Node group member collection

Use this page to manage node groups members. A node group member is a WebSphere Application
Server node.

Click Add to add node members to the node group. Click Remove to remove node members from the
node group.

To view this administrative console page, click System Administration > Node groups > node group
name > nodes > Node group members.

Name:

Specifies the name of a node group member.

Chapter 3. Setting up the application serving environment 159

Description:

Specifies a description that you previously defined for the node group member when you created the node
group member.

Node group member settings:

Use this page to view or change the configuration or topology settings for a node group member.

To view this administrative console page, click System Administration > Node groups > node group
name > nodes > Node group members > node group member name.

Name:

Specifies a logical name for the node group member. A node group member is a node. The name must be
unique within the cell.

A node group member name usually is identical to the host name for the computer.

Data type String

Maximum length 64 characters

The name must contain alphanumeric or national language characters and cannot start with a number.

Administration service settings

Use this page to view and change the configuration for an administration service.

To view this administrative console page, click Servers > Application Servers >server_name >
Administration > Administration Services

Standalone
Specifies whether the server process is a participant in a Network Deployment cell or not. If the box is
checked (true), the server does not participate in distributed administration. If the box is unchecked (false),
the server participates in the Network Deployment system.

The default value for base WebSphere Application Server installations is true. When addNode runs to
incorporate the server into a Network Deployment cell, the value switches to false.

Data type Boolean

Default true

Preferred Connector
Specifies the preferred JMX Connector type. Available options, such as SOAPConnector or RMIConnector,
are defined using the JMX Connectors page.

Data type String

Default SOAP

Extension MBean Providers collection

Use this page to view and change the configuration for JMX extension MBean providers.

You can configure JMX extension MBean providers to be used to extend the existing WebSphere
managed resources in the core administrative system. Each MBean provider is a library containing an
implementation of a JMX MBean and its MBean XML Descriptor file.

160 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this administrative console page, click Servers > Application Servers >server_name >
Administration > Administration Services > Extension MBean Providers
Name The name used to identify the Extension MBean provider library.
Description
An arbitrary descriptive text for the Extension MBean Provider configuration.
Classpath
The path to the Java archive (JAR) file that contains the Extension MBean provider library. This
class path is automatically added to the Application Server class path.

Extension MBean Provider settings:

Use this page to view and change the configuration for a JMX extension MBean provider.

You can configure a library containing an implementation of a JMX MBean, and its MBean XML Descriptor
file, to be used to extend the existing WebSphere managed resources in the core administrative system

To view this administrative console page, click Servers > Application Servers >server_name >
Administration > Administration Services > Extension MBean Providers >provider_library_name

Classpath: The path to the Java archive (JAR) file that contains the Extension MBean provider library.
This class path is automatically added to the Application Server class path. The class loader needs this
information to load and parse the Extension MBean XML Descriptor file.

Description: An arbitrary descriptive text for the Extension MBean Provider configuration. Use this field for
any text that helps identify or differentiate the provider configuration.

Name: The name used to identify the Extension MBean provider library.

Extension MBean collection

You can configure Java Management Extension (JMX) MBeans to extend the existing WebSphere
Application Server managed resources in the administrative console. Use this page to register JMX
MBeans. Any MBeans that are listed have already been registered.

To view this administrative console page, click Servers > Application Servers >server name >
Administration > Administration Services > Extension MBean Providers > provider library name>
Extension MBean
DescriptorURI
Specifies the location, relative to the provider class path, where the MBean XML descriptor file is
located.
Type Specifies the type to use for registering this MBean. The type must match the type that is declared
in the MBean descriptor file.

Extension MBean settings:

Use this page to view and configure Java Management Extension (JMX) MBeans.

To view this administrative console page, click Servers > Application Servers >server name>
Administration > Administration Services > Extension MBean Providers > provider library name>
Extension MBean >Extension MBean name

descriptorURI: Specifies the location, relative to the provider class path, where the MBean XML
descriptor file is located.

type: Specifies the type to use for registering this MBean. The type must match the type that is declared
in the MBean descriptor file.

Chapter 3. Setting up the application serving environment 161

Java Management Extensions connector properties
A Java Management Extensions (JMX) connector can either be a Remote Method Invocation (RMI)
connector or a Simple Object Access Protocol (SOAP) connector.

Depending on the property, you can specify or set a property in the administrative console, the wsadmin
tool, Application Server commands, scripts run from a command line interface, or a custom Java
administrative client program that you write. You can also set SOAP connector properties in the
soap.client.props file.

For specific information on how to code the JMX connector properties for the wsadmin tool, the Application
Server commands, or scripts, see the particular tool or command. For specific information on how to code
the JMX connector properties for a custom Java administrative client program, see the ″Java API
documentation for Application Server″ topic in the Information Center.

For the administrative console, this article specifies the coding of the particular setting or property. Coding
of properties in the soap.client.props file that are specific to JMX connectors is specified. These
properties begin with com.ibm.SOAP. Other properties in the soap.client.props file that contain
information that can be set elsewhere in the Application Server are not documented here. The coding for
the com.ibm.ssl.contextProvider property, which can be set only in the soap.client.props file, is specified.

Each profile has a property file at installation root/profiles/profile

name/properties/soap.client.props. These property files allow you to set different properties, including
security and timeout properties. These properties are the default for all administrative connections that use
the SOAP JMX connector between processes executing in a particular profile. For instance, the wsadmin
program executing under a particular profile uses the property values from that file for the SOAP connector
behavior unless the properties are overridden by some other programmatic means.

To view the JMX connector custom properties administrative console panel that goes with this article, click
one of the following paths:
v Servers -> Application servers ->server name -> Server Infrastructure -> Administration ->
Administration Services -> Additional properties -> JMX Connectors->connector type -> Additional
Properties -> Custom properties
v System administration -> Deployment manager ->Additional Properties -> Administration
Services -> Additional Properties -> JMX Connectors->connector type-> Additional Properties ->
Custom properties
v System administration -> Node agents ->node agent name -> Additional Properties ->
Administration Services -> Additional Properties -> JMX Connectors->connector type-> Additional
Properties -> Custom properties

SOAP connector properties

This section discusses JMX connector properties that pertain to SOAP connectors.

SOAP Request timeout

Specifies the SOAP client request timeout. The value that you choose depends on a number of factors
such as the size and the number of the applications that are installed on the server, the speed of your
machine, and the level of usage of your machine.

The program default value for the request timeout is 600 seconds. However, other components that
connect to the SOAP client can override the default. Components that use the soap.client.props file have
a default value of 180 seconds.

You can set the property by using one of the following options:
v Scripts run from a command line interface.

162 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v The soap.client.props file.

Property com.ibm.SOAP.requestTimeout
Data type Integer
Range in seconds 0 to n

If the property is zero (0), the request never times out.

Default 180

v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property requestTimeout
Data type Integer
Range in seconds 0 to n

If the property is zero (0), the request never times out.

Default 600

v A Java administrative client. The property is AdminClient.CONNECTOR_SOAP_REQUEST_TIMEOUT.

Configuration URL

Specifies the Universal Resource Locator (URL) of the soap.client.props file. Specify the configuration
URL property if you want a program to read SOAP properties from this file. You can set the property by
using one of the following options:
v Scripts run from a command line interface. Scripts can pass the Configuration URL property to the
Application Server on the com.ibm.SOAP.ConfigURL system property.
v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property ConfigURL
Data type String
Valid Value http://Path/soap.client.props
Default None

v A Java administrative client. The property is AdminClient.CONNECTOR_SOAP_CONFIG.

Security context provider

Specifies the Secure Sockets Layer (SSL) implementation to use between the Application Server and the
SOAP client. You can specify either IBM Java Secure Sockets Extension (IBMJSSE) or IBM Java Secure
Sockets Extension that has undergone Federal Information Processing Standards certification
(IBMJSSEFIPS).

You can set the property by using the soap.client.props file.

Property com.ibm.ssl.contextProvider
Data type String
Valid Values IBMJSSE
IBMJSSEFIPS
IBMJSSE2
Default IBMJSSE2

Secure Sockets Layer (SSL) security

Chapter 3. Setting up the application serving environment 163

Use this property to enable SSL security between Application Server and the SOAP client. You can set the
property by using one of the following options:
v Scripts run from a command line interface.
v The soap.client.props file.

Property com.ibm.SOAP.securityEnabled
Data type Boolean
Default False

v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property securityEnabled
Data type Boolean
Default False

v A Java administrative client. The property is AdminClient.CONNECTOR_SECURITY_ENABLED.

SOAP and RMI connector properties

This section discusses JMX connector properties that pertain to both SOAP connectors and RMI
connectors.

Connector type

Specify a connector type of SOAP or RMI, depending on whether Application Server connects to a SOAP
server or an RMI server. You can set the property by using one of the following options:
v The wsadmin tool.
v Scripts run from a command line interface.
v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property Type
Data type String
Valid values SOAPConnector
RMIConnector
Default SOAP

v A Java administrative client. The property is AdminClient.CONNECTOR_TYPE. Specify by using the

AdminClient.CONNECTOR_TYPE_RMI or the AdminClient.CONNECTOR_TYPE_SOAP constants.

Host

Use the host property to specify the host name or the IP address of the server to which Application Server
connects. The server can be a SOAP server or an RMI server. You can set the property by using one of
the following options:
v The wsadmin tool.
v Scripts run from a command line interface.
v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property host
Data type String
Valid values Host name or IP address
Default None

164 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v A Java administrative client. The property is AdminClient.CONNECTOR_HOST.

Port

Use the port property to specify the port number of the server to which Application Server connects. The
server can be a SOAP server or an RMI server. You can set the property by using one of the following
options:
v The wsadmin tool.
v Scripts run from a command line interface.
v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property port
Data type Integer
Valid value Port number
Default None

v A Java administrative client. The property is AdminClient.CONNECTOR_PORT.

User name

Specifies the user name that Application Server uses to access the SOAP server or the RMI server. You
can set the property by using one of the following options:
v The wsadmin tool.
v Scripts run from a command line interface.
v The soap.client.props file.

Property com.ibm.SOAP.loginUserid
Data type String
Valid value The value must match the global SSL settings for SOAP
or RMI.
Default None

v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property username
Data type String
Valid value The value must match the global SSL settings for SOAP
or RMI.
Default None

v A Java administrative client. The property is AdminClient.USERNAME.

Password

Specifies the password that Application Server uses to access the SOAP server or the RMI server. You
can set the property by using one of the following options:
v The wsadmin tool.
v Scripts run from a command line interface.
v The soap.client.props file.

Property com.ibm.SOAP.loginPassword

Chapter 3. Setting up the application serving environment 165

Data type String
Valid values The value must match the global SSL settings for SOAP
or RMI.
Default None

v The administrative console. Specify the property and the value as a name-value pair on the JMX
connector custom properties panel of the administrative console.

Property password
Data type String
Valid values The value must match the global SSL settings for SOAP
or RMI.
Default None

v A Java administrative client. The property is AdminClient.PASSWORD.

Java Management Extensions connectors

Use this page to view and change the configuration for Java Management Extensions (JMX) connectors.

To view this administrative console page, click one of the following paths:
v Servers > Application Servers >server_name > Administration > Administration Services > JMX
Connectors
v Servers > JMS Servers >server_name > Administration > Administration Services > JMX
Connectors

Java Management Extensions (JMX) connectors communicate with WebSphere Application Server when
you invoke a scripting process. There is no default for the type and parameters of a connector. The
wsadmin.properties file specifies the Simple Object Access Protocol (SOAP) connector and an appropriate
port number. You can also use the Remote Method Invocation (RMI) connector.

Use one of the following methods to select the connector type and attributes:
v Specify properties in a properties file.
v Indicate options on the command line.

Type:

Specifies the type of the JMX connector.

Data type Enum

Default SOAPConnector
Range SOAPConnector
For JMX connections using Simple Object Access
Protocol (SOAP).
RMIConnector
For JMX connections using Remote Method
Invocation (RMI).

JMX connector settings:

Use this page to view the configuration for a Java Management Extensions (JMX) connector.

To view this administrative console page, click one of the following paths:
v Servers > Application Servers >server_name > Administration > Administration Services > JMX
Connectors >connector_type
v Servers > JMS Servers >server_name > Administration > Administration Services > JMX
Connectors >connector_type

166 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Type:

Specifies the type of the JMX connector.

Data type Enum

Default SOAPConnector
Range SOAPConnector
For JMX connections using Simple Object Access
Protocol (SOAP).
RMIConnector
For JMX connections using Remote Method
Invocation (RMI).

Repository service settings

Use this page to view and change the configuration for an administrative service repository.

To view this administrative console page, click Servers > Application Servers >server_name >
Administration Services > Repository Service.

Audit Enabled:

Specifies whether to audit repository updates in the log file. The default is to audit repository updates.

Data type Boolean

Default true

Node agents
Node agents are administrative agents that route administrative requests to servers.

A node agent is a server that runs on every host computer system that participates in the WebSphere
Application Server Network Deployment product. It is purely an administrative agent and is not involved in
application serving functions. A node agent also hosts other important administrative functions such as file
transfer services, configuration synchronization, and performance monitoring.

Managing node agents

Node agents are administrative agents that represent a node to your system and manage the servers on
that node. Node agents monitor application servers on a host system and route administrative requests to
servers. A node agent is created automatically when a node is added to a cell.
1. View information about a node agent. Use the Node Agents page. Click System Administration >
Node Agents in the console navigation tree. To view additional information about a particular node
agent or to further configure a node agent, click on the node agent’s name under Name.

Note: Both Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6) are now
supported by WebSphere Application Server, but there are restrictions that apply to using both
IPv4 and IPv6 in the same cell. Note that when a node is added to a cell, the format in which
the name is specified is based on the version of IP the node will be using. For details, see “IP
version considerations for cells” on page 140.
2. Stop and then restart the processing of a node agent. On the Node Agents page, place a check mark
in the check box beside the node agent you want to restart, then click Restart. It is important to keep
a node agent running because a node agent must be running in order for application servers on the
node managed by the node agent to run.

Chapter 3. Setting up the application serving environment 167

3. Stop and then restart all application servers on the node managed by the node agent. On the Node
Agents page, place a check mark in the check box beside the node agent that manages the node
whose servers you want to restart, then click Restart all Servers on Node.
Note that the node agent for the node must be processing (step 2) in order to restart application
servers on the node.
4. Stop the processing of a node agent. On the Node Agents page, place a check mark in the check box
beside the node agent you want to stop processing, then click Stop.

Node agent collection

Use this page to view information about node agents. Node agents are administrative agents that monitor
application servers on a host system and route administrative requests to servers. A node agent is the
running server that represents a node in a Network Deployment environment.

To view this administrative console page, click System Administration > Node Agents .

Name:

Specifies a logical name for the node agent server.

Node:

Specifies a name for the node. The node name is unique within the cell.

A node name usually is identical to the host name for the computer. That is, a node usually corresponds to
a physical computer system with a distinct IP host address.

However, the node name is a purely logical name for a group of servers. You can name the node anything
you please. The node name does not have to be the host name.

Both Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6) are now supported by
WebSphere Application Server, but there are restrictions that apply to using both IPv4 and IPv6 in the
same cell. Note that when a node is added to a cell, the format in which the name is specified is based on
the version of IP the node will be using.

Version:

Specifies the product version of the node.

The product version is the version of a WebSphere Application Server node agent and Application Servers
that run on the node.

Status:

Indicates whether the node agent server is started or stopped.

Note that if the status of servers such application servers is Unavailable, the node agent is not running in
the servers’ node and you must restart the node agent before you can start the servers.

Node agent server settings:

Use this page to view information about and configure a node agent. A node agent coordinates
administrative requests and event notifications among servers on a machine. A node agent is the running
server that represents a node in a Network Deployment environment.

To view this administrative console page, click System Administraton > Node Agents
>node_agent_name.

168 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
A node agent must be started on each node in order for the deployment manager node to be able to
collect and control servers configured on that node. If you use configuration synchronization support, a
node agent coordinates with the deployment manager server to synchronize the node’s configuration data
with the master copy managed by the deployment manager.

You must initially start a node agent outside the administrative console. For information on how to initially
start a node agent, see the WebSphere Application Server Information Center.

The Runtime tab displays only when a node agent runs.

Name:

Specifies a logical name for the node agent server.

Data type String

Default NodeAgent Server

Short name:

Specifies the short name of the node agent server.

The name is 1-8 characters, alpha-numeric or national language. It cannot start with a numeric.

The system assigns a cell-unique, default short name.

Unique Id:

Specifies the unique ID of this node agent server.

The unique ID property is read only. The system automatically generates the value.

Process ID:

Specifies a string identifying the process.

Data type String

Cell Name:

Specifies the name of the cell for the node agent server.

Data type String

Default host_nameNetwork

Node Name:

Specifies the name of the node for the node agent server.

Both Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6) are now supported by
WebSphere Application Server, but there are restrictions that apply to using both IPv4 and IPv6 in the
same cell. Note that when a node is added to a cell, the format in which the name is specified is based on
the version of IP the node will be using.

Data type String

Chapter 3. Setting up the application serving environment 169

State:

Indicates whether the node agent server is started or stopped.

Data type String

Default Started

Remote file services

Configuration documents describe the available application servers, their configurations, and their
contents. Two file services manage configuration documents: the file transfer service and the file
synchronization service.

The file services do the following:

File transfer service
The file transfer service enables the moving of files between the network manager and the nodes.
It uses the HTTP protocol to transfer files. When you enable security in the WebSphere
Application Server product, the file transfer service uses certificate-based mutual authentication.
You can use the default key files in a test environment. Ensure that you change the default key file
to secure your system.
The ports used for file transfer are defined in the Network Deployment server configuration under
its WebContainer HTTP transports.
File synchronization service
The file synchronization service ensures that a file set on each node matches that on the
deployment manager node. This service promotes consistent configuration data across a cell. You
can adjust several configuration settings to control file synchronization on individual nodes and
throughout a system.
This service runs in the deployment manager and node agents, and ensures that configuration
changes made to the cell repository are propagated to the appropriate node repositories. The cell
repository is the master repository, and configuration changes made to node repositories are not
propagated up to the cell. During a synchronization operation a node agent checks with the
deployment manager to see if any configuration documents that apply to the node have been
updated. New or updated documents are copied to the node repository, and deleted documents
are removed from the node repository.
The default behavior, which is enabled, is for each node agent to periodically run a
synchronization operation. You can configure the interval between operations or disable the
periodic behavior. You can also configure the synchronization service to synchronize a node
repository before starting a server on the node.

Configuring remote file services

Configuration data for the WebSphere Application Server product resides in files. Two services help you
reconfigure and otherwise manage these files: the file transfer service and file synchronization service.

By default, the file transfer service is always configured and enabled at a node agent, so you do not need
to take additional steps to configure this service. However, you might need to configure the file
synchronization service.
1. Go to the File Synchronization Service page. Click System Administration > Node Agents in the
console navigation tree. Then, click the node agent for which you want to configure a synchronization
server and click File Synchronization Service.
2. On the File Synchronization Service page, customize the service that helps make configuration data
consistent across a cell by moving updated configuration files from the deployment manager to the
node. Change the values for properties on the File Synchronization Service page. The file
synchronization service is always started, but you can control how it runs by changing the values.
170 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
File transfer service settings
Use this page to configure the service that transfers files from the deployment manager to individual
remote nodes.

To view this administrative console page, click System Administration > Node Agents
>node_agent_name > File Transfer Service.

Enable service at server startup:

Specifies whether the server attempts to start the specified service. Some services are always enabled
and disregard this property if set. This setting is enabled by default.

Data type Boolean

Default true

Retries count:

Specifies the number of times you want the file transfer service to retry sending or receiving a file after a
communication failure occurs.

Data type Integer

Default 3

If the retries count setting is blank, the file transfer service

sets the default to 3. If the retries count setting is 0, the
file transfer service does not retry. The default is the
recommended value.

Retry wait time:

Specifies the number of seconds that the file transfer service waits before it retries a failed file transfer.

Data type Integer

Default 10

If the retry wait time setting is blank, the code sets the
default to 10. If the retry wait time setting is 0, the file
transfer service does not wait between retries. The default
is the recommended value.

File synchronization service settings

Use this page to specify that a file set on one node matches that on the central deployment manager node
and to ensure consistent configuration data across a cell.

You can synchronize files on individual nodes or throughout your system.

To view this administrative console page, click System Administration > Node Agents
>node_agent_name > File Synchronization Service.

Enable service at server startup:

Specifies whether the server attempts to start the file synchronization service. This setting does not cause
a file synchronization operation to start. This setting is enabled by default.

Data type Boolean

Default true

Chapter 3. Setting up the application serving environment 171

Synchronization Interval:

Specifies the number of minutes that elapse between synchronizations. The default is 1 minute. Increase
the time interval to synchronize files less often.

Data type Integer

Units Minutes
Default 1

The minimum value that the application server uses is 1. If

you specify a value of 0, the application server ignores the
value and uses the default of 1.

Automatic Synchronization:

Specifies whether to synchronize files automatically after a designated interval. When this setting is
enabled, the node agent automatically contacts the deployment manager every synchronization interval to
attempt to synchronize the node’s configuration repository with the master repository owned by the
deployment manager.

If the Automatic synchronization setting is enabled, the node agent attempts file synchronization when it
establishes contact with the deployment manager. The node agent waits the synchronization interval
before it attempts the next synchronization.

Remove the check mark from the check box if you want to control when files are sent to the node.

Data type Boolean

Default true

Startup Synchronization:

Specifies whether the node agent attempts to synchronize the node configuration with the latest
configurations in the master repository prior to starting an application server.

The default is to not synchronize files prior to starting an application server. Enabling the setting ensures
that the node agent has the latest configuration but increases the amount of time it takes to start the
application server.

Note that this setting has no effect on the startServer command. The startServer command launches a
server directly and does not use the node agent.

Data type Boolean

Default false

Exclusions:

Specifies files or patterns that should not be part of the synchronization of configuration data. Files in this
list are not copied from the master configuration repository to the node, and are not deleted from the
repository at the node.

The default is to have no files specified.

172 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
iSeries users: The default is */plugin-cfg.xml, which excludes the Web Server plug-in configuration file
from synchronization.

To specify a file, use a complete name or a name with a leading or trailing asterisk (*) for a wildcard. For
example:

cells/cell name/nodes/node name/file name Excludes this specific file

*/file name Excludes files named file name in any context
dirname/* Excludes the subtree under dirname

Press Enter at the end of each entry. Each file name appears on a separate line.

Since these strings represent logical document locations and not actual file paths, only forward slashes are
needed no matter the platform.

Changes to the exclusion list are picked up when the node agent is restarted.

Data type String

Units File names or patterns

Administrative agents: Resources for learning

Use the following links to find relevant supplemental information about WebSphere Application Server
administrative agents and distributed administration. The information resides on IBM and non-IBM Internet
sites, whose sponsors control the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

View links to additional information:

Administration
v IBM WebSphere Application Server Redbooks at http://publib-
b.boulder.ibm.com/Redbooks.nsf/portals/WebSphere.
This site contains a listing of all WebSphere Application Server Redbooks.
v IBM developerWorks WebSphere at http://www.software.ibm.com/wsdd/.
This site is the home of technical information for developers working with WebSphere products. You can
download WebSphere software, take a fast path to developerWorks zones, such as VisualAge Java or
WebSphere Application Server, learn about WebSphere products through a newcomers page, tutorials,
technology previews, training, and Redbooks, get answers to questions about WebSphere products, and
join the WebSphere community, where you can keep up with the latest developments and technical
papers.
v WebSphere Application Server Support page at
http://www.ibm.com/software/webservers/appserv/support.html.
Take advantage of the Web-based Support and Service resources from IBM to quickly find answers to
your technical questions. You can easily access this extensive Web-based support through the IBM
Software Support portal and search by product category, or by product name. For example, if you are
experiencing problems specific to WebSphere Application Server, click WebSphere Application Server
in the product list. The WebSphere Application Server Support page appears.

Chapter 3. Setting up the application serving environment 173

Configuring the environment
To assist in handling requests among Web applications, Web containers, and application servers, you can
configure cell-widesettings for virtual hosts, variables and shared libraries.
1. Configure virtual hosts.
2. Configure variables.
3. If your deployed applications use shared library files, define the shared library files needed.
See “Managing shared libraries” on page 184.

Virtual hosts
A virtual host is a configuration that enables a single host machine to resemble multiple host machines.
Resources associated with one virtual host cannot share data with resources associated with another
virtual host, even if the virtual hosts share the same physical machine.

Each virtual host has a logical name and a list of one or more DNS aliases by which it is known. A DNS
alias is the TCP/IP hostname and port number that is used to request the servlet, for example
yourHostName:80. When no port number is specified, 80 is assumed.

When a servlet request is made, the server name and port number entered into the browser are compared
to a list of all known aliases in an effort to locate the correct virtual host and serve the servlet. If no match
is found, an error is returned to the browser.

An application server provides a default virtual host with some common aliases, such as the machine’s IP
address, short host name, and fully qualified host name. The alias comprises the first part of the path for
accessing a resource such as a servlet. For example, it is localhost:80 in the request
http://localhost:80/myServlet.

A virtual host is not associated with a particular node (machine). It is a configuration, rather than a ″live
object,″ explaining why you can create it, but cannot start or stop it. For many users, creating virtual hosts
is unnecessary because the default_host is provided.

Adding a localhost to the virtual hosts adds the host name and IP address of the localhost machine to the
alias table. This allows a remote user to access the administrative console.

Why you would use virtual hosting

Virtual hosts let you manage a single application server on a single machine as if the application server
were multiple application servers each on their own host machine. Resources associated with one virtual
host cannot share data with resources associated with another virtual host. This is true even though the
virtual hosts share the same application server on the same physical machine.

Virtual hosts allow the administrator to isolate and independently manage multiple sets of resources on the
same physical machine.

Suppose an Internet service provider (ISP) has two customers with Internet sites hosted on the same
machine. The ISP keeps the two sites isolated from one another, despite their sharing a machine, by using
virtual hosts. The ISP associates the resources of the first company with VirtualHost1 and the resources of
the second company with VirtualHost2. Both virtual hosts map to the same application server.

Further suppose that both company sites offer the same servlet. Each site has its own instance of the
servlet, and is unaware of the same servlet on the other site. If the company whose site is organized on
VirtualHost2 is past due in paying its account with the ISP, the ISP can refuse all servlet requests that are
routed to VirtualHost2. Even though the same servlet is available on VirtualHost1, the requests directed at
VirtualHost2 do not go to the other virtual host.

174 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The servlets on one virtual host do not share their context with the servlets on the other virtual host.
Requests for the servlet on VirtualHost1 can continue as usual. This is true even though VirtualHost2 is
refusing to fill requests for the servlet with the same name.

You associate a servlet or other application with a virtual host instead of the actual DNS address.

The default virtual host (default_host)

The product provides a default virtual host (named default_host).

The virtual host configuration uses wildcard entries with the ports for its virtual host entries.
v The default alias is *:80, using an internal port that is not secure.
v Aliases of the form *:9080 use the secure internal port.
v Aliases of the form *:9443 use the external port that is not secure.
v Aliases of the form *:443 use the secure external port.

Unless you specifically want to isolate resources from one another on the same node (physical machine),
you probably do not need any virtual hosts in addition to the default host.

How requests map to virtual host aliases

Virtual hosts let you manage a single application server on a single machine as if the application server
were multiple application servers that are each on their own host machine. Resources associated with one
virtual host cannot share data with resources associated with another virtual host, even though the virtual
hosts share the same application server on the same physical machine.

When you request a resource, WebSphere Application Server tries to map the request to an alias of a
defined virtual host.

Mappings are both case sensitive and insensitive. For example, the portion ″http://host:port/″ is case
insensitive, but the URL that follows is case sensitive. The match must be alphanumerically exact. Also,
different port numbers are treated as different aliases.

For example, the request http://www.myhost.com/myservlet maps successfully to

http://WWW.MYHOST.COM/myservlet but not to http://WWW.MYHOST.COM/MYSERVLET or
Www.Myhost.Com/Myservlet. In the latter two cases, these mappings fail due to case sensitivity. The
request http://www.myhost.com/myservlet does not map successfully to http://myhost/myservlet or to
http://myhost:9876/myservlet. These mappings fail because they are not alphanumerically correct.

You can use wildcard entries for aliases by port and specify that all valid host name and address
combinations on a particular port map to a particular virtual host.

If you request a resource using an alias that cannot be mapped to an alias of a defined virtual host, you
receive a 404 error in the browser that was used to issue the request. A message states that the virtual
host could not be found.

Two sets of associations occur for virtual hosts. Application deployment associates an application with a
virtual host. Virtual host definitions associate the network address of the machine and the HTTP transport
or Web server port assignment of the application server with the virtual host. Looking at the flow from the
Web client request for the snoop servlet, for example, the following actions occur:
1. The Web client asks for the snoop servlet: at Web address
http://www.some_host.some_company.com:9080/snoop
2. The some_host machine has the 9080 port assigned to the stand-alone WebSphere Application
Server, server1.
3. The server1 Application Server looks at the virtual host assignments to determine the virtual host that
is assigned to the alias some_host.some_company.com:9080.

Chapter 3. Setting up the application serving environment 175

4. The application server finds that no explicit alias for that DNS string exists. However, a wild card
assignment for host name * at port 9080 does exist. This is a match. The virtual host that defines the
match is default_host.
5. The application server looks at the applications deployed on the default_host and finds the snoop
servlet.
6. The application server serves the application to the Web client and the requester is able to use the
snoop servlet.

You can have any number of aliases for a virtual host. You can even have overlapping aliases, such as:

Virtual host Alias Port

default_host * 9080
localhost 9080
my_machine 9080
my_machine.my_company.com 9080
localhost 80

The Application Server looks for a match using the explicit address specified on the Web client address.
However, it might resolve the match to any other alias that matches the pattern before matching the
explicit address. Simply defining an alias first in the list of aliases does not guarantee the search order
when WebSphere Application Server is looking for a matching alias.

A problem can occur if you use the same alias for two different virtual hosts. For example, assume that
you installed the default application and the snoop servlet on the default_host. You also have another
virtual host called the admin_host. However, you have not installed the default application or the snoop
servlet on the admin_host.

Assume that you define overlapping aliases for both virtual hosts because you accidentally defined port
9080 for the admin_host instead of port 9060:

Virtual host Alias Port

default_host * 9080
localhost 9080
admin_host * 9060
my_machine.com 9080

Assume that a Web client request comes in for http://my_machine.com:9080/snoop.

If the application server matches the request against *:9080, the application is served from the
default_host. If the application server matches the request to my.machine.com:9080, the application cannot
be found. A 404 error occurs in the browser that issues the request. A message states that the virtual host
could not be found.

This problem is the result of not finding the requested application in the first virtual host that has a
matching alias. The correct way to code aliases is for the alias name on an incoming request to match
only one virtual host in all of your virtual host definitions. If the URL can match more than one virtual host,
you can see the problem just described.

176 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring virtual hosts
Virtual hosts enable you to isolate and independently manage multiple sets of resources on the same
physical machine.
1. Create a virtual host using the “Virtual host collection” of the administrative console. Click
Environment > Virtual Hosts from the navigation tree of the console. Click New. On the “Virtual host
settings” on page 178 page that displays, specify an administrative name for the virtual host. When
you create a virtual host, a default set of 90 MIME entries is created for the virtual host.
2. There must be a virtual host alias corresponding to each port used by an HTTP transport. There is one
HTTP transport in each Web container, usually assigned to the virtual host named default_host. You
can change the default assignment to any valid virtual host.
You must create a virtual host for each HTTP port in the following cases:
v You are using the internal HTTP transport with a port other than the default of 9080. You must
define the port that you are using.
v You are using the default port 9080, but the port is no longer defined. You must define port 9080.
v You have created multiple Application Servers (either stand-alone servers or cluster members) that
use the same virtual host. Because each server must be listening on a different HTTP transport
port, you must define a virtual host alias for the transport port of each server.
If you define new virtual host aliases, identify the port values that the aliases use on the “HTTP
transport collection” on page 225 page.
3. If necessary, create a virtual host alias for each HTTP transport port.
From the “Virtual host collection” page, click your virtual host. On the “Virtual host settings” on page
178 page for the virtual host, click Host aliases. To define a virtual host alias on the “Host alias
collection” on page 178 page, click New. On the “Host alias settings” on page 179 page for the virtual
host alias, specify a host name and a port. Configure the virtual host to contain an alias for the port
number. For example, specify an alias of *:9082 if 9082 is the port number in use by the transport.
4. When you enter the URL for the application into a Web browser, include the port number in the URL.
For example, if 9082 is the port number, specify a URL such as
http://localhost:9082/wlm/SimpleServlet
5. If MIME entries are not specified at the Web module level, define MIME object types and their file
name extensions. For each needed MIME entry on the “MIME type collection” on page 180 page, click
New. On the “MIME type settings” on page 180 page, specify a MIME type and extension.
6. After you configure a virtual host alias or change a configuration, you must regenerate the Web server
plug-in configuration and restart WebSphere Application Server.

Virtual host collection

Use this page to create and manage configurations that each let a single host machine resemble multiple
host machines. Such configurations are known as virtual hosts.

To view this administrative console page, click Environment > Virtual Hosts.

Each virtual host has a logical name (which you define on this panel) and is known by its list of one or
more domain name system (DNS) aliases. A DNS alias is the TCP/IP host name and port number used to
request the servlet, for example yourHostName:80. (Port 80 is the default.)

You define one or more alias associations by clicking an existing virtual host or by adding a new virtual
host.

When a servlet request is made, the server name and port number entered into the browser are compared
to a list of all known aliases in an effort to locate the correct virtual host to serve the servlet. No match
returns an error to the browser.

Chapter 3. Setting up the application serving environment 177

An application server profile provides a default virtual host with some common aliases, such as the
internet protocol (IP) address, the DNS short host name, and the DNS fully qualified host name. The alias
comprises the first part of the path for accessing a resource such as a servlet.

For example, the alias is localhost:80 in the request http://localhost:80/myServlet.

A virtual host is not associated with a particular profile or node (machine), but is associated with a
particular server instead. It is a configuration, rather than a ″live object.″ You can create a virtual host, but
you cannot start or stop it.

For many users, creating virtual hosts is unnecessary because the default_host that is provided is
sufficient.

Adding the host name and IP address of the localhost machine to the alias table lets a remote user
access the administrative console.

Resources associated with one virtual host cannot share data with resources associated with another
virtual host, even if the virtual hosts share the same physical machine.

Name:

Specifies a logical name for configuring Web applications to a particular host name. The default virtual
host is suitable for most simple configurations.

Virtual hosts enable you to isolate, and independently manage, multiple sets of resources on the same
physical machine. Determine whether you need a virtual host alias for each port associated with an HTTP
transport channel or an HTTP transport. There must be a virtual host alias corresponding to each port
used by an HTTP transport channel or an HTTP transport. There is one HTTP transport channel or HTTP
transport associated with each Web container, and there is one Web container in each application server.

When you create a virtual host, a default set of 90 MIME entries is created for the virtual host.

You must create a virtual host for each HTTP port in the following cases:
v You use the internal HTTP transport with a port other than the default value of 9080, or for some reason
the virtual host does not contain the usual entry for port 9080.
v You create multiple application servers (stand-alone servers, managed servers, or cluster members) that
are using the same virtual host. Because each server must be listening on a different HTTP port, you
need a virtual host alias for the HTTP port of each server.

Virtual host settings:

Use this page to configure a virtual host instance.

To view this administrative console page, click Environment > Virtual Hosts >virtual_host_name.

Name:

Specifies a logical name for configuring Web applications to a particular host name. The default virtual
host is suitable for most simple configurations.

Data type String

Default default_host

Host alias collection:

178 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Use this page to manage host name aliases defined for a virtual host. An alias is the DNS host name and
port number that a client uses to form the URL request for a Web application resource.

To view this administrative console page, click Environment > Virtual Hosts >virtual_host_name > Host
Aliases.

Host Name:

Specifies the IP address, DNS host name with domain name suffix, or just the DNS host name, used by a
client to request a Web application resource (such as a servlet, JavaServer Pages (JSP) file, or HTML
page). For example, the host alias name is myhost in a DNS name of myhost:8080.

The product provides a default virtual host (named default_host). The virtual host configuration uses the
wildcard character * (asterisk) along with the port number for its virtual host entries. Unless you specifically
want to isolate resources from one another on the same node (physical machine), you probably do not
need any virtual hosts in addition to the default host.

Port:

Specifies the port for which the Web server has been configured to accept client requests. For example,
the port assignment is 8080 in a DNS name of myhost:8080. A URL refers to this DNS as:
http://myhost:8080/servlet/snoop.

Host alias settings:

Use this page to view and configure a host alias.

To view this administrative console page, click Environment > Virtual Hosts >virtual_host_name > Host
Aliases >host_alias_name.

Host name:

Specifies the IP address, domain name system (DNS) host name with domain name suffix, or the DNS
host name that clients use to request a Web application resource, such as a servlet, JSP file, or HTML
page.

For example, when the DNS name is myhost, the host alias is myhost:8080, where 8080 is the port. A URL
request can refer to the snoop servlet on the host alias as: http://myhost:8080/servlet/snoop.

When there is no port number specified for a host alias, the default port is 80. For existing virtual hosts,
the default host name and port reflect the values specified at product installation or configuration. For new
virtual hosts, the default can be * to allow any value or no specification.

Data type String

Default *

You can also use the IP address or the long or short DNS
name.

Port:

Specifies the port where the Web server accepts client requests. Specify a port value in conjunction with
the host name.

The default reflects the value specified at product setup. The default might be 80, 81, 9060 or a similar
value.

Chapter 3. Setting up the application serving environment 179

Data type Integer
Default 9060

MIME type collection:

Use this page to view and configure multi-purpose internet mail extensions (MIME) object types and their
file name extensions.

The list shows a collection of MIME type extension mappings defined for the virtual host. Virtual host
MIME entries apply when you do not specify MIME entries at the Web module level.

To view a list of current virtual host Mime types in the administrative console, click Environment > Virtual
Hosts >virtual_host_name > MIME Types.

MIME Type:

Specifies a MIME type, which can be application, audio, image, text, video, www, or x-world. An example
value for MIME type is text/html.

Extensions:

Specifies file extensions of files that map the MIME type. Do not specify the period before the extension.
Example extensions for a text/html MIME type are htm and html.

MIME type settings:

Use this page to configure a multi-purpose internet mail extensions (MIME) object type.

To view this administrative console page, click Environment > Virtual Hosts >virtual_host_name > MIME
Types >MIME_type.

MIME Type:

Specifies a MIME type, which can be application, audio, image, text, video, www, or x-world. An example
value for MIME type is text/html.

An example value for MIME type is text/html. A default value appears only if you are viewing the
configuration for an existing instance.

Data type String

Extensions:

Specifies file extensions of files that map the MIME type. Do not specify the period before the extension.
Example extensions for a text/html MIME type are htm and html.

File extensions for a text/html MIME type are .htm and .html. A default value appears only if you are
viewing the configuration for an existing MIME type.

Data type String

Variables
A variable is a configuration property that can be used to provide a parameter for some values in the
system. A variable has a name and a value.

180 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebSphere variables are used for:
v Configuring WebSphere Application Server path names, such as JAVA_HOME, and
APP_INSTALL_ROOT.
v Configuring certain cell-widecustomization values.

Each variable has a scope. A scope is the range of locations in the WebSphere Application Server network
where the variable is applicable.
v A variable with a cell-wide scope is available across the entire WebSphere Application Server cell.
v A variable with a node-level scope is available only on the node and the servers on that node. If a
node-level variable has the same name as a cell-wide variable, the node-level variable value takes
precedence.
v A server variable is available only on the one server process. A server variable takes precedence over a
variable with the same name that is defined at a higher level.

You can use variables in configuration values such as file system path settings. Use the following syntax
to refer to a variable:
${variable_name}

The value of a variable can contain a reference to another variable. The value of the variable is computed
by substituting the value of the referenced variable recursively.

Variables are useful when concatenating two path variables when the specification does not accept the
AND operator. For example, suppose that the following variables exist:

Variable name Variable value

ROOT_DIR /
HOME_DIR ${ROOT_DIR}home
USER_DIR ${HOME_DIR}/myuserdir

The variable reference ${USER_DIR} resolves to the value /home/myuserdir.

Configuring WebSphere variables

This topic describes how to create a WebSphere Application Server variable.

You can define a WebSphere Application Server variable to provide a parameter for some values in the
system. After you define the name and value for a variable, the value is used in place of the variable
name. Variables most often specify file paths. However, some system components also support the use of
variables.

WebSphere variables are used for:

v Configuring WebSphere Application Server path names, such as JAVA_HOME, and
APP_INSTALL_ROOT.
v Configuring certain cell-widecustomization values.

The scope of a variable can be cell-wide, node-wide, or applicable to only one server process.

Define variables on the Environment > WebSphere Variables console page.

Define the scope to apply a variable cell-wide, cluster-wide, node-wide or to only one server process. A
variable resolves to its new value when used in a component that supports the use of variables.
1. Click Environment > WebSphere Variables in the administrative console to define a new variable.

Chapter 3. Setting up the application serving environment 181

2. Specify the scope of the variable. Declare the new variable for the Cell, Cluster,Node or Server and
click Apply.
The variable exists at the level you specify. Define a variable at multiple levels to use multiple values.
The more granular definition overrides the higher level setting.
For instance, if you specify the same variable on a node and a server, the server setting overrides the
node setting. Similarly, a node level setting overrides a cluster or cell setting.
Scoping variables is particularly important when testing data source objects. Variable scoping can
cause a data source to fail the test connection, but to succeed at run time, or to pass the test
connection, but fail at run time.
See the Developing and deploying applications PDF for more information.
3. Click New on the WebSphere Variables page.
4. Specify a name, a value, and a description on the Variable page. Click OK.
5. Verify that the variable is displayed in the list of variables. The administrative console does not pick up
typing errors. The variable is ignored if it is referred to incorrectly.
6. Save your configuration.
7. Stop the server and start the server again to put the variable configuration into effect.

WebSphere variables collection

Use this page to view and change a list of substitution variables with their values and scope.

To view this administrative console page, click Environment > WebSphere Variables.

For information on a variable, click the variable and read the value in the Description field.

Name:

Specifies the symbolic name for a WebSphere Application Server variable. For example, a variable name
might represent a physical path or URL root used by WebSphere Application Server.

Value:

Specifies the value that the symbolic name represents. For example, the value might be an absolute path
value for a file or URL root.

Scope:

Specifies the level at which a WebSphere Application Server variable is visible on the administrative
console panel.

A resource can be visible in the administrative console collection table at the cell, cluster, node, or server
scope.

Variable settings:

Use this page to define the name and value of a WebSphere Application Server substitution variable.

To view this administrative console page, click Environment > WebSphere Variables
>WebSphere_variable_name.

Name:

Specifies the symbolic name for a WebSphere Application Server variable. For example, a variable name
might represent a physical path or URL root that is used by WebSphere Application Server.

182 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebSphere variables are used for:
v Configuring WebSphere Application Server path names, such as JAVA_HOME, and
APP_INSTALL_ROOT.
v Configuring certain cell-widecustomization values.

WebSphere Application Server substitutes the symbolic name wherever its value displays in the system.

For example, ″JAVA_HOME″ is the symbolic name representing the file system path to the installation
directory for the Java Virtual Machine (JVM). For example, the value is
/opt/IBM/WebSphere/AppServer/java for the WebSphere Application Server product on a Linux machine.

You can create new variables for use in WebSphere Application Server components that support the use
of variables.

Data type String

Value:

Specifies the value that the symbolic name represents. For example, the value might be an absolute path
value for a file or URL root.

For example, /opt/IBM/WebSphere/AppServer/java is the value on a Linux machine for a variable named
JAVA_HOME.

Data type String

Description:

Documents the purpose of a variable.

Data type String

IBM Toolbox for Java JDBC driver

WebSphere Application Server supports the IBM Toolbox for Java JDBC driver. The IBM Toolbox for Java
JDBC driver is included with the IBM Toolbox for Java product.

IBM Toolbox for Java is a library of Java classes that are optimized for accessing iSeries and AS/400 data
and resources. You can use the IBM Toolbox for Java JDBC driver to access local or remote DB2 UDB
for iSeries 400 databases from server-side and client Java applications that run on any platform that
supports Java.

IBM Toolbox for Java is available in these versions:

IBM Toolbox for Java licensed program
The licensed program is available with every OS/400 release, starting with Version 4 Release 2
(V4R2). You can install the licensed program on your iSeries 400 system, and then either copy the
IBM Toolbox for Java JAR file (jt400.jar) to your system or update your system classpath to locate
the server installation. Product documentation for IBM Toolbox for Java is available from the
iSeries information center: http://publib.boulder.ibm.com/iseries/v5r1/ic2924/index.htm
Locate the documentation by traversing the following path in the left-hand navigation window of
the iSeries information center: Programming > Java > IBM Toolbox for Java.
JTOpen
JTOpen is the open source version of IBM Toolbox for Java, and is more frequently updated than
the licensed program version. You can download JTOpen from http://www-

Chapter 3. Setting up the application serving environment 183

 1.ibm.com/servers/eserver/iseries/toolbox/downloads.htm. You can also download the JTOpen
Programming Guide. The guide includes instructions for installing JTOpen and information about
the JDBC driver.

The JDBC driver for both versions supports JDBC 2.0. For more information about IBM Toolbox for Java
and JTOpen, see the product Web site at http://www-
1.ibm.com/servers/eserver/iseries/toolbox/index.html.

Note: If you are using WebSphere Application Server on platforms other than iSeries, use the JTOpen
version of the Toolbox JDBC driver.

Configure and use the jt400.jar file

1. Download the jt400.jar file from the JTOpen URL at http://www-
1.ibm.com/servers/eserver/iseries/toolbox/downloads.htm. Place it in a directory on your
workstation such as C:\JDBC_Drivers\Toolbox.
2. Open the administrative console.
3. Select Environment.
4. Select Managed WebSphere Variables.
5. Set the managed variable OS400_TOOLBOX_JDBC_DRIVER_PATH at the Node level.
6. Double click OS400_TOOLBOX_JDBC_DRIVER_PATH.
7. Set the value to the full directory path to the jt400.jar file downloaded in step one. Do not include
jt400.jar in this value. For example,
OS400_TOOLBOX_JDBC_DRIVER_PATH == "C:\JDBC_Drivers\Toolbox"
When you choose a Toolbox driver from the list of possible resource providers the Classpath field
looks like:
Classpath == ${OS400_TOOLBOX_JDBC_DRIVER_PATH}/jt400.jar

Shared library files

Shared library files in WebSphere Application Server consist of a symbolic name, a Java class path, and a
native path for loading Java Native Interface (JNI) libraries.

You can define a shared library at the cell, node, or server level. Defining a library at one of the three
levels does not cause the library to be placed into the application server’s class loader. You must
associate the library to an application or server in order for the classes represented by the shared library
to be loaded in either a server-wide or application-specific class loader.

A separate class loader is used for shared libraries that are associated with an application server. This
class loader is the parent of the application class loader, and the WebSphere Application Server
extensions class loader is its parent. Shared libraries that are associated with an application are loaded by
the application class loader.

Managing shared libraries

Shared libraries are files used by multiple applications. Using the administrative console, you can define a
shared library at the cell, node, or server level. You can then associate the library to an application or
server to load the classes represented by the shared library in either a server-wide or application-specific
class loader. Using an installed optional package, you can associate a shared library to an application by
declaring the dependent library .jar file in the MANIFEST.MF file of the application. Refer to the Java 2
Platform, Enterprise Edition (J2EE) 1.4 specification, section 8.2 for an example.

If your deployed applications use shared library files, define shared libraries for the library files and
associate the libraries with specific applications or with an application server. Associating a shared library
file with a server associates the file with all applications on the server. Use the Shared Libraries page to
define new shared library files to the system and remove them.

184 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Use the administrative console to define a shared library.
1. Create a shared library for each library file that your applications need.
2. Associate each shared library with an application or a server.
– Associate a shared library with an application that uses the shared library file.
– Associate a shared library with an application server so every application on the server can use
the shared library file.
v Use an installed optional package to declare a shared library for an application.
v Remove a shared library.
1. Click Environment > Shared Libraries in the console navigation tree to access the Shared
Libraries page.
2. Select the library to be removed.
3. Click Delete.
The list of shared libraries is refreshed. The library file no longer displays in the list.

Creating shared libraries

Shared libraries are files used by multiple applications.

The first step for making a library file available to multiple applications deployed on a server is to create a
shared library for each library file that your applications need. When you create the shared libraries, set
variables for the library files.

Use the Shared Libraries page to create and configure shared libraries.
1. Go to the Shared Libraries page. Click Environment > Shared Libraries in the console navigation
tree.
2. Change the scope of the collection table to see what shared libraries are in a cell, node, or server.
a. Select the cell, a node, or a server.
b. Click Apply.
3. Click New.
4. Configure the shared library.
a. On the settings page for a shared library, specify the name, class path, and any other variables for
the library file that are needed.
b. Click Apply.
5. Repeat steps 1 through 4 until you define a shared library instance for each library file that your
applications need.

Using the administrative console, associate your shared libraries with specific applications or with the class
loader of an application server. Associating a shared library file with a server class loader associates the
file with all applications on the server.

Alternatively, you can use an installed optional package to associate your shared libraries with an
application.

Shared library collection

Use this page to define a list of shared library files that deployed applications can use.

To view this administrative console page, click Environment > Shared Libraries.

By default, a shared library is accessible to applications deployed (or installed) on the same node as the
shared library file. Use the Scope field to change the scope to a different node or to a specific server.

Name:

Chapter 3. Setting up the application serving environment 185

Specifies a name for the shared library.

Description:

Describes the shared library file.

Shared library settings:

Use this page to make a library file available to deployed applications.

To view this administrative console page, click Environment > Shared Libraries >shared_library_name.

Name:

Specifies a name for the shared library.

Data type String

Description:

Describes the shared library file.

Data type String

Classpath:

Specifies the class path used to locate the JAR files for the shared library support.

Data type String

Units Class path

Native Library Path:

Specifies the class path for locating platform-specific library files for shared library support; for example,
.dll, .so, or *SRVPGM objects.

Data type String

Units Class path

Associating shared libraries with applications

You can associate a shared library with an application. Classes represented by the shared library are then
loaded in the application’s class loader, making the classes available to the application.

This article assumes that you have defined a shared library at the cell, node, or server level. The shared
library represents a library file used by multiple deployed applications.

This article also assumes that you want to use the administrative console, and not an installed optional
package, to associate a shared library with an application.

To associate a shared library with an application, create and configure a library reference using the
administrative console. A library reference specifies the name of the shared library file.

If you associate a shared library with an application, do not associate the same shared library with a
server class loader.

186 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
1. Click Applications > Enterprise Applications >application_name > Libraries in the console
navigation tree to access the Library Ref page.
2. Click Add.
3. On the settings page for a library reference, specify variables for the library reference as needed. The
variables identify the shared library file that your application uses.
4. Click Apply.

The name of the library reference is shown in the list on the Library Ref page.

Repeat steps 2 through 4 until you define a library reference instance for each shared library that your
application requires.

Associating shared libraries with servers

You can associate shared libraries with the class loader of a server. Classes represented by the shared
library are then loaded in a server-wide class loader, making the classes available to all applications
deployed on the server.

This article assumes that you have defined a shared library at the cell, node, or server level. The shared
library represents a library file used by multiple deployed applications.

To associate a shared library with the class loader of a server, create and configure a library reference
using the administrative console. A library reference specifies the name of the shared library file.

If you associate a shared library with a server class loader, do not associate the same shared library with
an application.
1. Configure class loaders for applications deployed on the server.
a. Click Servers > Application Servers > server_name to access the settings page for the
application server.
b. Set values for the application Class loader policy and Class loading mode of the server. For
information on these settings, see “Application server settings” on page 204 and class loaders.
2. Create a library reference for each shared library file that your application needs.
a. Go to the settings page for a class loader.
b. Click Libraries to access the Library Ref page.
c. Click Add.
d. On the settings page for a library reference, specify variables for the library reference as needed.
The variables identify the shared library file that your application uses.
e. Click Apply. The name of the library reference is shown in the list on the Library Ref page.
Repeat the previous steps until you define a library reference for each shared library that your
application needs.

Installed optional packages

Installed optional packages enable applications to use the classes in Java archive (.jar) files without
having to include them explicitly in a class path. An installed optional package is a .jar file containing
specialized tags in its manifest file that enable the application server to identify it. An installed optional
package declares one or more shared library .jar files in the manifest file of an application. When the
application is installed on a server or cluster, the classes represented by the shared libraries are loaded in
the class loader of the application, making the classes available to the application.

When a Java 2 Platform, Enterprise Edition (J2EE) application is installed on a server or cluster,
dependency information is specified in its manifest file. WebSphere Application Server reads the
dependency information of the application (.ear file) to automatically associate the application with an

Chapter 3. Setting up the application serving environment 187

installed optional package .jar file. WebSphere Application Server adds the .jar files in associated
optional packages to the application class path. Classes in the installed optional packages are then
available to application classes.

Installed optional packages used by WebSphere Application Server are described in section 8.2 of the
J2EE specification, Version 1.4 at http://java.sun.com/j2ee/j2ee-1_4-fr-spec.pdf.

WebSphere Application Server supports using the manifest file (manifest.mf) in shared library .jar files
and application .ear files. WebSphere Application Server does not support the Java 2 Platform Standard
Edition (J2SE) Installed Optional Package semantics used in the J2SE specification
(http://java.sun.com/j2se/1.3/docs/guide/extensions/spec.html), which primarily serve the applet
environment. WebSphere Application Server ignores applet-specific tags within manifest files.

Sample manifest.mf file

A sample manifest file follows for an application app1.ear that refers to a single shared library file
util.jar:
app1.ear:
META-INF/application.xml
ejb1.jar:
META-INF/MANIFEST.MF:
Extension-List: util
util-Extension-Name: com/example/util
util-Specification-Version: 1.4
META-INF/ejb-jar.xml

util.jar:
META-INF/MANIFEST.MF:
Extension-Name: com/example/util
Specification-Title: example.com’s util package
Specification-Version: 1.4
Specification-Vendor: example.com
Implementation-Version: build96

The syntax of a manifest entry depends on whether the entry applies to a member with a defining role (the
shared library) or a member with a referencing role (a J2EE application or a module within a J2EE
application).

Manifest entry tagging

Main tags used for manifest entries include the following:

Extension-List
A required tag with variable syntax. Within the context of the referencing role (application’s
manifest), this is a space delimited list that identifies and constructs unique Extension-Name,
Extension-Specification tags for each element in the list. Within the context of the defining role
(shared library), this tag is not valid.
Extension-Name
A required tag that provides a name and links the defining and referencing members. The syntax
of the element within the referencing role is to prefix the element with the <ListElement> string.
For each element in the Extension-List, there is a corresponding <ListElement>-Extension-Name
tag. The defining string literal value for this tag (in the above sample com/example/util1) is used
to match (in an equality test) the corresponding tags between the defining and referencing roles.
Specification-Version
A required tag that identifies the specification version and links the defining and referencing
members.

188 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Implementation-Version
An optional tag that identifies the implementation version and links the defining and referencing
members.

Further information on these tags is in the .jar file specification at

http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#Manifest%20Specification.

Using installed optional packages

You can associate one or more shared libraries with an application using an installed optional package
that declares the shared libraries in the application’s manifest file. Classes represented by the shared
libraries are then loaded in the application’s class loader, making the classes available to the application.

Read about installed optional packages in “Installed optional packages” on page 187 and in section 8.2 of
the Java 2 Platform, Enterprise Edition (J2EE) specification, Version 1.4 at
http://java.sun.com/j2ee/j2ee-1_4-fr-spec.pdf.

WebSphere Application Server does not support the Java 2 Platform Standard Edition (J2SE) Installed
Optional Package semantics used in the J2SE specification
(http://java.sun.com/j2se/1.3/docs/guide/extensions/spec.html), which primarily serve the applet
environment. WebSphere Application Server ignores applet-specific tags within manifest files.

Installed optional packages expand the existing shared library capabilities of an application server. Prior to
Version 6, an administrator was required to associate a shared library to an application or server. Installed
optional packages enable an administrator to declare a dependency in an application’s manifest file to a
shared library, with installed optional package elements listed in the manifest file, and automatically
associate the application to the shared library. During application installation, the shared library .jar file is
added to the class path of the application class loader.

If you use an installed optional package to associate a shared library with an application, do not associate
the same shared library with an application class loader or a server class loader using the administrative
console.
1. Assemble the library file, including the manifest information that identifies it as an extension. Two
sample manifest files follow. The first sample manifest file has application app1.ear refer to a single
shared library file util.jar:
app1.ear:
META-INF/application.xml
ejb1.jar:
META-INF/MANIFEST.MF:
Extension-List: util
util-Extension-Name: com/example/util
util-Specification-Version: 1.4
META-INF/ejb-jar.xml

util.jar:
META-INF/MANIFEST.MF:
Extension-Name: com/example/util
Specification-Title: example.com’s util package
Specification-Version: 1.4
Specification-Vendor: example.com
Implementation-Version: build96

The second sample manifest file has application app1.ear refer to multiple shared library .jar files:
app1.ear:
META-INF/application.xml
ejb1.jar:
META-INF/MANIFEST.MF:
Extension-List: util1 util2 util3
Util1-Extension-Name: com/example/util1
Util1-Specification-Version: 1.4

Chapter 3. Setting up the application serving environment 189

 Util2-Extension-Name: com/example/util2
Util2-Specification-Version: 1.4
Util3-Extension-Name: com/example/util3
Util3-Specification-Version: 1.4
META-INF/ejb-jar.xml

util1.jar:
META-INF/MANIFEST.MF:
Extension-Name: com/example/util1
Specification-Title: example.com’s util package
Specification-Version: 1.4
Specification-Vendor: example.com
Implementation-Version: build96

util2.jar:
META-INF/MANIFEST.MF:
Extension-Name: com/example/util2
Specification-Title: example.com’s util package
Specification-Version: 1.4
Specification-Vendor: example.com
Implementation-Version: build96

util3.jar:
META-INF/MANIFEST.MF:
Extension-Name: com/example/util3
Specification-Title: example.com’s util package
Specification-Version: 1.4
Specification-Vendor: example.com
Implementation-Version: build96
2. Create a shared library that represents the library file assembled in step 1. This installs the library file
as a WebSphere Application Server shared library.
3. Copy the shared library .jar file to the cluster members.
4. Assemble the application, declaring in the application manifest file dependencies to the library files
named the manifest created for step 1.
5. Install the application on the server or cluster.

During application installation, the shared library .jar files are added to the class path of the application
class loader.

Library reference collection

Use this page to view and manage library references that define how to use global libraries. For example,
you can use this page to associate shared library files with a deployed application.

To view this administrative console page, click Applications > Enterprise Applications
>application_name > Libraries.

If no shared libraries are defined, after you click Add a message is displayed stating that you must define
a shared library before you can create a library reference. A shared library is a container-wide library file
that can be used by deployed applications. To define a shared library, click Environment > Shared
Libraries and specify the scope of the container. Then, click New and specify a name and one or more
paths for the shared library. After you define a shared library, return to this page, click Add, and create a
library reference.

Library name:

Specifies a name for the library reference.

Library reference settings:

Use this page to define library references, which specify how to use global libraries.

190 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this administrative console page, click Applications > Enterprise Applications
>application_name > Libraries >library_reference_name. A shared library must be defined to view this
page.

A shared library is a container-wide library file that can be used by deployed applications. To define a
shared library, click Environment > Shared Libraries and specify the scope of the container. Then, click
New and specify a name and one or more paths for the shared library.

Library name:

Specifies the name of the shared library to use for the library reference.

Data type String

Environment: Resources for learning

Use the following links to find relevant supplemental information about configuring the WebSphere
Application Server cell-wide environment. The information resides on IBM and non-IBM Internet sites,
whose sponsors control the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

Programming instructions and examples

v WebSphere Application Server education at http://www.ibm.com/software/websphere/technical.

Administration
v Listing of all IBM WebSphere Application Server Redbooks at http://publib-
b.boulder.ibm.com/Redbooks.nsf/Portals/WebSphere.

Working with server configuration files

Application server configuration documents define the available application servers, their configurations,
and their contents.

You should periodically save changes to your administrative configuration. You can change the default
locations of configuration files, as needed.
1. Edit configuration files. The master repository is comprised of .xml configuration files. You can edit
configuration files using the administrative console, scripting, wsadmin commands, programming, or by
editing a configuration file directly.
2. Save changes made to configuration files. Using the console, you can save changes as follows:
a. Click Save on the taskbar of the administrative console.
b. Put a check mark in the Synchronize changes with Nodes check box.
c. On the Save page, click Save.
3. Handle temporary configuration files resulting from a session timing out.
4. Change the location of temporary configuration files.
5. Change the location of backed-up configuration files.
6. Change the location of temporary workspace files.
7. Back up and restore configurations.

Chapter 3. Setting up the application serving environment 191

Configuration documents
WebSphere Application Server stores configuration data for servers in several documents in a cascading
hierarchy of directories. The configuration documents describe the available application servers, their
configurations, and their contents. Most configuration documents have XML content.

Hierarchy of directories of documents

The cascading hierarchy of directories and the documents’ structure support multinode replication to
synchronize the activities of all servers in a cell. In a Network Deployment environment, changes made to
configuration documents in the cell repository, are automatically replicated to the same configuration
documents that are stored on nodes throughout the cell.

At the top of the hierarchy is the cells directory. It holds a subdirectory for each cell. The names of the cell
subdirectories match the names of the cells. For example, a cell named cell1 has its configuration
documents in the subdirectory cell1.

On the Network Deployment node, the subdirectories under the cell contain the entire set of documents for
every node and server throughout the cell. On other nodes, the set of documents is limited to what applies
to that specific node. If a configuration document only applies to node1, then that document exists in the
configuration on node1 and in the Network Deployment configuration, but not on any other node in the
cell.

Each cell subdirectory has the following files and subdirectories:

v The cell.xml file, which provides configuration data for the cell
v Files such as security.xml, virtualhosts.xml, resources.xml, and variables.xml, which provide
configuration data that applies across every node in the cell
v The clusters subdirectory, which holds a subdirectory for each cluster defined in the cell. The names of
the subdirectories under clusters match the names of the clusters.
Each cluster subdirectory holds a cluster.xml file, which provides configuration data specifically for that
cluster.
v The nodes subdirectory, which holds a subdirectory for each node in the cell. The names of the nodes
subdirectories match the names of the nodes.
Each node subdirectory holds files such as variables.xml and resources.xml, which provide
configuration data that applies across the node. Note that these files have the same name as those in
the containing cell’s directory. The configurations specified in these node documents override the
configurations specified in cell documents having the same name. For example, if a particular variable is
in both cell- and node-level variables.xml files, all servers on the node use the variable definition in the
node document and ignore the definition in the cell document.
Each node subdirectory holds a subdirectory for each server defined on the node. The names of the
subdirectories match the names of the servers. Each server subdirectory holds a server.xml file, which
provides configuration data specific to that server. Server subdirectories might hold files such as
security.xml, resources.xml and variables.xml, which provide configuration data that applies only to
the server. The configurations specified in these server documents override the configurations specified
in containing cell and node documents having the same name.
v The applications subdirectory, which holds a subdirectory for each application deployed in the cell. The
names of the applications subdirectories match the names of the deployed applications.
Each deployed application subdirectory holds a deployment.xml file that contains configuration data on
the application deployment. Each subdirectory also holds a META-INF subdirectory that holds a J2EE
application deployment descriptor file as well as IBM deployment extensions files and bindings files.
Deployed application subdirectories also hold subdirectories for all .war and entity bean .jar files in the
application. Binary files such as .jar files are also part of the configuration structure.

An example file structure is as follows:

192 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
cells
cell1
cell.xml resources.xml virtualhosts.xml variables.xml security.xml
nodes
nodeX
node.xml variables.xml resources.xml serverindex.xml
serverA
server.xml variables.xml
nodeAgent
server.xml variables.xml
nodeY
node.xml variables.xml resources.xml serverindex.xml
applications
sampleApp1
deployment.xml
META-INF
application.xml ibm-application-ext.xml ibm-application-bnd.xml
sampleApp2
deployment.xml
META-INF
application.xml ibm-application-ext.xml ibm-application-bnd.xml

Changing configuration documents

You can use one of the administrative tools (console, wsadmin, Java APIs) to modify configuration
documents or edit them directly. It is preferable to use the administrative console because it validates
changes made to configurations. ″“Configuration document descriptions”″ states whether you can edit a
document using the administrative tools or must edit it directly.

Configuration document descriptions

Most configuration documents have XML content. The table below describes the documents and states
whether you can edit them using an administrative tool or must edit them directly.

If possible, edit a configuration document using the administrative console because it validates any
changes that you make to configurations. You can also use one of the other administrative tools (wsadmin
or Java APIs) to modify configuration documents. Using the administrative console or wsadmin scripting to
update configurations is less error prone and likely quicker and easier than other methods.

However, you cannot edit some files using the administrative tools. Configuration files that you must edit
manually have an X in the Manual editing required column in the table below.

Document descriptions

(Locations split for publishing)

Configuration file Locations Purpose Manual editing required

admin-authz.xml config/cells/ Define a role for X
cell_name/ administrative operation
authorization.
app.policy config/cells/ Define security permissions X
cell_name/ for application code.
nodes/node_name/
cell.xml config/cells/ Identify a cell.
cell_name/

Chapter 3. Setting up the application serving environment 193

cluster.xml config/cells/ Identify a cluster and its
cell_name/ members and weights.
clusters/
cluster_name/ This file is only available
with the Network
Deployment product.
deployment.xml config/cells/ Configure application
cell_name/ deployment settings such
applications/ as target servers and
application_name/ application-specific server
configuration.
filter.policy config/cells/ Specify security X
cell_name/ permissions to be filtered
out of other policy files.
integral-jms- config/cells/ Provide security X
authorizations.xml cell_name/ configuration data for the
integrated messaging
system.
library.policy config/cells/ Define security permissions X
cell_name/ for shared library code.
nodes/node_name/
multibroker.xml config/cells/ Configure a data replication
cell_name/ message broker.
namestore.xml config/cells/ Provide persistent name X
cell_name/ binding data.
naming-authz.xml config/cells/ Define roles for a naming X
cell_name/ operation authorization.
node.xml config/cells/ Identify a node.
cell_name/
nodes/node_name/
pmirm.xml config/cells/ Configure PMI request X
cell_name/ metrics.
resources.xml config/cells/ Define operating
cell_name/ environment resources,
config/cells/ including JDBC, JMS,
cell_name/ JavaMail, URL, JCA
nodes/node_name/ resource providers and
config/cells/ factories.
cell_name/
nodes/node_name/
servers/
server_name/

security.xml config/cells/ Configure security, including

cell_name/ all user ID and password
data.
server.xml config/cells/ Identify a server and its
cell_name/ components.
nodes/
node_name/
servers/
server_name/

194 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
serverindex.xml config/cells/ Specify communication
cell_name/ ports used on a specific
nodes/ node.
node_name/
spi.policy config/cells/ Define security permissions X
cell_name/ for service provider libraries
nodes/ such as resource providers.
node_name/
variables.xml config/cells/ Configure variables used to
cell_name/ parameterize any part of
config/cells/ the configuration settings.
cell_name/
nodes/
node_name/
config/cells/
cell_name/
nodes/node_name/
servers/
server_name/

virtualhosts.xml config/cells/ Configure a virtual host and

cell_name/ its MIME types.

Object names
When you create a new object using the administrative console or a wsadmin command, you often must
specify a string for a name attribute. Most characters are allowed in the name string. However, the name
string cannot contain the following characters. The name string also cannot contain leading and trailing
spaces.

/ forward slash
\ backslash
* asterisk
, comma
: colon
; semi-colon
= equal sign
+ plus sign
? question mark
| vertical bar
< left angle bracket
> right angle bracket
& ampersand (and sign)
% percent sign
’ single quote mark
″ double quote mark
]]> No specific name exists for this character combination.
. period (not valid if first character; valid if a later character)

Configuration repositories
A configuration repository stores configuration data. By default, configuration repositories reside in the
config subdirectory of the product installation root directory.

A cell-level repository stores configuration data for the entire cell and is managed by a file repository
service that runs in the deployment manager. The deployment manager and each node have their own

Chapter 3. Setting up the application serving environment 195

repositories. A node-level repository stores configuration data needed by processes on that node and is
accessed by the node agent and application servers on that node.

When you change a WebSphere Application Server configuration by creating an application server,
installing an application, changing a variable definition or the like, and then save the changes, the cell-level
repository is updated. The file synchronization service distributes the changes to the appropriate nodes.

Handling temporary configuration files resulting from session timeout

If the console is not used for 15 minutes or more, the session times out. The same thing happens if you
close the browser window without saving the configuration file. Changes to the file are saved to a
temporary file when the session times out, after 15 minutes.

When a session times out, the configuration file in use is saved under the userid/timeout directory under
the ServletContext’s temp area. This is the value of the javax.servlet.context.tempdir attribute of the
ServletContext. By default, it is: install_root/temp/hostname/Administration/admin/admin.war

You can change the temp area by specifying it as a value for the tempDir init-param of the action servlet in
the deployment descriptor (web.xml) of the administrative application.

The next time you log on to the console, you are prompted to load the saved configuration file. If you
decide to load the saved file:
1. If a file with the same name exists in the install_root/config directory, that file is moved to the
userid/backup directory in the temp area.
2. The saved file is moved to the install_root/config directory.
3. The file is then loaded.

If you decide not to load the saved file, it is deleted from the userid/timeout directory in the temp area.

The configuration file is also saved automatically when the same user ID logs into the non-secured
console again, effectively starting a different session. This process is equivalent to forcing the existing user
ID out of session, similar to a session timing out.

Changing the location of temporary configuration files

The configuration repository uses copies of configuration files and temporary files while processing
repository requests. It also uses a backup directory while managing the configuration. You can change the
default locations of these files from the configuration directory to a directory of your choice using system
variables or the administrative console.

The default location for the configuration temporary directory is CONFIG_ROOT/temp. Change the location
by doing either of the following:
v Set the system variable was.repository.temp to the location you want for the repository temporary
directory. Set the system variable when launching a Java process using the -D option. For example, to
set the default location of the repository temporary directory, use the following option:
-Dwas.repository.temp=%CONFIG_ROOT%/temp
v Use the administrative console to change the location of the temporary repository file location for each
server configuration. For example, on the Network Deployment product, to change the setting for a
deployment manager, do the following:
1. Click System Administration > Deployment Manager in the navigation tree of the administrative
console. Then, click Administration Services, Repository Service, and Custom Properties.
2. On the Properties page, click New.
3. On the settings page for a property, define a property for the temporary file location. The key for this
property is was.repository.temp. The value can include WebSphere Application Server variables
such as ${WAS_TEMP_DIR}/config. Then, click OK.

196 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The system property set using the first option takes precedence over the configuration property set using
the second option.

Changing the location of backed-up configuration files

During administrative processes like adding a node to a cell or updating a file, configuration files are
backed up to a backup location. The default location for the backup configuration directory is
CONFIG_ROOT/backup. Change the location by doing either of the following:
v Set the system variable was.repository.backup to the location you want as the repository backup
directory. Set the system variable when launching a Java process using the -D option. For example, to
set the default location of the repository backup directory, use the following option:
-Dwas.repository.backup=%CONFIG_ROOT%/backup
v Use the administrative console to change the location of the repository backup directory for each server
configuration. For example, on the Network Deployment product, do the following to change the setting
for a deployment manager:
1. Click System Administration > Deployment Manager in the navigation tree of the administrative
console. Then, click Administration Services, Repository Service, and Custom Properties.
2. On the Properties page, click New.
3. On the settings page for a property, define a property for the backup file location. The key for this
property is was.repository.backup. The value can include WebSphere Application Server variables
such as ${WAS_TEMP_DIR}/backup. Then, click OK.

The system property set using the first option takes precedence over the configuration property set using
the second option.

Changing the location of temporary workspace files

The administrative console workspace allows client applications to navigate the configuration. Each
workspace has its own repository location defined either in the system property or the property passed to
a workspace manager when creating the workspace: workspace.user.root or workspace.root, which is
calculated as %workspace.root%/user_ID/workspace/wstemp.

The default workspace root is calculated based on the user installation root: %user.install.root%/wstemp.
You can change the default location of temporary workspace files by doing the following:
v Distributed platforms: Change the setting for the system variable workspace.user.root or workspace.root
so its value is no longer set to the default location. Set the system variable when launching a Java
process using the -D option. For example, to set the default location the full path of the root of all users’
directories, use the following option:
-Dworkspace.user.root=full_path_for_root_of_all_user_directories

Backing up and restoring administrative configurations

WebSphere Application Server represents its administrative configurations as XML files. You should back
up configuration files on a regular basis.
1. Synchronize administrative configuration files.
a. Click System Administration > Nodes in the console navigation tree to access the Nodes page.
b. Click Full Resynchronize. The resynchronize operation resolves conflicts among configuration files
and can take several minutes to run.
2. Run the backupConfig command to back up configuration files.
3. Run the restoreConfig command to restore configuration files. Specify backup files that do not contain
invalid or inconsistent configurations.

Chapter 3. Setting up the application serving environment 197

Transformation of configuration files
The WebSphere Application Server master configuration repository stores configuration files for all the
nodes in the cell. When you upgrade the deployment manager from one release of WebSphere Application
Server to another, the configuration files that are stored in the master repository for the nodes on the old
release are converted into the format of the new release.

With this conversion, the deployment manager can process the configuration files uniformly. However,
nodes on an old release cannot readily use configuration files that are in the format of the new release.
WebSphere Application Server addresses the problem when it synchronizes the configuration files from the
master repository to a node on an old release. The configuration files are first transformed into the old
release format before they ship to the node. WebSphere Application Server performs the following
transformations on configuration documents:
v Changes the XML name space from the format of the new release to the format of the old release
v Strips out attributes of cell-level documents that are applicable to the new release only
v Strips out new resource definitions that are not understood by old release nodes

Server configuration files: Resources for learning

Use the following links to find relevant supplemental information about administering WebSphere
Application Server configuration files. The information resides on IBM and non-IBM Internet sites, whose
sponsors control the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

View links to additional information:

Administration
v IBM WebSphere Application Server Redbooks at http://publib-
b.boulder.ibm.com/Redbooks.nsf/Portals/WebSphere.
This site contains a listing of all WebSphere Application Server Redbooks.
v IBM developerWorks WebSphere at http://www.software.ibm.com/wsdd.
This site is the home of technical information for developers working with WebSphere products. You can
download WebSphere software, take a fast path to developerWorks zones, such as VisualAge Java or
WebSphere Application Server, learn about WebSphere products through a newcomers page, tutorials,
technology previews, training, and Redbooks, get answers to questions about WebSphere products, and
join the WebSphere community, where you can keep up with the latest developments and technical
papers.
v WebSphere Application Server Support page at
http://www.ibm.com/software/webservers/appserv/support.html.
Take advantage of the Web-based Support and Service resources from IBM to quickly find answers to
your technical questions. You can easily access this extensive Web-based support through the IBM
Software Support portal at URL http://www-3.ibm.com/software/support/ and search by product
category, or by product name. For example, if you are experiencing problems specific to WebSphere
Application Server, click WebSphere Application Server in the product list. The WebSphere Application
Server Support page appears.

Administering application servers

An application server configuration provides settings that control how an application server provides
services for running enterprise applications and their components.

198 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This section describes how to create and configure application servers in an existing application server
environment.

A WebSphere Application Server administrator can configure one or more application servers and perform
tasks such as the following:
1. Create application servers.
2. Manage application servers.
3. Configure transport chains.
4. Develop custom services.
5. Define processes for the application server. As part of defining processes, you can define:
6. Use the Java virtual machine.

After preparing a server, deploy an application or component on the server. See “Preparing to host
applications” on page 259 for a sample procedure that you might follow in configuring the application
server runtime and resources.

Application servers
Application servers extend a Web server’s capabilities to handle Web application requests, typically using
Java technology. An application server makes it possible for a server to generate a dynamic, customized
response to a client request.

For example, suppose--

1. A user at a Web browser on the public Internet visits a company Web site. The user requests to use
an application that provides access to data in a database.
2. The user request flows to the Web server.
3. The Web server determines that the request involves an application containing resources not handled
directly by the Web server (such as servlets). It forwards the request to a WebSphere Application
Server product.
4. The WebSphere Application Server product forwards the request to one of its application servers on
which the application is running.
5. The invoked application then processes the user request. For example:
v An application servlet prepares the user request for processing by an enterprise bean that performs
the database access.
v The application produces a dynamic Web page containing the results of the user query.
6. The application server collaborates with the Web server to return the results to the user at the Web
browser.

The WebSphere Application Server product provides multiple application servers that can be either
separately configured processes or nearly identical clones.

Understanding server templates

One step in the process of creating an application server is to specify a template. A server template is
used to define the configuration settings of the new server. You have the option of specifying the default
server template or choosing a template that is based on a server that already exists. The default template
will be used if you do not specify a different template when you create the server.

For information about creating server templates, see “Creating server templates” on page 201. For
information about listing server templates, see “Listing server templates” on page 201. For information
about deleting server templates, see “Deleting server templates” on page 201.

Chapter 3. Setting up the application serving environment 199

Creating application servers
For the Network Deployment and z/OS products, you can create a new application server using either the
createApplicationServer, createWebServer, or the createGenericServer wsadmin commands (see the
Administering applications and their environment PDF), or the Create New Application Server wizard in
the administrative console. You can also create a new application server when you add a cluster member
to a server cluster.

With WebSphere Application Server Version 6.0, you can now upgrade a portion of the nodes in a cell,
while leaving others at the older release level. This means that, for a period of time, you may be managing
servers that are at the current release and servers that are running the newer release in the same cell. In
this mixed environment, there are restrictions on what you can do with servers at the older release level.
They are:
v You can only create new server definitions on nodes that are running WebSphere Application Server
Version 6.0.
v When you create a new server definition, you must use a server configuration template, and that
template must be created from a WebSphere Application Server Version 6.0 server instance. You
cannot create (or use) a template from a WebSphere Application Server Version 5.x server instance.

There are no restrictions on what you can do with the servers running on the newer release level.

The steps below describe how to use the Create New Application Server page.
1. Go to the Application Servers page and click New. This brings you to the Create New Application
Server page. You can also create the new application server using the wsadmin
createApplicationServer command. For information, see “Commands for the AdminTask object” on
page 672.
2. Follow the instructions on the Create New Application Server page and define your application server.
a. Select a node for the application server.
b. Type in a name for the application server. The name must be unique within the node.
c. Select a template to be used in creating the new server. You can use a default application server
template for your new server or use an existing application server as a template. The new
application server will inherit all properties of the template server.
d. Select whether the new server will have unique ports for each HTTP transport. By default, this
option is enabled. If you select this option, you might need to update the alias list for the virtual
host that you plan to use with this server to contain these new port values. If you deselect this
option, ensure that the default port values do not conflict with other servers on the same physical
machine.
e. If you create the new server using an existing application server as a model, select whether to map
applications from the existing server to the new server. By default, this option is disabled.
3. To use multiple language encoding support in the administrative console, configure an application
server with UTF-8 encoding enabled.

The new application server appears in the list of servers on the Application Servers page.

Note that the application server created has many default values specified for it. An application server has
many properties that can be set and creating an application server on the Create New Application Server
page specifies values for only a few of the important properties. To view all of the properties of your
application server and to customize your application server further, click on the name of your application
server on the Application Servers page and change the settings for your application server as needed.

200 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring application servers for UTF-8 encoding
To use multiple language encoding support in the administrative console, you must configure an
application server with UTF-8 encoding enabled.
1. Create an application server or use an existing application server.
2. On the Application Server page, click on the name of the server you want enabled for UTF-8.
3. On the settings page for the selected application server, under Server Infrastructure, click Java and
Process Management > Process Definition.
4. On the Process Definition page, click Java Virtual Machine.
5. On the Java Virtual Machine page, specify -Dclient.encoding.override=UTF-8 for Generic JVM
Arguments and click OK.
6. Click Save on the console task bar.
7. Restart the application server.

Note that the autoRequestEncoding option does not work with UTF-8 encoding enabled. The default
behavior for WebSphere Application Server is, first, to check if charset is set on content type header. If it
is, then the product uses content type header for character encoding; if it is not, then the product uses
character encoding set on server using the system property default.client.encoding. If charset is not
present and the system property is not set, then the product uses ISO-8859-1. Enabling
autoRequestEncoding on a Web module changes the default behavior: if charset it not present on an
incoming request header, the product checks the Accept-Language header of the incoming request and
does encoding using the first language found in that header. If there is no charset on content type header
and no Accept language header, then the product uses character encoding set on server using the system
property default.client.encoding. As with the default behavior, if charset is not present and the system
property is not set, then the product uses ISO-8859-1.

Creating server templates

The steps below describe how to create a server template.
1. In the administrative console, go to Servers --> Application Servers --> and then click Templates.
This brings you to the Server templates page.
Note that you can also create server templates using the createServerTemplate wsadmin command.
For more information, see the Administering applications and their environment PDF.
2. On the Server templates page, click New. This brings you to the Select a server page.
3. Select the server that you want to use to create the new template, then click OK. This brings you to
the Create new server template page.
4. On the Create new server template page, enter the name of the new template and, optionally, a
description, then click OK. This brings you to the Server templates page. You should see your new
template on the list.

Listing server templates

The step below describes how to list your server templates.

In the administrative console, go to Servers --> Application Servers --> and then click Templates. This
brings you to the Server templates page, which lists all of the existing templates.

Note that you can also list server templates using the listServerTemplates wsadmin command. For more
information, see the Administering applications and their environment PDF.

Deleting server templates

The steps below describe how to delete a server template.

Chapter 3. Setting up the application serving environment 201

1. In the administrative console, go to Servers --> Application Servers --> and then click Templates.
This brings you to the Server templates page.
Note that you can also delete server templates using the deleteServerTemplate wsadmin command.
For more information, see the Administering applications and their environment PDF.
2. On the Server templates page, select the template you want to delete, then click Delete. The template
you chose is removed from the list.

Managing application servers

To view information about an application server, use the Application Servers panel on the administrative
console.

You can use the Application Servers panel of the administrative console, the “Getting started with
scripting” on page 365, or command line tools such as startServer and stopServer to manage your
application servers.

Note: With WebSphere Application Server Version 6.0, you can now upgrade a portion of the nodes in a
cell, while leaving others at the older release level. This means that, for a period of time, you may
be managing servers that are at the current release and servers that are running the newer release
in the same cell. Note that in this mixed environment, there are some restrictions on what you can
do with servers that are running the older release level. There are no restrictions on what you can
do with the servers that are running on the newer release level. For details, see “Creating
application servers” on page 200 and “Creating clusters” on page 271.
1. Access the Application Servers page. Click Servers > Application Servers in the console navigation
tree.
2. View information about application servers.
The Application Servers page lists application servers in the cell and the nodes holding the application
servers. The Network Deployment product also shows the status of the application servers. The status
indicates whether a server is started, stopped, or unavailable.
To view additional information about a particular application server or to further configure an application
server, click on the application server name under Name. This accesses the settings page for an
application server.
To view product information for an application server:
a. Verify that the application server is running.
b. Display the Runtime tab on the settings page for an application server.
c. Click Product Information.
The Product Information page displayed lists the WebSphere Application Server products installed for
the application server, the version and build levels for the products, the build dates, and any interim
fixes applied to the application server.

Note: You can also get this information by using the versionInfo command. For more information, see
″versionInfo command″ in the information center.
3. Create an application server.
a. Click Servers > Application Servers in the console navigation tree to access the Application
Servers page.
b. Click New, and follow the instructions on the Create New Application Server page.
4. Start your application server.
5. Monitor the running of application servers.
6. Stop your application server.
7. Delete an application server.

202 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 a. Click Servers > Application Servers in the console navigation tree to access the Application
Servers page.
b. Place a checkmark in the check box beside an application server to delete it.
c. Click Delete.
d. Click OK to confirm the deletion.

Server collection
Use this page to view information about and manage application servers, generic servers, Java Message
Service (JMS) servers, and Web servers.

Application Servers

The Application Servers page lists the application servers in the cell. You can use this page to create new
application servers, create application server templates, or delete existing application servers. You can
also use this page to start and stop these application servers.

The Network Deployment product also shows the status of the application servers. The status indicates
whether a server is running, stopped, or encountering problems.

To view this administrative console page, click Application Servers.

Generic Servers

The Generic Servers page lists the generic servers in the cell. You can use this page to create new
generic servers, create generic server templates, or delete existing generic servers. You can also use this
page to start and stop these generic servers.

The Network Deployment product also shows the status of the generic servers. The status indicates
whether a server is running, stopped, or encountering problems.

You can use this page to add or delete application servers.

To view this administrative console page, click Generic Servers.

Java Message Service (JMS) Servers

The JMS Servers page lists the JMS servers in the cell. You can use this page to start and stop these
JMS servers.

Each JMS server provides the functions of the JMS provider for a node in your administrative domain.
There can be at most one JMS server on each node in the administration domain, and any application
server within the domain can access JMS resources served by any JMS server on any node in the
domain.

Note: JMS servers apply only to WebSphere Application Server Version 5.x nodes. You cannot create a
JMS server on a node that is running WebSphere Application Server 6.0, but the existing Version
5.x JMS servers will continue to be displayed, and you can modify their properties. You can also
delete Version 5.x JMS servers.

To view this administrative console page, click JMS Servers.

Web Servers

Chapter 3. Setting up the application serving environment 203

The Web Servers page lists the Web servers in your administrative domain. You can use this page to
generate and propagate a Web server plug-in configuration file, create new Web servers, create new Web
server templates, or delete existing Web servers. You can also use this page to start and stop these Web
servers.

To view this administrative console page, click Web Servers.

Name:

Specifies a logical name for the server. For WebSphere Application Server, server names must be unique
within a node.

Node:

Specifies the name of the node holding the server.

Version:

Specifies the version of the WebSphere Application Server product on which the server runs.

Status:

Indicates whether the server is started or stopped. (Network Deployment only)

Note that if the status is Unavailable, the node agent is not running in that node and you must restart the
node agent before you can start the server.

Application server settings:

An application server is a server which provides services required to run enterprise applications. Use this
page to view or change the settings of an application server instance.

To view this administrative console page, click Servers > Application Servers >server_name.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.
The Runtime tab is available only when the server is running.

Name:

Specifies a logical name for the server. Server names must be unique within a node. However, for multiple
nodes within a cluster, you may have different servers with the same server name as long as the server
and node pair are unique.

For example, a server named server1 in a node named node1 in the same cluster with a server named
server1 in a node named node2 is allowed. Configuring two servers named server1 in the same node is
not allowed. WebSphere Application Server uses the server name for administrative actions, such as
referencing the server in scripting.

Data type String

Default server1

Run in development mode:

204 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Enabling this option may reduce the startup time of an application server. This may include JVM settings
such as disabling bytecode verification and reducing JIT compilation costs. Do not enable this setting on
production servers. This setting is only available on application servers running WebSphere Application
Server Version 6.0 and later.

Specifies that you want to use the JVM settings -Xverify and -Xquickstart on startup. After selecting this
option, save the configuration and restart the server to activate development mode.

The default setting for this option is false, which indicates that the server will not be started in
development mode. Setting this option to true specifies that the server will be started in development
mode (with settings that will speed server startup time).

Data type Boolean

Default false

Parallel start:

Select this field to start the server on multiple threads. This might shorten the startup time.

Specifies that you want the server components, services, and applications to start in parallel rather than
sequentially.

The default setting for this option is true, which indicates that the server be started using multiple threads.
Setting this option to false specifies that the server will not be started in using multiple threads (which
may lengthen startup time).

Note that the order in which the applications start depends on the weights you assigned to each them.
Applications that have the same weight are started in parallel. You set an application’s weight with the
Starting weight option on the Applications > Enterprise Applications > application_name page of the
Administrative Console. For more information about the Starting weight option, see the Installing your
application serving environment PDF.

Data type Boolean

Default true

Class loader policy:

Select whether there is a single class loader to load all applications or a different class loader for each
application.

Class loading mode:

Specifies whether the class loader should search in the parent class loader or in the application class
loader first to load a class. The standard for Developer Kit class loaders and WebSphere Application
Server class loaders is Parent first.

If you select Parent last, your application can override classes contained in the parent class loader, but
this action can potentially result in ClassCastException or linkage errors if you have mixed use of
overridden classes and non-overridden classes.

Process Id:

The native operating system’s process ID for this server.

The process ID property is read only. The system automatically generates the value.

Chapter 3. Setting up the application serving environment 205

Cell name:

The name of the cell in which this server is running.

The Cell name property is read only.

Node name:

The name of the node in which this server is running.

The Node name property is read only.

State:

The run-time execution state for this server.

The State property is read only.

Ports collection:

Use this page to view and manage communication ports used by run-time components running within a
process. Communication ports provide host and port specifications for a server.

To view this administrative console page, click Servers > Application Servers >server_name
Communications > Ports.

Note that this page displays only when you are working with ports for application servers.

Port Name:

Specifies the name of a port. Each name must be unique within the server.

Host:

Specifies the IP address, domain name server (DNS) host name with domain name suffix, or just the DNS
host name, used by a client to request a resource (such as the naming service, or administrative service).

Port:

Specifies the port for which the service is configured to accept client requests. The port value is used in
conjunction with the host name.

Transport Details:

Provides a link to the transport chains associated with this port. If no transport chains are associated with
this port, the string ″No associated transports″ appears in this column.

Ports settings:

Use this to view and change the configuration for a communication port used by run-time components
running within a process. A communication port provides host and port specifications for a server.

For WebSphere Application Server for Network Deployment, you can view this administrative console page
by clicking one of the following paths:
v Servers > Application Servers >server_name > Ports >port_name
v Servers > JMS Servers >server_name > Security Port Endpoint
v Servers > JMS Servers >server_name > Ports >port_name

206 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Port Name:

Specifies the name of the port. The name must be unique within the server.

Note that this field displays only when you are defining a port for an application server. You can select a
radio button to:
Well-known Port
select a previously defined port from the drop down list
User-defined Port
create a port with a new name by entering the name in the text box

Data type String

Host:

Specifies the IP address, domain name server (DNS) host name with domain name suffix, or just the DNS
host name, used by a client to request a resource (such as the naming service, administrative service, or
JMS broker).

For example, if the host name is myhost, the fully qualified DNS name can be myhost.myco.com and the IP
address can be 155.123.88.201.

Host names on the ports can be resolvable names or IP addresses. The server will bind to the specific
host name or IP address that is supplied. That port will only be accessible through the IP address that is
resolved from the given host name or IP address. The IP address may be of the IPv4 (Internet Protocol
Version 4) format for all platforms, and IPv6 (Internet Protocol Version 6) format on specific operating
systems where the server supports IPv6.

Data type String

Default * (asterisk)

Port:

Specifies the port for which the service is configured to accept client requests. The port value is used in
conjunction with the host name.

Port numbers in the server can be reused among multiple ports as long as they have host names that
resolve to unique IP addresses and there is not a port with the same port number and a wildcard ( * ) host
name. A port number is valid in the range of 0 and 65535. 0 specifies that the server should bind to any
ephemeral port available.

Data type Integer

Default None
Range 1-65536

Custom property collection:

Use this page to view and manage arbitrary name-value pairs of data, where the name is a property key
and the value is a string value that can be used to set internal system configuration properties.

The administrative console contains several Custom Properties pages that work similarly. To view one of
these administrative pages, click a Custom Properties link.

Name:

Chapter 3. Setting up the application serving environment 207

Specifies the name (or key) for the property.

Do not start your property names with was. because this prefix is reserved for properties that are
predefined in WebSphere Application Server.

Value:

Specifies the value paired with the specified name.

Description:

Provides information about the name-value pair.

Custom property settings:

Use this page to configure arbitrary name-value pairs of data, where the name is a property key and the
value is a string value that can be used to set internal system configuration properties. Defining a new
property enables you to configure a setting beyond that which is available in the administrative console.

For Network Deployment and the z/OS platform, you can view this administrative console page by clicking
one of the following paths:
v Servers > Application Servers >server_name. Then, under Server Infrastructure, click Administration
> Custom Properties
v Servers >JMS Servers > server_name. Then, under Server Infrastructure, click Administration >
Custom Properties

Name:

Specifies the name (or key) for the property.

Do not start your property names with was. because this prefix is reserved for properties that are
predefined in WebSphere Application Server.

Data type String

Value:

Specifies the value paired with the specified name.

Data type String

Description:

Provides information about the name and value pair.

Data type String

Server component collection:

Use this page to view information about and manage server component types such as application servers,
messaging servers, or name servers.

To view this administrative console page, click Servers > Application Servers >server_name. Then,
under Server Infrastructure, click Administration > Server Components.

208 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Type:

Specifies the type of internal server.

Server component settings:

Use this page to view or configure a server component instance.

To view this administrative console, click Servers > Application Servers >server_name. Then, under
Server Infrastructure, click Administration > Server Components >server_component_name.

Name:

Specifies the name of the component.

Data type String

Initial State:

Specifies the desired state of the component when the server process starts. The options are: Started and
Stopped. The default is Started.

Data type String

Default Started

Thread pool collection:

Use this page to select or create a group of threads that an application server uses. Requests are sent to
the server through any of the HTTP transports. A thread pool enables components of the server to reuse
threads to eliminate the need to create new threads at run time. Creating new threads expends time and
resources.

To view this administrative console page, click Servers > Application Servers >server_name > Thread
Pools. (You can reach this page through more than one navigational route.)

Thread pool settings:

Use this page to configure a group of threads that an application server uses. Requests are sent to the
server through any of the HTTP transport channels or HTTP transports. A thread pool enables components
of the server to reuse threads to eliminate the need to create new threads at run time. Creating new
threads expends time and resources.

To view this administrative console page, click Servers > Application Servers >server_name > Thread
Pools, then select the thread pool. (You can reach this page through more than one navigational route.)

Minimum size:

Specifies the minimum number of threads to allow in the pool.

Data type Integer

Default 10

Maximum size:

Specifies the maximum number of threads to allow in the pool.

Chapter 3. Setting up the application serving environment 209

If your Tivoli Performance Viewer shows the Percent Maxed metric to remain consistently in the double
digits, consider increasing the Maximum size. The Percent Maxed metric indicates the amount of time that
the configured threads are used. If there are several simultaneous clients connecting to the server-side
ORB, increase the size to support up to 1000 clients.

Data type Integer

Default 50
Recommended 50 (25 on Linux systems)

Thread inactivity timeout:

Specifies the number of milliseconds of inactivity that should elapse before a thread is reclaimed. A value
of 0 indicates not to wait and a negative value (less than 0) means to wait forever.

Note: The administrative console does not allow you to set the inactivity timeout to a negative number. To
do this you must modify the value directly in the server.xml file.

Data type Integer

Units Milliseconds
Default 3500

Allow thread allocation beyond maximum thread size:

Specifies whether the number of threads can increase beyond the maximum size configured for the thread
pool.

Data type Boolean

Default Not enabled (false)

Generic server settings:

Use this page to view or change the settings of a generic server.

A generic server is a server that is managed in the WebSphere Application Server administrative domain,
although it is not a server that is supplied by the WebSphere Application Server product. The generic
server can be any server or process that is necessary to support the Application Server environment,
including a Java server, a C or C++ server or process, or a Remote Method Invocation (RMI) server.

To view this administrative console page, click Servers > Generic Servers >server_name.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.
The Runtime tab is available only when the server is running.

Name:

Specifies a logical name for the generic server.

Generic server names must be unique within a node. For multiple nodes within a cluster, you can have
different generic servers with the same server name as long as the server and node pair are unique. For
example, a server named server1 in a node named node1 in the same cluster with a server named
server1 in a node named node2 is allowed. Configuring two servers named server1 in the same node is
not allowed. WebSphere Application Server uses the server name for administrative actions, such as
referencing the server in scripting.

210 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
It is highly recommended that you use a naming scheme that makes it easy to distinguish your generic
application servers from regular WebSphere Application Servers. This will enable you to quickly determine
whether to use the Terminate or Stop button in the administrative console to stop a specific application
server.

You must use the Terminate button to stop a generic application server.

Data type String

Default

Starting servers
Starting a server starts a new server process based on the process definition settings of the current server
configuration. The node agent for the node on which the Application Server resides must be running
before you can start the Application Server.

If you need to restart a server, follow the directions in this article for starting servers. The procedure that
applies to starting servers also applies to restarting servers.

Note: If you created a new server definition using a base WebSphere Application Server, you cannot start,
stop, or manage the new server using the original base Application Server.

Note: After you start an Application Server, other processes might not discover the running Application
Server immediately. Application Servers are discovered by the node agent. Node agents are
discovered by the deployment manager. Node agents usually can discover local Application Servers
quickly but it can take a deployment manager from 2 to 60 seconds to discover a node agent.

Note: If you are using clusters, note that the Initial State property of the Application Server
subcomponent (Servers > Application Server > server_name > Administration > Server
Components > Application Server) is not intended to be used to control the state of individual
servers in the cluster at the time the cluster is started. It is intended only as a way to control the
state of the Application Server subcomponent of a server. It is best to start and stop the individual
servers of a cluster using the Server options of the Administrative Console or command line
commands (startServer and stopServer).

There are several options for starting an Application Server:

v If you are using Windows, you can use the Start menu to start the Application Server. If you
are using the Network Deployment version of the product, click Start > Programs > IBM WebSphere >
Network Deployment v6.0 > Start the Manager You can check that the server has successfully
started by checking the startServer.log file. If the server has successfully started, the last two lines of
the startServer.log file reads:
Server launched. Waiting for initialization status.
Server server1 open for e-business; process id is 1932.
The startServer.log file is located in the <drive>:\Program
Files\IBM\WebSphere\AppServer\profiles\profile_name\logs\server1 directory if you have installed
your server with the default settings. The server name and process id vary depending on your settings.
v On distributed platforms, use the startServer command to start an Application Server from the
command line.
If the node agent for the node on which the Application Server resides is not running, run the startNode
command and then run the startServer command.

v On AIX, you can use the command line to start the server. Use the startServer command
from the /usr/WebSphere/AppServer/bin directory, as shown below. To start a server that is associated

Chapter 3. Setting up the application serving environment 211

 with a non-default profile, issue the startServer command from the
/opt/WebSphere/AppServer/profiles/profile_name/bin directory.
# ./startServer.sh server1

Use the startManager command from the /usr/IBM/WebSphere/AppServer/product/bin directory:

# ./startManager.sh

You can check that the server has successfully started by checking the startServer.log file. If the
server has successfully started, the last two lines of the startServer.log file reads:
Server launched. Waiting for initialization status.
Server server1 open for e-business; process id is 1932.

On AIX, the startServer.log file is located in the

/usr/IBM/WebSphere/AppServer/profiles/profile_name/logs/server1/ directory.
v Start an Application Server using the administrative console.
1. Click Servers > Application Servers from the administrative console navigation tree to go to the
Application Server page.
2. If the node agent for the node on which the Application Server resides is not running, click Restart
or Restart all Servers on Node on the Node Agents page (System Administration > Node
agents) to start the node agent.
If the node agent does not start, run the startNode command and then run the startServer
command.. Once a node agent completely stops running and remains stopped, you cannot remotely
start the node agent from the Node Agents page. You must run the startNode command to start the
node agent on the node where it runs.
3. Select the Application Server and click Start.
4. View the Status value and any messages or logs to see whether the Application Server starts.
v Start an Application Server for tracing and debugging.
To start the Application Server with standard Java debugging enabled:
1. Click Servers > Application Servers from the administrative console navigation tree. Then, click
the Application Server whose processes you want to trace and debug, then Java and Process
Management > Process Definition > Java Virtual Machine.
2. On the Java Virtual Machine page, place a checkmark in the check box for the Debug Mode setting
to enable the standard Java debugger. If needed, set debug arguments. Then, click OK.
3. Save the changes to a configuration file.
4. Stop the Application Server.
5. Start the Application Server again as described previously.

Once the server is started, you can install your applications.

Running application servers from a non-root user

By default, each base WebSphere Application Server node uses the root user ID to run all application
server processes. However, you can run all application server processes under the same non-root user
and user group. This task describes how to run an application server process from a non-root user.

If global security is enabled, the user registry must not be Local OS. Using the Local OS user registry
requires the application server to run as root. Refer to the Securing applications and their environment
PDF for details.

Run your application servers as non-root when you no longer want to use root authority. For security or
administrative reasons, you may want to change to non-root user IDs. Perform this task at any time to
change the permissions of an application server. You must restart the application server in order for the
changes to take effect.

212 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If your application server is part of a cell, see “Running an application server from a non-root user and the
node agent from root” on page 214 or “Running an Application Server and node agent from a non-root
user” on page 215

Note: If you are using the Tivoli Access Manager (TAM) to perform authentication or authorization for
WebSphere Application Server, it is important to be aware of potential permissions problems. For
more information, see the Securing applications and their environment PDF.

For the following steps, assume that:

v was1 is the user to run the application server
v wasgroup is the primary user group for user was1
v wasnode is the node name
v server1 is the application server
v /opt/WebSphere/AppServer is the installation root
v nodeProfile1 is the profile name.

Note: For information about creating a profile, see the Administering applications and their environment
PDF.

To configure an application server to run as non-root, complete the following steps.

1. Log on to the application server system as the root user.
2. Create the user ID was1 with a primary user group of wasgroup. The user ID, was1, is an example. You
can name the user something else.
3. Log off and back on as root.
4. Start server1 as root. Run the startServer.sh script from the /bin directory of the installation root:
startServer.sh server1
5. Specify user and group ID values for the Run As User and Run As Group settings for a server:
a. Start the administrative console.
b. Go to the Process execution page of the administrative console. You must define all three
properties in the following table. Click Servers > Application Servers > server1 > Server
Infrastructure > Java and Process Management > Process Execution and change all of the
following values:

Property Value
Run As User was1
Run As Group wasgroup
UMASK 022

c. Click OK.
d. Save the configuration.
6. Stop the application server. Use the stopServer.sh script from the /bin directory of the installation
root:
stopServer.sh server1
7. Change file permissions as the root user. The following example assumes that the installation root
directory for WebSphere Application Server is /opt/WebSphere/AppServer:
chgrp wasgroup /opt/WebSphere
chgrp wasgroup /opt/WebSphere/AppServer
chgrp -R wasgroup /opt/WebSphere/AppServer/cloudscape
chgrp -R wasgroup /opt/WebSphere/AppServer/profiles/nodeProfile1
chmod g+wr /opt/WebSphere

Chapter 3. Setting up the application serving environment 213

 chmod g+wr /opt/WebSphere/AppServer
chmod -R g+wr /opt/WebSphere/AppServer/cloudscape
chmod -R g+wr /opt/WebSphere/AppServer/profiles/nodeProfile1
8. Log on to the application server system as was1.
9. Start server1 as was1. Run the startServer.sh script from the /bin directory of the installation root:
startServer.sh server1
10. If creating another server with a different user ID, follow this procedure again for the new user ID and
server name.
The two user IDs must share the same group, wasgroup.

You can start an application server from a non-root user.

Running an application server from a non-root user and the node agent from root
By default, each base WebSphere Application Server node on a Linux and UNIX platform uses the root
user to run application servers. However, you can use a non-root user to run application servers. This task
describes how to configure an application server to run as non-root while letting the node agent process
run as root.

If global security is enabled, it is not recommended that the Local OS be used for user registry. In general,
using the Local OS user registry requires that all processes run as root. Refer to Local operating system
user registries for details. If you are attempting to run an Application Server as root in WebSphere
Application Server Version 6 when you previously used a non-root user ID on Linux and UNIX platforms in
Version 5.x, see ″Migrating a previously non-root configuration to root″ in the information center.

Using a non-root user ID to run application servers can be done by setting all the application servers to
run under the same operating system group. Run your application servers as non-root when you no longer
want to use root authority. For security or administrative reasons, you may want to change to non-root
user IDs. Perform this task at any time to change the permissions of an application server. You must
restart the application servers in order for the changes to take effect.

Note: If you are using the Tivoli Access Manager (TAM) to perform authentication or authorization for
WebSphere Application Server, it is important to be aware of potential permissions problems. For
more information, see “Tivoli Access Manager JACC provider configuration” on page 1838.
1. Log on to the application server system as root.
2. Create the was1 user and wasgroup group that you can use to run the application server. If you will be
using peer recovery with your transaction logs on a shared system (such as NAS), between two or
more machines, create users and groups with the same identification numbers on all machines
participating in peer recovery. This ensures that the non-root users and groups match across
machines.
3. Add users root and was1 to the wasgroup group.
4. Log off and back on.
5. Log on to the Network Deployment system as root.
6. If it is not started, start the deployment manager process with the startManager.sh script from the
/bin directory of the installation root:
startManager.sh
7. Configure application server properties for the root and was1 users. Use the administrative console
on the deployment manager to complete the following steps:
a. Define the node agent to run as a root process. You must define all three properties in the
following table. Click System Administration> Node agents > nodeagent (for the node)Server
Infrastructure > Java and Process Management > Process Definition > Process Execution
and change all of the following values:

214 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Property Value
Run As User root
Run As Group wasgroup
UMASK 002

b. Define each application server to run as a was1 process. Substitute the name of each server for
server1. You must define all three properties in the following table. Click Servers > Application
Servers > server1 > Server Infrastructure > Java and Process Management > Process
Definition > rocess Execution and change all of the following values:

Property Value
Run As User was1
Run As Group wasgroup
UMASK 002

c. Save and synchronize all nodes.

8. Log on to the application server system as root.
9. Ensure that all servers on the application server system are stopped, including the server1 process.
Use the stopServer.sh script from the /bin directory of the installation root:
stopServer.sh server1 -user userID -password password
10. Ensure that the node agent process is stopped. Use the stopNode.sh script from the /bin directory of
the installation root:
stopNode.sh -user userID -password password
11. As root, use operating system tools to change the following file permissions on the application server
system:
chgrp wasgroup /opt/WebSphere
chgrp wasgroup /opt/WebSphere/AppServer
chgrp -R wasgroup /opt/WebSphere/AppServer/cloudscape
chgrp -R wasgroup /opt/WebSphere/AppServer/profiles/nodeProfile1
chmod g+wr /opt/WebSphere
chmod g+wr /opt/WebSphere/AppServer
chmod -R g+wr /opt/WebSphere/AppServer/cloudscape
chmod -R g+wr /opt/WebSphere/AppServer/profiles/nodeProfile1
12. Start the node agent process from root. Use the startNode.sh script from the /bin directory of the
installation root:
startNode.sh
13. Log on to the application server system as the was1 user.
14. Start all application servers from the was1 user. Use the startServer.sh script from the /bin directory
of the installation root:
startServer.sh server1

You can start an application server from a non-root user and run the node agent as root.

Running an Application Server and node agent from a non-root user

By default, each base Application Server node on a Linux, or UNIX operating system uses the root user ID
to run the node agent process and all Application Server processes. However, you can run the node agent
and all Application Server processes under the same non-root user and user group. If you do run the node
agent process with a non-root user ID, you must run all Application Server processes that the node agent
controls under the same non-root user ID.

Chapter 3. Setting up the application serving environment 215

If global security is enabled, the user registry must not be Local OS. Using the Local OS user registry
requires the node agent to run as root. Refer to the Securing applications and their environment PDF for
details.

Using the same non-root user and user group gives the node agent process the operating system
permissions to start all other server processes.

Run your application servers and node agent as non-root when you no longer want to use root authority.
For security or administrative reasons, you may want to change to non-root user IDs. Perform this task at
any time to change the permissions of a node agent or application server. You must restart the node agent
and application servers in order for the changes to take effect.

Note: If you are using the Tivoli Access Manager (TAM) to perform authentication or authorization for
WebSphere Application Server, it is important to be aware of potential permissions problems. For
more information, see the Securing applications and their environment PDF.

For the steps that follow, assume that:

v wasadmin is the user to run all servers
v wasnode is the node name
v wascell is the cell name
v server1 is the Application Server
v /opt/WebSphere/AppServer is the installation root for the base node
v wasgroup is the group that will run all servers, with wasadmin as a member
v nodeProfile1 is the profile name

Note: For information about creating a profile, see the Administering applications and their environment
PDF.

To configure a user ID to run the node agent and all server processes, complete the following steps.
1. Log on to the Application Server system as root.
2. Create user wasadmin with primary group wasgroup. If you will be using peer recovery with your
transaction logs on a shared system (such as NAS) between two or more machines, you will need to
create a user and group with the same identification numbers on all machines participating in peer
recovery. This will ensure that the non-root users and groups match across machines.
3. Log off and back on.
4. Log on to the Network Deployment system as root.
5. If the deployment manager process is not started, start it with the startManager.sh script from the
/bin directory of the installation root:
startManager.sh
6. Start the administrative console.
7. Define the node agent to run as a wasadmin process using the administrative console of the
deployment manager. You must define all three properties in the following table. Click System
Administration > Node agents > nodeagent (for the node)Server Infrastructure > Java and
Process Management > Process Definition > Process Execution and change all of the following
values:

Property Value
Run As User wasadmin
Run As Group wasgroup
UMASK 022

216 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Note: Make sure that the node agent is running if you are going to change the value specified for
either the Run As Group or Run As User property. If the value for either of these properties is
changed while the node agent is not running, the Deployment Manager can not push the
changes to the node.
8. Define each Application Server to run as a wasadmin process. Substitute the name of each server for
server1. You must define all three properties in the following table. Click Servers > Application
Servers > server1 > Server Infrastructure > Java and Process Management > Process
Execution and change all of the following values:

Property Value
Run As User wasadmin
Run As Group wasgroup
UMASK 022

9. Save and synchronize all nodes. Stop all changed application servers and the node agent from the
administrative console.
10. Log on to the Application Server system as root.
11. Ensure that all servers and the node agent are stopped.
12. As root, use operating system tools to change file permissions on Linux and UNIX platforms:
chgrp wasgroup /opt/WebSphere
chgrp wasgroup /opt/WebSphere/AppServer
chgrp -R wasgroup /opt/WebSphere/AppServer/cloudscape
chgrp -R wasgroup /opt/WebSphere/AppServer/profiles/nodeProfile1
chmod g+wr /opt/WebSphere
chmod g+wr /opt/WebSphere/AppServer
chmod -R g+wr /opt/WebSphere/AppServer/cloudscape
chmod -R g+wr /opt/WebSphere/AppServer/profiles/nodeProfile1
13. Log in as wasadmin on the Application Server system.
14. From wasadmin, run the startNode.sh script from the /bin directory of the installation root to start the
node agent:
startnode.sh node1
15. Log into the administrative console and start the application servers.

You can start an application server and the node agent from a non-root user.

Detecting and handling problems with run-time components

You must monitor the status of run-time components to ensure that, once started, they remain operational
as needed.
1. Regularly examine the status of run-time components. Browse messages displayed under Websphere
Runtime Messages in the status area at the bottom of the console. The run-time event messages
marked with a red X provide detailed information on event processing. You can also use the Logging
and Tracing page of the administrative console to monitor the status of run-time components. Click
Troubleshooting > Logs and Trace in the console navigation tree to access the page.
2. If an application stops running when it should be operational, examine the application’s status on an
Applications page and try restarting the application. If messages indicate that a server has stopped
running, use the Application Servers page to try restarting the server. If a cluster of servers has
stopped running, use the Server Cluster page to try restarting the cluster. If the status of an application
server is Unavailable, the node agent is not running in that node and you must restart the node agent
before you can start the server.
3. If the run-time components do not restart, reexamine the messages and read information on problem
determination to help you to restart the components.

Chapter 3. Setting up the application serving environment 217

Stopping servers
Stopping an application server stops a server process based on the process definition settings in the
current application server configuration.

v In Windows, you can use the Start menu to stop your application server. Cllick Start >
Programs > IBM WebSphere > Network Deployment v6.0 > Stop the server. When the server stops
successfully, the stopServer.log file contains the following in the last two lines:
Server stop request issued. Waiting for stop status.
Server server1 stop completed.
The server name varies depending on your settings.
v Stop the application server from the command line. In distributed environments, you can use the
stopServer command to stop a single server or the stopManager command to stop the deployment
manager. In AIX, use the stopServer or the stopManager command from the
/usr/WebSphere/AppServer/bin directory:
# ./stopServer.sh server1
# ./stopManager.sh
v Use the administrative console to stop an application server:
1. In the administrative console, click Servers > Application Servers.
2. Select the application server that you want stopped and click Stop.
3. Confirm that you want to stop the application server.
4. View the Status value and any messages or logs to see whether the application server stops.

Core group service settings

Use this page to set up the application server properties that relate to core groups.

To view this administrative console page, click Servers > Application servers> > server. Then under
Additional properties, select Core group service.

Click Save to save and synchronize your changes with all managed nodes.

Core group name: Specifies the name of the core group that contains this application server as a
member. To move a server to a different core group, in the administrative console, click Servers > Core
groups > Core group settings > core_group> Core group servers.

Data type String

Allow activation: When selected, high availability group members can be activated on this application
server.

Is alive timer: Specifies the time interval, in seconds, at which the high availability manager will check
the health of all of the active high availability group members that are running in this application server
process. An active group member is a member that is able to accept work. If a group member fails, the
application server on which the group member resides is restarted. If -1 is specified, the timer is disabled.
If 0 (zero) is specified, the default value of 120 seconds is used.

Important: The value specified for this property can be overridden for the high availability groups using a
particular policy if the Is alive timer property for that policy specifies a different time interval. If
the Is alive timer setting specified for a policy is greater than 0 (zero), the high availability
manager uses that time interval, instead of the one specified at this level, when determining
how frequently it should check the health of a high availability group member using that
particular policy.

Data type Any integer between -1 and 600, inclusive

218 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Default 120 seconds

Transport buffer size: Specifies the buffer size, in megabytes, of the underlying group communication
transport. The minimum buffer size is 10 megabytes.

Data type String

Default 10 megabytes

Creating generic servers

There are two types of generic application servers:
v Non-Java applications or processes.
v Java applications or processes

You can use the wsadmin tool or the Generic servers panel of the administrative console to create either
type.

Note: For the Base WebSphere Application Server product, although you can use the administrative
console to create a generic application server definition, you cannot use it to start, stop or, in any
way, control or manage that application server. The Base product administrative console can only
be used to create server definitions and, if necessary, adjust the server definitions that it creates. To
manage Base generic application servers, use the wsadmin tool.
v Create a non-Java application as a generic server. The following steps describe how to use the
administrative console to create a non-Java application as a generic application server.
1. Select Servers > Generic servers
2. Click New. You can then specify the name of the generic server you are creating.
3. Type in a name for the generic server. The name must be unique within the node. It is highly
recommended that you use a naming scheme that makes it easy to distinguish your generic
application servers from regular Websphere Application Servers. This will enable you to quickly
determine whether to use the Terminate or Stop button in the administrative console to stop
specific application server. You must use the Terminate button to stop a generic application server.
4. Select a template to use in creating the new server. You can use a default application server
template for your new server or use an existing application server as a template. The new
application server will inherit all properties of the template server. If you create the new server
using an existing application server do not enable the option to map applications from the existing
server to the new server. This option does not apply for a generic server.
5. Click Next
6. Click Finish. The generic server now appears as an option on the Generic servers panel in the
administrative console.
7. On the Generic servers panel, click on the name of the generic server.
8. Under Additional Properties click Process Definition.
9. In the Executable name field under General Properties, enter the name of the non-WebSphere
Application Server program that is to be launched when you start this generic server. Executable
target type and Executable target properties are not used for non-Java applications. Executable
target type and Executable target properties are only used for Java applications
10. Click OK.
v Create a Java application as a generic server: The following steps describe how to use the
administrative console to create a Java application as a generic application server.
1. Select Servers > Generic servers
2. Click New. You can then specify the name of the generic server you are creating.

Chapter 3. Setting up the application serving environment 219

 3. Type in a name for the generic server. The name must be unique within the node. It is highly
recommended that you use a naming scheme that makes it easy to distinguish your generic
application servers from regular Websphere Application Servers. This will enable you to quickly
determine whether to use the Terminate or Stop button in the administrative console to stop
specific application server. You must use the Terminate button to stop a generic application server.
4. Click Next
5. Click Finish. The generic server now appears as an option on the Applications Server panel in
the administrative console.
6. Click Finish. The generic server now appears as an option on the Generic servers panel in the
administrative console.
7. On the Generic servers panel, click on the name of the generic server.
8. Under Additional Properties click Process Definition.
9. In the Executable name field under General Properties, enter the path for Websphere Application
Server’s default JVM (${JAVA_HOME}/bin/java), which will be used to run the Java application
when you start this generic server.
10. In the Executable target type field under General Properties, select whether a Java class name,
JAVA_CLASS, or the name of an executable JAR file, EXECUTABLE_JAR, will be used as the
executable target of this Java process. The default for Websphere Application Server is
JAVA_CLASS.
11. In the Executable target field under General Properties, enter the name of the executable target.
(Depending on the executable target type, this will be either a Java class containing a main()
method, or the name of an executable JAR file.) The default for Websphere Application Server is
com.ibm.ws.runtime.WsServer.
12. Click OK.

Note: If the generic server is to run an application server other than the WebSphere Application
Server, leave the Executable name field set to the default value and specify the Java class
containing the main function for your application serve in the Executable target field.

You can now start and terminate the generic server whenever you want to start or terminate the
non-WebSphere Application Server server or process associated with this server.

Starting and terminating generic servers

This topic describes how to start and terminate generic servers.

If you created a generic server on a Base WebSphere Application Server, you cannot start, terminate, or
monitor this server with the Base Application Server administrative console. You must use the wsadmin
tool to manage Base generic servers.

Starting generic servers

There are two ways to start a generic server in a Network Deployment environment:
v Use the administrative console:
1. From the administrative console navigation tree, select Servers > Application Servers.
2. Select the check box beside the name of the generic server, and then click Start.
3. View the Status value and any messages or logs to see whether the generic server starts.
v Use the MBean NodeAgent launchProcess operation of the wsadmin tool.

Terminating generic servers

There are two ways to terminate a generic server in a Network Deployment environment:
v Use the administrative console:

220 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 1. From the administrative console navigation tree, select Servers > Application Servers.
2. Select the check box beside the name of the generic server, and then click Terminate.
3. View the Status value and any messages or logs to see whether the generic server terminates.

Note: The Stop and Stop Immediate buttons on the administrative console do not work for generic
servers.
v Use the MBean terminate launchProcess operation of the wsadmin tool.

Configuring transport chains

You need to configure transport chains to provide networking services to such functions as the service
integration bus component of IBM service integration technologies, WebSphere Secure Caching Proxy,
and the high availability manager core group bridge service.

A transport chain consists of one or more types of channels, each of which supports a different type of I/O
protocol, such as TCP or HTTP. Network ports can be shared among all of the channels within a chain.
The channel framework function automatically distributes a request arriving on that port to the correct I/O
protocol channel for processing. To define these channels:
1. Create a transport chain: You can either use the administrative console or wsadmin commands to
create a transport chain. If you want to use the administrative console:
a. Ensure that a port is available for the new transport chain.
b. In the administrative console, click Servers > Application servers >server_name, and then click
on one of the following:
v Under Web container settings, click Web container transport chains.
v Under Server messaging, click either Messaging engine inbound transports or WebSphere
MQ link inbound transports.
c. Click New. The Create New Transport Chain wizard initializes. During the transport chain creation
process, you are asked to:
v Specify a name for the new chain.
v Select a transport chain template
v Select a port, if one is available to which the new transport chain will be bound. If a port is not
available or you want to define a new port, specify a port name, the host name or IP address for
that port, and a valid port number.
When you click Finish, the new transport chain is added to the list of defined transport chains on
the Transport chain panel.
2. Click on the transport chain’s name to view the configuration settings that are in effect for the transport
channels contained in this chain. To change any of these settings:
a. Click on the channel that requires changes to its settings.
b. Make your changes to the configuration settings. Some of the settings, such as the port number
are determined by what is specified for the transport chain when it is created and cannot be
changed.
c. Click on Custom properties to set any custom properties that have been defined for your system.
3. When you have made all of your changes, click OK.
4. Stop the application server and start it again. You must stop the application server and start it again
before the configuration changes you made take affect.

Transport chains
Transport chains represent a network protocol stack that is used for I/O operations within an application
server environment. Transport chains are part of the channel framework function that provides a common

Chapter 3. Setting up the application serving environment 221

networking service for all components, including the service integration bus component of IBM service
integration technologies, WebSphere Secure Caching Proxy, and the high availability manager core group
bridge service.

A transport chain consists of one or more types of channels, each of which supports a different type of I/O
protocol, such as TCP, DCS or HTTP. Network ports can be shared among all of the channels within a
chain. The channel framework function automatically distributes a request arriving on that port to the
correct I/O protocol channel for processing.

The transport chain configuration settings determine which I/O protocols are supported for that chain.
Following are some of the more common types of channels. Custom channels that support requirements
unique to a particular customer or environment can also be added to a transport chain.
TCP channel
Used to provide client applications with persistent connections within a Local Area Network (LAN).
When configuring a TCP channel, you can specify a list of IP addresses that are allowed to make
inbound connections and a list of IP addresses that are not allowed to make inbound connections.
You can also specify the thread pool that this channel uses, which allows you to segregate work
by the port that the application server is listening on.
HTTP channel
Used to enable communication with remote servers. It implements the HTTP 1.0 and 1.1
standards and is used by other channels, such as the Web container channel, to server HTTP
requests and to send HTTP specific information to servlets expecting this type of information.
HTTP Tunnel channel
Used to provide client applications with persistent HTTP connections to remote hosts that are
either blocked by firewalls or require an HTTP proxy server (including authentication) or both. An
HTTP Tunnel channel enables the exchange of application data in the body of an HTTP request or
response that is sent to or received from a remote server. An HTTP Tunnel channel also enables
client-side applications to poll the remote host and to use HTTP requests to either send data from
the client or to receive data from an application server. In either case, neither the client nor the
application server is aware that HTTP is being used to exchange the data.
Web container channel
Used to create a bridge in the transport chain between an HTTP inbound channel and a servlet
and JavaServer Pages (JSP) engine.
DCS channel
Used by the core group bridge service, the data replication service (DRS), and the high availability
manger to transfer data, objects, or events among application servers.
MQ channel
Used in combination with other channels, such as a TCP channel, within the confines of
WebSphere MQ support to facilitate communications between a WebSphere System Integration
Bus and a WebSphere MQ client or queue manager.
JFAP channel
Used by the Java Message Service (JMS) server to create connections to JMS resources on a
service integration bus.
SSL channel
Used to associate an SSL configuration repertoire with the transport chain. This channel is only
available when Secure Sockets Layer (SSL) support is enabled for the transport chain. An SSL
configuration repertoire is defined in the administrative console, under security, on the SSL
configuration repertoires > SSL configuration repertoires page.

HTTP transport channel custom property

If you are using an HTTP transport channel, you can add the following custom property to the
configuration settings for that HTTP transport channel.

222 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To add a custom property:
1. In the administrative console, click Application servers > server_name Web container settings >
Web container transport chains >chain_name > HTTP Inbound Channel > Custom Properties >
New
2. Under General Properties specify the name of the custom property in the Name field and a value for
this property in the Value field. You can also specify a description of this property in the Description
field.
3. Click Apply or OK.
4. Click Save to save your configuration changes.
5. Restart the server.

Following is a list of custom properties provided with the application server. These properties are not
shown on the settings page for an HTTP transport channel.

inProcessLogFilenamePrefix

Use to specify a prefix for the filename of the network log file. Normally, when inprocess optimization is
enabled, requests through the inprocess path are logged based on the logging attributes set up for the
Web container’s network channel chain. You can use this property to add a prefix to the filename of the
network log file. This new filename is then used as the filename for the log file for inprocess requests.
Requests sent through the inprocess path are logged to this file instead of to the network log file. For
example, if the log file for a network transport chain is named .../httpaccess.log, and this property is set
to local for the HTTP channel in that chain, the filename of the log file for inprocess requests to the host
associated with that chain is .../localhttpaccess.log.

Data type String

HTTP Tunnel transport channel custom property

If you are using an HTTP Tunnel transport channel, you can add the following custom property to the
configuration settings for that HTTP Tunnel transport channel.

To add a custom property:

1. In the administrative console, click Servers > Application servers >server_name > Ports. Click on
View associated transports for the HTTP Tunnel port to whose configuration settings you want to
add this custom property.
2. Click New.
3. Under General Properties specify the name of the custom property in the Name field and a value for
this property in the Value field. You can also specify a description of this property in the Description
field.
4. Click Apply or OK.
5. Click Save to save your configuration changes.
6. Restart the server.

Following is a description of the custom property that is provided with the application server. This property
is not shown on the settings page for an HTTP Tunnel transport channel.
pluginConfigurable
Indicates whether or not the configuration settings for the HTTP Tunnel transport channel are
included in the plugin-cfg.xml file for the Web server associated with the application server that is
using this channel. Configuration settings for each of the Web container transport channels defined
for an application server are automatically included in the plugin-cfg.xml file for the Web server
associated with that application server.

Chapter 3. Setting up the application serving environment 223

Data type Boolean
Default False

Troubleshooting transport chain problems

TCP transport channel fails to bind to a specific host/port combination

If a TCP transport channel fails to bind to a specific port, one of the following situations might have
occurred:
v You are trying to bind the channel to a port that is already bound to another application, such as
another instance of a WebSphere Application Server.
v You are trying to bind to a port that is in a transitional state waiting for closure. This socket must
transition to closed before you restart the server. The port might be in TIME_WAIT, FIN_WAIT_2, or
CLOSE_WAIT state. Issue the netstat -a command from a command prompt window to display the
state of the port to which you are trying to bind. If you need to change the amount of elapse time that
must occur before TCP/IP can release a closed connection and reuse its resources, see the
Troubleshooting and support PDF.

Configuring HTTP transports

Important: On a distributed platform, HTTP transport support is deprecated. Therefore, the administrative
console page used to configure an HTTP transport is not available unless your migrated an
HTTP transport from your V5 environment. You must define an HTTP transport channel
instead of an HTTP transport to handle your HTTP requests.

An HTTP transport is the request queue between a WebSphere Application Server plug-in for Web servers
and a Web container in which the Web modules of an application reside. To define the characteristics of
the connections between that plug-in and the Web container, you must specify:
v How the transport is to handle a set of connections. For example, you must specify the number of
concurrent requests that is to be allowed.
v Whether to secure the connections with SSL.
v The Host and IP information for the transport participants.
1. Change the configuration for an existing HTTP transport.
a. Ensure that virtual host aliases include port values for the transport your are changing.
b. Go to the HTTP Transports page and click on the transport under Host whose configuration you
want to change.
Remember, on a distributed platform, HTTP transport support is deprecated. Therefore you cannot
view this administrative console page unless you are a V5.x user who, during the V6 migration
process, indicated that you want to continue using the HTTP transports that are defined for your V5
environment.
c. On the settings page for an HTTP transport, which might have the page title DefaultSSLSettings,
change the specified values as needed, then click OK.
d. Custom properties page, add and set any custom properties you want to use.
2. Stop the WebSphere Application Server and start it again. You must stop the WebSphere Application
Server and start it again before the configuration changes you made take affect.

If the Web server is located on a machine remote from the Application Server but is defined on a managed
node, the updated plugin-cfg.xml is automatically propagated to the Web server.

If the Web server is defined on an unmanaged node and is not an IHS V6.0 Web server, copy the updated
plugin-cfg.xml file to the remote Web server and replace the file that is there. See ″Editing Web server
configuration files″ in the information center for information about copying the plugin-cfg.xml and binary
plug-in module to a remote Web server and configuring the Web server to use the files.

224 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If the Web server is an IHS V6.0 Web server, is located on a machine remote from the Application Server
and is defined on an unmanaged node, you can configure the plugin-cfg.xml file so that whenever it is
updated, it is automatically propagated to the remote IHS Web server.

HTTP transport collection:

Use this page to view or manage HTTP transports. Transports provide request queues between
WebSphere Application Server plug-ins for Web servers and Web containers in which the Web modules of
applications reside. When you request an application in a Web browser, the request is passed to the Web
server, then along the transport to the Web container.

On a distributed platform, if, when migrating from WebSphere Application Server Version 5.x, you indicate
that you want to continue using an HTTP transport to handle your HTTP requests, your Version 5.x
transports are migrated for you. If you are not migrating from Version 5.x, you must set up an HTTP
transport channel to handle your HTTP requests.

To view the HTTP Transport administrative console page, click Servers > Application Servers
>server_name > Web Container Settings > Web Container > HTTP Transports.

the HTTP Transport panel on the administrative console

Host:

Specifies the host IP address to bind for transport. If the application server is on a local machine, the host
name might be localhost.

Port:

Specifies the port to bind for transport. The port number can be any port that currently is not in use on the
system. The port number must be unique for each application server instance on a given machine.

For distributed platforms, there is no limit to the number of HTTP ports that are allowed per process.

SSL Enabled:

Specifies whether to protect connections between the WebSphere plug-in and application server with
Secure Sockets Layer (SSL). The default is not to use SSL.

HTTP transport settings:

Use this page to view and configure an HTTP transport. The name of the page might be that of an SSL
setting such as DefaultSSLSettings.

On a distributed platform, if, when migrating from Version 5, you indicate that you want to continue using
an HTTP transport to handle your HTTP requests, your Version 5 transports are migrated for you. If you
are not migrating from WebSphere Application Server Version 5.x, you must set up an HTTP transport
channel to handle your HTTP requests.

To view the HTTP Transport panel on the administrative console, click Servers > Application Servers
>server_name > Web Container Settings > Web Container > HTTP Transports >host_name.

Host:

Specifies the host IP address to bind for transport.

Chapter 3. Setting up the application serving environment 225

If the application server is on a local machine, the host name might be localhost.

Data type String

Port:

Specifies the port to bind for transport. Specify a port number between 1 and 65535. The port number
must be unique for each application server on a given machine.

Data type Integer

Range 1 to 65535

SSL Enabled:

Specifies whether to protect connections between the WebSphere Application Server plug-in and
application server with Secure Sockets Layer (SSL). The default is not to use SSL.

Data type Boolean

Default false

SSL:

Specifies the Secure Sockets Layer (SSL) settings type for connections between the WebSphere
Application Server plug-in and application server. The options include one or more SSL settings defined in
the Security Center; for example, DefaultSSLSettings, ORBSSLSettings, or LDAPSSLSettings.

Data type String

Default An SSL setting defined in the Security Center

Transports:

A transport is the request queue between a WebSphere Application Server plug-in for Web servers and a
Web container in which the Web modules of an application reside. When a user at a Web browser
requests an application, the request is passed to the Web server, then along the transport to the Web
container.

Transports define the characteristics of the connections between a Web server and an application server,
across which requests for applications are routed. Specifically, they define the connection between the
Web server plug-in and the Web container of the application server.

Administering transports is closely related to administering WebSphere Application Server plug-ins for Web
servers. Indeed, without a plug-in configuration, a transport configuration is of little use.

On a distributed platform, when migrating from WebSphere Application Server Version 5.x, you indicate
that you want to continue using an HTTP transport to handle your HTTP requests, your Version 5.x
transports are migrated for you. If you are not migrating from Version 5.x, you must set up an HTTP
transport channel to handle your HTTP requests.

The internal transport

The internal HTTP transport allows HTTP requests to be routed to the application server directly through a
Web server plug-in. Logging is provided for debug purposes.

226 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Prior to WebSphere Application Server Version 5.0.2, the HTTP transport functionality existed only as a
means of accepting HTTP requests forwarded by an HTTP plug-in that was connected to a Web server. In
WebSphere Application Server Version 5.0.2, HTTP transport functionality is now a supported internal Web
server. By default, the internal HTTP transport listens for HTTP requests on port 9080 and for HTTPS
requests on port 9443.

For example, use the URL http://localhost:9080/snoop to send requests to the snoop servlet on the
local machine over HTTP and https://localhost:9443/snoop to send requests to the snoop servlet on the
local machine over HTTPS.

The transport configuration is a part of the Web container configuration. You can configure the internal
transport to use ports other than 9080 and 9443. However, you must also adjust your virtual host alias and
what you type into the Web browser.

HTTP transport custom properties:

Use this page to set custom properties for an HTTP transport.

On a distributed platform, HTTP transport support is deprecated. Therefore you cannot create a new HTTP
transport. Instead you must create an HTTP transport channel to handle your HTTP requests. If you are a
WebSphere Application Server Version 5.x user who has migrated to Version 6, and during the migration
process you indicated that you want to continue using an HTTP transport to handle your HTTP requests,
your Version 5.x transports are still available for your use.

If you are using HTTP transports, you can set the following custom properties on either the Web Container
or HTTP Transport Custom Properties panel on the administrative console. When set on the Web
container Custom Properties page, all transports inherit the properties. Setting the same properties on a
transport overrides like settings defined for a Web container.

To specify values for these custom properties for a specific transport on the HTTP Transport Custom
Properties page:
1. In the console navigation tree, click Servers > Application Servers >server_name > Web Container
settings > Web Container >HTTP Transport

To specify a custom property:

1. Click on the HOST whose properties you want to set.
2. Under Additional Properties select Custom Properties.
3. On the Custom Properties page, click New.
4. On the settings page, enter the property you want to configure in the Name field and the value you
want to set it to in the Value field.
5. Click Apply or OK.
6. Click Save on the console task bar to save your configuration changes.
7. Restart the server.

Following is a list of custom properties provided with the Application Server. These properties are not
shown on the settings page for an HTTP transport.

ConnectionIOTimeOut:

Use the ConnectionIOTimeOut property to specify the maximum number of seconds to wait when trying to
read or process data during a request.

Data type Integer

Default For distributed platforms: 5 seconds

Chapter 3. Setting up the application serving environment 227

ConnectionKeepAliveTimeout:

Use the ConnectionKeepAliveTimeout property to specify the maximum number of seconds to wait for the
next request on a keep alive connection.

Data type Integer

MaxConnectBacklog:

Use the MaxConnectBacklog property to specify the maximum number of outstanding connect requests that
the operating system will buffer while it waits for the application server to accept the connections. If a
client attempts to connect when this operating system buffer is full, the connect request will be rejected.

Set this value to the number of concurrent connections that you would like to allow. Keep in mind that a
single client browser might need to open multiple concurrent connections (perhaps 4 or 5); however, also
keep in mind that increasing this value consumes more kernel resources. The value of this property is
specific to each transport.

Data type Integer

Default 511

MaxKeepAliveRequests:

Use the MaxKeepAliveRequests property to specify the maximum number of requests which can be
processed on a single keep alive connection. This parameter can help prevent denial of service attacks
when a client tries to hold on to a keep-alive connection. The Web server plug-in keeps connections open
to the application server as long as it can, providing optimum performance.

Data type Integer

Default For distributed platforms: 100 requests

KeepAliveEnabled:

This property is only valid in a distributed environment. Use the KeepAliveEnabled property to specify
whether or not to keep connections alive

Data type String

Default true

Trusted:

This property is only valid in a distributed environment. Use the Trusted property to indicate that the
application server can use the private headers that the Web server plug-in adds to requests.

Data type String

Default false

Configuring error logging for internal Web server HTTP transport:

To debug potential problems with using the HTTP transport as an internal Web server, you can use the
following error logging capabilities.
1. Turn error logging on. To turn error logging on, add the following custom property to the HTTP
Transport’s configuration settings, and set the value to false:

228 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Property name: ErrorLogDisable
Value: True/False
Default: Error log is disabled by default
When you are ready to turn error logging off, set the value of the ErrorLogDisable property back to
true.
2. To specify your own error log file, add the following property to the transport section of the server.xml
file:
Property name: ErrorLog
Value: <filename>
Default: logs/<server instance>/http.log

The error log property is used to specify where to place the error log. For example:<properties
xmi:id=″WebContainer_Property_6″ name=″ErrorLog″ value=″logs/<server instance>/http.log″/>

Note: The error log should appear in each instance of the server.

If you are going to be using error logging for multiple HTTP transports in a single HTTP server,
make sure you specify a unique filename for the error log file associated with each HTTP
transport.
3. Add the LogLevel property to the transport section of the server.xml file to specify the level of
messages to log in the error log file.
Property name: LogLevel
Value: <level> (Levels include: debug, info, warn, error, crit)
Default: warn (warn includes error and crit; debug includes all levels)
Scope: Virtual/Global

Log levels specify the type of message that appears in the error log. The warn, error, and crit
messages are logged by default.
4. Restart the server.

If you have enabled error logging and encounter an error, there should be an error log message in the
error log file you specified.

Configuring access logging for internal Web server HTTP transport:

To debug potential problems with using the HTTP transport as an internal Web server, you can use the
following access logging capabilities.
1. Turn access logging on. To turn access logging on, add the following custom property to the HTTP
Transport’s configuration settings, and set the value to false:
Property name: AccessLogDisable
Values: True/False
Default: Access log is disabled by default
When you are ready to turn access logging off, set the value of the AccessLogDisable property back
to true.
2. To specify your own access log file, add the following property to the transport section of the
server.xml file:
Property name: AccessLog
Value: <filename>
Default Value: logs/<server instance>/http_access.log

The default access log file is logs/<server_instance>/http_access.log. Access log entries should
have the format:
<hostname or IP> <user agent> [<local time> -<status code>] <thread id> <http request> <status code> <bytecount>

Chapter 3. Setting up the application serving environment 229

 Note: If you are going to be using access logging for multiple HTTP transports in a single HTTP
server, make sure you specify a unique filename for the access log file associated with each
HTTP transport.
3. Restart the server.

If you have enabled access logging, there will be an access log in the location you specified.

Transport chains collection

Use this page to view or manage transport chains. Transport chains enable communication through
transports, or protocol stacks, which are usually socket based.

A transport chain consists of one or more types of channels, each of which supports a different type of I/O
protocol, such as TCP or HTTP. Network ports can be shared among all of the channels within a chain.
The Channel Framework function automatically distributes a request arriving on that port to the correct I/O
protocol channel for processing.

The Transport chains page lists the transport chains defined for the selected application server. Transport
chains represent network protocol stacks operating within this application server.

To view this administrative console page, click Servers > Application servers > server_name > Ports.
Click on View associated transports for the port whose transport chains you want to view.

Name: Specifies a unique identifier for the transport chain. For WebSphere Application Server, transport
name must be unique within a WebSphere Application Server configuration. Click on the name of a
transport chain to change its configuration settings.

Enabled: When set to true, the transport chain is activated at application server startup.

Host: Specifies the host IP address to bind for transport. If the application server is on a local machine,
the host name might be localhost.

Port: Specifies the port to bind for transport. The port number can be any port that currently is not in use
on the system, might be localhost or the wildcard character * (an asterisk). The port number must be
unique for each application server instance on a given machine

SSL Enabled: When set to true, users are notified if there is a channel that enables Secure Sockets
Layer (SSL) in the listed chain. When SSL is enabled, all traffic going through this transport is encrypted
and digitally secured.

Transport chain settings

This page lists the types of transport channels configured for the selected transport chain. A transport
chain consists of one or more types of channels, each of which supports a different type of I/O protocol,
such as TCP, HTTP, or DCS.

To view this administrative console page, click Servers > Application servers > server_name > Ports.
Click on View associated transports for the port whose transport chains you want view and then click on
the name of a specific chain.

Name:

Specifies the name of the selected transport chain.

You can edit this field to rename this transport chain. However, remember that the name must be unique
within a WebSphere Application Server configuration.

Enabled: When checked, this transport chain is activated at application server startup.

230 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Transport channels: Lists the transport channels configured for this transport chain and their
configuration settings. To change a transport channel’s configuration settings, click on the name of that
transport channel.

HTTP tunnel transport channel settings

Use this page to view and configure an HTTP tunnel transport channels. Inbound connections sent
through this channel are tunneled over HTTP, allowing intermediates to view this data as the body of an
HTTP message instead of in its natural format. This type of channel is often used to circumvent firewalls
with protocol restrictions.

To view this administrative console page, click Servers > Application servers >server_name > Ports .
Click on View associated transports for the port associated with the HTTP Tunnel transport channel
whose settings you want to look at.

Transport channel name:

Specifies the name of the HTTP tunnel transport channel.

This name must be unique across all channels in a WebSphere Application Server environment. For
example DCS and TCP transport channels cannot have the same name if they reside within the same
system.

Discrimination weight:

Specifies the priority this channel has in relation to the other channels in this transport chain. This property
is only used when port sharing is enabled and the channel chain includes multiple channels to which it
might forward data. The channel in the chain with the lowest discrimination weight is the first one given the
opportunity to look at incoming data and determine whether or not it owns that data.

Data type Positive integer

Default 10

HTTP transport channel settings

Use this page to view and configure an HTTP transport channel. This type of transport channel handles
HTTP requests from a remote client.

An HTTP transport channel parses HTTP requests and then finds an appropriate application channel to
handle the request and send a response.

To view this administrative console page, click Servers > Application servers >server_name > Ports .
Click on View associated transports for the port associated with the HTTP transport channel whose
settings you want to look at.

Transport channel name:

Specifies the name of the HTTP transport channel.

This name must be unique across all channels in a WebSphere Application Server environment. For
example, an HTTP transport channel and a TCP transport channel cannot have the same name if they
reside within the same system.

Discrimination weight:

Specifies the priority this channel has in relation to the other channels in this transport chain. This property
is only used when port sharing is enabled and the channel chain includes multiple channels to which it

Chapter 3. Setting up the application serving environment 231

might forward data. The channel in the chain with the lowest discrimination weight is the first one given the
opportunity to look at incoming data and determine whether or not it owns that data.

Data type Positive integer

Default 10

Maximum persistent requests:

Specifies the maximum number of persistent (keep-alive) requests that are allowed on a single HTTP
connection. If a value of 0 (zero) is specified, only one request is allowed per connection. If a value of -1 is
specified, an unlimited number of requests is allowed per connection.

Data type Integer

Default 100

Use Keep-Alive: When selected, the HTTP transport channel, when sending an outgoing HTTP
message, uses a persistent connection (keep-alive connection) instead of a connection that closes after
one request or response exchange occurs.

Note: If a value other than 0 is specified for the maximum persistent requests property, the Use
Keep-Alive property setting is ignored.

The default for this property is selected.

Read timeout:

Specifies the amount of time, in seconds, the HTTP transport channel waits for a read request to complete
on a socket after the first read request occurs. The read being waited for could be an HTTP body (such as
a POST) or part of the headers if they were not all read as part of the first read request on the socket.

Data type Integer

Default 60 seconds

Write timeout:

Specifies the amount of time, in seconds, that the HTTP transport channel waits on a socket for each
portion of response data to be transmitted. This timeout usually only occurs in situations where the writes
are lagging behind new requests. This can occur when a client has a low data rate or the server’s network
interface card (NIC) is saturated with I/O.

Data type Integer

Default 60 seconds

Persistent timeout:

Specifies the amount of time, in seconds, that the HTTP transport channel allows a socket to remain idle
between requests.

Data type Integer

Default 30 seconds

Enable NCSA access logging:

232 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
When selected, the HTTP transport channel performs NCSA access and error logging. Enabling NCSA
access and error logging slows server performance.

To configure NCSA access and error logging, click HTTP error and NCSA access logging under Related
Items. Even if HTTP error and NCSA access logging is configured, it is not enabled unless the Enable
NCSA access logging property is selected.

The default value for the Enable NCSA access logging property is not selected.

TCP transport channel settings

Use this page to view and configure an TCP transport channels. This type of transport channel handles
inbound TCP/IP requests from a remote client.

To view this administrative console page, click Servers > Application servers >server_name > Ports > .
Click on View associated transports for the port associated with the TCP transport channel whose
settings you want to view.

Transport channel name:

Specifies the name of the TCP transport channel.

This name must be unique across all channels in a WebSphere Application Server environment. For
example, a TCP transport channel and an HTTP transport channel cannot have the same name if they
reside within the same system.

Port: Specifies the TCP/IP port this transport channel uses to establish connections between a client and
an application server. The TCP transport channel binds to the hostnames and ports listed for the Port
property. You can specify the wildcard * (an asterisk), for the hostname if you want this channel to listen to
all hosts that are available on this system. However, before specifying the wildcard value, make sure this
TCP transport channel does not have to bind to a specific hostname.

Thread pool: Select from the drop-down list of available thread pools the thread pool you want the TCP
transport channel to use when dispatching work.

Maximum open connections:

Specifies the maximum number of connections that can be open at one time.

Data type Integer between 1 and 20,000 inclusive

Default 20,000

Inactivity timeout: Specifies the amount of time, in seconds, that the TCP transport channel waits for a
read or write request to complete on a socket.

Note: The value specified for this property might be overridden by the wait times established for channels
above this channel. For example, the wait time established for an HTTP transport channel overrides
the value specified for this property for every operation except the initial read on a new socket.

Data type Integer

Default 60 seconds

Address exclude list:

Lists the IP addresses that are not allowed to make inbound connections. Use a comma to separate the
IPv4 or IPv6 or both addresses to which you want to deny access on inbound TCP connection requests.

Chapter 3. Setting up the application serving environment 233

All four numeric values in an IPv4 address must be represented by a number or the wildcard character *
(an asterisk).

Following are examples of valid IPv4 addresses that can be included in an Address exclude list:
*.1.255.0
254.*.*.9
1.*.*.*

All eight numeric values of an IPv6 address must be represented by a number or the wildcard character *
(an asterisk). No shortened version of the IPv6 address should be used. Even though a shortened version
is processed with no error given, it does not function correctly in this list. Each numeric entry should be a
1- 4 digit hexadecimal number.

Following are examples of valid IPv6 addresses that can be included in an Address exclude list:
0:*:*:0:007F:0:0001:0001
F:FF:FFF:FFFF:1:01:001:0001
1234:*:4321:*:9F9f:*:*:0000

Note: The Address include list and Host name include list are processed before the Address exclude
list and the Host name exclude list. If all four lists are defined:
v An address that is defined on either inclusion list will be allowed access provided it is not
included on either of the exclusion lists.
v If an address is included in both an inclusion list and in an exclusion list, it will not be allowed
access.

Address include list:

Lists the IP addresses that are allowed to make inbound connections. Use a comma to separate the IPv4
or IPv6 or both addresses to which you want to grant access on inbound TCP connection requests.

All four numeric values in an IPv4 address must be represented by a number or the wildcard character *
(an asterisk).

Following are examples of valid IP addresses that can be included in an Address include list:
*.1.255.0
254.*.*.9
1.*.*.*

All eight numeric values of an IPv6 address must be represented by a number or the wildcard character *
(an asterisk). No shortened version of the IPv6 address should be used. Even though a shortened version
is processed with no error given, it does not function correctly in this list. Each numeric entry should be a
1- 4 digit hexadecimal number.

Following are examples of valid IPv6 addresses that can be included in an Address include list:
0:*:*:0:007F:0:0001:0001
F:FF:FFF:FFFF:1:01:001:0001
1234:*:4321:*:9F9f:*:*:0000

Note: The Address include list and Host name include list are processed before the Address exclude
list and the Host name exclude list. If all four lists are defined:
v An address that is defined on either inclusion list will be allowed access provided it is not
included on either of the exclusion lists.
v If an address is included in both an inclusion list and in an exclusion list, it will not be allowed
access.

Host name exclude list:

234 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
List the host names that are not allowed to make connections. Use a comma to separate the URL
addresses to which you want to deny access on inbound TCP connection requests.

A URL address can start with the wildcard character * (an asterisk) followed by a period; for example,
*.Rest.Of.Address. If a period does not follow the wildcard character, the asterisk will be treated as a
normal non-wildcard character. The wildcard character can not appear any where else in the address. For
example, ibm.*.com is not a valid hostname.

Following are examples of valid URL addresses that can be included in a Host name exclude list:
*.ibm.com
www.ibm.com
*.com

Note: The Address include list and Host name include list are processed before the Address exclude
list and the Host name exclude list. If all four lists are defined:
v An address that is defined on either inclusion list will be allowed access provided it is not
included on either of the exclusion lists.
v If an address is included in both an inclusion list and in an exclusion list, it is not allowed access.

Host name include list:

Lists the host names that are allowed to make inbound connections. Use a comma to separate the URL
addresses to which you want to grant access on inbound TCP connection requests.

A URL address can start with the wildcard character * (an asterisk) followed by a period; for example,
*.Rest.Of.Address. If a period does not follow the wildcard character, the asterisk will be treated as a
normal non-wildcard character. The wildcard character can not appear any where else in the address. For
example, ibm.*.com is not a valid hostname.

Following are examples of valid URL addresses that can be included in a Host name include list:
*.ibm.com
www.ibm.com
*.com

Note: The Address include list and Host name include list are processed before the Address exclude
list and the Host name exclude list. If all four lists are defined:
v An address that is defined on either inclusion list will be allowed access provided it is not
included on either of the exclusion lists.
v If an address is included in both an inclusion list and in an exclusion list, it is not allowed access.

DCS transport channel settings

Use this page to view and configure an DCS transport channels. This type of transport channel handles
inbound Distribution and Consistency Services (DCS) messages.

By default, two channel transport chains are defined for an application server that contains a DCS
channel:
v The chain named DCS contains a TCP and a DCS channel.
v The chain named DCS-Secure contains a TCP, an SSL, and a DCS channel.

Both of these chains terminate in, or use the same TCP channel instance. This TCP channel is associated
with the DCS_UNICAST_ADDRESS port and is not used in any other transport chains. One instance of an
SSL channel is reserved for use in the DCS-Secure chain. It also is not used in any other transport chains.

Chapter 3. Setting up the application serving environment 235

To view this administrative console page, click Servers > Application servers >server_name > Ports > .
Click on View associated transports for the port associated with the DCS transport channel whose
settings you want to look at.

Transport channel name:

Specifies the name of the DCS transport channel.

This name must be unique across all channels in a WebSphere Application Server environment. For
example DCS and TCP transport channels cannot have the same name if they reside within the same
system.

Discrimination weight:

Specifies the priority this channel has in relation to the other channels in this transport chain. This property
is only used when port sharing is enabled and the channel chain includes multiple channels to which it
might forward data. The channel in the chain with the lowest discrimination weight is the first one given the
opportunity to look at incoming data and determine whether or not it owns that data.

The discrimination weight of the DCS channel in a DCS-Secure transport chain should always be less than
the discrimination weight of the SSL channel that is in that chain. Other SSL channels in other chains
might have different discrimination values.

Data type Positive integer

Default 1 for the DCS channel 2 for the SSL channel

Web container transport channel settings

Use this page to view and configure a Web container inbound channel transport. This type of channel
transport handles inbound Web container requests from a remote client.

To view this administrative console page, click Servers > Application servers > server_instance > Web
container settings > Web container transport chains > transport_chain > Web Container Inbound
Channel .

Transport Channel Name:

This name must be unique across all channels in a WebSphere Application Server environment. This
means that TCP transport channels and HTTP transport channels cannot have the same name if they
reside within the same system.

Discrimination weight:

Specifies the priority that this transport chain has in relation to other transport chains if this transport
channel is shared amongst several transport chains.

Write buffer size:

Specifies the amount of content in bytes to buffer unless the servlet explicitly calls flush/close on the
response/writer output stream.

Data type bytes

Default 9192 bytes

236 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Custom services
A custom service provides the ability to plug into a WebSphere Application Server application server to
define a hook point that runs when the server starts and shuts down.

A developer implements a custom service containing a class that implements a particular interface. The
administrator configures the custom service in the administrative console, identifying the class created by
the developer. When an application server starts, any custom services defined for the application server
are loaded and the server runtime calls their initialize methods.

Developing custom services

To define a hook point to be run when a server or node agent starts and shuts down, you develop a
custom service class and then configure a custom service instance. When the application server or node
agent starts, the custom service starts and initializes.

The following restrictions apply to the WebSphere Application Server custom services implementation:
v The init and shutdown methods must return control to the runtime.
v No work is dispatched into the server instance until all custom service initialize methods return.
v The init and shutdown methods are called only once on each service, and once for each operating
system process that makes up the server instance. File I/O is supported.
v Initialization of process level static data, without leaving the process, is supported.
v Only JDBC RMLT (resource manager local transaction) operations are supported. Every unit of work
(UOW) must be completed before the methods return.
v Creation of threads is not supported.
v Creation of sockets and I/O, other than file I/O, is not supported. Running standard J2EE code (client
code, servlets, enterprise beans) is not supported.
v The JTA interface is not available. This feature is available in J2EE server processes and distributed
generic server processes only.
v While the runtime makes an effort to call shutdown, there is no guarantee that shutdown will be called
prior to process termination.

Note that these restrictions apply to the shutdown and init methods equally. Some JNDI operations are
available.
1. Develop a custom service class that implements the com.ibm.websphere.runtime.CustomService
interface. The properties passed by the application server runtime to the initialize method can include
one for an external file containing configuration information for the service (retrieved with
externalConfigURLKey). In addition, the properties can contain any name-value pairs that are stored
for the service, along with the other system administration configuration data for the service. The
properties are passed to the initialize method of the service as a Properties object.
There is a shutdown method for the interface as well. Both methods of the interface declare that they
may create an exception, although no specific exception subclass is defined. If an exception is created,
the runtime logs it, disables the custom service, and proceeds with starting the server.
2. On the Custom Service page of the administrative console, click New. Then, on the settings page for a
custom service instance, create a custom service configuration for an existing application server or
node agent, supplying the name of the class implemented. If your custom service class requires a
configuration file, specify the fully-qualified path name to that configuration file in the
externalConfigURL field. This file name is passed into your custom service class.
To invoke a native library from the custom service, provide the path name in the Classpath field in
addition to the path names that are used to locate the classes and JAR files for the custom service.
Doing this adds the path name to the WebSphere Application Server extension classloader, which
allows the custom service to locate and correctly load the native library.

Chapter 3. Setting up the application serving environment 237

3. If you are developing a custom service for an application server, stop the application server and then
restart the server.
4. If you are developing a custom service for a node agent, stop and then restart the processing of the
node agent. On the Node Agents page of the administrative console (System Administration > Node
Agents), place a checkmark in the check box beside the node agent you want to stop, then click Stop.
To restart the node agent, place a checkmark in the check box beside the node agent, then click
Restart.
5. Check the application server or node agent to ensure that the initialize method of the custom service
ran as intended. Also ensure that the shutdown method performs as intended when the server or node
agent stops.

As mentioned above, your custom services class must implement the CustomService interface. In addition,
your class must implement the initialize and shutdown methods. Suppose the name of the class that
implements your custom service is ServerInit, your code would declare this class as shown below. The
code below assumes that your custom services class needs a configuration file. It shows how to process
the input parameter in order to get the configuration file. If your class does not require a configuration file,
the code that processes configProperties is not needed.
public class ServerInit implements CustomService
{
/**
* The initialize method is called by the application server run-time when the
* server starts. The Properties object passed to this method must contain all
* configuration information necessary for this service to initialize properly.
*
* @param configProperties java.util.Properties
*/
static final java.lang.String externalConfigURLKey =
"com.ibm.websphere.runtime.CustomService.externalConfigURLKey";

static String ConfigFileName="";

public void initialize(java.util.Properties configProperties) throws Exception

{
if (configProperties.getProperty(externalConfigURLKey) != null)
{
ConfigFileName = configProperties.getProperty(externalConfigURLKey);
}

// Implement rest of initialize method

}
/**
* The shutdown method is called by the application server run-time when the
* server begins its shutdown processing.
*
* @param configProperties java.util.Properties
*/
public void shutdown() throws Exception
{
// Implement shutdown method
}

Custom service collection

Use this page to view a list of services available to the application server and to see whether the services
are enabled. A custom service provides the ability to plug into a WebSphere application server and define
code that runs when the server starts or shuts down.

To view this administrative console page, click Servers > Application servers >server_name. Then, under
Server Infrastructure, click Administration > Custom Services.

238 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If you are developing a custom service for a node agent, click System Administration > Node agents
>node_agent_name. Then, under Additional Properties, click Custom Services to view this administrative
console page.

External Configuration URL:

Specifies the URL for a custom service configuration file.

If your custom services class requires a configuration file, the value provides a fully-qualified path name to
that configuration file. This file name is passed into your custom service class.

Classname:

Specifies the class name of the service implementation. This class must implement the Custom Service
interface.

Display Name:

Specifies the name of the service.

Enable service at server startup:

Specifies whether the server attempts to start and initialize the service when its containing process (the
server) starts. By default, the service is not enabled when its containing process starts.

Custom service settings:

Use this page to configure a service that runs in an application server.

To view this administrative console page, click Servers > Application servers >server_name. Then, under
Server Infrastructure, click Administration > Custom services >custom_service_name.

If you are developing a custom service for a node agent, click System administration > Node agents
>node_agent_name. Then, under Additional Properties, click Custom services >custom_service_name to
view this administrative console page.

Enable service at server startup:

Specifies whether the server attempts to start and initialize the service when its containing process (the
server) starts. By default, the service is not enabled when its containing process starts.

Data type Boolean

Default false

External Configuration URL:

Specifies the URL for a custom service configuration file.

If your custom services class requires a configuration file, specify the fully-qualified path name to that
configuration file for the value. This file name is passed into your custom service class.

Data type String

Units URL

Classname:

Chapter 3. Setting up the application serving environment 239

Specifies the class name of the service implementation. This class must implement the Custom Service
interface.

Data type String

Units Java class name

Display Name:

Specifies the name of the service.

Data type String

Description:

Describes the custom service.

Data type String

Classpath:

Specifies the class path used to locate the classes and JAR files for this service.

Data type String

Units Class path

Process definition
A process definition specifies the run-time characteristics of an application server process.

A process definition can include characteristics such as JVM settings, standard in, error and output paths,
and the user ID and password under which a server runs.

Defining application server processes

To enhance the operation of an application server, you can define command-line information for starting or
initializing an application server process. Such settings define run-time properties such as the program to
run, arguments to run the program, and the working directory.
1. Go to the settings page for a process definition in the administrative console. Click Servers >
Application Servers in the console navigation tree, click on an application server name and then Java
and Process Management > Process Definition. Note that you can also define application server
processes using the wsadmin tool. For more information, see the Administering applications and their
environment PDF.
2. On the settings page for a process definition, specify the name of the executable to run, any
arguments to pass when the process starts running, and the working directory in which the process will
run. Then click OK.
3. Specify process execution statements for starting or initializing a UNIX process.
4. Specify monitoring policies to track the performance of a process.
5. Specify process logs to which standard out and standard error streams write. Complete this step if you
do not want to use the default file names.
6. Specify name-value pairs for properties needed by the process definition.
7. Stop the application server and then restart the server.
8. Check the application server to ensure that the process definition runs and operates as intended.

240 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Process definition settings
Use this page to view or change settings for a process definition. For WebSphere Application Server, this
page provides command-line information for starting or initializing a process.

To view this administrative console page, click Servers > Application Servers >server_name. Then under
Server Infrastructure click Java Process Management > Process Definition.
Related concepts
“Process definition” on page 240
A process definition specifies the run-time characteristics of an application server process.
Related tasks
“Defining application server processes” on page 240
Related reference
“Administrative console page features” on page 357
This topic provides information about the basic elements of an administrative console page, such as
the various tabs.
“Java virtual machine settings” on page 253
Use this page to view and change the Java virtual machine (JVM) configuration for the application
server’s process.
“Custom property collection” on page 207
Use this page to view and manage arbitrary name-value pairs of data, where the name is a property
key and the value is a string value that can be used to set internal system configuration properties.

Working Directory:

Specifies the file system directory that the process uses as its current working directory.

The process uses this directory to determine the locations of input and output files with relative path
names.

Passivated enterprise beans are placed in the current working directory of the application server on which
the beans are running. Make sure the working directory is a known directory under the root directory of the
WebSphere Application Server product.

Data type String

Process execution settings:

Use this page to view or change the process execution settings for a server process that applies to either
an application server, a node agent or a deployment manager.

To view this administrative console page for an application server, click Servers > Application Servers
>server_name. Then, under Server Infrastructure , click Java and Process Management > Process
Execution.

To view this administrative console page for a node agent, click System Administration > Node agents
>node_agent_name. Then, under Server Infrastructure , click Java and Process Management > Process
Definition > Process Execution.

To view this administrative console page for a deployment manager, click System Administration >
Deployment manager. Then, under Server Infrastructure , click Java and Process Management >
Process Definition > Process Execution.

Process Priority:

Chapter 3. Setting up the application serving environment 241

Specifies the operating system priority for the process. The administrative process that launches the server
must have root operating system authority in order to honor this setting.

Data type Integer

Default 20 for WebSphere Application Server on all operating
systems.

UMASK:

Specifies the user mask under which the process runs (the file-mode permission mask).

Data type Integer

Run As User:

Specifies the user that the process runs as.

Data type String

Run As Group:

Specifies the group that the process is a member of and runs as.

On OS/400, the Run As Group setting is ignored.

Data type String

Run In Process Group:

Specifies a specific process group for the process. This process group is useful for such things as
processor partitioning. A system administrator can assign a process group to run on, for example, 6 of 12
processors. The default (0) is not to assign the process to any specific group.

On OS/400, the Run In Process Group setting is ignored.

Data type Integer

Default 0

Process logs settings:

Use this page to view or change settings for specifying the files to which standard out and standard error
streams write.

To view this administrative console page, click Servers > Application Servers >server_name. Then,
under Troubleshooting, click Logging and Tracing > Process Logs.

Stdout File Name:

Specifies the file to which the standard output stream is directed. The file name can include a symbolic
path name defined in the variable entries.

Use the field on the configuration tab to specify the file name. Use the field on the Runtime tab to select a
file for viewing. View the file by clicking View.

242 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Direct server output to the administrative console or to the process that launched the server, by either
deleting the file name or specifying console on the configuration tab.

Data type String

Units File path name

Stderr File Name:

Specifies the file to which the standard error stream is directed. The file name can include a symbolic path
name defined in the variable entries.

Use the field on the configuration tab to specify the file name. Use the field on the runtime tab to select a
file for viewing. View the file by clicking View.

Data type String

Units File path name

Monitoring policy settings:

Use this page to view or change settings that control how the node agent monitors and restarts a process.

To view this administrative console page, click Servers > Application Servers >server_name. Then,
under Server Infrastructure, click Java and Process Management > Process Definition > Monitoring
Policy.

Maximum Startup Attempts:

Specifies the maximum number of times to attempt to start the application server before giving up.

Data type Integer

Ping Interval:

Specifies the frequency of communication attempts between the parent process, such as the node agent,
and the process it has spawned, such as an application server. Adjust this value based on your
requirements for restarting failed servers. Decreasing the value detects failures sooner; increasing the
value reduces the frequency of pings, reducing system overhead.

Data type Integer

Range Set the value greater than or equal to 0 (zero) and less
than 2147483.

Ping Timeout:

When a parent process is spawning a child process, such as when a process manager spawns a server,
the parent process pings the child process to see whether the child was spawned successfully. This value
specifies the number of seconds that the parent process should wait (after pinging the child process)
before assuming that the child process failed.

Data type Integer

Units Seconds
Range Set the value greater than or equal to 0 (zero) and less
than 2147483.

Chapter 3. Setting up the application serving environment 243

Automatic Restart:

Specifies whether the process should restart automatically if it fails. The default is to restart the process
automatically.

Data type Boolean

Default true

Node Restart State:

Specifies the desired state for the process after the node completely shuts down and restarts.

Data type String

Default STOPPED
Range Valid values are STOPPED, RUNNING, or PREVIOUS. If
you want the process to return to its current state after the
node restarts, use PREVIOUS.

Automatically restarting server processes

There are several server processes related to WebSphere Application Server products that the operating
system can monitor and automatically restart when the server processes stop abnormally. This task
describes how to set up these monitored processes.

To set up this function on a Linux or UNIX-based operating system, you must have root authority to edit
the inittab file.

On a Windows operating system, you must belong to the Administrator group and have the following
advanced user rights:
v Act as part of the operating system
v Log on as a service

The Installation wizard grants you the user rights if your user ID is part of the administrator group. If you
are running on a Microsoft Windows 2000 Operating System, the Installation wizard displays a message
that states that although the advanced user rights are now effective, they do not display as effective until
the next time you log on to the Windows machine.

You can also add the advanced user rights manually if you are performing a silent installation on a
Windows platform. For example, to grant the user rights to your administrator group user ID on a Windows
2000 Server platform, perform the following procedure:
1. Click Administrative Tools in the Control Panel.
2. Click Local Security Policy.
3. Click Local Policies.
4. Click User Rights Assignments.
5. Right click Act as part of the operating system.
6. Click Security.
7. Click Add.
8. Click your user ID.
9. Click Add.
10. Click OK.
11. Click OK.
12. Right click Log on as a service.

244 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
13. Click Security.
14. Click Add.
15. Click OK.
16. Click OK.
17. Reboot your machine to make the settings effective.

Consult your Windows help system for more information.

There are several environments where you might use this function of automatically restarting servers. You
can restart the server1 managed node process, for example. Here is a list of processes you might
consider restarting:
v The server1 managed node process
v The server1 process on a stand-alone Application Server
v The dmgr process on a deployment manager node
v The nodeagent server process on any managed node
v The IBM HTTP Server process
v The IBM HTTP Administration process

You can create Windows services during installation, using the installation wizard. The wizard lets you
create services for these servers:
v The server1 managed node process, defined as a manually started (versus automatic) service
v The server1 stand-alone Application Server process, defined as a manually started service
v The IBM HTTP Server process and the IBM HTTP Administration process, defined as automatically
started services when you choose to install the IBM HTTP Server feature
v The dmgr process on a deployment manager node, defined as a manually started service

The installation wizard does not provide a way to create a service for a node agent because the
deployment manager instantiates each node agent after installation when you add an Application Server
node to the deployment manager cell. For this reason, you must manually create a function that
automatically starts a failed nodeagent server process.

You must manually create a shell script that automatically starts any of the processes previously
mentioned, on a Linux and UNIX-based operating system. Each Windows service or UNIX shell script
controls a single process, such as a stand-alone WebSphere Application Server instance. Multiple
stand-alone Application Server processes require multiple Windows service or UNIX scripts, which you can
define.

In a Network Deployment environment, the addNode or startNode command starts a single unmonitored
node agent only, the nodeagent process, and does not start all of the processes that you might define on
the node. While running, the node agent monitors and restarts Application Server processes on that node,
on either a Windows or a Linux and UNIX-based platform. Each Application Server process has
MonitoringPolicy configuration settings that the node agent uses when monitoring and restarting the
process.

It is recommended that you set up a monitored node agent process manually, either through a Windows
service, or through the rc.was example shell script on Linux and UNIX-based platforms. The operating
system monitors and automatically restarts the node agent process, nodeagent, if the process terminates
abnormally, which means if the process stops without going through a normal shutdown. Setting up the
deployment manager server, dmgr, as a monitored process is recommended. As mentioned, you can do
this during installation on a Windows platform. On a Linux and UNIX-based platform, use the rc.was
example shell script to set up the deployment manager dmgr server as a monitored process.

If you do not install the WebSphere Application Server Network Deployment product as a Windows service
during installation, you can use the do so at a later time. The operating system can then monitor each
server process and restart the process if it stops.

Chapter 3. Setting up the application serving environment 245

1. Use the profile creation wizard to set up a Windows service to automatically monitor and restart
processes related to the WebSphere Application Server product.
v Perform the following procedure from the profile creation wizard to select services that the
installation wizard can set up:
a. Click Run WebSphere Application Server Network Deployment as a service.
If you select this option, the installation wizard creates the following service during installation:
IBMWAS6Service - node_name
IBMWAS6Service -node_name service controls the node_name process.
After you complete and verify the installation, use the Windows Services panel to change the
IBMWAS6Service -node_name service to an automatic startup type.
1) Right click IBMWAS6Service -node_name and click Properties.
2) Click Automatic from the Startup type list box and click OK.
b. Click Run IBM HTTP Server as a service.
Select this option on the machine where you are installing the IBM HTTP Server.
If you select this option, the installation wizard creates the following services during the
installation:
– IBM HTTP Server 2.0.x
– IBM HTTP Administration 2.0.x
The installation wizard defines the startup type of these services as automatic. It is not
necessary for you to change the type from manual to automatic.
c. Enter your user ID and password and click Next.
In a coexistence environment, you can change the default service names to make them unique. In a
same version coexistence scenario for IBM HTTP Server 2.0.x on a Windows platform, you cannot
use the default service names created by the installer because they are common.
To work around this problem:
a. Install the first copy of IBM HTTP Server, either by itself or with WebSphere Application Server
and select to install the services.
b. Customize the service names for the first install by running the following commands from the
first install location:
apache -k install -n "IHS 2.0(1)"
apache -k install -f conf\admin.conf -n "IHS 2.0 Administration (1)"
c. Edit the AdminAlias directive in the installLocation 1\conf\admin.conf file to point to the new
service name, such as IHS 2.0(1).
d. Remove the default service names installed by the first install by running the following
commands:
apache -k uninstall -n "IBM HTTP Server 2.0"
apache -k uninstall -n "IBM HTTP Administration 2.0"
e. Install the second copy of IBM HTTP Server, either by itself or with WebSphere Application
Server. The default service names correspond to the second install.

Note: Customized service names must be unique on your system.

2. After installing, you can use the WASService.exe utility in the install_root\bin directory to manually
define a Windows service for another installation instance or for another configuration instance of the
server1 process.
3. After installing, use the WASService.exe tool to manually define the nodeagent server process as a
Windows service.
You can use the same tool to manually define a Windows service for another installation instance or
for another configuration instance of either the server1 process or the dmgr process.
4. After installing, set up a Linux and UNIX-based shell script to automatically monitor and restart the
nodeagent process or any other related server process.
a. Locate the rc.was example shell script, which is in the install_root/bin directory.
b. Create a new shell script for each process that the operating system is to monitor and restart.

246 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 c. Edit each shell script according to comments in its header, which provide instructions for identifying
a WebSphere Application Server process.
d. Edit the inittab table of the operating system, to add an entry for each shell script you have
created.
Comments in the header of the rc.was file show a sample inittab entry line for adding the script.
This inittab entry causes the Linux and UNIX-based system to call each shell script whenever the
system initializes. As it runs, each shell script monitors and starts the server process you specified.
Each shell script monitors and restarts the following processes in an WebSphere Application Server
Network Deployment environment:
v A server process on a managed node
v A node agent process on a managed node
v A stand-alone Application Server process
v A deployment manager process

You can use the net start and net stop commands to control the IBM HTTP Server services on a
Windows system. For more information about these commands, see the Windows help file. Access these
commands from the Start menu, clicking Start > Programs > IBM HTTP Server.

You can also use the Start the Server and Stop the Server commands to control the IBM WebSphere
Application Server process on a Windows system. Access these commands from the Start menu, clicking
Start > Programs > IBM WebSphere > Application Server V6.

You can also use the Start the Manager and Stop the Manager commands to control the Network
Deployment dmgr process on a Windows system. Access these commands from the Start menu, clicking
Start > Programs > IBM WebSphere > Application Server V6 > Deployment Manager.

Processes started by a startServer command, a startNode command, or a startManagercommand are

not running as monitored processes, regardless of how you have configured them.

For example, you can configure a server1 process as a monitored process. However, if you start the
server1 process using the startServer command, the operating system does not monitor or restart the
server1 process because the operating system did not originally start the process as a monitored process.

Return to Defining application server processes to continue.

WASService command:

The WASService command line tool lets you create a Windows service for any WebSphere Application
Server Java process.

You can create Windows services for WebSphere Application Server Java processes. Potential Windows
services include the following server processes:
v The default server1 process on an application server node
v Application server processes that you create on an application server node
v The nodeagent process on an application server node that is part of a deployment manager cell
v The deployment manager process, dmgr

Location of the command file: The WASService.exe command file is located in the install_root\bin
directory.

Command syntax:

Chapter 3. Setting up the application serving environment 247

WASService.exe command syntax for starting an existing service

The command syntax is as follows:

WASService.exe [-start] "service_name" [optional startServer.bat parameters]

WASService.exe command syntax for creating a service or updating an existing service

The command syntax is as follows:

WASService.exe -add "service_name"
-serverName server
-profilePath server_profile_directory

[-wasHome install_root]
[-configRoot configuration_repository_directory]
[-startArgs additional_start_arguments]
[-stopArgs additional_stop_arguments]
[-userid user_id -password password]
[-logFile service_log_file]
[-logRoot server_log_directory]
[-restart true | -restart false]
[-startType automatic | manual | disabled]

WASService.exe command syntax for deleting a service

The command syntax is as follows:

WASService.exe -remove "service_name"

WASService.exe command syntax for stopping a running service

The command syntax is as follows:

WASService.exe -stop "service_name" [optional stopServer.bat parameters]

WASService.exe command syntax for retrieving service status

The command syntax is as follows:

WASService.exe -status "service_name"

WASService.exe command syntax for encoding parameters

The command syntax is as follows:

WASService.exe -encodeParams "service_name"

Parameters: Supported arguments include:

-add ″service_name″
Creates a service named service_name or updates an existing Windows service. The syntax is the
same for both cases.
-configRoot configuration_repository_directory
Optional parameter that identifies the configuration directory of the installation root directory of a
WebSphere Application Server product.
-encodeParams service_name
Optional parameter that forces the service to encode the -startArgs and -stopArgs so that the
arguments cannot be determined by editing the registry. Use the parameter when creating a service
with the -add parameter by adding -encodeParams to the command line with no arguments. Or
encode the parameters of an existing service:
WASService -encodeParams service_name

248 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-logFile service_log_file
Optional parameter that identifies a log file that the WASService command uses to record its activity.
-logRoot server_log_directory
Required parameter that identifies the server log directory for the profile. The WASService command
looks for a file named server_name.pid to determine if the server is running.
-profilePath server_profile_directory
Specifies the directory path of the profile that defines the server process.
-remove service_name
Deletes the specified service.
-restart true | false
Restarts the existing service automatically if the service fails when set to true.
-serverName Server_name
Identifies the server that the service controls.
-start ″service_name″ [optional startServer.bat parameters]
Starts the existing service.
-startArgs additional_start_arguments
Optional parameter that identifies additional parameters.
-startType automatic | manual | disabled
Defines the startup type of the new service. An automatic startup type starts automatically when the
system starts or when the service is called for the first time. You must start a manual service before
the operating system can load it and make it available. You cannot start a disabled service before
changing the startup type.
-status service_name
Returns the current status of the service, which includes whether the service is running or stopped.
-stop service_name [optional stopServer.bat parameters]
Stops the specified service.
-stopArgs additional_stop_arguments
Optional parameter that identifies additional parameters.
-userid user_ID -password password
Optional parameters that identify a privileged user ID and password that the Windows service will run
as.
-wasHome install_root
Optional parameter that identifies the installation root directory of the WebSphere Application Server
product.

Default names for Windows services that are created by the wizard: The names of the Windows services
that the Profile creation wizard can create are:
Deployment manager
IBM WebSphere Application Server V6 - node_name_of_the_deployment_manager_node
Application Server
IBM WebSphere Application Server V6 - node_name_of_the_server1_node
Custom profile
After federating the node and creating an Application Server, a service can be created named IBM
WebSphere Application Server V6 - node_name_of_the_managed_node.

Chapter 3. Setting up the application serving environment 249

After creating a custom profile, you must federate the node to create a node agent server on the node.
You can also use the administrative console of the deployment manager to create application server
processes on the node. You can create a Windows service for the nodeagent server process or the
application servers on the node.

A node agent server is also created after adding an application server node to a deployment manager cell.
You can create a Windows service for the nodeagent server process as described later.

Viewing the Windows services panel: To view Windows services, open the Control panel and click
Administrative Tools > Services. Select a service to view information about it. Right click the service and
click Properties. Four tabs provide information and functionality. For example, select the Setup type field
on the General tab to change the setup type.

Examples:
Creating a deployment manager service

This example creates a service called IBM WebSphere Application Server V6 - dmgr that starts the dmgr
process:
WASService -add dmgr
-servername dmgr
-profilePath "C:\Program Files\IBM\WebSphere\AppServer\
profiles\Dmgr1"
-wasHome "C:\Program Files\IBM\WebSphere\AppServer"
-logfile "C:\Program Files\IBM\WebSphere\AppServer\
profiles\Dmgr1\logs\startManager.log"
-logRoot "C:\Program Files\IBM\WebSphere\AppServer\
profiles\Dmgr1\logs"
-restart true

After entering the command, messages that are similar to those in the following example display in the
command window:
Adding Service: dmgr
Config Root: C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr1\config
Server Name: dmgr
Profile Path: C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr1
Was Home: D:\Program Files\IBM\WebSphere\AppServer\
Start Args:
Restart: 1
IBM WebSphere Application Server V6 - dmgr service successfully added.

Click Start > Settings > Control Panel > Administrative Tools > Services to work with the new service.

Creating a node agent service

This example creates a service called IBM WebSphere Application Server V6 - nodeagent that starts the
nodeagent process:
WASService -add nodeagent
-servername nodeagent
-profilePath "C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile"
-wasHome "C:\Program Files\IBM\WebSphere\AppServer"
-logfile "C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile\logs\startNode.log"
-logRoot "C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile\logs"
-restart true

After entering the command, messages that are similar to those in the following example display in the
command window:

250 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Adding Service: nodeagent
Config Root: C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile\config
Server Name: nodeagent
Profile Path: C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile
Was Home: C:\Program Files\IBM\WebSphere\AppServer\
Start Args:
Restart: 1
IBM WebSphere Application Server V6 - nodeagent service successfully added.

Creating an Application Server service

This example creates a service called IBM WebSphere Application Server V6 - server2 that starts an
Application Server process:
WASService -add server2
-servername server2
-profilePath "C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile"
-wasHome "C:\Program Files\IBM\WebSphere\AppServer"
-logfile "C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile\logs\startNode.log"
-logRoot "C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile\logs"
-restart true

After entering the command, messages that are similar to those in the following example display in the
command window:
Adding Service: server2
Config Root: C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile\config
Server Name: server2
Profile Path: C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile
Was Home: C:\Program Files\IBM\WebSphere\AppServer\
Start Args:
Restart: 1
IBM WebSphere Application Server V6 - server2 service successfully added.

Updating an existing Application Server service

This example updates an existing service called IBM WebSphere Application Server V6 - server2 with
additional stop arguments, username and password. The user name and password are required by the
stopServer command to stop the application server with security enabled.
WASService -add server2
-servername server2
-profilePath "C:\Program Files\IBM\WebSphere\AppServer\
profiles\CustomProfile"
-stopArgs "-username user_name -password password"
-encodeParams server2

Starting and stopping a server process after creating a Windows service: If you issue the startServer
server1 command or the stopServer server1 after creating a Windows service for server1, a message
that is similar to the following example displays:
Because server1 is registered to run as a Windows Service, the
request to start this server will be completed by starting the
associated Windows Service.

If you issue the startNode command or the stopNode command after creating a Windows service for the
nodeagent process, a message that is similar to the following example displays:

Chapter 3. Setting up the application serving environment 251

Because nodeagent is registered to run as a Windows Service, the
request to start or stop this server will be completed by
starting or stopping the associated Windows Service. Examine
the log files to view messages related to this command.

If you issue the startManager command or the stopManager command after creating a Windows service
for the deployment manager, a message that is similar to the following example displays:
Because dmgr is registered to run as a Windows Service, the
request to start or stop this server will be completed by
starting or stopping the associated Windows Service. Examine
the log files to view messages related to this command.

Stopping a server after enabling security

If you enable security while a Windows service is running, you cannot stop the server from the command
line, even when using the username and password parameters on the stopServer command. A message
similar to the following example is displayed:
Could not stop the IBM WebSphere Application Server V6 -
server_name service on Local Computer. The service
did not return an error. This could be an internal Windows
error or an internal service error. If the problem persists,
contact your system administrator.

The problem is due to the service control of the process. You must change the service to use the proper
stop-server arguments for a secure server.

Use the -stopArgs parameter and the -encodeParams parameter to update the service as described in the
″Updating an existing application server service″ example.

Java virtual machines (JVMs)

The Java virtual machine (JVM) is an interpretive computing engine responsible for running the byte codes
in a compiled Java program. The JVM translates the Java byte codes into the native instructions of the
host machine. The application server, being a Java process, requires a JVM in order to run, and to support
the Java applications running on it. JVM settings are part of an application server configuration.

Using the JVM

As part of configuring an application server, you might define settings that enhance your system’s use of
the Java virtual machine (JVM).

To view and change the JVM configuration for an application server’s process, use the Java Virtual
Machine page of the administrative console or use the wsadmin tool to change the configuration through
scripting.
1. Access the Java Virtual Machine page.
a. Click Servers > Application Servers in the console navigation tree.
b. On the Application Server page, click on the name of the server whose JVM settings you want to
configure.
c. On the settings page for the selected application server, click Java and Process Management >
Process Definition.
d. On the Process Definition page, click Java Virtual Machine.
2. On the Java Virtual Machine page, specify values for the JVM settings as needed and click OK.
3. Click Save on the console task bar.
4. Restart the application server.

252 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
″“Configuring application servers for UTF-8 encoding” on page 201″ provides an example that involves
specifying a value for the Generic JVM Arguments property on the Java Virtual Machine page to enable
UTF-8 encoding on an application server. Enabling UTF-8 allows multiple language encoding support to be
used in the administrative console.

″“Configuring JVM sendRedirect calls to use context root” on page 257″ provides an example that involves
defining a property for the JVM.

Java virtual machine settings

Use this page to view and change the Java virtual machine (JVM) configuration for the application server’s
process.

To view this administrative console page, click Servers > Application Servers >server_name > Process
Definition > Java Virtual Machine.

Classpath:

Specifies the standard class path in which the Java virtual machine code looks for classes.

Enter each classpath entry into a table row. You do not need to add the colon or semicolon at the end of
each entry.

Data type String

Units Class path

Boot Classpath:

Specifies bootstrap classes and resources for JVM code. This option is only available for JVM instructions
that support bootstrap classes and resources. You can separate multiple paths by a colon (:) or semi-colon
(;), depending on operating system of the node.

Data type String

Verbose Class Loading:

Specifies whether to use verbose debug output for class loading. The default is not to enable verbose
class loading.

Data type Boolean

Default false

Verbose Garbage Collection:

Specifies whether to use verbose debug output for garbage collection. The default is not to enable verbose
garbage collection.

Data type Boolean

Default false

Verbose JNI:

Specifies whether to use verbose debug output for native method invocation. The default is not to enable
verbose Java Native Interface (JNI) activity.

Chapter 3. Setting up the application serving environment 253

Data type Boolean
Default false

Initial Heap Size:

Specifies the initial heap size available to the JVM code, in megabytes.

Increasing the minimum heap size can improve startup. The number of garbage collection occurrences are
reduced and a 10% gain in performance is realized.

Increasing the size of the Java heap improves throughput until the heap no longer resides in physical
memory, in general. After the heap begins swapping to disk, Java performance suffers drastically.

Data type Integer

Default The default is 50.

Maximum Heap Size:

Specifies the maximum heap size available to the JVM code, in megabytes.

Increasing the heap size can improve startup. By increasing heap size, you can reduce the number of
garbage collection occurrences with a 10% gain in performance.

Increasing the size of the Java heap improves throughput until the heap no longer resides in physical
memory, in general. After the heap begins swapping to disk, Java performance suffers drastically. Set the
maximum heap size low enough to contain the heap within physical memory.

Data type Integer

Default 0 for iSeries, 256 for all other platforms. Keep the value
low enough to avoid paging or swapping-out-memory-to-
disk.

Debug Mode:

Specifies whether to run the JVM in debug mode. The default is not to enable debug mode support.

If you set the Debug Mode property to true, then you must specify command-line debug arguments as
values for the Debug Arguments property.

Data type Boolean

Default false

Debug Arguments:

Specifies command-line debug arguments to pass to the JVM code that starts the application server
process. You can specify arguments when Debug Mode is enabled.

Debug arguments are only required if the Debug Mode property is set to true. If you enable debugging on
multiple application servers on the same node, make sure that the servers are using different address
arguments, which define the port for debugging. For example, if you enable debugging on two servers and
leave the default debug port for each server as address=7777, the servers could fail to start properly.

Data type String

Units Java command-line arguments

254 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Generic JVM Arguments:

Specifies command line arguments to pass to the Java virtual machine code that starts the application
server process.

The following are optional command line arguments that you can use by entering them into the General
JVM Arguments field. If you enter more than one argument, separate each argument by a space.

Note: If the argument says it is for the IBM Developer Kit only, you cannot use the argument with another
JVM, such as the Sun JDK or the HP JDK.
v -Xquickstart: You can use -Xquickstart for initial compilation at a lower optimization level than in
default mode. Later, depending on sampling results, you can recompile to the level of the initial compile
in default mode. Use -Xquickstart for applications where early moderate speed is more important than
long run throughput. In some debug scenarios, test harnesses and short-running tools, you can improve
startup time between 15-20%.
The -Xquickstart option is not supported on OS/400.
v -Xverify:none: When using this value, the class verification stage is skipped during class loading . By
using -Xverify:none with the just in time (JIT) compiler enabled, startup time is improved by 10-15%.
The -Xverify:none option is not supported on OS/400.
v -Xnoclassgc: You can use this value to disable class garbage collection, which leads to more class
reuse and slightly improved performance. The trade-off is that you won’t be collecting the resources
owned by these classes. You can monitor garbage collection using the verbose:gc configuration setting,
which will output class garbage collection statistics. Examining these statistics will help you understand
the trade-off between the reclaimed resources and the amount of garbage collection required to reclaim
the resources. However, if the same set of classes are garbage collected repeatedly in your workload,
you should disable garbage collection. Class garbage collection is enabled by default.
v -Xgcthreads: You can use several garbage collection threads at one time, also known as parallel
garbage collection. When entering this value in the Generic JVM Arguments field, also enter the
number of processors that your machine has, for example, -Xgcthreads=number_of_processors. On a
node with n processors, the default number of threads is n. You should use parallel garbage collection if
your machine has more than one processor. This argument is valid only for the IBM Developer Kit.
The -Xgcthreads option is not supported on OS/400.
v -Xnocompactgc: This value disables heap compaction which is the most expensive garbage collection
operation. Avoid compaction in the IBM Developer Kit. If you disable heap compaction, you eliminate all
associated overhead.
v -Xinitsh: You can use this value to set the initial heap size where class objects are stored. The method
definitions and static fields are also stored with the class objects. Although the system heap size has no
upper bound, set the initial size so that you do not incur the cost of expanding the system heap size,
which involves calls to the operating system memory manager. You can compute a good initial system
heap size by knowing the number of classes loaded in the WebSphere Application Server product,
which is about 8,000 classes, and their average size. Having knowledge of the applications helps you
include them in the calculation. You can use this argument only with the IBM Developer Kit.
v -Xgpolicy: You can use this value to set the garbage collection policy. If the garbage collection policy
(gcpolicy) is set to optavgpause, concurrent marking is used to track application threads starting from
the stack before the heap becomes full. The garbage collector pauses become uniform and long pauses
are not apparent. The trade-off is reduced throughput because threads might have to do extra work.
The default, recommended value is optthruput. Enter the value as
-Xgcpolicy:[optthruput|optavgpause]. You can use this argument only with the IBM Developer Kit.
v -XX: The Sun-based Java Development Kit (JDK) Version 1.4.2 has generation garbage collection,
which allows separate memory pools to contain objects with different ages. The garbage collection cycle
collects the objects independently from one another depending on age. With additional parameters, you
can set the size of the memory pools individually. To achieve better performance, set the size of the
pool containing short lived objects so that objects in the pool do not live through more then one garbage

Chapter 3. Setting up the application serving environment 255

 collection cycle. The size of new generation pool is determined by the NewSize and MaxNewSize
parameters. Objects that survive the first garbage collection cycle are transferred to another pool. The
size of the survivor pool is determined by parameter SurvivorRatio. If garbage collection becomes a
bottleneck, you can try customizing the generation pool settings. To monitor garbage collection statistics,
use the object statistics in Tivoli Performance Viewer or the verbose:gc configuration setting. Enter the
following values: -XX:NewSize (lower bound) , -XX:MaxNewSize (upper bound), and
-XX:SurvivorRatio=NewRatioSize. The default values are:NewSize=2m MaxNewSize=32m SurvivorRatio=2
However, if you have a JVM with more than 1 GB heap size, you should use the values:
-XX:newSize=640m -XX:MaxNewSize=640m -XX:SurvivorRatio=16, or set 50 to 60% of total heap size to a
new generation pool.
The -XX option is not supported on OS/400.
v -Xminf: You can use this value to specify the minimum free heap size percentage. The heap grows if
the free space is below the specified amount. In reset enabled mode, this option specifies the minimum
percentage of free space for the middleware and transient heaps. This is a floating point number, 0
through 1. The default is .3 (30%).
v -server | -client: Java HotSpot Technology in the Sun-based Java Development Kit (JDK) Version 1.4.2
introduces an adaptive JVM containing algorithms for optimizing byte code execution over time. The
JVM runs in two modes, -server and -client. If you use the default -client mode, there will be a faster
startup time and a smaller memory footprint, but lower extended performance. You can enhance
performance by using -server mode if a sufficient amount of time is allowed for the HotSpot JVM to
warm up by performing continuous execution of byte code. In most cases, use -server mode, which
produces more efficient run-time execution over extended periods. You can monitor the process size
and the server startup time to check the difference between -client and-server.
The -server | -client option is not supported on OS/400.

Data type String

Units Java command line arguments

Executable JAR File Name:

Specifies a full path name for an executable JAR file that the JVM code uses.

Data type String

Units Path name

Disable JIT:

Specifies whether to disable the just in time (JIT) compiler option of the JVM code.

If you disable the JIT compiler, throughput decreases noticeably. Therefore, for performance reasons, keep
JIT enabled.

Data type Boolean

Default false (JIT enabled)
Recommended JIT enabled

Operating System Name:

Specifies JVM settings for a given operating system. When started, the process uses the JVM settings for
the operating system of the node.

Data type String

256 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring JVM sendRedirect calls to use context root
If the com.ibm.websphere.sendredirect.compatibility property is not set and your application servlet code
has statements such as sendRedirect(″/home.html″), your Web browser might display messages such as
Error 404: No target servlet configured for uri: /home.html. To instruct the server not to use the Web
server’s document root and to use instead the Web application’s context root for sendRedirect() calls,
configure the JVM by setting the com.ibm.websphere.sendredirect.compatibility property to a true or false
value.
1. Access the settings page for a property of the JVM.
a. Click Servers > Application Servers in the console navigation tree.
b. On the Application Server page, click on the name of the server whose JVM settings you want to
configure.
c. On the settings page for the selected application server, under Server Infrastructure, click Java and
Process Management > Process Definition.
d. On the Process Definition page, click Java Virtual Machine.
e. On the Java Virtual Machine page, click Custom Properties.
f. On the Custom Properties page, click New.
2. On the settings page for a property, specify a name of
com.ibm.websphere.sendredirect.compatibility and either true or false for the value, then click OK.
3. Click Save on the console task bar.
4. Stop the application server and then restart the application server.

Setting custom JVM properties

In the WebSphere Application Server administrative console, you can change the values of the following
custom JVM properties:
com.ibm.websphere.network.useMultiHome
For a distributed platform:
Set this property in a multihomed environment where WebSphere Application Server is restricted
to listen only on a specific IP address for Discovery and SOAP messages.
The settings for the com.ibm.websphere.network.useMultiHome property are as follows:
v Setting this property to false specifies that WebSphere Application Server will listen on all IP
addresses on the host for Discovery and SOAP messages.
v Setting this property to true specifies that WebSphere Application Server will only listen on the
configured host name for Discovery and SOAP messages. If you set this property to true, you
should have a host name configured on WebSphere Application Server that resolves to a
specific IP address.
v Setting this property to null specifies that WebSphere Application Server will only listen on the
default IP address only.

If you cannot contact the server, check the setting for

com.ibm.websphere.network.useMultihome to ensure it is correct.

You can change the value through the administrative console. Modify the defaults by setting the
value for the server, deployment manager, and node agent. In order for these changes to take
place, you must restart the server.

Steps for this task

1. To set this property, connect to the administrative console and navigate to the indicated page.

Application server Servers > Application Servers >server1> Process

Definition >Control > Java Virtual Machine > Custom
Properties

Chapter 3. Setting up the application serving environment 257

Deployment manager System Administration > Deployment Manager >
Process definition > Control > Java Virtual Machine >
Custom Properties
Node agent System Administration >Node Agent > nodeagent >
Process definition >Control > Java Virtual Machine >
Custom Properties

2. If the com.ibm.websphere.network.useMultiHome property is not present in the list, create a

new property name and indicate its value.
3. Restart the server.
com.ibm.websphere.deletejspclasses
Deletes JavaServer Pages classes for all applications after those applications have been deleted
or updated. By default, the value of this property is true.
Steps for this task
1. Connect to the administrative console and navigate to the Java Virtual Machine Custom
Properties panel.
For a distributed platform:

Base configuration Servers > Application Servers >server1. Then, under

Server Infrastructure, click Java and Process
Management > Process definition > Java Virtual
Machine > Custom Properties
ND configuration System Administration > Node Agents >nodeagent.
Then, under Server Infrastructure, click Java and
Process Management > Process definition > Java
Virtual Machine > Custom Properties

2. If the com.ibm.websphere.deletejspclasses property is not present in the list, create a new

property name.
3. Enter the name and value.
com.ibm.websphere.deletejspclasses.delete
Deletes JavaServer Pages classes for all applications after those applications have been deleted,
but not after they have been updated. By default, the value of this property is true.
Steps for this task
1. Connect to the administrative console and navigate to the Java Virtual Machine Custom
Properties panel.
For a distributed platform:

Base configuration Servers > Application Servers >server1 > Process

definition > Java Virtual Machine > Custom Properties
ND configuration System Administration > Node Agents >nodeagent.
Then, under Server Infrastructure, click Java and
Process Management > Process definition > Java
Virtual Machine > Custom Properties

2. If the com.ibm.websphere.deletejspclasses.delete property is not present in the list, create a

new property name.
3. Enter the name and value.
com.ibm.websphere.deletejspclasses.update
Deletes JavaServer Pages classes for all applications after those applications have been updated,
but not after they have been deleted. By default, the value of this property is true.
Steps for this task

258 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 1. Connect to the administrative console and navigate to the Java Virtual Machine Custom
Properties panel.
For a distributed platform:

Base configuration Servers > Application Servers >server1. Then, under

Server Infrastructure, click Java and Process
Management > Process definition > Java Virtual
Machine > Custom Properties
ND configuration System Administration > Node Agents >nodeagent.
Then, under Server Infrastructure, click Java and
Process Management > Process definition > Java
Virtual Machine> Custom Properties

2. If the com.ibm.websphere.deletejspclasses.update property is not present in the list, create

a new property name.
3. Enter the name and value.

Tuning Java virtual machines

The application server, being a Java process, requires a Java virtual machine (JVM) to run, and to support
the Java applications running on it. As part of configuring an application server, you can fine-tune settings
that enhance system use of the JVM. In addition to the following tuning parameters, see also “Java
memory tuning tips” on page 260.

Use the following JVM parameters, including garbage collection options for IBM Developer Kit 1.4.2, to
tune the Java virtual machine. For instructions on view and change the JVM configuration , go to “Using
the JVM” on page 252. For information on specifying any of the following settings, go to “Java virtual
machine settings” on page 253.
v Specify any or all of the following generic JVM arguments. These optional command line arguments
are passed to the Java virtual machine code that starts the application server process.
– Quickstart (-Xquickstart)
– Avoiding class verification (-Xverify:none)
– Class garbage collection (-Xnoclassgc)
– Garbage collection threads (-Xgcthreads)
– Garbage collection policy (-Xgcpolicy)
– Sun JDK 1.4.2 Generational Garbage Collection (-XX)
You can find more information about generational garbage collection at
http://java.sun.com/docs/hotspot/gc/index.html.
– Sun Java Development Kit 1.4.2 HotSpot JVM warm-up (-server)
– Heap compaction (-Xnocompactgc)
– Initial system heap size (-Xinitsh)
v Set the initial heap size.
v Set the maximum heap size.

Preparing to host applications

Rather than use the default application server provided with the product, you can configure a new server
and set of resources.

The default application server and a set of default resources are available to help you begin quickly. You
can choose instead to configure a new server and set of resources. Here is what you need to do in order
to set up a run-time environment to support applications.
1. Create an application server.
2. Create a virtual host.
3. Configure a Web container.

Chapter 3. Setting up the application serving environment 259

 4. Configure an EJB container.
5. Create resources for data access.
6. Create a JDBC provider and data source.
7. Create a URL and URL provider.
8. Create a JavaMail session.
9. Create resources for session support.
10. Configure a Session Manager.

Java memory tuning tips

Enterprise applications written in the Java language involve complex object relationships and utilize large
numbers of objects. Although, the Java language automatically manages memory associated with object
life cycles, understanding the application usage patterns for objects is important. In particular, verify the
following:
v The application is not over-utilizing objects
v The application is not leaking objects
v The Java heap parameters are set properly to handle a given object usage pattern

Understanding the effect of garbage collection is necessary to apply these management techniques.

The garbage collection bottleneck

Examining Java garbage collection gives insight to how the application is utilizing memory. Garbage
collection is a Java strength. By taking the burden of memory management away from the application
writer, Java applications are more robust than applications written in languages that do not provide
garbage collection. This robustness applies as long as the application is not abusing objects. Garbage
collection normally consumes from 5% to 20% of total execution time of a properly functioning application.
If not managed, garbage collection is one of the biggest bottlenecks for an application, especially when
running on symmetric multiprocessing (SMP) server machines. The Java virtual machine (JVM) uses a
parallel garbage collector to fully exploit an SMP during most garbage collection cycles where the Sun
HotSpot 1.3.1 JVM has a single-threaded garbage collector. For more information about garbage collection
in a Solaris operating environment see ″Performance: Resources for learning″ in the information center.

The garbage collection gauge

You can use garbage collection to evaluate application performance health. By monitoring garbage
collection during the execution of a fixed workload, you gain insight as to whether the application is
over-utilizing objects. Garbage collection can even detect the presence of memory leaks.

You can monitor garbage collection statistics using object statistics in the Tivoli Performance Viewer, or
using the verbose:gc JVM configuration setting. The verbose:gc format is not standardized between
different JVMs or release levels. For a description of the IBM verbose:gc output and more information
about the IBM garbage collector, see ″Performance: Resources for learning″ in the information center.

For this type of investigation, set the minimum and maximum heap sizes to the same value. Choose a
representative, repetitive workload that matches production usage as closely as possible, user errors
included.

To ensure meaningful statistics, run the fixed workload until the application state is steady. It usually takes
several minutes to reach a steady state.

Detecting over-utilization of objects

You can use the Tivoli Performance Viewer to check if the application is overusing objects, by observing
the counters for the JVM runtime. You have to set the -XrunpmiJvmpiProfiler command line option, as

260 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
well as the JVM module maximum level in order to enable the Java virtual machine profiler interface
(JVMPI) counters. The best result for the average time between garbage collections is at least 5-6 times
the average duration of a single garbage collection. If you do not achieve this number, the application is
spending more than 15% of its time in garbage collection.

If the information indicates a garbage collection bottleneck, there are two ways to clear the bottleneck. The
most cost-effective way to optimize the application is to implement object caches and pools. Use a Java
profiler to determine which objects to target. If you can not optimize the application, adding memory,
processors and clones might help. Additional memory allows each clone to maintain a reasonable heap
size. Additional processors allow the clones to run in parallel.

Detecting memory leaks

Memory leaks in the Java language are a dangerous contributor to garbage collection bottlenecks.
Memory leaks are more damaging than memory overuse, because a memory leak ultimately leads to
system instability. Over time, garbage collection occurs more frequently until the heap is exhausted and
the Java code fails with a fatal Out of Memory exception. Memory leaks occur when an unused object has
references that are never freed. Memory leaks most commonly occur in collection classes, such as
Hashtable because the table always has a reference to the object, even after real references are deleted.

High workload often causes applications to crash immediately after deployment in the production
environment. This is especially true for leaking applications where the high workload accelerates the
magnification of the leakage and a memory allocation failure occurs.

The goal of memory leak testing is to magnify numbers. Memory leaks are measured in terms of the
amount of bytes or kilobytes that cannot be garbage collected. The delicate task is to differentiate these
amounts between expected sizes of useful and unusable memory. This task is achieved more easily if the
numbers are magnified, resulting in larger gaps and easier identification of inconsistencies. The following
list contains important conclusions about memory leaks:
v Long-running test
Memory leak problems can manifest only after a period of time, therefore, memory leaks are found
easily during long-running tests. Short running tests can lead to false alarms. It is sometimes difficult to
know when a memory leak is occurring in the Java language, especially when memory usage has
seemingly increased either abruptly or monotonically in a given period of time. The reason it is hard to
detect a memory leak is that these kinds of increases can be valid or might be the intention of the
developer. You can learn how to differentiate the delayed use of objects from completely unused objects
by running applications for a longer period of time. Long-running application testing gives you higher
confidence for whether the delayed use of objects is actually occurring.
v Repetitive test
In many cases, memory leak problems occur by successive repetitions of the same test case. The goal
of memory leak testing is to establish a big gap between unusable memory and used memory in terms
of their relative sizes. By repeating the same scenario over and over again, the gap is multiplied in a
very progressive way. This testing helps if the number of leaks caused by the execution of a test case is
so minimal that it is hardly noticeable in one run.
You can use repetitive tests at the system level or module level. The advantage with modular testing is
better control. When a module is designed to keep the private module without creating external side
effects such as memory usage, testing for memory leaks is easier. First, the memory usage before
running the module is recorded. Then, a fixed set of test cases are run repeatedly. At the end of the test
run, the current memory usage is recorded and checked for significant changes. Remember, garbage
collection must be suggested when recording the actual memory usage by inserting System.gc() in the
module where you want garbage collection to occur, or using a profiling tool, to force the event to occur.
v Concurrency test
Some memory leak problems can occur only when there are several threads running in the application.
Unfortunately, synchronization points are very susceptible to memory leaks because of the added
complication in the program logic. Careless programming can lead to kept or unreleased references.

Chapter 3. Setting up the application serving environment 261

 The incident of memory leaks is often facilitated or accelerated by increased concurrency in the system.
The most common way to increase concurrency is to increase the number of clients in the test driver.
Consider the following points when choosing which test cases to use for memory leak testing:
– A good test case exercises areas of the application where objects are created. Most of the time,
knowledge of the application is required. A description of the scenario can suggest creation of data
spaces, such as adding a new record, creating an HTTP session, performing a transaction and
searching a record.
– Look at areas where collections of objects are used. Typically, memory leaks are composed of
objects within the same class. Also, collection classes such as Vector and Hashtable are common
places where references to objects are implicitly stored by calling corresponding insertion methods.
For example, the get method of a Hashtable object does not remove its reference to the retrieved
object.

Tivoli Performance Viewer can help find memory leaks. For best results, repeat experiments with
increasing duration, like 1000, 2000, and 4000-page requests. The Tivoli Performance Viewer graph of
used memory should have a sawtooth shape. Each drop on the graph corresponds to a garbage
collection. There is a memory leak if one of the following occurs:
v The amount of memory used immediately after each garbage collection increases significantly. The
sawtooth pattern looks more like a staircase.
v The sawtooth pattern has an irregular shape.

Also, look at the difference between the number of objects allocated and the number of objects freed. If
the gap between the two increases over time, there is a memory leak.

Heap consumption indicating a possible leak during a heavy workload (the application server is
consistently near 100% CPU utilization), yet appearing to recover during a subsequent lighter or near-idle
workload, is an indication of heap fragmentation. Heap fragmentation can occur when the JVM can free
sufficient objects to satisfy memory allocation requests during garbage collection cycles, but the JVM does
not have the time to compact small free memory areas in the heap to larger contiguous spaces.

Another form of heap fragmentation occurs when small objects (less than 512 bytes) are freed. The
objects are freed, but the storage is not recovered, resulting in memory fragmentation until a heap
compaction has been run.

To avoid heap fragmentation, turn on the -Xcompactgc flag in the JVM advanced settings command line
arguments. The -Xcompactgc function verifies that each garbage collection cycle eliminates fragmentation.
However, compaction is a relatively expensive operation. See the heap compaction command line
argument (-Xnocompactgc) in “Java virtual machine settings” on page 253 for more information.

Java heap parameters

The Java heap parameters also influence the behavior of garbage collection. Increasing the heap size
supports more object creation. Because a large heap takes longer to fill, the application runs longer before
a garbage collection occurs. However, a larger heap also takes longer to compact and causes garbage
collection to take longer. Refer to the sections on Java Heap sizes in “Java virtual machine settings” on
page 253 for more information.

For performance analysis, the initial and maximum heap sizes should be equal.

When tuning a production system where the working set size of the Java application is not understood, a
good starting value for the initial heap size is 25% of the maximum heap size. The JVM then tries to adapt
the size of the heap to the working set size of the application.

262 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Varying Java Heap Settings

-ms256M, -mx256M Time spent in Garbage Collection

100 Processor #1
CPU%

80
60
40 Processor #2
20
0

Time

-ms128M, -mx128M Time spent in Garbage Collection

100 Processor #1
CPU%

80
60
40
Processor #2
20
0

Time

-ms64M, -mx64M Time spent in Garbage Collection

100
Processor #1
CPU%

80
60
40 Processor #2
20
0

Time

The illustration represents three CPU profiles, each running a fixed workload with varying Java heap
settings. In the middle profile, the initial and maximum heap sizes are set to 128MB. Four garbage
collections occur. The total time in garbage collection is about 15% of the total run. When the heap
parameters are doubled to 256MB, as in the top profile, the length of the work time increases between
garbage collections. Only three garbage collections occur, but the length of each garbage collection is also
increased. In the third profile, the heap size is reduced to 64MB and exhibits the opposite effect. With a
smaller heap size, both the time between garbage collections and the time for each garbage collection are
shorter. For all three configurations, the total time in garbage collection is approximately 15%. This
example illustrates an important concept about the Java heap and its relationship to object utilization.
There is always a cost for garbage collection in Java applications.

Run a series of test experiments that vary the Java heap settings. For example, run experiments with
128MB, 192MB, 256MB, and 320MB. During each experiment, monitor the total memory usage. If you
expand the heap too aggressively, paging can occur. Use the vmstat command or the Windows NT or
Windows 2000 Performance Monitor to check for paging. If paging occurs, reduce the size of the heap or
add more memory to the system. When all the runs are finished, compare the following statistics:
v Number of garbage collection calls
v Average duration of a single garbage collection call
v Ratio between the length of a single garbage collection call and the average time between calls

If the application is not over-utilizing objects and has no memory leaks, the state of steady memory
utilization is reached. Garbage collection also occurs less frequently and for short duration.

If the heap free space settles at 85% or more, consider decreasing the maximum heap size values
because the application server and the application are under-utilizing the memory allocated for heap.

For more information about garbage collection see ″Performance: Resources for learning″ in the
information center.

For current information available from IBM Support on known problems and their resolution, see the IBM
Support page.

Chapter 3. Setting up the application serving environment 263

IBM Support has documents that can save you time gathering information needed to resolve this problem.
Before opening a PMR, see the IBM Support page.

Configuring multiple network interface card support

Use this task to first prepare your server for multiple network interface card support and enable multiple
network interface card logic, including configuring multiple network interface cards to coexist on the same
machine.
1. Configure object request broker (ORB) properties to support multiple network interface cards.
v Set the com.ibm.CORBA.LocalHost property to resolve to a valid host name or IP address. The value
should not resolve to a local host or loop back address (for example, 127.0.0.1).
a. In the administrative console, click Servers > Application servers > server_name > Java and
process management > Process Definition > Java Virtual Machine.
b. Add the following generic JVM argument:
-Dcom.ibm.CORBA.LocalHost=xxxx.xx.xx.xx -Dcom.ibm.websphere.network.useMultiHome=
false -Dcom.ibm.CORBA.ServerSocketQueueDepth=50 -Dcom.ibm.ws.orb.transport
.useMultiHome=false
2. Update the host name for all HTTP transport chains. In the administrative console, click Servers >
Application servers > server_name > Web container settings > Web container transport chains.
Update the host name for all of the transport chains listed on this page. The value should not resolve
to a local host or loop back address (for example, 127.0.0.1).
3. Change the initial state to stopped for each of the listener ports. In the administrative console, click:
v Servers > Application servers > server_name > Messaging > Message listener service >
Listener ports > SamplePtoPListenerPort
v Servers > Application servers > server_name > Messaging > Message Listener Service >
Listener Ports > SamplePubSubListenerPort
Update the state to stopped for each port.
4. Change the initial state of the JMS server to stopped. In the administrative console, click Servers >
JMS Servers >JMS_server > Initial state > stopped.
5. Apply these changes to all application servers and the deployment manager.

By completing these steps, you enabled multiple network interface card support.

To configure multiple application servers to coexist on a single machine that is using two network interface
cards, perform the following steps:
1. Install the WebSphere Application Server base product for each network interface card. To install on
distributed platforms, see ″Installing the product and additional software″ in the information center for
more information.
2. Start the server that is on the first network interface card. Follow the preceding steps in this task to
prepare this server for multiple network interface card support and enable multiple network interface
card logic. After you complete this step, stop the server.
3. Start the server that is on the other network interface card. Follow the preceding steps in this task to
prepare this server for multiple network interface card support and enable multiple network interface
card logic. After you complete this step, stop the server.
4. Start the servers on both network interface cards.

By completing these steps, you enabled multiple application servers to coexist on a single machine that
has two network interface cards.

264 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Tuning application servers
The WebSphere Application Server contains interrelated components that must be harmoniously tuned to
support the custom needs of your end-to-end e-business application.

This group of interrelated components is known as the “Queuing network” on page 43. The queuing
network helps the system achieve maximum throughput while maintaining the overall stability of the
system.

The follow steps describe various tuning tasks that may improve your application server performance. You
can choose to implement any of these application server settings.
v Tune the object request broker. An Object Request Broker (ORB) manages the interaction between
clients and servers, using the Internet InterORB Protocol (IIOP). It supports client requests and
responses received from servers in a network-distributed environment. You can tune the ORB with the
following parameters:
– Set Pass by reference (com.ibm.CORBA.iiop.noLocalCopies) as described in “Object Request
Broker service settings” on page 2033.
– Set the Connection cache minimum (com.ibm.CORBA.MaxOpenConnections) as described in
“Object Request Broker service settings” on page 2033.
– Set Maximum size as described in “Thread pool settings” on page 209
– Set com.ibm.CORBA.ServerSocketQueueDepth as described in “Object Request Broker custom
properties” on page 2036.
– Set the com.ibm.CORBA.FragmentSize as described in “Object Request Broker custom properties”
on page 2036.
The “Object Request Broker tuning guidelines” on page 2031 offer tips on using these parameters to
tune the ORB.
v Tune the XML parser definitions.
– Description: Facilitates server startup by adding XML parser definitions to the jaxp.properties and
xerxes.properties files in the ${install_root}/jre/lib directory. The XMLParserConfiguration value
might change as new versions of Xerces are provided.
– How to view or set: Insert the following lines in both files:
javax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
javax.xml.parsers.DocumentBuildFactory=org.apache.xerces.jaxp.
DocumentBuilderFactoryImpl
org.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.
StandardParserConfiguration
– Default value: None
– Recommended value: None
v Tune the dynamic cache service. Using the dynamic cache service can improve performance. See
“Task overview: Using the dynamic cache service to improve performance” on page 2122 for information
about using the dynamic cache service and how it can affect your application server performance.
v Tune the Web container. The WebSphere Application Server Web container manages all HTTP
requests to servlets, JSPs and Web services. Requests flow through a transport chain to the Web
container. The transport chain defines the important tuning parameters for performance for the Web
container. There is a transport chain for each TCP port that WebSphere Application Server is listening
on for HTTP requests. For example, the default HTTP port 9080 is defined in Web container inbound
channel chain. Use the following parameters to tune the Web container:
– HTTP requests are processed by a pool of server threads. The minimum and maximum thread pool
size for the Web container can be configured for optimal performance. Generally, 5 to 10 threads per
server CPU will provide the best throughput. The number of threads configured does not represent
the number of requests WebSphere can process concurrently. Requests are queued in the transport
chain when all threads are busy. To specify the thread pool settings:
1. Click Servers > Application Servers >server_name Web Container Settings> Web Container
> Web container transport chains.

Chapter 3. Setting up the application serving environment 265

 2. Select the normal inbound chain for serving requests. This will usually be named
WCInboundDefault, on port 9080.
3. Click TCP Inbound Channel (TCP_2).
4. Set Thread Pools under Related Items.
5. Select WebContainer.
6. Enter values for Minimum Size and Maximum Size.
– The HTTP 1.1 protocol provides a ″keep-alive″ feature to enable the TCP connection between HTTP
clients and the server to remain open between requests. By default WebSphere Application Server
will close a given client connection after a number of requests or a timeout period. After a connection
is closed, it will be recreated if the client issues another request. Early closure of connections can
reduce performance. Enter a value for the maximum number of persistent requests to (keep-alive) to
specify the number of requests that are allowed on a single HTTP connection. Enter a value for
persistent timeouts to specify the amount of time, in seconds, that the HTTP transport channel allows
a socket to remain idle between requests. To specify values for Maximum persistent requests and
Persistent timeout:
1. Click Servers > Application Servers >server_name Web Container Settings> Web Container
> Web container transport chains.
2. Select the normal inbound chain for serving requests. This will usually be named
WCInboundDefault, on port 9080.
3. Click HTTP Inbound Channel (HTTP_2).
4. Enter values for Maximum persistent requests and Persistent timeout.
v Tune the EJB container. An EJB container is automatically created when you create an application
server. After the EJB container is deployed, you can use the following parameters to make adjustments
that improve performance.
– Set the Cleanup interval and the Cache size as described in “EJB cache settings” on page 1033.
– Break CMP enterprise beans into several enterprise bean modules while assembling EJB
modules. See ″Assembling EJB modules″ in the information center for more information.
See also “EJB method Invocation Queuing” on page 1014.
v Tune the session management. The installed default settings for session management are optimal for
performance. See “Tuning session management” on page 987 and “Tuning parameter settings” on page
988 for more information about tuning session management.
v Tune the data sources. A data source is used to access data from the database. The following
parameters reveal how the number of physical connections within a connection pool can change
performance.
– Review information on “Connection pooling” on page 1336.
– Set the Maximum connection pool and Minimum connection pool as described in “Connection
pool settings” on page 1400.
– Set the Statement cache size as described in “Data source settings” on page 1372.

Web services client to Web container optimized communication

To improve performance, there is an optimized communication path between a Web services client
application and a Web container that are located in the same application server process. Requests from
the Web services client that are normally sent to the Web container using a network connection are
delivered directly to the Web container using an optimized local path. The local path is available because
the Web services client application and the Web container are running in the same process.

This direct communication eliminates the need for clients and web containers that are in the same process
to communicate over the network. For example, a Web services client might be running in an application
server. Instead of accessing the network to communicate with the Web container, the Web services client
can communicate with the Web container using the optimized local path. This optimized local path
improves the performance of the application server by allowing Web services clients and Web containers
to communicate without using network transports.

266 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
In a clustered environment, there is typically an HTTP server (such as IBM HTTP server) that handles
incoming client requests, distributing them to the correct application server in the cluster. The HTTP server
uses information about the requested application and the defined virtual hosts to determine which
application server receives the request. The Web services client also uses the defined virtual host
information to determine whether the request can be served by the local Web container. You must define
unique values for the host and port on each application server. You cannot define the values of host and
port as wild cards denoted by the asterisk symbol (*) when you enable the optimized communication
between the Web services application and the Web container. Using wild cards indicate that the local Web
container can handle Web services requests for all destinations.

The optimized local communication path is disabled by default. You can enable the local communication
path with the enableInProcessConnections custom property. Before configuring this custom property, make
sure that you are not using wild cards for host names in your Web container end points. Set this property
to true in the Web container to enabled the optimized local communication path. When disabled, the Web
services client and the Web container communicate using network transports.

For information about how to configure the enableInProcessConnections custom property, see the
Developing and deploying applications PDF.

When the optimized local communication path is enabled, logging of requests through the local path uses
the same log attributes as the network channel chain for the Web container. To use a different log file for
in process requests than the log file for network requests, use a custom property on the HTTP Inbound
Channel in the transport chain. Use the inProcessLogFilenamePrefix custom property to specify a string
that is added to the beginning of the network log file name to create a file name that is unique. Requests
through the local process path are logged to this specified file. For example, if the log filename is
../httpaccess.log for a network chain, and the inProcesslLogFilenamePrefix custom property is set to
“local” on the HTTP channel in that transport chain, the local log file name for requests to the host
associated with that chain is /localhttpaccess.log.

Application servers: Resources for learning

Use the following links to find relevant supplemental information about configuring application servers. The
information resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of
the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

View links to additional information about:

v Programming instructions and examples
v Programming specifications
v Administration

Programming instructions and examples

v WebSphere Application Server education at http://www.ibm.com/software/webservers/learn/.

Programming specifications
v The JavaTM Virtual Machine Specification, Second Edition at http://java.sun.com/docs/books/vmspec/.
v Sun’s technology forum for the JavaTM Virtual Machine Specification at
http://forum.java.sun.com/forum.jsp?forum=37

Administration
v Listing of all IBM WebSphere Application Server Redbooks at http://publib-
b.boulder.ibm.com/Redbooks.snf/Portals/WebSphere.

Chapter 3. Setting up the application serving environment 267

Balancing workloads with clusters
Consider your options for configuring application servers. See “Managing application servers” on page 202
for more information.

To monitor application servers and manage the workloads of servers, use server clusters and cluster
members.

To assist you in understanding how to configure and use clusters for workload management, consider this
scenario. Client requests are distributed among the cluster members on a single machine. (A client refers
to any servlet, Java application, or other program or component that connects the end user and the
application server that is being accessed.) In more complex workload management scenarios, you can
distribute cluster members to remote machines.
1. Decide which application server you want to cluster.
2. Decide whether you want to replicate data. Replication is a service that transfers data, objects, or
events among application servers. See “Replicating data across application servers in a cluster” on
page 283 for more information. You can create a replication domain when creating a cluster.
3. Deploy the application onto the application server. See the Developing and deploying applications PDF
for information on how to perform this task.
4. After configuring the application server and the application components exactly as you want them to
be, create a cluster. The original server instance becomes a cluster member that is administered
through the cluster. See “Creating clusters” on page 271 for more information.
5. You can create one or more cluster members of the cluster.
6. Configure a backup cluster that handles requests if the primary cluster fails.
7. Start all of the application servers by starting the cluster. Workload management automatically begins
when you start the cluster members of the application server.
8. Once you have the cluster running, you can perform the following tasks:
v Stop the cluster.
v Upgrade applications on clusters. (See the Developing and deploying applications PDF for
information on how to perform this task.)
v Detect and handle problems with server clusters and their workloads.
v Tune the behavior of the workload management run time. If your application is experiencing
problems with timeouts or your network experiences extreme latency, change the timeout interval for
the com.ibm.CORBA.RequestTimeout property. Or, if the workload management state of the client is
refreshing too soon or too late, change the interval for the
com.ibm.websphere.wlm.unusable.interval property.

For stand-alone Java clients, you must define a bootstrap host. Stand-alone Java clients are clients that
are located on a different machine from the application server and have no administrative server. Add the
following line to the Java Virtual Machine (JVM) arguments for the client:
-Dcom.ibm.CORBA.BootstrapHost=machine_name

where machine_name is the name of the machine on which the administrative server is running.

Clusters and workload management

Clusters are sets of servers that are managed together and participate in workload management. The
servers that are members of a cluster can be on different host machines, as opposed to the servers that
are part of the same node and must be located on the same host machine. A cell can have no clusters,
one cluster, or multiple clusters.

Servers that belong to a cluster are members of that cluster set and must all have identical application
components deployed on them. Other than the applications configured to run on them, cluster members do

268 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
not have to share any other configuration data. One cluster member might be running on a huge
multi-processor enterprise server system, while another member of that same cluster might be running on
a smaller system. The server configuration settings for each of these two cluster members are very
different, except in the area of application components assigned to them. In that area of configuration, they
are identical. This allows client work to be distributed across all the members of a cluster instead of all
workload being handled by a single application server.

When you create a cluster, you make copies of an existing application server template. The template is
most likely an application server that you have previously configured. You are offered the option of making
that server a member of the cluster. However, it is recommended that you keep the server available only
as a template, because the only way to remove a cluster member is to delete the application server. When
you delete a cluster, you also delete any application servers that were members of that cluster. There is no
way to preserve any member of a cluster. Keeping the original template intact allows you to reuse the
template if you need to rebuild the configuration.

A vertical cluster has cluster members on the same node, or physical machine. A horizontal cluster has
cluster members on multiple nodes across many machines in a cell. You can configure either type of
cluster, or have a combination of vertical and horizontal clusters.

See “Balancing workloads with clusters” on page 268 to specify the amount of work targeted to each
cluster member. You can distribute client tasks according to the capacities of different machines in the
enterprise. A Web server plug-in routes application access among cluster members by server weighting, to
provide better distribution control.

WebSphere Application Server can respond to increased use of an enterprise application by automatically
replicating the application to additional cluster members as needed. This lets you deploy an application on
a cluster instead of on a single node, without considering workload.

Multiple servers that can service the same client request is the basis for failover support. If a server fails
while processing a client request, the failed request can be rerouted to any of the remaining cluster
members. In fact, several servers could fail, and as long as at least one cluster member is running, client
requests can continue to be serviced. For further information backing up failed processes, see “Replicating
data across application servers in a cluster” on page 283.

See “Backup clusters” on page 279 for information on backup cluster support. A backup cluster continues
functioning when all cluster members of the primary cluster are not available.

Clusters and node groups

Node groups bound clusters. All cluster members of a given cluster must be members of the same node
group.

Any application you install to a cluster must be able to execute on any application server that is a member
of that cluster. For the application you deploy to run successfully, all the members of the cluster must be
located on nodes that meet the requirements for that application.

In a cell that has many different server configurations, it might be difficult to determine which nodes have
the capabilities to host your application. A node group can be used to define groups of nodes that have
enough in common to host members of a given cluster. All cluster members in a cluster must be in the
same node group.

All nodes are members of at least one node group. When you create a cluster, the first application server
you add to the cluster defines the node group that bounds the cluster. All other cluster members you add
to the cluster can only be on nodes that are members of this same node group. When you create a new
cluster member in the administrative console, you are allowed to create the application server on a node
that is a member of the node group for that cluster only.

Chapter 3. Setting up the application serving environment 269

Nodes can be members of multiple node groups. If the first cluster member you add to a cluster has
multiple node groups defined, the system automatically chooses the node group that bounds the cluster.
You can change the node group by modifying the cluster settings. Use the “Server cluster settings” on
page 275 page to change the node group.

Workload management (WLM) for distributed platforms

Workload management optimizes the distribution of client processing tasks. Incoming work requests are
distributed to the application servers, enterprise beans, servlets, and other objects that can most effectively
process the requests. Workload management also provides failover when servers are not available,
improving application availability.

Workload management provides the following benefits to WebSphere Application Server applications:
v It balances client workloads, allowing processing tasks to be distributed according to the capacities of
the different machines in the system.
v It provides failover capability by redirecting client requests if one or more servers is unable to process
them. This improves the availability of applications and administrative services.
v It enables systems to be scaled up to serve a higher client load than provided by the basic
configuration. With clustering, additional instances of servers, servlets, and other objects can easily be
added to the configuration.
v It enables servers to be transparently maintained and upgraded while applications remain available for
users.
v It centralizes the administration of servers and other objects.

In the WebSphere Application Server environment, you implement workload management by using
clusters, transports, and replication domains.

Techniques for managing state

Multiple machine scaling techniques rely on using multiple copies of an application server; multiple
consecutive requests from various clients can be serviced by different servers. If each client request is
completely independent of every other client request, it does not matter if consecutive requests are
processed on the same server. However, in practice, client requests are not independent. A client often
makes a request, waits for the result, then makes one or more subsequent requests that depend on the
results received from the earlier requests. This sequence of operations on behalf of a client falls into two
categories:
Stateless
A server processes requests based solely on information provided with each request and does not
reply on information from earlier requests. The server does not need to maintain state information
between requests.
Stateful
A server processes requests based on both the information provided with each request and
information stored from earlier requests. The server needs to access and maintain state
information generated during the processing of an earlier request.

For stateless interactions, it does not matter whether different requests are processed by different servers.
However, for stateful interactions, the server that processes a request needs access to the state
information necessary to service that request. Either the same server can process all requests that are
associated with the same state information, or the state information can be shared by all servers that
require it. In the latter case, accessing the shared state information from the same server minimizes the
processing overhead associated with accessing the shared state information from multiple servers.

The load distribution facilities in WebSphere Application Server use several different techniques for
maintaining state information between client requests:
v Session affinity, where the load distribution facility recognizes the existence of a client session and
attempts to direct all requests within that session to the same server.

270 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Transaction affinity, where the load distribution facility recognizes the existence of a transaction and
attempts to direct all requests within the scope of that transaction to the same server.
v Server affinity, where the load distribution facility recognizes that although multiple servers might be
acceptable for a given client request, a particular server is best suited for processing that request.
v The session manager, which is part of each application server, stores client session information and
takes session affinity and server affinity into account when directing client requests to the cluster
members of an application server. The workload management service considers server affinity and
transaction affinity when directing client requests among the cluster members of an application server.

Creating clusters
Use this task to create clusters, which are sets of application servers that are managed together and
participate in workload management.

You can manage application servers collectively using a cluster. Use the “Server cluster collection” on
page 274 to view and manage the cluster.
1. Enter basic cluster information.
a. In the administrative console, click Servers > Clusters > New.
b. Create a name for the cluster.
c. To enable or disable node-scoped routing optimization, select Prefer local. The default is enabled,
which indicates that, if possible, Enterprise JavaBeans (EJB) requests are routed to the client node.
If you enable this feature, performance is improved because client requests are sent to local
enterprise beans.
d. To create a replication domain for this cluster, select Create a replication domain for this cluster.
Use replication domains to transfer data, objects, or events for session manager, dynamic cache,
or stateful session beans among the application servers in a cluster. Create a separate replication
domain to use with each component that acts as a consumer of the replication. For example, you
can configure one replication domain to use with a session manager and another domain to use
with dynamic cache. The replication domain name that is created is identical to the cluster name.
See “Replicating data across application servers in a cluster” on page 283 for more information.
e. Choose whether to create an empty cluster or to create a cluster based on an existing server.
To create an empty cluster, select Do not include an existing server in this cluster.
To create a cluster based on an existing server, choose Select an existing server to add to this
cluster and select the server you want to add. The server you add becomes a template for any
additional cluster members that you add to the cluster. Be sure that the template is configured
correctly before adding more cluster members that are based on this template. Note that this is the
only time you are able to add an existing server to the cluster. After you create the first cluster
member, you cannot add other existing application servers to the cluster. Be careful when adding
an existing server because the only way to remove an application server from a cluster is to delete
the application server. Consider using the existing server as a template for the cluster members but
not as a cluster member. Keeping the original application server out of the cluster allows you to
reuse the template if you need to rebuild the configuration.
f. If you chose to add an existing server, specify the server weight. The weight value controls the
amount of work that is directed to the application server. If the weight value for this server is greater
than the weight values assigned to other servers in the cluster, then the server receives a larger
share of the workload. The weight value represents a relative proportion of the workload that is
assigned to a particular application server. The value can range from 0 to 20.
2. Create cluster members.

Note: With WebSphere Application Server Version 6.0, you can upgrade a portion of the nodes in a
cell, while leaving others at the older release level. This means that, for a period of time, you
might be managing servers that are at the current release and servers that are running the
newer release in the same cell. Note that in this mixed environment, there are some restrictions
on what you can do with clusters and cluster members:

Chapter 3. Setting up the application serving environment 271

 v You cannot create a cluster member using a server running on WebSphere Application
Server Version 5.x.
v You cannot add a member that is running WebSphere Application Server Version 5.x to any
cluster.
v You can add a new WebSphere Application Server Version 6.0 cluster member to a mixed
cluster only if the cluster already contains a WebSphere Application Server Version 6.0
member that was upgraded from WebSphere Application Server Version 5.x. All new cluster
members must be running WebSphere Application Server Version 6.0.
For each new cluster member, perform the following actions:
a. Type the name of a new application server (cluster member) to add to the cluster.
b. Select the node on which the server resides.
c. Specify the server weight. The weight value controls the amount of work directed to the application
server. If the weight value for the server is greater than the weight values assigned to other servers
in the cluster, then the server receives a larger share of the workload. The value can range from 0
to 20.
d. Make sure that Generate Unique HTTP Port is selected.
e. Specify the server template. You can choose the default application server template or an existing
application server template. All the application servers you add after the first application server use
the same template.
f. Click Apply to finish the cluster member. You can add more cluster members. All cluster members
you add are based on the same server template.
3. View the summary. View a summary of the changes and then click Finish. Your cluster is created.
4. Define a virtual host with a unique port number. See “Configuring virtual hosts” on page 177 for more
information.
a. In the administrative console, click Environment > Virtual Hosts > default_host > Host Aliases.
b. Click New and, on the settings page for a virtual host that displays, specify an administrative name
for the virtual host.
c. Under Additional Properties, click Host Aliases and define a unique port number for the virtual
host.
5. Save your configuration. As part of saving the change to the configuration, you can select
Synchronize changes with Nodes before clicking Save on the Save page.
6. Before you can start the cluster, the configuration needs to be synchronized to the nodes. If you
selected Synchronize changes with Nodes when saving your configuration in the previous step, you
can ignore this step. If you are running automatic synchronization, wait until synchronization runs. Or,
run manual synchronization to get the configuration files moved to the nodes. Click System
administration > Nodes and, on the Nodes page, select the node and click Synchronize or Full
resynchronize. The Nodes page displays status indicating whether the node is synchronized.
7. To further configure a cluster, click Servers > Clusters. To view the settings for the cluster, click on the
cluster Name. Note that unless you have clicked Save and saved your administrative configuration,
you only see the Configuration and Local Topology tabs; to see the Runtime tab you must save
your administrative configuration. Also, ensure that changes are synchronized to the nodes (step 7).

You can create cluster members or start the cluster. See “Balancing workloads with clusters” on page 268
for more information about cluster configuration options.

Use scripting to automate the task of creating clusters. See the Administering applications and their
environment PDF for more information.

Creating a cluster : Basic cluster settings

Use this page to enter the basic cluster settings.

To view this administrative console page, click Servers > Clusters > New.

272 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Cluster name:

Specifies the name of the cluster. The cluster name must be unique within the cell.

Prefer local:

Specifies that the node scoped routing optimization is enabled or disabled. The default is enabled, which
means that Enterprise JavaBeans (EJB) requests are routed to the client node when possible. Enabling
this setting improves performance because client requests are sent to local enterprise beans.

Create replication domain for this cluster:

Specifies that when the cluster is created, a replication domain is also created with the cluster. The
replication service transfers both Java 2 Platform, Enterprise Edition (J2EE) application data and any
internal data that is used to maintain the application data among WebSphere Application Server run-time
processes in a cluster of application servers.

Create a separate replication domain to use with each component that acts as a consumer of the
replication. For example, you can configure one replication domain to use with a session manager and
another domain to use with dynamic cache. The replication domain name that is created is identical to the
cluster name. To manage the replication domain that is created, click Environment > Replication
domains in the administrative console.

Existing server:

Specifies whether to create an empty cluster or to add an existing application server to the cluster.

To create a cluster without an existing application server as a cluster member, click Do not include an
existing server in this cluster.

To add an existing server to the cluster, click Select an existing server to add to this cluster and
choose the application server to add to the cluster. This application server becomes a template for any
additional cluster members that you add to the cluster. When adding servers to a cluster, the only way to
remove an application server from a cluster is to delete the application server.

Weight:

Specifies the amount of work that is directed to the application server.

If the weight value for the server is greater than the weight values that are assigned to other servers in the
cluster, the server receives a larger share of the cluster workload. The value can range from 0 to 20. Enter
zero to indicate that you do not want requests to route to this application server unless this server is the
only server that is available to receive requests.

Creating a cluster : Basic cluster member settings

Use this page to enter cluster member settings. You can create a cluster member during or after cluster
creation.

You can create a new application server to become a cluster member in two ways:
v Create a cluster member when you create the cluster. In the administrative console, click Servers >
Clusters > New in the administrative console.
v Create a cluster member after you create the cluster. In the administrative console, click Servers >
Clusters > cluster_name > Cluster Members > New.

Member name:

Chapter 3. Setting up the application serving environment 273

Specifies the name of the application server that is created for the cluster.

The member name must be unique within the cell.

Select node:

Specifies the node on which the application server resides.

Core group: Specifies the core group in which the application server resides. This field is displayed only
if you have multiple core groups configured. You can change this value for the first cluster member only.

Generate unique HTTP ports:

Specifies that a unique HTTP port is generated for the application server. By generating unique HTTP
ports for the application server, you avoid potential port collisions and configurations that are not valid.

Select template:

Specifies an application server template for the new application server.

The new application server contains identical configuration settings to the application server template.

Click Existing application server to choose from a list of application server templates. The application
server that you choose becomes a template for the cluster member.

The template options are available only for the first cluster member that is created. All cluster members
that you create after the first member are identical.

Creating a cluster : Summary settings

Use this administrative console page to save settings that you modified when creating a cluster or cluster
member.

You can view this administrative console page when creating a new cluster or a new cluster member. This
summary page displays your configuration changes before you commit the changes and a new cluster or
cluster member is created. To create a cluster or cluster member, click the following paths in the
administrative console:
v Click Servers > Clusters > New to create a new cluster.
v Click Servers > Clusters > cluster_name > Cluster Members > New to create new application servers
for an existing cluster.

Review the changes to your configuration. Click Finish to complete and save your work. The bounding
node group of the cluster is based on the first application server that is added as a member of the cluster.
To select a different bounding node group, click Servers > Clusters >cluster_name in the administrative
console to edit the settings for the cluster.

Server cluster collection

Use this page to view information about and manage clusters of application servers.

To view this administrative console page, click Servers > Clusters.

Click New to access the Create New Cluster page, which you use to define a new cluster.

Name:

Specifies a logical name for the cluster. The name must be unique among clusters within the containing
cell.

274 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Status:

Specifies whether cluster members are stopped, starting, or running.

If all cluster members are stopped, the cluster status and state is stopped. After you request to start a
cluster by clicking Start or Ripplestart, the cluster state briefly changes to starting and each server that is
a member of that cluster launches, if it is not already running. When the first member launches, the state
changes to partially started. The state remains partially started until all cluster members are running, then
the state changes to running and the status is started. Similarly, when stopping a cluster by clicking Stop
or ImmediateStop, the state changes to partially stopped as the first member stops and changes to
stopped when all members are not running.

Server cluster settings:

Use this page to view or change the configuration and local topology of a server cluster instance. Provided
you saved your administrative configuration after creating the server cluster instance, you can also view
run-time information such as the status of the server cluster instance.

To view this administrative console page, click Servers > Clusters >cluster_name.

Cluster name:

Specifies a logical name for the cluster. The name must be unique among clusters within the containing
cell.

Data type String

Bounding node group name:

Specifies the node group that bounds this cluster. All application servers that are members of a cluster
must be on nodes that are members of the same node group.

A node group is a collection of WebSphere Application Server nodes. A node is a logical grouping of
managed servers, usually on a computer system that has a distinct IP host address. All application servers
that are members of a cluster must be on nodes that are members of the same node group. Nodes that
are organized into a node group need enough capabilities in common to ensure that clusters formed
across the nodes in the node group can host the same application in each cluster member. A node must
be a member of at least one node group and can be a member of more than one node group.

Create and manage node groups by clicking System administration > Node groups in the administrative
console.

Prefer local:

Specifies whether enterprise bean requests are routed to the node on which the client resides, if it is
possible to do so.

Select the Prefer Local check box to specify routing of requests to the node on which the client resides.
By default, the Prefer Local check box is selected, specifying routing of requests to the node.

Data type Boolean

Default true

Enable high availability for persistent services:

Chapter 3. Setting up the application serving environment 275

Specifies that the recovery logs for persistent services reside on storage devices that have been
configured according to high availability requirements.

wlcID:

Specifies the currently registered workload controller (WLC) identifier for the cluster. This setting might not
display for all configurations.

Data type String

State:

Specifies whether cluster members are stopped, starting, or running.

If all cluster members are stopped, the cluster state is stopped. After you request to start a cluster, the
cluster state briefly changes to starting and each server that is a member of that cluster launches, if it is
not already running. When the first member launches, the state changes to websphere.cluster.partial.start.
The state remains partially started until all cluster members are running, then the state changes to running.
Similarly, when stopping a cluster, the state changes to partially stopped as the first member stops and
changes to stopped when all members are not running.

Data type String

Range Valid values are starting, partially started, running, partially
stopped, or stopped.

Creating cluster members

Use this task to create application servers to be members of a configured cluster.

Create a cluster. See “Creating clusters” on page 271 for more information.

You create a cluster member to represent an application server in a cluster. To create a cluster member,
view information about cluster members, or manage members of a cluster, use the Cluster Members page.

Note: With WebSphere Application Server Version 6.0, you can now upgrade a portion of the nodes in a
cell, while leaving others at the older release level. This means that, for a period of time, you might
be managing servers that are at the current release and servers that are running the newer release
in the same cell. Note that in this mixed environment, there are some restrictions on what you can
do with clusters and cluster members:
v You cannot create a cluster member using a server that is running on WebSphere Application
Server Version 5.x.
v You cannot add a member that is running WebSphere Application Server Version 5.x to any
cluster.
v You can add a new WebSphere Application Server Version 6.0 cluster member to a mixed cluster
only if the cluster already contains a WebSphere Application Server Version 6.0 member that
was upgraded from WebSphere Application Server Version 5x. All new cluster members must be
running WebSphere Application Server Version 6.0.
1. Click Servers > Clusters in the administrative console. Then, click a cluster in the collection of
clusters and click Cluster members. The Cluster members page lists members of a cluster, states the
nodes on which members reside, and states whether members are started, stopped or encountering
problems.
2. Click New and follow the steps on the Create new cluster members page.
a. Type a name for the cluster member (application server).
b. Select the node for the server.

276 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 c. Specify the server weight. The weight value controls the amount of work that is directed to the
application server. If the weight value for the server is greater than the weight values assigned to
other servers in the cluster, then the server receives a larger share of the workload. The value can
range from 0 to 20.
d. Specify whether to generate a unique HTTP port.
e. Specify the server template.
f. Click Apply to finish the cluster member. Repeat these steps to define another cluster member.
g. Click Next.
h. Review the summary of information on new cluster members and click Finish.
3. Click Save to save your administrative configuration.
4. To examine a cluster member’s settings, click on the member’s name under Member name on the
Cluster members page. This displays the settings page for the cluster member instance.

You created application servers that became members of an existing server cluster.

If you are finished configuring your cluster, you can create a backup cluster and start the cluster. See
“Creating backup clusters” on page 278 and “Starting clusters” on page 282 for more information.

You can automate the task of adding cluster members by using scripting. See the Administering
applications and their environment PDF for more information.

Cluster member collection

Use this page to view information about and manage members of an application server cluster.

To view this administrative console page, click Servers > Clusters >cluster_name > Cluster Members.

Member name:

Specifies the name of the server in the cluster. On most platforms, the name of the server is the process
name. The name must match the (object) name of the application server.

Node:

Specifies the name of the node for the cluster member.

Status:

Specifies whether a cluster member is running, stopped, or unavailable.

If a cluster member is stopped, its status is Stopped. After you request to start a cluster member by
clicking Start, the status becomes Started. After you click Stop, its status changes to Stopped when it
stops running.

Note that if the status is unavailable, the node agent is not running in that node and you must restart the
node agent before you can start the cluster member.

Cluster member settings:

Use this page to configure a member instance of an application server cluster.

To view this administrative console page, click Servers > Clusters >cluster_name > Cluster members
>cluster_member_name.

Member name:

Chapter 3. Setting up the application serving environment 277

Specifies the name of the server in the cluster. On most platforms, the name of the server is the process
name. The name must match the (object) name of the application server.

Data type String

Weight:

Controls the amount of work that is directed to the application server. If the weight value for the server is
greater than the weight values assigned to other servers in the cluster, then the server receives a larger
share of the server workload.

Data type Integer

Range 0 to 20

Unique ID:

Specifies a numerical identifier for the application server that is unique within the cluster. The ID is used
for affinity.

Data type Integer

Creating backup clusters

Use this task to configure a backup cluster that handles Enterprise JavaBeans (EJB) requests if the
primary cluster fails.

Before you begin, create two clusters that are able to provide backup for each other. The objects and
resources available in the primary cluster must also be available in the backup cluster. You must use the
same cluster name, install the same applications, use the same application names, and define the same
resources in the backup cluster as in the primary cluster.

The primary cluster and the backup cluster must reside in separate cells because a cluster must have a
unique name within a cell. See “Backup clusters” on page 279 for more information.

Perform this task to create a backup cluster for your EJB clusters. When all the servers in the primary
cluster fail, work is not halted because the backup cluster can continue serving requests for EJB work.

To configure a backup cluster, specify a name and a port. The port is called a domain bootstrap address
and consists of a bootstrap host and port. The bootstrap host is the host that contains the deployment
manager in which the backup cluster is configured. The bootstrap port is equal to the bootstrap port for the
same deployment manager.

The primary cluster and the backup cluster must reside in separate cells. The bootstrap host and port for
the backup cluster determine which cell contains the backup cluster.
1. Determine the bootstrap host and port of the backup cluster.
a. Connect the administrative console for the deployment manager that contains the backup cluster.
b. Click System administration > Deployment manager > Ports > BOOTSTRAP_ADDRESS. The
host and port for the BOOTSTRAP_ADDRESS instance is the host and port that the backup
cluster uses. Remember these values for when you configure the primary cluster.
2. Connect the administrative console to the deployment manager that contains the primary cluster. Click
Servers > Clusters > cluster_name > Backup cluster.
3. Ensure that the name of the backup cluster is the same as the primary cluster.

278 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
4. Click Domain bootstrap address. Specify the backup cluster deployment manager bootstrap host and
port in the Host and Port fields. Click OK. The bootstrap host and port combined define a bootstrap
address for the deployment manager. On the Domain Bootstrap Address page, use the Configuration
tab to statically define the backup cluster; the static value is consumed each time the deployment
manager starts. You can use the Runtime tab to define the backup cluster during run time only; when
the deployment manager stops, the run-time backup cluster information is discarded.
5. Click OK.
6. Configure a core group bridge between each of the cluster core groups. Use an access point group to
join the two core groups. In the deployment manager for the primary cell, configure an access point
group that has a peer access point that refers to the core group access point in the backup cell. In the
deployment manager for the backup cell, create an access point group that has the same name as the
access point group that you created in the primary cell. Add a peer access point that refers to the core
group access point in the primary cell. See “Configuring communication between core groups that are
in different cells” on page 338 for more information.

Tip: If you are configuring a V5.x cluster to back up a cluster that is on the current release, you do not
have to configure the core group bridge service because the V5.x cluster does not belong to a
core group. The backup cluster still functions using only the domain bootstrap address.
7. Save the configuration.

The backup cluster completes EJB requests when the primary cluster fails.

If you experience problems when configuring your backup cluster, see the Troubleshooting and support
PDF.

Backup clusters
Backup clusters mirror the primary server clusters. Mirrored cluster support is for Enterprise JavaBeans
(EJB) requests only.

Overview and prerequisites

When all the members of a cluster are no longer available to service EJB requests, any clients that must
interact with one of the EJB application servers in the cluster do not function. Mirrored clusters enable an
EJB cluster (primary cluster) to failover to another EJB cluster (backup cluster) when none of the EJB
application servers in the primary cluster are able to service a request. The backup cluster allows the
client to continue functioning when all of cluster members in the primary cluster are not available.

The fail back is automatic. You do not have to initiate fail back to the primary cluster after restarting the
servers in the primary cluster. The backup cluster stops servicing requests as soon as the primary cluster
becomes available.

For the backup cluster to take over servicing requests successfully, the objects and resources available in
the primary cluster must also be available in the backup cluster. You must use the same cluster name,
install the same applications, use the same application names, and define the same resources in the
backup cluster as in the primary cluster.

The primary cluster and the backup cluster must reside in separate cells because a cluster must have a
unique name within a cell.

For successful fail back, the primary cluster must be defined as the backup for the backup cluster. Both
the primary and backup clusters must have a backup cluster configured, and each cluster must specify the
opposite cluster as its backup cluster.

Because the primary and backup clusters reside in different cells, with the current version of WebSphere
Application Server, the clusters also reside in different core groups. You must configure the core group

Chapter 3. Setting up the application serving environment 279

bridge service to allow communication between core groups. The core group bridge service eliminates the
requirement of a running deployment manager and a node agent for the backup cluster support. In the
previous release, if the deployment manager stopped, new requests could not be forwarded to the backup
cluster after the primary cluster failed. In WebSphere Application Server V6, any core group bridge server
that is configured in the primary cluster’s cell can provide information about the backup cluster. The
backup cluster support fails only if all of the core group bridge servers in a cell are not running.

For cluster failover and fail back to function as expected, all of the servers (deployment manager, node
agents and application servers) for both the primary cluster and the backup cluster must be at a release
and level that provides mirrored cluster support; that is, WebSphere Application Server Enterprise or
WebSphere Business Integration Server Foundation V5.0.2 or later or WebSphere Application Server
Network Deployment V6. However, if you are using a V5.x cluster to back up a cluster that is on the
current release, you do not have the additional functionality from the core group bridge service. All the
deployment managers must be functional for backup cluster support.

Configuration

Mirrored cluster support is not configured by default. To use the mirrored cluster support, you must specify
backup clusters in your configuration. Each cluster can have only one backup cluster, which must be
configured before it is specified as a backup cluster.

To configure a backup cluster in a cluster, you must specify a name and a domain bootstrap address. The
bootstrap host is the host that contains the deployment manager in which the backup cluster is configured.
The bootstrap port is the bootstrap port for this deployment manager.

The primary cluster and the backup cluster must reside in separate cells. To place mirrored clusters in
separate cells, configure the appropriate backup cluster domain bootstrap address. The backup cluster
bootstrap host and port determine which cell contains the backup cluster.

You can configure a backup cluster using the administrative console or the ExtendedCluster MBean. To
determine the value for the domain bootstrap address and configure a backup cluster using the console,
see Creating backup clusters.

To configure a backup cluster using the administrative console, use the Configuration tab on the Domain
Bootstrap Address page to statically define the backup cluster; the static value is consumed each time the
deployment manager starts. Use the Runtime tab on the Domain Bootstrap Address page to define the
backup cluster during run time only; when the deployment manager stops, the run-time backup cluster
information is discarded.

Because the primary and backup clusters reside in different cells, with the current version of WebSphere
Application Server, the clusters also reside in different core groups. You must configure the core group
bridge service to allow communication between core groups. Use an access point group to join the two
core groups. In the deployment manager for the primary cell, configure an access point group that has the
core group access point for the backup cell as a peer access point. In the deployment manager for the
backup cell, create an access point group that has the same name as the access point group you created
in the primary cell. Add a peer access point that refers to the core group access point in the primary cell.
See “Configuring communication between core groups that are in different cells” on page 338 for more
information. If you are configuring a V5.x cluster to back up a cluster that is on the current release, you do
not have to configure the core group bridge service because the V5.x cluster does not belong to a core
group. The backup cluster still functions using only the domain bootstrap address.

If you are configuring a backup cluster using the ExtendedCluster MBean, you can change the runtime
configuration only. The MBean change does not affect the static configuration. You can use the setBackup
operation on the ExtendedCluster MBean to change the run-time configuration. For example, you can use
the following Java code to set the primary cluster’s backup cluster:

280 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
ac.invoke(extendedCluster, "setBackup", new Object[] {
backupClusterName, backupBootstrapHost, backupBootstrapPort},
new String[] {
"java.lang.String", "java.lang.String", "java.lang.Integer"});

In this sample, ac is the AdminClient, and extendedCluster is the ExtendedClusterObjectName for the
primary cluster.

Fail back support scenarios

There are two scenarios that affect the cluster fail back support.

In the first scenario, requests are made by the client to the primary cluster, which eventually stops
accepting requests. The requests are then routed to the backup cluster. The client initially sent requests to
the primary cluster and therefore has information about the primary cluster. As a result, when the primary
cluster is available again, the requests fail back to the primary cluster.

In the second scenario, the client does not start sending requests until after the primary cluster is down,
and the requests go directly to the backup cluster. In this case, the client has information about the backup
cluster only. Because the client knows about the backup cluster only, when the primary cluster becomes
available, the requests from this client continue to route to the backup cluster and do not fail back to the
primary cluster when it becomes available. This scenario occurs when an object is created on the backup
cluster. In this case, the backup cluster becomes the primary cluster for this object.

Both of these scenarios can occur within the same client at the same time, if the client is sending requests
to existing objects and creating new objects after the primary cluster stops processing.

Backup cluster settings

Use this page to configure a backup server cluster. The backup server cluster is used if the primary server
cluster fails.

Configuration of a backup cluster is only useful if the cluster contains an Enterprise JavaBeans (EJB)
module and a client outside of the cluster uses the EJB module.

You can view run-time information such as the status of the backup cluster, provided you saved your
administrative configuration after configuring the backup cluster, restarted the server and the workload
management configuration reads the backup cluster value when the server starts.

To view this administrative console page, click Servers > Clusters > cluster_name > Backup cluster.

Backup cluster name:

Specifies the name of the backup cluster. The backup cluster must have the same name as the server
cluster that is containing the backup cluster. The backup cluster and its containing server cluster can have
identical names because they must reside in different cells.

Data type String

Domain bootstrap address settings:

Use this page to specify the bootstrap address host and port of the deployment manager that contains the
backup cluster.

Chapter 3. Setting up the application serving environment 281

When values is shown for the bootstrap address port, the backup cluster is not set. No host or port values
are shown if a user has never set values for the backup cluster or if the user defined a backup cluster with
an actual host and port and then removed the backup cluster by removing all text from the host and port
fields.

After you set host and port values on the Configuration tab, the bootstrap address endpoint values
become active when you restart the server. Use the Runtime tab to update the bootstrap address host
and port dynamically. The system uses the run-time values until you restart the server or change the
values. The values on the two tabs are independent. That is, you can specify a run-time backup cluster
that is different from the configuration backup cluster.

To view this administrative console page, click Servers > Clusters > cluster_name > Backup cluster >
Domain bootstrap address.

Host:

Specifies the IP address, domain name server (DNS) host name with domain name suffix, or just the DNS
host name, of the bootstrap host for the deployment manager of the backup cluster.

For example, if the host name is myhost, the fully qualified DNS name can be myhost.myco.com and the IP
address can be 155.123.88.201.

Data type String

Port:

Specifies the bootstrap port number for the deployment manager of the backup cluster. The port value is
used in conjunction with the host name.

Data type Integer

Starting clusters
Make sure that the members of your cluster have the debug port properly set. If multiple servers on the
same node have the same debug port set, the cluster could fail to start. See “Java virtual machine
settings” on page 253 for more information on how to change the debug port.

You can start all members of a cluster at the same time by requesting that the state of a cluster change to
running. That is, you can start all application servers in a server cluster at the same time.

When you request that all members of a cluster start, the cluster state changes to partially started and
each server that is a member of that cluster launches, if it is not already running. After all members of the
cluster are running, the cluster state becomes running.
1. Click Servers > Clusters in the console navigation tree to access the Server Cluster page.
2. Select the clusters whose members you want started.
3. Click Start or RippleStart.
v Start launches the server process of each member of the cluster by calling the node agent for each
server to start the servers. After all servers are running, the state of the cluster changes to running.
If the call to a node agent for a server fails, the server does not start.
v RippleStart combines stopping and starting operations. It first stops and then restarts each member
of the cluster.

By starting the members of a cluster, you automatically enabled workload management.

282 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Note to Windows users: If you start and stop application servers that are part of a cluster
using the Windows Services facility, the cluster state does not always update correctly. For example, if a
cluster is running and you stop a cluster member through the Services GUI, the cluster state remains as
started even though the server is no longer running.

See “Balancing workloads with clusters” on page 268 for more information about the tasks that you can
complete with clusters.

Stopping clusters
Use this task to stop a cluster and any application servers that are members of that cluster.

You can stop all application servers that are members of a cluster at the same time by stopping the
cluster. That is, you can stop all application servers in a server cluster at the same time.

Note to Windows users: If you start and stop application servers that are part of a cluster
using the Windows Services facility, the cluster state does not always update correctly. For example, if a
cluster is running and you stop a cluster member through the Services GUI, the cluster state remains as
Started even though the server is no longer running.
1. Click Servers > Clusters in the console navigation tree to access the Server Cluster page.
2. Select those clusters whose members you want stopped.
3. Click Stop or Immediate Stop.
v Stop halts each server in a manner that allows the server to finish existing requests and allows
failover to another member of the cluster. When the stop operation begins the cluster state changes
to partially stopped. After all servers stop, the cluster state becomes stopped.
v Immediate Stop brings down the server quickly without regard to existing requests. The server
ignores any current or pending tasks. When the stop operation begins, the cluster state changes to
partially stopped. After all servers stop, the cluster state becomes stopped.

See “Balancing workloads with clusters” on page 268 for more information about the tasks you can
complete with clustering.

Replicating data across application servers in a cluster

Use this task to configure a data replication domain to transfer data, objects, or events for session
manager, dynamic cache, or stateful session beans. Data replication domains use the data replication
service (DRS), which is an internal WebSphere Application Server component that performs replication
services, including replicating data, objects, and events among application servers.

If you configured a data replication domain with a previous version of WebSphere Application Server, you
might be using a multi-broker replication domain. Any replication domains that you create with the current
version of WebSphere Application Server are data replication domains. Migrate any multi-broker replication
domains to data replication domains. To learn the differences between the two types of replication
domains, see “Comparison of multi-broker versus data replication domains” on page 288 and “Migrating
V6.0 servers from multi-broker replication domains to data replication domains” on page 287.

Use this task to configure replication, a service that transfers data, objects, or events among the
application servers in a cluster. Use replication to prevent loss of session data with session manager, to
further improve the performance of the dynamic cache service, and to provide failover in stateful session
beans. For more information about replication, see “Replication” on page 284.
1. Create a replication domain. Use one of the following methods to create a replication domain:
v Create a replication domain manually.
To create a replication domain manually without creating a new cluster, click Environment >
Replication domains > New in the administrative console.

Chapter 3. Setting up the application serving environment 283

 On this page you can specify the properties for the replication domain, including timeout, encryption,
and number of replicas. See “Data replication domain settings” on page 286 for more information
about the properties that you can configure for your replication domain.
v Create a replication domain when creating a cluster.
To create a replication domain when you create a cluster, click Servers > Clusters > New in the
administrative console. Enable Create replication domain for this cluster. The replication domain
that is created has the same name as the cluster and has the default settings for a replication
domain. The default settings for a replication domain are to create a single replica of each piece of
data and to have encryption disabled. To modify the replication domain properties, click
Environment > Replication domains > replication_domain_name in the administrative console.
See “Creating clusters” on page 271 for more information about creating a cluster.
For more information about the replication domain settings that you can configure in the administrative
console, see “Data replication domain settings” on page 286
2. Configure the consumers, or the components that use the replication domains. Dynamic cache,
session manager, and stateful session beans are the three types of replication domain consumers.
Each type of consumer must be configured with a different replication domain. For example, session
manager uses one domain and dynamic cache uses a different replication domain. However, use one
replication domain if you are configuring HTTP session memory-to-memory replication and stateful
session bean replication. Using one replication domain in this case ensures that the backup state
information of HTTP sessions and stateful session beans are on the same application servers.
v To configure dynamic cache replication, see the Developing and deploying applications PDF.
v To configure memory-to-memory replication for session manager, see the Developing and deploying
applications PDF.
v To configure replication of stateful session beans, see the Developing and deploying applications
PDF.

Data is replicating among the application servers in a configured replication domain.

If you use the Data Encryption Standard (DES) or DES3 encryption type for a replication domain, an
encryption key is used for the encryption of messages. Click Regenerate encryption key on the “Data
replication domain settings” on page 286 page at regular intervals to regenerate the key and protect your
configuration. After the key has been changed or regenerated, you must restart all of the application
servers that are configured as part of the replication domain. Consider performing this step every month to
secure your configuration.

Replication
Replication is a service that transfers data, objects, or events among application servers. Data replication
service (DRS) is the internal WebSphere Application Server component that replicates data.

Use data replication to make data for session manager, dynamic cache, and stateful session beans
available across many application servers in a cluster. The benefits of using replication vary depending on
the component that you configure to use replication.
v Session manager uses the data replication service when configured to do memory-to-memory
replication. When memory-to-memory replication is configured, session manager maintains data about
sessions across multiple application servers, preventing the loss of session data if a single application
server fails. For more information about memory-to-memory replication, see the Developing and
deploying applications PDF.
v Dynamic cache uses the data replication service to further improve performance by copying cache
information across application servers in the cluster, preventing the need to repeatedly perform the
same tasks and queries in different application servers. For more information about replication in the
dynamic cache, see the Developing and deploying applications PDF.

284 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Stateful session beans use the replication service so that applications using stateful session beans are
not limited by unexpected server failures. For more information about stateful session bean failover, see
the Developing and deploying applications PDF.

You can define the number of replicas that DRS creates on remote application servers. A replica is a copy
of the data that copies from one application server to another. The number of replicas that you configure
affects the performance of your configuration. Smaller numbers of replicas result in better performance
because the data does not have to copy many times. However, if you create more replicas, you have more
redundancy in your system. By configuring more replicas, your system becomes more tolerant to possible
failures of application servers in the system because the data is backed up in several locations.

By having a single replica configuration defined, you can avoid a single point of failure in the system.
However, if your system must be tolerant to more failure, introduce extra redundancy in the system.
Increase the number of replicas that you create for any HTTP session that is replicated with DRS. Any
replication domain that is used by dynamic cache must use a full group replica.

Session manager, dynamic cache, and stateful session beans are the three consumers of replication. A
consumer is a component that uses the replication service. When you configure replication, the same
types of consumers belong to the same replication domain. For example, if you are configuring both
session manager and dynamic cache to use DRS to replicate objects, create separate replication domains
for each consumer. Create one replication domain for all the session managers on all the application
servers and one replication domain for the dynamic cache on all the application servers. The only
exception to this rule is to create one replication domain if you are configuring replication for HTTP
sessions and stateful session beans. Configuring one replication domain in this case ensures that the
backup state information is located on the same backup application servers.

To configure replication, see “Replicating data across application servers in a cluster” on page 283.

Replication domain collection

Use this page to view the configured replication domains that are used for replication by the HTTP session
manager, dynamic cache service, and stateful session bean failover components. All components that
need to share information must be in the same replication domain. Data replication domains replace
multi-broker replication domains that were available for replication in prior releases. Migrated application
servers use multi-broker replication domains which are collections of replicators. You should migrate any
multi-broker replication domains to be data replication domains.

To view this administrative console page, click Environment > Replication domains.

Name:

Specifies a name for the replication domain. The name of the replication domain must be unique within the
cell.

Domain type:

Following are the two types of replication domains:

Chapter 3. Setting up the application serving environment 285

Multi-broker domain Specifies a replication domain that was created with a
previous version of WebSphere Application Server. This
type of replication domain consists of replicator entries.
Support of this type of domain remains for backward
compatibility, but is deprecated. Multi-broker and data
replication domains do not communicate with each other,
so migrate any multi-broker replication domains to the
new data replication domains. You cannot create a
multi-broker domain or replicator entries in the
administrative console after the deployment manager is
upgraded to the current version of WebSphere Application
Server.
Data replication domain Specifies a replication domain created with the latest
version of WebSphere Application Server. If the
deployment manager has been upgraded to the latest
version of WebSphere Application Server, you can create
data replication domains only. With the data replication
domain, you can specify a number of replicas instead of
statically partitioning your replication settings. Specify a
data replication domain for each consumer of the domain,
for example, two separate domains for dynamic cache
and session manager.

Data replication domain settings:

Use this page to configure a data replication domain. Use data replication domains to transfer data,
objects, or events for session manager, dynamic cache, or stateful session beans among the application
servers in a cluster.

To view this administrative console page, click Environment > Replication domains
>replication_domain_name.

Name:

Specifies a name for the replication domain. The name must be unique within the cell.

Request timeout:

Specifies how long a replication domain consumer waits when requesting information from another
replication domain consumer before it gives up and assumes the information does not exist.

Units seconds
Default 5 seconds

Encryption type:

Specifies the type of encryption to use when transferring replicated data to another area of the network.
The options are NONE, DES, and DES3. The default is NONE. The DES and DES3 options encrypt data
sent between application server processes (for example, session manager and dynamic caching) to better
secure the network joining the processes.

If you specify DES or DES3, a key for global data replication is generated after you click Apply or OK. If
you use the DES or DES3 encryption type, click Regenerate encryption key at regular intervals, for
example once each month. Periodically regenerating the key enhances security.

Data type String

286 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Default NONE

Number of replicas:

Specifies the number of replicas that are created for every entry or piece of data that is replicated in the
replication domain.

Single replica One replica is created. This is the default value.

Full group replica Each object is replicated to every application server that is
configured as a consumer of the replication domain.
Specific number of replicas A custom number of replicas for any entry that is created
in the replication domain.

Migrating V6.0 servers from multi-broker replication domains to data replication

domains
Use this task to migrate multi-broker replication domains to data replication domains. Multi-broker domains
were created with a previous version of WebSphere Application Server.

For HTTP session affinity to continue working correctly when migrating V5.x application servers to V6.0
application servers, you must upgrade all of the Web server plug-ins for WebSphere Application Server to
the latest version before upgrading the application servers that perform replication.

After you upgrade your deployment manager to the latest version of WebSphere Application Server, you
can create data replication domains only. Any multi-broker domains that you created with a previous
release of WebSphere Application Server are still functional, however, you cannot create new multi-broker
domains or replicators with the administrative console.

The different versions of application servers cannot communicate with each other. When migrating your
servers to the current version of WebSphere Application Server, keep at least two application servers
running on the previous version so that replication remains functional.

Perform this task on any multi-broker domains in your configuration after all of your servers that are using
this multi-broker domain have been migrated to the current version of WebSphere Application Server. For
more information about the differences between multi-broker domains and the data replication domains,
see “Comparison of multi-broker versus data replication domains” on page 288.

The following examples illustrate the migration process for common configurations:

Migrating an application server configuration that uses an instance of data replication service in
peer-to-peer mode

Use this migration path to migrate a replication domain that uses the default peer-to-peer configuration.
Dynamic cache replication domains use the peer-to-peer topology. See the Developing and deploying
applications PDF for more information.

Before you begin, migrate all the Web server plug-ins for your application server cluster to the current
version.
1. Migrate one or more of your existing servers to the current version of WebSphere Application Server.
2. In the administrative console, create an empty data replication domain. Click Environment >
Replication domains > New in the administrative console. See “Replicating data across application
servers in a cluster” on page 283 for more information about creating a data replication domain.
3. Add your migrated application servers to the new data replication domain. For example, if you are
migrating 4 servers, migrate 2 servers first and add them to the new replication domain. Configure the
servers to use the new domain by configuring the consumers of the replication domain.

Chapter 3. Setting up the application serving environment 287

4. When the new data replication domains are successfully sharing data, migrate the rest of the servers
that are using the multi-broker replication domain to data replication domains.
5. Delete the empty multi-broker replication domain.

Migrating an application server configuration that uses an instance of the data replication service
in client/server mode

Use this set of steps to migrate a replication domain that uses client/server mode.

Before you begin migrating a client/server mode replication domain, consider if migrating your replication
domains might cause a single point of failure. Because you migrate the servers to the new type of
replication domain one at a time, you risk a single point of failure if there are 3 or fewer application
servers. Before migrating, configure at least 4 servers that use multi-broker replication domains. Perform
the following steps to migrate the multi-broker domains to data replication domains:
1. Migrate one or more of your existing servers to the current version of WebSphere Application Server.
2. In the administrative console, create an empty data replication domain. Click Environment >
Replication domains > New in the administrative console. See “Replicating data across application
servers in a cluster” on page 283 for more information about creating a data replication domain.
3. Add your migrated servers to the new data replication domain. For example, if you are migrating 4
servers, migrate two of these servers and then add them to the new replication domain. Configure the
servers to use the new domain by configuring the consumers of the replication domain.
4. Add a part of the clients to the new data replication domain.
5. When the new data replication domains are successfully sharing data, migrate the rest of the clients
and servers that are using the multi-broker replication domain to data replication domains.
6. Delete the empty multi-broker replication domain.

Migrating a replication domain that uses HTTP session memory-to-memory replication that is
overloaded at the application or web module level
1. Upgrade your deployment manager to the current version of WebSphere Application Server. All the
application servers remain configured with the old multi-broker domains on the previous version of
WebSphere Application Server.
2. In the administrative console, create an empty data replication domain. Click Environment >
Replication domains > New in the administrative console. See “Replicating data across application
servers in a cluster” on page 283 for more information about creating a data replication domain.
3. Migrate each application server to the current version of WebSphere Application Server, one at a time.
The remaining servers on the previous version of WebSphere Application Server can still communicate
with each other, but not with the migrated servers. The migrated servers can also communicate with
each other.
4. Continue migrating all of the servers to the current version of WebSphere Application Server. All of the
application servers are still using multi-broker replication domains, so the features of data replication
domains cannot be used.
5. Configure all of the application servers to use the new data replication domain, adding the application
servers to the empty replication domain that you created.
6. Restart all of the application servers in the cluster.
7. Delete the empty multi-broker replication domain.

During this process, you might lose existing sessions. However, the application remains active through the
entire process, so users do not experience down time during the migration. Create a new replication
domain for each type of consumer. For example, create one replication domain for session manager and
another replication domain for dynamic cache. See “Replicating data across application servers in a
cluster” on page 283 for more information.

Comparison of multi-broker versus data replication domains:

288 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data replication domains replace multi-broker domains for data replication between application servers in a
cluster.

Any replication domains that are created with a previous version of WebSphere Application Server might
be multi-broker domains. Migrate any multi-broker domains to the new data replication domains. Although
you can configure existing multi-broker domains with the current version of WebSphere Application Server,
after you upgrade your deployment manager, you can create only data replication domains in the
administrative console.

Multi-broker and data replication domains both perform the same function, which is to replicate data across
the consumers in a replication domain. Configure all the instances of replication that need to communicate
in the same replication domain. You can also configure the session manager with both types of replication
domains to use topologies such as peer-to-peer and client/server to isolate the function of creating and
storing replicas on separate application servers. You can control the redundancy of replication for each
type of replication domain. With a data replication domain, you can specify a specific number of replicas.

If you used multi-broker domains with earlier releases of WebSphere Application Server, use the following
comparison chart to learn the differences between how V5.x and V6.0 application servers use the two
types of replication domains:

V5.x application servers using V6.0 application servers using

replication domains replication domains
Replication domain types Uses only multi-broker replication Servers that are using the current
domains for replication. version of WebSphere Application
Server can be configured to use both
multi-broker replication domains and
data replication domains for
replication. The two types of domains
provide backward compatibility with
multi-broker domains that were
created with a V5.x server. You
should migrate any multi-broker
domains to data replication domains.
Data transport method Uses multi-broker domain objects that Uses data replication domain objects
contain configuration information for that contain configuration information
the internal Java Message Service to configure the high availability
(JMS) provider, which uses JMS framework on WebSphere Application
brokers as replicators. Server. The transport is no longer
based on the JMS API. Therefore, no
replicators and no JMS brokers exist.
You do not have to perform the
complex task of configuring local,
remote, and alternate replicators. The
earlier version of WebSphere
Application Server did not support
data replication domains. The current
version of WebSphere Application
Server can be configured to perform
replication using old multi-broker
domains by ignoring any JMS-specific
configuration and by using the other
parameters to configure replication
through the high availability
framework.

Chapter 3. Setting up the application serving environment 289

 V5.x application servers using V6.0 application servers using
replication domains replication domains
Replication domain configuration The earlier version of WebSphere The current version of WebSphere
Application Server encourages the Application Server encourages
sharing of replication domains creating a separate replication
between different consumers, such as domain for each consumer. For
session manager and dynamic cache. example, create one replication
domain for session manager and
another replication domain for
dynamic cache. The only situation
where you should configure one
replication domain is when
configuring session manager
replication and stateful session bean
failover. Using one replication domain
in this case ensures that the backup
state information of HTTP sessions
and stateful session beans are on the
same application servers.
Partial partitioning You can configure partial partitioning. Partial partitioning is deprecated.
Partition the replication domain to When using data replication domains,
filter the number of processes to send you can specify a specific number of
data. replicas for each entry. However, if
you specify a number of replicas
larger than the number of backup
application servers that are running,
the number of replicas is the number
of application servers that are
running. After the number of
application servers increases above
your configured number of replicas,
the number of replicas that are
created is equal to the number that
you specified.
Domain sharing Multiple data replication service All DRS instances in a replication
(DRS) instances share multi-broker domain use the same mode. Each
domains. A limitation exists on the replication domain must contain either
number of multi-broker domains that client only and server only instances,
you can create because every or client and server instances only.
multi-broker domain contains at least For example, if one instance is
one replicator. A maximum of one configured to client and server, all
replicator can be on each application other instances must be client and
server. server. If one instance in a replication
domain is configured to be a client
only, you can add client only and
server only instances, but not a client
and server instance.

To migrate multi-broker domains to data replication domains, see “Migrating V6.0 servers from multi-broker
replication domains to data replication domains” on page 287.

Replicating data with a multi-broker replication domain

Use this task to work with replication domains that were created and used with a previous version of
WebSphere Application Server.

Multi-broker domains were created with a previous version of WebSphere Application Server, but remain
functional in the current version. Although you can configure existing multi-broker domains with the current

290 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
version of WebSphere Application Server, after you upgrade your deployment manager, you can create
only data replication domains in the administrative console. Consider migrating any existing multi-broker
domains to the new data replication domains. See “Migrating V6.0 servers from multi-broker replication
domains to data replication domains” on page 287 for more information about the benefit of migrating your
replication domains.

If you do not have any existing replication domains, see “Replicating data across application servers in a
cluster” on page 283 for information about creating new data replication domains.

If you are performing this task, it is assumed that you configured replication with a previous version of
WebSphere Application Server and defined replication domains that list connected replicator entries
(residing in managed servers in the cell) that can exchange data. You can manage these existing
replication domains and replicator entries, but you cannot create new multi-broker replication domains or
new replicator entries in the administrative console.

A replicator does not need to run in the same process as the application server that uses it. However, it
might be easier to manage replicators and replication domains if a one-to-one relationship exists between
replicators and application servers. During configuration, you can select the local replicator as the default
replicator.
1. Manage multi-broker replication domain configuration settings. In the administrative console, click
Environment > Replication domains.
2. Click on a multi-broker domain. Specify the values for a particular multi-broker replication domain. The
default values are generally sufficient, especially for the pooling and timeout values.
a. Name the replication domain.
b. Specify the timeout interval.
c. Specify the encryption type. The DES and TRIPLE_DES options encrypt data sent between
WebSphere Application Server processes and better secure the network joining the processes.
d. Partition the replication domain to filter the number of processes to which data is sent. Partitioning
the replication domain is most often done if you are replicating data to support retrieval of an HTTP
session if the process maintaining the HTTP session fails. Partitioning is not supported for sharing
of cached data that is maintained by Web container dynamic caching.
e. Specify whether you want a single replication of data to be made. Enable the option if you are
replicating data to support retrieval of an HTTP session if the process maintaining the HTTP
session fails.
f. Specify whether processes should receive data in objects or bytes. Processes receiving data in
objects receive the data and class definitions. Processes receiving data in bytes receive the data
only.
g. Configure a pool of replication resources. Pooling replication resources can enhance the
performance of the replication service.
3. Maintain the replicators that you have already defined. You cannot create any new replicators. The
default convention is to define a replicator in each application server that uses replication. However,
you can define a pool of replicators, separate from the servers hosting applications.
a. In the administrative console, click Environment > Replication domains >
replication_domain_name > Replicator entries >replicator_entry_name.
b. Specify a replicator name and select a server available within the cell to which you can assign a
replicator. Also specify a host name and ports. Note that a replicator has two ports (replicator and
client ports) that use the same host name but have different ports.
4. If you use the DES or TRIPLE_DES encryption type for a replicator, click Regenerate encryption key
on the settings for a replication domain instance at regular intervals, such as monthly.
Periodically changing the key enhances security.

Multi-broker replication domains:

Chapter 3. Setting up the application serving environment 291

A multi-broker replication domain is a collection of replicator entry (or replicator) instances used by clusters
or individual servers within a cell. Multi-broker replication domains were created with a previous release of
WebSphere Application Server.

Note: After you upgrade your deployment manager to the latest version of WebSphere Application Server,
you can create data replication domains only. Any multi-broker domains that you created with a
previous release of WebSphere Application Server are still functional, however, you cannot create
new multi-broker domains or replicators with the administrative console. See “Comparison of
multi-broker versus data replication domains” on page 288 for more information.

A replication entry (or replicator) is a run-time component that handles the transfer of internal WebSphere
Application Server data. All replicators within a replication domain connect with each other, forming a
network of replicators.

Components such as session manager and dynamic cache can connect to any replicator within a domain
to receive data from their peer components on other application servers that are connected other
replicators in the same domain. If the replicator that a component is connected to fails, the component
automatically attempts to reconnect to another replicator in the domain and recover any data that was
missed while the component was not connected to a replicator.

The default is to define a replication domain for a cluster when creating the cluster. However, replication
domains can span across clusters.

Global default settings apply to a given replication domain across a cell. Most default settings tune and
control the behavior of replicator entries that are in managed servers across the cell. Such default settings
control the use of encryption or the serialization and transferring of objects. Some default settings tune and
control how specific WebSphere Application Server functions (for example, session manager and dynamic
caching) leverage replication, such as session use of partitions.

For situations that require settings values other than the default, change the values for a given replication
domain. Settings include various resource allocation, replication strategies (such as grouping or
partitioning) and methods, as well as some security related items.

If you are using replication for HTTP session failover, you might also need to filter where the session
replicates. For example, only replicate to two places out of many. The global default settings define the
partition size or number of groups and the session manager settings define the groups to which a
particular instance belongs.

Filtering is less important if you are using replication to distribute information on data that is no longer valid
and actual cached data maintained by dynamic caching. Replication does not occur for failover as much
as for data synchronization across a cluster or cell when you likely want to avoid expensive costs for
generating data potentially needed across those various servers.

Note that you can filter or segment by using multiple replication domains.

Multi-broker replication domain settings:

Use this page to configure a multi-broker replication domain. This administrative console page applies only
to replication domains that were created with a previous version of WebSphere Application Server.
Replication domains use the data replication service (DRS).

To view this administrative console page, click Environment > Replication domains
>multibroker_replication_domain_name.

292 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
An application server that is connected to a replicator within a domain can access the ame set of data
sent out by any application server connected to any other replicator (including the same replicator). Data is
not shared across replication domains.

Name:

Specifies a name for the replication domain. The name must be unique within the cell.

Request timeout:

Specifies the number of seconds that a replication domain consumer waits when requesting information
from another replication domain consumer before giving up and assuming the information does not exist.
The default is 5 seconds.

Data type Integer

Units Seconds
Default 5

Encryption type:

Specifies the type of encryption used before the object transfers over the network. The options include
NONE, DES, TRIPLE_DES. The default is NONE. The DES and TRIPLE_DES options encrypt data sent
between WebSphere Application Server processes and secure the network joining the processes.

If you specify DES or TRIPLE_DES, a key for global data replication is generated after you click Apply or
OK. When you use the DES or TRIPLE_DES encryption type, click Regenerate encryption key at regular
intervals such as monthly because periodically changing the key enhances security.

DRS partition size:

Specifies the number of groups into which a replication domain is partitioned. By default, data sent by a
WebSphere Application Server process to a replication domain is transferred to all other WebSphere
Application Server processes connected to that replication domain. To filter or reduce the number of
destinations for the data being sent, partition the replication domain. There should be at least one server
listening to every partition. If there are no servers listening on a partition, all the replicas created in that
partition are lost because there is no server to cache the objects. The default partition size is 10, and the
partition size should be 10 or more to enhance performance.

Partitioning the replication domain is only applicable if you are replicating data to support retrieval of an
HTTP session if the process maintaining the HTTP session fails. Partitioning is not supported for sharing
of cached data maintained by Web container dynamic caching. As to dynamic caching, all partitions or
groups are always active and used for data replication.

When you partition a replication domain, you define the total number of groups or partitions. Use this
setting to define the number of groups. Then, when you configure a specific session manager under a
Web container or as part of an enterprise application or Web module, select the partition to which that
session manager instance listens and from which it accepts data. To specify the groups to which an
application server listens, change the settings for affected servers on a session manager page. In addition,
you can set a role or runtime mode for a server. This role or mode affects whether a WebSphere
Application Server process sends data to the replication domain, receives data, or does both. The default
is both to receive and send data.

Data type Integer

Default 10

Chapter 3. Setting up the application serving environment 293

Single replica:

Specifies that a single replication of data is made. Use this option only if you are using session manager
with memory to memory replication. Enable this option if you are replicating data to support retrieval of an
HTTP session if the process maintaining the HTTP session fails. This option restricts the recipient of the
data to a single instance.

Note: Do not enable this option on a domain that is using dynamic cache replication.

This setting provides filtering beyond grouping or partitioning. Using this setting, you can choose to have
data only sent to one other listening instance in the replication domain.

Default false

Serialization method:

Specifies the object serialization method to use when replicating data. An administrative concern with
replicating Java objects is locating the class definition, especially in a Java 2, Enterprise Edition (J2EE)
environment where class definitions might reside only in certain web modules or enterprise applications.
Object serialization methods define whether the processes receiving data also need the class definition.

The options for this setting are OBJECT and BYTES. The default is BYTES.

OBJECT instructs a replicator to write the object directly to the stream. With OBJECT, a replicator must
instantiate the object on the receiving side so it must have the class definition.

BYTES instructs a replicator to break down the object into bytes and then send only the bytes across the
stream. With BYTES, a replicator does not need to instantiate the object on the receiving side. The
BYTES option is useful for failover, where the data is not used at the receiving side and the class
definitions do not need to be stored on the receiving side. Or, the option requires that you move class
definitions from the Web application class path to the system class path.

DRS pool size:

Specifies the size of the pool of resources allocated for communication with its Java Message Service
(JMS) transport. You must configure this number to be the same as the DRS partition size. The default is
10.

Pooling replication resources can enhance the performance of the WebSphere internal data replication
service.

DRS pool connections:

Specifies that the domain replication service should create a pool of connections with its Java Message
Service (JMS) transport rather than reusing a single connection. You can pool connections when using a
single replica or client server environment. You should not pool connections in a peer to peer environment.

The default is to not create a pool of connections for replication.

Replicator entry collection:

Use this page to view and manage replicator entries. Replicator entries are for use only with multi-broker
replication domains. Each multi-broker replication domain consists of one or more replicator entries.

To view this administrative console page, click Environment > Replication domains
>replication_domain_name > Replicator entries.

294 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Replicator entries are only valid for multi-broker domains, which are replication domains created with a
previous version of WebSphere Application Server. When you migrate your deployment manager to the
current version of WebSphere Application Server, you are no longer be able to create new replicator
entries in the administrative console. You can only view and modify settings for replicator entries that were
created with the previous version of WebSphere Application Server.

Replicator name:

Specifies a name for the replicator entry.

Replicator entry settings:

Use this page to view and configure a replicator entry (or replicator). Replicators are used with multi-broker
replication domains.

To view this administrative console page, click Environment > Replication domains
>replication_domain_name > Replicator entries >replicator_entry_name.

Replicators communicate using Transmission Control Protocol/Internet Protocol (TCP/IP). Therefore, you
must allocate an IP address and ports for replicators. Use this page to name a replicator and then to
allocate an IP address and two ports (replicator and client ports) for the replicator.

Replicator name:

Specifies a name for the replicator entry.

Server:

Specifies the server for which you are defining a replicator. You can view the names of servers that do not
already have replicators. You can create a maximum of one replicator on any application server.

Replicator and client host name:

Specifies the IP address, domain name service (DNS) host name with domain name suffix, or just the
DNS host name, used by a client to request a Web application resource (such as a servlet, JavaServer
Pages (JSP) file, or HTML page).

A replicator port and client port share the same host name.

Replicator Port:

Specifies the port for which the replicator is configured to accept messages from other replicators. The
port value is used in conjunction with the host name.

The replicator port enables communication among replicators. It provides replicator port to replicator
communication. The usual value specified is 7874.

Client Port:

Specifies the port for which the Web server is configured to accept client requests. The port value is used
in conjunction with the host name.

The client port enables communication between an application server process and a replicator. It provides
client port to application server communication. The usual value specified is 7873.

Chapter 3. Setting up the application serving environment 295

Deleting clusters
Use this task to remove a cluster that has cluster members.

Removing a cluster deletes the cluster and all associated cluster members. When you delete a cluster,
there is no option to keep certain cluster members or applications that you have installed on any part of
the cluster.
1. Click Servers > Clusters in the console navigation tree to access the Server Cluster page.
2. Make sure the cluster you want to remove is stopped. If the cluster is started, see “Stopping clusters”
on page 283.
3. Remove the cluster. Select the cluster and click Delete.
4. Save your configuration. Click Save on the administrative console task bar. As part of saving the
change to the configuration, select Synchronize changes with Nodes before clicking Save on the
Save page.

The cluster is deleted.

Deleting cluster members

Use this task to remove a cluster member from an existing cluster. Removing a cluster member deletes
the associated application server. You cannot remove an application server from a cluster without deleting
it.
1. Choose the cluster that contains your cluster member. Click Servers > Clusters in the console
navigation tree to access the Server Cluster page. Select the cluster for your cluster member and click
Cluster members.
2. Make sure the cluster member you want to remove is stopped. If the cluster is started, see “Stopping
servers” on page 218.
3. Remove the cluster member from the cluster. Select the cluster member you want and click Delete.
4. Save your configuration. Click Save. As part of saving the change to the configuration, select
Synchronize changes with Nodes before clicking Save on the Save page.

The cluster member is deleted.

Tuning a workload management configuration

You can set values for several workload management client properties to tune the behavior of the
workload management run time. You set the properties as command-line arguments for the Java virtual
machine (JVM) process in which the workload management client is running.

Caution: Set the values of these properties only in response to problems that you encounter. In most
cases, you do not need to change the values. If workload management is functioning correctly, changing
the values can produce undesirable results.

To change the property values, you can use the Java Virtual Machine page of the administrative console
or use the wsadmin tool. In cases such as where a servlet is a client to an enterprise bean, use the
administrative console page for the application server where the servlet is running to configure the
properties. The steps below describe how to change the values using the console.
1. Access the Java Virtual Machine page.
a. In the administrative console, click Servers > Application Servers > server_name > Java and
Process Management > Process Definition.
b. On the Process Definition page, click Java Virtual Machine.
2. On the Java Virtual Machine page, specify one or more of the following command-line arguments in
the Generic JVM arguments field:

296 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v -Dcom.ibm.CORBA.RequestTimeout=timeout_interval
If your application is experiencing problems with timeouts, this argument changes the value for the
com.ibm.CORBA.RequestTimeout property, which specifies the timeout period for responding to
requests sent from the client. This argument uses the -D option. timeout_interval is the timeout
period in seconds. If your network experiences extreme latency, specify a large value to prevent
timeouts. If you specify a value that is too small, an application server that participates in workload
management can time out before it receives a response.
CAUTION:
Be careful specifying this property; it has no recommended value. Set it only if your
application is experiencing problems with timeouts.
v -Dcom.ibm.websphere.wlm.unusable.interval=interval
If the workload management state of the client is refreshing too soon or too late, this argument
changes the value for the com.ibm.websphere.wlm.unusable.interval property, which specifies the
time interval that the workload management client run time waits after it marks a server as
unavailable before it attempts to contact the server again. This argument uses the -D option. interval
is the time in seconds between attempts. The default value is 300 seconds. If the property is set to
a large value, the server is marked as unavailable for a long period of time. This prevents the
workload management refresh protocol from refreshing the workload management state of the client
until after the time period has ended.
3. Click OK.
4. Stop the application server and then restart the application server.

Workload management run-time exceptions

The workload management service might create the following exceptions if it encounters problems:
org.omg.CORBA.TRANSIENT with a minor code 1229066306 (0x40421042)
This exception is created if the workload management routing service cannot retry a request and
the failure resulted from a connection error. This exception indicates that the application should
invoke some compensation logic and resubmit the request.
org.omg.CORBA.NO_IMPLEMENT with a minor code 1229066304 (0x49421040)
This exception is created if the workload management service cannot contact any of the Enterprise
JavaBeans (EJB) application servers that participate in workload management.

The WebSphere Application Server client can catch these exceptions and then implement its own
strategies to handle the situation. For example, it can display an error message if no servers are available.

The workload management routing service can reroute a failed request to a different target transparently to
the application if the application will not be adversely affected by a second attempt. Currently, the only way
is to check if the request did not run in whole or part on the previous attempt. When a request runs in
whole or in part, an org.omg.CORBA.TRANSIENT with the minor code 1229066306 (0x49421042)
exception is created to signal that a request can be made again. This informs the application that another
target might be available to satisfy the request, but the request could not be failed over transparently to
the application. Thus, the application can resubmit the request. The routing service creates an
org.omg.CORBA.NO_IMPLEMENT with the minor code 1229066304 (0x49421040) exception if it cannot
locate a suitable target for the request. The exception is created, for example, if the cluster is stopped or if
the application does not have a path to any of the cluster members.

Clustering and workload management: Resources for learning

Use the following links to find relevant supplemental information about clustering and workload
management. The information resides on IBM and non-IBM Internet sites, whose sponsors control the
technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links

Chapter 3. Setting up the application serving environment 297

are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

View links to additional information about:

v Programming model and decisions
v Programming instructions and examples

Programming model and decisions

v IBM WebSphere V5.0 Performance, Scalability, and High Availability: WebSphere Handbook Series at
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/SG246198.html.
v IBM WebSphere Application Server V5.0 System Management and Configuration: WebSphere
Handbook Series at http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/SG246195.html.

Programming instructions and examples

v WebSphere Application Server education at
http://www.software.ibm.com/wsdd/education/enablement/curriculum/cur_webappsrvadm.html.
v Listing of all IBM WebSphere Application Server Redbooks at http://publib-
b.boulder.ibm.com/Redbooks.nsf/Portals/WebSphere.

Setting up a high availability environment

Planning ahead for high availability support is important to avoid the risk of a failure without failover
coverage. The application server infrastructure that is managed by a high availability manager includes
cells and clusters. These components relate closely to core groups, high availability groups, and the policy
that controls the high availability infrastructure.

In a high availability environment that is set up properly, a high availability manager can reassess the
environment it is managing and accept new components as they are added to the environment. For
example, when a Java virtual machine (JVM) is added to the infrastructure, a discovery process begins.
During startup the JVM tries to contact the other members of the core group. When it finds another
running JVM, it initiates a join process with that JVM that determines whether or not the JVM can join the
core group. If the new JVM is accepted as a member of the core group, all of the JVMs, including the new
one, log message HMGR0218I . This message is also displayed on the administrative console.

Message HMGR0218I indicates the number of application servers in the core group that are currently
online. If this message is not displayed after a JVM starts, either a configuration problem or a
communication problem has occurred. To fix this situation, verify that the application server is running on a
current configuration, by either using the deployment manager to tell the node agent to synchronize, or
use the syncNode command to manually perform the synchronization. If the JVM still cannot join the core
group, a network configuration problem exists.

The high availability manager is designed to function in all of the supported WebSphere Application Server
topologies. However, a high availability-managed environment must comply to the following rules:
v A cell in a high availability infrastructure is partitioned into one or more core groups. WebSphere
Application Server provides a default core group as part of the high availability manager function.
Additional core groups can be created using the administrative console.
v A core group cannot extend beyond the boundaries of a cell, and it cannot overlap with any other core
groups.
v A cluster must be a member of only one core group. All of the individual members of that cluster must
be members of the same core group. This one-to-one relationship between a cluster and a core group
exists for both static and dynamic clusters.
v Individual application servers that are part of the high availability environment must also be part of a
core group.

298 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v An application server can only join a core group if its JVM can communicate with all of the other online
application servers that are part of that core group. If a single application server can not open a
connection to the JVM or send a heartbeat to it, the application server is not joined to the core group.

Tip: If a communication problem occurs, one of the following situations might exist.
– Two or more of the online application servers are using different IP addresses when they
attempt to communicate with the new application server. If the new application server’s host
name can resolve to multiple IP addresses or if the application server is configured with
multiple host files, specify a preferred IP address for the application server.
– One or more application servers in the core group are using a network card or a different
subnet or physical network than the other application servers. This situation results in two
visible partitions: one partition for each network and subnet. To fix this problem, specify the
preferred IP address for each application server and make sure that the IP address for the new
application server is on a compatible subnet as well as on the same physical network as the
other application servers.

The following diagram illustrates what a cell might look like in a high availability environment:
cell_1

core group A core group B

core group C

clusters

single server

Important: After you set up your WebSphere Application Server environment to comply with all of the
high availability-managed environment rules, use the default core group to control this
environment. DO NOT add additional core groups unless your environment absolutely requires
them. Also, do not change the default configurations unless you are doing so to solve a
specific problem or situation. When you do make configuration changes, such as changing the
policy for a high availability group or moving core group members between core groups in a
multi-core group environment, make sure you fully understand the effect such changes will
have on your entire environment.

Following are tasks you might perform if you need to change the default configuration:
1. Create additional core groups, if required..
2. Modify the attributes of an existing core group.

Chapter 3. Setting up the application serving environment 299

3. Modify the attributes of an existing high availability group policy.
4. Create a new policy and associate it with a high availability group.
5. Create core group access points if you create additional core groups.

High availability manager

WebSphere Application Server uses a high availability manager to eliminate single points of failure. A high
availability manager is responsible for running key services on available application servers rather than on
a dedicated one (such as the deployment manager). It takes advantage of fault tolerant storage
technologies such as network attached storage (NAS), which significantly lowers the cost and complexity
of high availability configurations. The high availability manager also provides peer-to-peer failover for
critical services by always maintaining a backup for these services.

A high availability manager continually monitors the application server environment. If an application server
component fails, the high availability manager takes over the in-flight and in-doubt work for the failed
server. This action significantly improves application server availability.

In a highly available environment, all single points of failure are eliminated. Because the high availability
manager function is dynamic, any configuration changes that you make and save while an application
server is running are eventually be picked up and used. You do not have to restart an application server to
enable a change. For example, if you change a policy for a messaging engine high availability group while
the messaging engine is running, the new policy is dynamically loaded and applied, and the behavior of
the messaging engine reflects this change.

A high availability manager focuses on recovery support and scalability in the following areas:
v Messaging
v Transaction managers
v Workload Management (WLM) controllers
v Application servers
v WebSphere partitioning facility instances

To provide this focused failover service, the high availability manager supervises the Java Virtual Machines
(JVMs) of the application servers that are core group members. The high availability manager uses one of
the following methods to detect failures:
v An application server is marked as failed if the socket fails. This method uses the KEEP_ALIVE function
of TCP/IP, and is very tolerant of extreme application server loading, which might occur if the application
server is swapping or thrashing heavily. This method is recommended for determining a JVM failure if
you are using multicast emulation, and are running enough JVMs on a single application server to push
the application server into extreme CPU starvation or memory starvation.
v A JVM is marked as failed if it stops sending heartbeats for a specified time interval. This method is
referred to as active failure detection. When it is used, a JVM sends out one heartbeat, or pulse every
second. If the JVM is unresponsive for more than 20 seconds, it is considered down. You can use this
method with multicast emulation. However, this method must be used for true multicast addressing.

In either case, if a JVM fails, the application server on which it is running is separated from the core group
and any services running on that application server are failed over to the surviving core group members.

A JVM can be a node agent, an application server or a deployment manager. If a JVM fails, any singletons
running in that JVM are restarted on a peer JVM after the failure is detected. This peer JVM is already
running, and eliminates the normal startup time, which potentially can be minutes.

All of the application servers in a cell are defined as members of a core group. Each core group has only
one logical high availability manager that services all of the members of that core group. The high

300 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
availability manager is responsible for making the services within a core group highly available and
scalable. It continually polls all of the core group members to verify that they are active and healthy.

A policy matching program is used to localize certain policy-driven components and to place these
components into high availability groups. When a core group member fails, the high availability manger
assigns the failing member’s work to the same type of component from the same high availability group.
Using NAS devices in the position of common logging facilities helps to recover in-doubt and in-flight work
if a component fails.

WebSphere Application Server provides a default core group that is created during installation. New server
instances are added to the default core group as they are created. The WebSphere Application Server
environment can support multiple core groups, but one core group is usually sufficient for most
environments.

A high availability manager is comprised of a variety of components. All of the components in a high
availability manager infrastructure work together to ensure peer-to-peer failover is effectively protecting the
application server environment from failures. The following table describes the main high availability
components, or areas of components, required for an effective high availability manager environment:

Server component areas Focus on the application server run time and include such
entities as cells and clusters. These areas are necessary
for a healthy high availability manager run time because
they closely relate to core groups, high availability groups,
and the policy that defines the infrastructure.
Core groups Provide failover support. A default core group is created
during startup. This core group should be sufficient for
most environments. Additional core groups can be
created, but you should only create them if you fully
understand the implications to your high availability
environment.

Core groups are static in nature. The configuration applied

to a core group through user-defined policies determines
the dynamic relationship within high availability groups.
High availability groups Closely bound to policy definitions. High availability groups
are dynamic in nature and are not configured directly by
users. Policy match criteria determines the high availability
group to which a core group member belongs.
Network components Provide the underlying network infrastructure that is crucial
to the success of the high availability manager. By default,
WebSphere Application Server uses a channel framework
protocol. However, a unicast or multicast protocol can also
be used. The network components include a technology
that enables communication throughout the high
availability manager infrastructure.

All of these components must be active and properly configured to achieve a highly available
infrastructure.

High availability network components

The foundation for a highly available environment is dependent on the network that is created for this
environment. The WebSphere Application Server high availability manager, by default, uses a channel
framework network protocol model to establish network connections. This model enables network ports to
be shared among all of the channels within a transport chain. A unicast protocol, which supports
communication between a specific receiver and a specific sender, or a multicast protocol, which supports
open communication to all receivers, can also be used.

Chapter 3. Setting up the application serving environment 301

A high availability environment ties all of the network components together. It provides the basis for
providing peer-to-peer failover. The moment a component loses its network connection to the rest of the
infrastructure, the high availability manager assumes a failure has occurred and assumes the work
assigned to that component.

Thousands of high availability groups can exist within a core group. The policies that are associated with a
high availability group control how and when members of that group are activated. A group services
mechanism is used to communicate high availability group membership information between members of a
core group. This information includes the group services that are available and the lightweight component
groups that are part of a high availability group.

The group services mechanism also supports the following types of messaging between core group
members.
v High speed First In First Out (FIFO) messaging between members of the lightweight component groups.
v High speed view synchronous messaging.
v Java Virtual Machine (JVM) heartbeats or pulses, which are used to indicate that the associated
application server is still healthy.

Transport protocol for a high availability manager

The high availability manager network components can be built on either a channel framework, unicast or
multicast transport protocol. Channel framework is the default protocol, but there are options and features
available with multicast that might be a better match for your application server environment. Multicast
emulation can be used with any of these protocols.

The following network protocol configurations can be used with WebSphere Application Server:

Channel framework

Channel framework is the default network protocol configuration for the high availability manager. It
provides a common model for connection management, thread usage, channel management, and
message access within WebSphere Application Server. It extends the concept of a networking protocol
stack, or transport chain, to the WebSphere run time. Each transport chain consists of one or more types
of channels, and each channel supports a different type of I/O protocol, such as TCP, DCS or HTTP.
Network ports can be shared among all of the channels within a chain. The channel framework function
automatically distributes a request arriving on that port to the correct I/O protocol channel for processing.

The transport chain configuration settings determine which I/O protocols are supported for that chain.
Custom channels that support requirements unique to a particular customer or environment can also be
added to a transport chain.

Unicast protocol

Unicast protocol is a direct method of sending and receiving messages. JVMs are discovered when a new
application server attempts to open connections to application servers in the same core group that are
already running. The use of TCP/IP makes this suitable for high speed Wide Area Networks (WANs) and
Local Area Networks (LANs). This protocol uses less CPU and memory per connection than multicast
protocol, and might be more appropriate for larger core groups.

Multicast protocol

Multicast protocol requires a tuned environment. Heartbeats must be used as the failure detection method
with this protocol. In this environment the JVMs cannot be swapped or kept from running. A non
responsive JVM is viewed as a failed unit and all work items are taken away from that application server
and dispersed among other core group members. The network used by all of the members of the core
group must be able to use multicast protocol.

302 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Performance in terms of data rate is about the same for all three protocols. WebSphere Application Server
usually performs the best if a channel framework model is used, because this model supports using
multiple protocols at the same time. However if you are choosing between a unicast and a multicast
protocol, the unicast protocol is usually better because the most common WebSphere Application Server
scenario is low fan out or point-to-point messaging. Using the multicast protocol in a low fan out
environment forces all the recipients to process the message, even though only a low number of
application servers use the message.

Creating a new core group

Before creating a new core group, you must determine which application server processes to add to the
core group. For example, if you are creating a new core group because a firewall is used to separate your
proxy environment from your application server environment, you might leave the deployment manager,
the node agent, and some of the other Application Server processes in the default core group, and move
the server processes that exist on the other side of a firewall to the new core group after you create it.

You might want to perform this task if:

v A firewall is used to separate your proxy environment from your application server environment.
(Additional core groups are required to provide proper failover support in this topology.)
v The number of open TCP/IP sockets becomes unacceptable. (This could occur if you are using a
multicast protocol.)

Every WebSphere process is initially a member of the default core group provided with the WebSphere
Application Server product. Using the default core group is sufficient in most configurations.

To create a new core group:

1. In the administrative console, click Servers > Core groups > Core group settings > New .
2. In the Name field, specify a unique name for the new core group. This field can only be edited when
you create the new core group. Make sure that the name is meaningful and consistent with the
names of the other core groups in the cell. It is helpful if the name conveys why the application
servers are being moved to this core group. For example, if your company’s human resources
applications are installed on the application servers that are moved to this core group, you might
include HR as part of the core group name.
3. Add a description of this core group that helps other administrators understand the purpose of this
core group.
4. In the Number of coordinators field, specify the number of active application servers you want serving
as coordinators for this core group. Each core group coordinator can manage up to 10,000 core
group components. Specify a value for this field based on the anticipated number of core group
components.
5. Select the type of transport that the application servers contained in this core group are using.
a. If you select CHANNEL_FRAMEWORK, specify the name of an already defined transport chain
in the Channel chain name field. Any value specified for the Multicast port, Multicast group IP start
or Multicast group IP end fields are ignored.
b. If you select MULTICAST, you must enter a port number in the Multicast port field, enter the first
IP address in the range of IP addresses that can be used in the Multicast group IP start field, and
enter the last IP address in the range of IP addresses that can be used in the field.
c. If you select UNICAST, any value specified for the Channel chain name, Multicast port, Multicast
group IP start or Multicast group IP end fields are ignored.
6. Click Apply.
7. On the administrative console panel click Core groups > core_group_name > Policies > New , and
then select the policy that you want to associate with a high availability group in this core group. The
high availability groups that are part of the new core group determine the policies that are required for
this core group. New policies do not have to be defined if:

Chapter 3. Setting up the application serving environment 303

 v The processes contained in the new core group do not contain any high availability groups.
v The new core group only contains processes, such as the service integration bus, for which default
policies are provided as part of the high availability manager function.
If you need to define a new policy, the policy options are:
v All active policy: Under this policy, all of the group members are activated.
v M of N policy: Under this policy, M group members are activated. The number represented by M is
defined as part of the policy details.
v No operation policy: Under this policy, no group members are activated.
v One of N policy: Under this policy, only one group member is activated.
v Static policy: Under this policy, the active members of a group are statically assigned.
Multiple policies can be defined if different high availability groups require different policies. However,
only one policy can be associated with a given high availability group. See “Core group policies” on
page 319 for more information about these policies.

Note: If you are setting up a policy for a transaction manager, you must select One of N as your
policy type because a transaction manager requires that only one server can have access to a
failed server’s recovery log at any point in time.
8. Click Next.
9. Specify a name for the policy that is unique within the scope of the core group.
10. Change the value specified in the Is alive timer field if the default value is too long or too short a time
period. This value, specified in seconds, determines how frequently the high availability manager
checks the health of the core group members. Valid values are any integer between -1 and 600,
inclusive. If -1 is specified, the timer is disabled. If 0 (zero) is specified, the default value of 120
seconds is used.
11. Select Quorum if you want to enable quorum checking for the core group. Quorum is a mechanism
that can be used to protect resources shared across members of the group in the event of a failure.
CAUTION:
Quorum is an advanced hardware function and should not be enabled unless you thoroughly
understand how to properly use this function. If not used properly, this function can cause
data corruption.
The Quorum setting in the policy will only have an effect if the following items are true:
v The group members are also cluster members.
v GroupName.WAS_CLUSTER=clustername must be specified as a property in the group name of
any high availability group matching this policy.
When enabled, any group that is using this policy does not achieve quorum until a majority of the
members are running. For example, if there are n members in the group, (n/2) + 1 servers must be
online in order to achieve quorum. No group members are activated until quorum has been achieved.
The quorum mechanism is designed to work in conjunction with a hardware control facility that allows
application servers to be shut down if a failure causes the group to be partitioned.
12. Click Apply, and then select Match criteria .
13. On the next panel, click New and then specify the match criterion for this policy. A match criterion is a
set of one or more name=value pairs of data that can be matched to attributes contained in the name
of a high availability group.
a. In the Name field, enter the name of one of the properties contained in a high availability group’s
name that you want to use to associate this policy with that high availability group.
b. In the Value field, enter the value of this property that, along with the property name, forms the
name=value pair.
c. Optional: Add a description of this match criteria in the Description field.
d. Click Ok.

304 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 e. If you need to specify additional name=value pairs for your match criterion, repeat this step. Each
name=value pair must be entered separately. Repeat this step until you have specified all of the
name=value pairs required for this match criterion.
14. Click Save, select Synchronize changes with nodes and then click Save again to save your
changes.

You are now ready to add members to this new core group.

Core groups
A core group is a set of application servers that can be divided up into various high availability groups. It is
a statically defined component of the WebSphere Application Server high availability manager function that
monitors the application server environment and provides peer to peer failover of application server
components.

A core group can contain one or more high availability groups. However, a high availability group must be
totally contained within a single core group. Any component, such as the service integration bus
component of IBM service integration technologies or the WebSphere Application Server transaction
manager, can create a high availability group for that component’s use. For example, the service
integration bus might need a high availability group to support its messaging engines, and the transaction
manager component might need a high availability group to support its transaction logs.

A cell must have at least one core group. The WebSphere Application Server creates a default core group,
called DefaultCoreGroup, for each cell. All the server processes and Java virtual machines (JVMs),
including node agents on all managed nodes, the deployment manager, and application servers residing
within a cell are initially members of this default core group.

When properly configured, the default core group is sufficient for establishing a high availability
environment. However, certain topologies require the use of multiple core groups. For example, if a firewall
is used to separate the proxy environment from the server environment, an additional core group is
required in order to provide proper failover support. For this particular type of environment, application
servers outside of the firewall are members of a separate core group from the application servers that are
inside of the firewall.

The core group contains a bridge service, which supports cluster services that span multiple core groups.
Core groups are connected by access point groups. A core group access point defines a set of bridge
interfaces that resolve to IP addresses and ports. It is through this set of bridge interfaces that the core
group bridge provides access to a core group.

If you create additional core groups, when you move core group members to the new core groups,
remember that:
v Each server process and Java virtual machine (JVM), including node agents on all managed nodes, the
deployment manager, and application servers within a cell can only be a member of one core group.
Core groups cannot overlap each other.
v If a cluster is defined for the cell, all of the cluster members must belong to the same core group.

Network communication between all the members of a core group is essential. The network environment
must consist of a fast local area network (LAN) with full Internet Protocol (IP) visibility and bidirectional
communication between all core group members. IP visibility means that each member is entirely receptive
to the communications of any other core group member.

A core group consists of the following elements:

Coordinator
The coordinator is the elected, or default, high availability manager. The coordinator is responsible
for tracking all of the members of a core group when members leave, join, or fail. The coordinator

Chapter 3. Setting up the application serving environment 305

 is not a single point of failure. In the event of a failure involving the coordinator, the preferred
coordinator, or a default, picks up the high availability manager work, including the management of
the core group.
Core group members
Any application server that is created within a cell that is defined as part of a high availability
environment is automatically designated as a core group member.
Messaging subsystem
A messaging subsystem is a subsystem, such as the service integration bus component of IBM
service integration technologies, that provides high-speed connections between core group
members. This subsystem enables all core group members to quickly and effectively communicate
with each other.
Core group bridge service
The core group bridge service is only utilized in high availability environments that contain multiple
core groups. Use the bridge service to provide quick and effective communication between core
groups.
Policy A policy is used to control which members of a high availability group are activated. Even though a
policy is defined at the core group level, it does not apply to the core group. The same policy can
be used by several different high availability groups but all of the high availability groups to which
it applies must be part of the same core group. A policy is established for a high availability group
when that group is created. The following policies can be specified for a high availability group:
v All active policy: Under this policy, all of the group members are activated.
v M of N policy: Under this policy, M group members are activated. The number represented by M
is defined as part of the policy details.
v No operation policy: Under this policy, no group members are activated.
v One of N policy: Under this policy, only one group member is activated.
v Static policy: Under this policy, only specified group members are activated.

In a run-time server environment each core group functions as an independent unit. A Java Virtual
Machine (JVM) that is contained within a cell can be a member of one core group only. This JVM can be a
node agent, an application server or a deployment manager. However, even though the deployment
manager can belong to one core group only, it is still responsible for configuring all of the application
servers within a cell, even if multiple core groups are defined for that cell.

Within a core group, Java Management Extensions (JMX) connectors are given access to run-time
MBeans in one of two ways:
1. They can be attached directly to the application server that contains the run-time MBeans.
2. They can be attached to the deployment manager of that cell.

Attaching the JMX connectors to the deployment manager is the easier approach because you need to
specify only the host name and port numbers. However, the deployment manager and the node agent
must both be running for the JMX connectors to access the run-time MBeans.

Attaching the JMX connectors directly to the application server that contains the run-time MBeans is a
more reliable approach because even if the deployment manager is down, the JMX connectors can still
access the run-time MBeans as long as the application server that contains the MBeans is still running, .

The coordinator retains and tracks membership and state changes for a core group. To work efficiently, the
coordinator must have enough memory to contain the group and state information for the online members
of the core group. Configuring multiple coordinators enables this task to be shared equally among a set of
online coordinators.

306 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Using the administrative console, you can designate specific servers as preferred coordinator servers.
High availability manager coordinators run in these servers. If no preferred coordinator servers are
specified, the high availability manager selects them. To minimize churn on the core group, it is
recommended that you designate specific servers as preferred coordinator servers and limit how often you
restart these servers. The heap sizes for the JVMs and the relative amount of memory that the JVMs use
to host coordinator services need to be tuned to ensure that enough memory is available to hold the group
and state information for the core group.

While core group members are statically configured, high availability group members are dynamically
selected and only exist as run-time entities. The WebSphere Application Server runtime uses a policy
matching program to determine the policy that should be used for each high availability group. Each policy
includes a match criterion that consists of a set of name=value pairs. The policy matching program
matches these name=value pairs with attributes contained in the name of a high availability group. When a
match is made, the policy is associated with that high availability group.

High availability groups

High availability groups are dynamically created components of a core group. They cannot be configured
directly but are directly affected by static data, such as policy configurations, which are specified at the
core group level.

A high availability group cannot extend beyond the boundaries of a core group. However, members of a
high availability group can also be members of other high availability groups as long as all of these high
availability groups are defined within the same core group.

Any WebSphere Application Server component, such as the transaction manager, can create a high
availability group for that component to use. The component code must specify the attributes that are used
to create the name of the high availability group for that component. For example, to establish a high
availability group for the transaction manager:
v Code included in the transaction manager component code specifies the attribute
type=WAS_TRANSACTIONS as part of the name of the high availability group associated with this
component.
v The high availability manager function includes the default policy Clustered TM Policy that includes
type=WAS_TRANSACTIONS as part of its match criteria.

Whenever transaction manager code creates a high availability group, the high availability manager
matches the match criteria of the Clustered TM Policy to the high availability group member name. In this
example, the string type=WAS_TRANSACTIONS included in the high availability group name is matched to the
same string in the policy match criteria for the Clustered TM Policy. This match associates the Clustered
TM Policy with the high availability group the transaction manager component creates.

After a policy is established for a high availability group, you can change some of the policy attributes,
such as quorum, fail back, and preferred servers. However, you can not change the policy type. If you
need to change the policy type, you must create a new policy and then use the match criteria to associate
it with the appropriate group.

If you want to use the same match criteria, you must delete the old policy before defining the new policy.
You cannot use the same match criteria for two different policies.

Important: If the old policy is one of the default policies that IBM provides, it is recommended that you do
not delete the old policy. Instead, you should use a different match criteria for your new policy.
This new match criteria should include more matches with the attributes contained in high
availability group’s name than the default policy uses for its match criterion. The policy with
the greatest number of matches is the one that is used. Not deleting the IBM provided policy
enables you to revert back to that policy if a problem occurs when you use your newly created
policy.

Chapter 3. Setting up the application serving environment 307

Before changing the policy type for a high availability group you must fully understand how the application
server processes that are contained in that high availability group are configured and how they will be
affected by the policy change. You must also verify that the component that uses that particular high
availability group supports the new policy type. For example, if the high availability group for the service
integration bus uses a One of N policy, because it only wants one server to be active at any given point in
time, and you change the policy associated with that group to All Active, the service integration bus high
availability support no longer functions properly and data corruption might occur.

Core group collection

A core group is a component of the high availability manager function. A default core group, called
DefaultCoreGroup is created for each cell in the WebSphere Application Server environment. A core
group can contain standalone servers, cluster members, node agents and the deployment manager. A core
group must contain at least one node agent or the deployment manager.

To view this administrative console page, click Servers > Core Groups > Core group settings .

Name Specifies the name of the core group. Click the core group
name to edit the settings for that core group. This field is
read-only.
Description Describes the core group. This field is read-only.
Connected core groups Specifies the core groups that are connected to this core
group by access points. This field is read-only.

Click New to define a new core group. After a core group is defined, several fields become read-only. To
change those fields, delete and redefine the core group.

Click Delete to delete a core group. A core group must be empty before it can be deleted.

Core group settings

Use this page to create a core group or to edit an existing core group. A core group is a component of the
high availability manager function. It can contain standalone servers, cluster members, node agents and
the deployment manager. A core group must contain at least one node agent or the deployment manager.

Before you create a core group you must understand the relationship of core groups in a high availability
environment and know how you intend to use each core group.

To view this administrative console page, click Servers > Core groups > Core group settings > New or
Select an existing core group for editing.

On the Configuration tab, you can edit fields. On the Runtime tab, you can look at read-only information.

After you specify your core group settings, click Apply before defining additional properties or setting up a
core group bridge.

Extended information about the core group fields:

Configuration Tab::

Name: This field can only be edited when you create new core groups.

If you are defining a new core group, specify a name that is unique name among the existing core groups.
It is helpful to other WebSphere Application Server administrators if the name helps define the use of this
core group and if it is consistent with the names of the other core groups in the cell.

This field can contain alpha and numeric characters. The following characters cannot be used in this field:
# \ / , : ; " * ? < > | = + & % ’

308 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Also, the name cannot begin with a period (.) or a blank space. A blank space does not generate an error.
However, leading and trailing blank spaces are automatically deleted.

For example, DefaultCoreGroup is the name of the core group that contains the deployment manager
server process.

Description: Use this optional field to include a description of the core group. In environments where
there are multiple system administrators this field can help these administrators understand the overall
organization of the core groups. The supported length of this field is quite large. However, long
descriptions take time to load and can cause a delay when displaying the page.

Example: ″Default Core Group. The default core group cannot be deleted.″ is the description of the
DefaultCoreGroup.

Number of coordinators: The coordinator is a component in each server in a core group that provides
the service functionality of the high availability manager. The coordinator for a core group determines
membership and communicates state and status to the other members of the core group.

The default value is one coordinator, although multiple coordinators are advisable for large core groups. All
of the group data must fit in the memory of the allocated coordinators. One coordinator can run out of
memory in a system with a large core group, which can cause the system to work improperly.

Transport type: The transport type is a required field that specifies the type of network communication
your core group uses to communicate to members and to other core groups. The following transport
options are available:
CHANNEL_FRAMEWORK
CHANNEL_FRAMEWORK is the default transport type. It uses the channel framework topology to
incorporate port reusability and shared port technology into the communication system.
UNICAST
UNICAST is a targeted network model that focuses on a direct recipient for communication. This
type of communication is most suitable when the intended message is sent to a specific set of
recipients.
MULTICAST
MULTICAST consists of a broadcast network model. This model broadcasts communication across
the defined network, depending upon the values that are provided for the multicast settings.
Multicast settings are suitable when there are many recipients for the intended message;
otherwise broadcast communication tends to overload the network with traffic, and can impact
performance goals.

Channel chain name: Specifies the name of the channel chain if CHANNEL_FRAMEWORK is selected
for transport type.

MULTICAST settings: Specifies the following settings if a multicast transport type is used:
v Multicast port
The port setting tells the coordinator where to scan for transmissions. When setting this value, verify
that you are specifying a port that is not used by another network communication device. Setting a port
value that has conflicts causes problems with your high availability manager infrastructure.
v Multicast group IP start
Specify the starting Internet Protocol (IP) address of the intended communication area.
v Multicast group IP end
Specify the ending IP address of the intended communication area. Plan the network to accommodate
scalability.

Chapter 3. Setting up the application serving environment 309

Additional properties:
Core group servers
Use to display the server processes that belong to the core group. Server processes include the
deployment manager, node agents, application servers, and cluster members. You can use the
panel that displays to move server processes to a different core group.
Custom properties
Use to define custom properties to be used for configuration purposes.
Policies
Use to define the policies that the coordinator servers use to select the active members of a core
group. You can select from existing policies, or create new custom policies.
Preferred Coordinator Servers
Use to designate core group servers as preferred coordinator servers.

Related topics:
Core group bridge
Click on to specify core group bridge communication settings between core groups.

Runtime Tab::

Group name properties:

Specify one or more name=value pairs as the match criterion for a high availability group. If you specify
more than one name=value pair, use a comma to separate the pairs. You can specify an asterisk (*) to
obtain the selected information for all of the high availability groups within this core group.

When a WebSphere Application Server component creates a new high availability group, it establishes a
map of that group’s properties as the group name. This map is used to uniquely identify that high
availability group.

After you specify a match criterion or an asterisk:

v Select Calculate to determine how many high availability groups have names that match this match
criterion.
v Select Show groups to view a list of the high availability groups that match this match criterion. For
each group, this list indicates:
– Its high availability group name
– Whether or not quorum has been enabled
– The policy that is associated with the high availability group. If more than one policy is listed for a
high availability group, you must change the match criterion for one or more of your policies so that
only one policy is associated with this high availability group.
– Its status (either the OK icon or the Error icon). If only one policy is listed in the Policy column, the
OK icon is displayed in the Status column. If more than one policy is listed Policy column, the Error
icon is displayed in the Status column.
v Select Show severs to view a list of servers which are hosting active members of the high availability
groups that match the specified Group name properties. For each server, this list indicates:
– The names of the servers which are hosting the active high availability group members.
– The name of the node on which these servers resides.
– The version of the WebSphere Application Server product on which these servers are running.
– The number of high availability group members that are currently active on these servers.

Example: Suppose the following high availability groups are defined for a core group:
v Component A uses the following properties for its group name: [ name=compA, policy=oneofN,
owner=smith ]

310 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Component B uses the following properties for its group name: [ name=compB, policy=MofN,
owner=smith ]
v Component C uses the following properties for its group name: [ name=compC, policy=oneofN,
owner=smith ]

If you specify policy=oneofN in the Group name properties field and then select Show groups, the
groups for components A and C are listed.

If you specify owner=smith in the Group name properties field and then select Show groups, the groups
for components A, B and C are listed.

If you specify all of component C’s name properties in the Group name properties field:
name=compC,policy=oneofN,owner=smith

Then select Show groups, only the group for component C is listed. Note that the properties are
separated by commas. There are no blank spaces.

Changing a core group’s configuration

You might want to perform this task if you need to:
v Change the number of coordinators that are to be active.
v Change the transport type for the core group members.
v Set up some custom properties for your specific environment.
v Add or remove application servers from the list of preferred coordinator servers.

To change a core group’s configuration:

1. In the administrative console, click Servers > Core groups > Core group settings >
core_group_name.
2. If you want to change the number of coordinators that must be active for this core group, specify a
new value in the Number of coordinators field.
3. If you want to change the transport specification for this core group, in the Transport type pull-down,
select the type of transport the application servers in this core group are going to use.
a. If you select CHANNEL_FRAMEWORK, specify the name of the channel chain in the Channel
chain name field.
b. If you select MULTICAST, enter the multicast port number in the Multicast port field, enter the first
IP address in the range of IP addresses that can be used in the Multicast group IP start field, and
enter the last IP address in the range of IP addresses that can be used in the Multicast group IP
end field.
4. If you need to set up a custom property for your specific environment, click Custom properties > New
and then specify the name and value pair of your custom property.
5. If you need to change the list of preferred coordinator servers, click Preferred coordinator servers
and then add or delete the appropriate application servers from the list of preferred coordinator
servers.
6. Click Save, select Synchronize changes with Nodes and then click Save again to save your
changes.

Core group and core group bridge custom properties

Use these custom properties for advanced configurations with core groups and core groups that
communicate with the core group bridge.

FW_PASSIVE_MEMBER:

Chapter 3. Setting up the application serving environment 311

Use this property in a core group bridge configuration when there is a firewall between the core groups
and the secure side of the firewall is configured to listen only.

Set the FW_PASSIVE_MEMBER custom property to make the bridge interfaces that are in the core group
access point passive. Set the value on the core group access point that is on the secure side of the
firewall so that the core group bridge interfaces listen for connections from the unsecured side of the
firewall but do not initiate any connections. The servers on the secure side of the firewall are passive. The
custom property should correspond to your defined firewall rules that allow connections from the
unsecured region to the secure region only.

To configure this custom property, click Servers > Core groups > Core group bridge settings > Access
point groups >access_point_group_name > Core group access points >
core_group_access_point_name > Show detail > Custom properties > New in the administrative
console.

You also must set this custom property in any peer access points that refer to the core group access
points that you configure with this custom property.

Firewall

Set the custom

core group access points
property on the
secured core group
access point to
core_group_2 make server_C and
core_group_1
server_D passive.

server_A server_C
server_B
server_D

Set the custom

unsecured cell property on the peer secured cell
access point that
refers to the core group
access point in the
secured cell.

access point group

Figure 1. Configuring the FW_PASSIVE_MEMBER custom property

For example, server_A and server_B are configured in core_group_1. Server_C and server_D are
configured in core_group_2. Core_group_2 is behind a firewall that is configured to listen only through the
firewall. Core_group_1 is on the unsecured side of the firewall. Core_group_1 and core_group_2 can
communicate with each other through an access point group. To configure server_C and server_D to be
passive, perform the following steps:
1. In the administrative console for the cell that contains core_group_2, click Servers > Core groups >
Core group bridge settings > Access point groups > access_point_group_name > Core group
access points > core_group_access_point_name > Show detail > Custom properties >New .
2. Add the FW_PASSIVE_MEMBER custom property. Enter any value to enable the property.
3. In the administrative console for the cell that contains core_group_1, click Servers > Core groups >
Core group bridge settings > Access point groups > access_point_group_name > Peer access
points > peer_access_point_name > Show detail > Custom properties > New. The peer access
point you select should correspond to the core group access point for core_group_2.
4. Add the FW_PASSIVE_MEMBER custom property. Enter any value to enable the property.

312 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
By configuring the FW_PASSIVE_MEMBER custom property, you configured the servers on the secured
side of the firewall, server_C and server_D, to be passive. These servers listen for connections from the
other side of the firewall but do not initiate any connections to the unsecured side of the firewall.

IBM_CS_LS_DATASTACK_MEG:

Use this custom property to eliminate a condition that is reported by a message that is displayed
repeatedly in your SystemOut.log file.

You might see a message similar to the following message in the SystemOut.log file multiple times:
[9/24/04 13:28:19:497 CDT] 00000013 VSync W
DCSV2005W: DCS Stack DefaultAccessPointGroup.P at Member 172.16.1.86:9353:
The amount of memory available for synchronization is low. The configured memory
size is 418816 bytes. Currently used memory size is 420307 bytes.

If the member IP address is in the format of a dotted decimal IP address and port, you can eliminate these
messages by increasing the amount of memory that is allocated to the core stack that is used for core
group communication. Increase the value of this property until you no longer see the message in your
SystemOut.log file. Because the memory is dynamically allocated, setting a larger stack size than you
need does not cause memory problems.

Set the custom property on the bridge interface that contains the particular member that is in the
messages. You can also set the custom property on the access point group or the core group access
point. If you set the value on the access point group or core group access point, all the bridge interfaces
that are in the particular group are affected. If you set the value on an individual bridge interface and an
access point group or core group access point, the value that is set for the bridge interface is used. If the
value is set on both an access point group and a core group access point, the value that is set for the
core group access point is used.

To configure this custom property, complete the following steps:

1. Set the custom property in the administrative console.
v To set the custom property on a bridge interface, click Servers > Core groups > Core group
bridge settings > Access point groups > access_point_group_name > Core group access
points > core_group_access_point_name > Show detail > Bridge interfaces
>bridge_interface_name > Custom properties > New.
v To set the custom property on a core group access point, click Servers > Core groups > Core
group bridge settings > Access point groups > access_point_group_name > Core group
access points > core_group_access_point_name > Show detail > Custom properties > New.
v To set the custom property on an access point group, click Servers > Core groups > Core group
bridge settings > Access point groups > access_point_group_name > Custom properties >
New.
2. Add the IBM_CS_LS_DATASTACK_MEG custom property. Enter a value that is greater than the
default value of 5 megabytes.

Units megabytes
Default 5

Changing the configuration of a high availability group

High availability groups are dynamically created components of a core group. They cannot be configured
directly but are directly affected by static data, such as policy configurations, which are specified at the
core group level.

A high availability group has been established for a core group.

Chapter 3. Setting up the application serving environment 313

You might want to perform this task if you want to remove a high availability group from a cell.

You can use the administrative console to activate or disable all of the members of a high availability
group.
1. In the administrative console, click Servers > Core groups > Core group settings.
2. Click on the core group whose high availability groups you want to view.
3. Click on the Runtime tab
4. Specify a match criterion in the Group name properties field that matches the high availability group
you want to enable or disable. (You can specify an asterisk (*) to get a list of all the high availability
groups that are part of this core group.)
5. Click show groups.
6. The Status column of the High availability groups panel shows the state of the high availability
groups in this core group that match the specified match criterion.
7. In the Select column, indicate the high availability group whose state you want to change and then
click Enable or Disable.
Enable activates members of the high availability group that are currently in the disabled state. If
all of the members are already active, no action is taken.
Disable disables all of the high availability group members that are active.

It can take several minutes for this change to take affect.

High availability group servers collection

Use this page to determine how many high availability group members are active on a particular
application server.

To view this administrative console page, click Servers > Core groups > Core group settings >
core_group. Click on the Runtime tab and specify group name properties for a high availability group.
(You can specify an asterisk (*) to get a list of the servers that are hosting active members for all the high
availability groups in this core group.) Then select Show severs.

Server Specifies the name of a server on which there are active

high availability group members. This field is read-only.
Node Specifies the node on which each server is running. This
field is read-only.
Version Specifies the version of the WebSphere Application
product on which each node is running. This field is
read-only.
Active members Specifies the number of high availability group members
that are currently active on that server. This field is
read-only.

High availability group settings

Use this page to manage the state of a high availability groups.

To view this administrative console page, click Servers > Core groups > Core group settings
>core_group. Click on the Runtime tab. In the Group name properties field, specify a match criterion for a
specific high availability group, or specify an asterisk (*) to get a list of all the high availability groups that
are part of this core group. (A match criterion is one or more name=value pairs that match attributes
contained in a high availability group’s name.) Then click Show groups.

314 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
High availability group Specifies the names of the high availability groups. The
name of a high availability group is a set of name=value
pairs or attributes, separated with commas. For example,
name=productiongroup,policy=abc,ibm=websphere could
be the name of a high availability group. This field is
read-only.
Quorum Specifies if quorum is enabled for each high availability
group. This field is read-only.
Policy Lists the policies that have match criteria that matches
properties contained in the name of that high availability
group. There should only be one policy listed for a high
availability group. However, if multiple policies have match
criteria that equally match properties in a high availability
group’s name, all of the policies with matching criteria are
listed, and the ERROR icon appears in the status column.

For example, if you have a high availability group named

name=productiongroup,policy=abc,ibm=websphere, and
MyPolicy1 has the match criteria name=productiongroup,
and MyPolicy2 has the match criteria policy=abc, both
MyPolicy1 and MyPolicy2 are considered matching
policies and are listed in the Policy column.

This field is read-only.

Status Indicates, with icons, whether or not only one policy is
associated with a high availability group. If the OK icon
displays in this column, a single policy is associated with
that high availability group. If the ERROR icon displays in
this column, multiple policies are associated with that
group.

If the ERROR icon displays for a high availability group,

you must adjust the match criteria for one or more of the
policies listed in the Policy column for that group so that
the correct policy is the only one associated with that high
availability group.

The match criteria for multiple policies can match some of

the same properties in a group’s name as long as one
policy has a match criteria that matches more of the
properties in that group’s name than the match criteria of
any of the other policies. For example, if you have a high
availability group with a name that consists of the
following name and value pairs:
name=productiongroup,policy=abc,ibm=websphere

and MyPolicy1 has the match criteria

name=productiongroup and MyPolicy2 has the match
criteria name=productiongroup,ibm=websphere MyPolicy2 is
considered the matching policy because it has more
match criteria that matched the properties contained in the
high availability group’s name.

This field is read-only.

Use the Disable button if you want to prevent all of the members of a high availability group from being
activated. One of the few times you might want to use this button is if you are planning to remove or
delete the server on which this group is running.

Chapter 3. Setting up the application serving environment 315

Use the Enable button to enable all of the members of a high availability group that were previously
disabled. These members can then be activated according to the policy associated with that group.

High availability group members

Use this page to manage the state of the individual members of a high availability group. This page lists
the current members of the selected high availability group.

To view this administrative console page, click Servers > Core groups > Core group settings
>core_group. Click on the Runtime tab. In the Group name properties field, specify a match criterion for a
specific high availability group, or specify an asterisk (*) to get a list of all the high availability groups that
are part of this core group. (A match criterion is one or more name=value pairs that match attributes
contained in a high availability group’s name.) Then click Show groups and select one of the high
availability groups listed.

Name Specifies the name of a high availability group member.

Node Specifies the node on which each high availability group
member is running.
Version Specifies the version of the WebSphere Application Server
product on which each node is running.
Status Indicates the state of the high availability group members.

High availability group members are either idle, activated,

or disabled. The usual states are idle or activated. One of
the few times you might want to disable a member is if it
is running on a server that you plan to remove or delete.
v If a group member is idle, it cannot be assigned any
work.
v If a group member is activated, it can be assigned
work.
v If a group member is disabled, it must be enabled
before it can be activated.

Only use the Disable buttons if you want to prevent a group member from being activated.

Use the Enable button to enable a group member that was previously disabled.

Use the Activate button to activate an idle group member.

Use the Deactivate button to make a group member idle.

Creating a policy for a high availability group

Before creating a new policy, you should understand the following requirements for matching a high
availability group to a policy:
v A single high availability group cannot match to more than one policy. If the same match criteria is used
for multiple policies, the high availability groups with names that match this criteria do not activate when
the server is started and an error message, indicating that multiple policies match this group, is logged.
v The same policy can be used for multiple high availability groups.
v A hierarchy is used when matching a high availability group to a policy. If multiple properties are used
for the match criteria, the policy that has the most matches with the high availability group name is the
policy that is used.

You might want to perform this task if you have a high availability group that requires a policy that is
different from the policy governing other high availability groups in the same core group. For example:
v A One of N policy is in effect for all of your high availability groups

316 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v There is a high availability group within the core group that needs to have 5 members active at all
times.

You can create a policy with M of N specified as the policy type and 5 specified for the Number of active
members, and specify a match criterion that associates this policy with the high availability group that
requires this policy.

Important:
v Do not change any of the default policies that are shipped with the WebSphere Application
Server product. If you need to use different polices, create new policies and specify a
match criterion that matches multiple attributes contained in the name of the high availability
group. A policy with a greater number of match criterion matches overrides the IBM
provided default policies. The IBM provided policies are still available for your use if you
encounter a problem with the policies you create.
v Before changing the policy type for a high availability group, make sure you fully understand
how the application server processes that are contained in that high availability group are
configured and how they will be affected by the policy change. You must also verify that the
component that uses that particular high availability group supports the new policy type. For
example, if the high availability group for the service integration bus is using a one of N
policy, because it only wants one server to be active at any given point in time, and you
change the policy associated with that group to All Active, the service integration bus high
availability support no longer functions properly and data corruption might occur.

To create a new policy:

1. In the administrative console, click Servers > Core groups > Core group settings
core_group_name > Policies > New
2. Select the new policy you want in effect for a specific high availability group. If you need to define a
new policy, the policy options are:
v All active policy: Under this policy, all of the group members are activated.
v M of N policy: Under this policy, M group members are activated. The number represented by M is
defined as part of the policy details.
v No operation policy: Under this policy, no group members are activated.
v One of N policy: Under this policy, only one group member is activated.
v Static policy: Under this policy, the active members of a group are statically assigned.
Multiple policies can be defined if different high availability groups require different policies. However,
only one policy can be associated with a given high availability group. See “Core group policies” on
page 319 for more information about these policies.
3. Click Next.
4. Specify a name for the policy in the Name field. The name must be unique within the scope of the
core group. The name should be meaningful to other administrators. For example, if you are setting
up a new policy for the service integration bus, you might name the policy My Service Integration
Bus Policy.
5. Specify a value for the Is alive timer field if the default value is too long or too short a time period.
This value determines how frequently the high availability manager checks the health of the high
availability group members. The default value is 0 seconds.
v If you specify -1 the Is alive timer is disabled.
v If 0 (zero) is specified, the value specified for the Is alive timer at the core group services level is
used for high availability groups associated with this policy.
v If an integer between 1 and 2147483647, inclusive, is specified, this value is used for high
availability groups associated with this policy.

Chapter 3. Setting up the application serving environment 317

 6. Select Quorum if you want to enable quorum checking. When selected, quorum checking is enabled
for a high availability group governed by this policy. Quorum is a mechanism that can be used to
protect resources shared across members of the group in the event of a failure.
CAUTION:
Quorum is an advanced hardware function and should not be enabled unless you thoroughly
understand how to properly use this function. If not used properly, this function can cause
data corruption.
The Quorum setting in the policy will only have an effect if the following items are true:
v The group members are also cluster members.
v GroupName.WAS_CLUSTER=cluster_name must be specified as one of the name=value pairs
contained in the dynamically generated name of a high availability group to which this policy
applies. (A component that is using the high availability group function must include the name of its
high availability group as part of its component code.)
When enabled, any group using this policy will not achieve quorum until a majority of the members
are running. For example, if there are n members in the group, (n/2) + 1 servers must be online in
order to achieve quorum. No group members will be activated until quorum has been achieved.
The quorum mechanism is designed to work in conjunction with a hardware control facility that allows
application servers to be shut down if a failure causes the group to be partitioned.
7. For M of N and One of N policies, select the Fail back option if, when the most preferred server is
available, you want it to take back the workload from the servers that did the failover.
8. For M of N and One of N policies, select the Preferred servers only option if you only want group
members activated on servers included in the list of preferred servers for the group. If you select this
option, you must set up a list of preferred servers after you click OK. A description of how to set up
this list is provided in a later optional step.
9. For an M of N policy, specify in the Number of active members field the number of group members
that you want to be activated.
10. Click OK and then select Match criteria .
11. On the next panel, click New and then specify one of the name and value pairs that you want to
include in the match criterion for this policy. The name and value pair must match one of the
name=value attributes contained in the name of a high availability group to which you want to
associate this policy.
You, as the WebSphere Application Server administrator, do not have any direct control over the high
availability group name. The implementer of the high availability group code decides which properties
are used for the group name. You can only control the policy match criterion. “Core group settings” on
page 308 describes how to determine the name of a high availability group. that is part of a core
group.
You should set the match criterion for a new policy to two or more of the name=value attributes
contained in the high availability group’s name to ensure that this policy is used instead of the default
policy that IBM provides.
To Specify one of the name and value pairs that you want to include in the match criterion for this
policy:
a. In the Name field, enter the name of one of the name=value attributes contained in the name of
the high availability group with which you want to associate this policy. For example, the service
integration bus high availability group has the name:
IBM_hc=AcceptanceCluster WSAF_SIB_BUS=SSS_Bus WSAF_SIB_MESSAGING_ENGINE=AcceptanceCluster.000-SSS_
Bus temp_property=WSAF_TEMP type=WSAF_SIB

You can specify IBM_hc, WSAF_SIB_BUS, WSAF_SIB_MESSAGING_ENGINE, temp_property or type in the

Name field.

318 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 b. In the Value field, enter the value of the attribute you specified in the Name field. For example, if
you specify IBM_hc in the Name field, you must specify AcceptanceCluster in the Value field for
this match criterion to match an attribute included in the name of the service integration bus high
availability group.
c. Optional: Add a description of this match criterion in the Description field. For example, you might
specify First attribute to indicate that this name=value pair matches the first attribute contained
in the group name.
d. Click OK.
e. Repeat these steps for each additional attribute you want to include as part of your match
criterion. For example, you can specify type for the Name field and WSAF_SIB for the Value field to
include this name and value pair as part of your match criterion for this policy.
Using this example, the following high availability group-to-policy association is established:

High availability High availability group name Policy name Policy match criterion
group
service integration IBM_hc=AcceptanceCluster My Service IBM_hc=AcceptanceCluster,
bus WSAF_SIB_BUS=SSS_Bus Integration Bus type=WSAF_SIB
WSAF_SIB_MESSAGING_ENGINE= Policy
AcceptanceCluster.000-SSS_Bus
temp_property=WSAF_TEMP
type=WSAF_SIB

12. For a Static policy, under Additional Properties, select Static group servers to select the servers
that you want activated. Use Add to move core group servers into this list.
13. Optional: If you selected the Preferred servers only option, set up a list of preferred servers.
a. Under Additional Properties, select Preferred servers.
b. Use Add to move core group servers into the list of preferred servers. You can use Move up and
Move down to adjust the order of the servers within the list. Make sure that the most preferred
server is at the top of the list and the least preferred server is at the bottom.
14. Click Save, select Synchronize changes with Nodes and then click Save again to save your
changes.

The new policy goes into affect after it is saved and synchronized. You do not have to stop and restart the
affected application servers. In the future, you can change this policy’s settings for the Fail back and
Preferred servers only options, and create or update the list of preferred servers associated with this policy
without stopping and restarting the affected application servers.

Core group policies

Use this page to create or update the policy that determines how many members of a high availability
group should be active at a given point in time. A high availability group member is active if it is able to
accept work.

To view this administrative console page, click Servers > Core groups > Core group settings > New or
existing core group > Policies.

Click New to define a new policy. After a policy is defined there are several fields that you can no longer
change. To change those fields, delete and redefine the policy. Click Delete after selecting a policy to
delete the selected policy.

All of the policy fields on this page are read-only. To change the values specified in any of these fields,
click on the name of the policy you want to change. When the console page Core group settings >
group_name > Policies > policy name displays, you can edit the policy properties.

Name Displays the name of the policy

Chapter 3. Setting up the application serving environment 319

Description Displays the description of the policy.
Policy type Specifies the type of policy that is implemented for a high
availability group that is associated with this policy.
v All active policy: Under this policy, all of the group
members are activated.
v M of N policy: Under this policy, M group members are
activated. The number represented by M is defined as
part of the policy details.
v No operation policy: Under this policy, no group
members are activated.
v One of N policy: Under this policy, only one group
member is activated.
v Static policy: Under this policy, the active members of
a group are statically assigned.
Restrictions:
1. If you are setting up a policy for a transaction
manager, you must select One of N as the policy type.
2. If you are setting up a policy for a service integration
bus you must select One of N or Static as the policy
type. The default policy that IBM provides for a service
integration bus uses a One of N policy type.
Match criteria Specifies one or more name=value pairs that are used to
associate this policy with a high availability group. These
pairs must match attributes that are contained in the name
of a high availability group before this policy is associated
with that group.

Core group policy settings

Use this page to define a policy for a high availability group. Even though a policy is defined at the core
group level, it only applies to a high availability group that is contained within the core group.

To view this administrative console page, click Servers > Core groups > Core group settings > New or
existing core group > Policies > policy_name.

Name Specifies the name of the policy. This name must be unique within the scope
of a core group.
Policy type Specifies the policy type that was selected when this policy was created. This
is a read-only field. If you want to change the policy type, you must delete this
policy and then create it again specifying a different policy type. If this is an
IBM provided policy, do not delete it. Instead create a new policy and specify
more of the attributes contained in the high availability group’s name as the
match criterion for this new policy. The policy with the greatest number of
matches to attributes in a group’s name is the policy that is associated with
that group.
Policy type Specifies the policy type that was selected when this policy was created. This
is a read-only field. If you want to change the policy type, you must delete this
policy and then create it again specifying a different policy type. If this is an
IBM provided policy, do not delete it. Instead create a new policy and specify
more of the attributes contained in the high availability group’s name as the
match criterion for this new policy. The policy with the greatest number of
matches to attributes in a group’s name is the policy that is associated with
that group.
Description You can use this field to provide meaningful information about this policy. For
example, the Clustered TM Policy provided with the product has TM
One-Of-N Policy in the description field.

320 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Integer
v Valid values are -1 to 600 seconds, inclusive.
v If -1 (negative 1) is specified, this function is disabled.
v If 0 (zero) is specified, the high availability manager uses the time interval
specified at the application server process level is used.
v If a value larger than 0 (zero) is specified, the high availability manager
uses the time interval specified here, instead of the one specified at the
application server process level, when determining how frequently it should
check the health of the high availability group members using this policy.
Default 0 (zero)
Quorum When selected, quorum checking is enabled for a group governed by this
policy. Quorum is a mechanism that can be used to protect resources that are
shared across members of the group in the event of a failure.

CAUTION:
Quorum is an advanced hardware function and should not be enabled
unless you thoroughly understand how to properly use this function. If
not used properly, this function can cause data corruption.

The Quorum setting in the policy will only have an effect if the following items
are true:
v The group members are also cluster members.
v GroupName.WAS_CLUSTER=clustername must be specified as a property
in the group name of any high availability group matching this policy.

When enabled, any group using this policy will not achieve quorum until a
majority of the members are running. For example, if there are n members in
the group, (n/2) + 1 servers must be online in order to achieve quorum. No
group members will be activated until quorum has been achieved.

The quorum mechanism is designed to work in conjunction with a hardware

control facility that allows application servers to be shut down if a failure
causes the group to be partitioned.
Fail back When selected, if a failure occurs, work items assigned to the failing server
are moved to the server that is designated as the most preferred server for
the group. This field only applies for M of N and One of N policies.
Preferred servers only When selected, group members are only activated on servers that are on the
list of preferred servers for this group. This field only applies for M of N and
One of N policies.
Number of active members This field only applies for the M of N policy. Use this field to specify how
many of the high availability group members are to be activated.

The options available under Additional Properties are determined by the type of policy selected. One or
more of the following options are available:

Custom properties Use this link to specify custom properties for the policy.
Match criteria Use this link to set up a match criterion for the policy.
Preferred servers Use this link to set up a list of servers that are given preference when group
members are activated.
Static group servers Use this link to set up a list of the specific servers that are activated.

New core group policy definition

Use this page to create a new policy for a high availability group.

Chapter 3. Setting up the application serving environment 321

When you create a new policy, the first page that displays lets you select a policy type. To view the
administrative console page where you select a policy type, click Servers > Core groups > Core group
settings > New or select an existing core group > Policies > New.

Select one of the following policy types:

v All active policy: Under this policy, all of the group members are activated.
v M of N policy: Under this policy, M group members are activated. The number represented by M is
defined as part of the policy details.
v No operation policy: Under this policy, no group members are activated.
v One of N policy: Under this policy, only one group member is activated.
v Static policy: Under this policy, only specified group members are activated.

See “Core group policies” on page 319 for more information about these policies and restrictions that
apply for specific high availability groups.

After selecting a policy, click Next to continue.

Preferred servers
Use this page to define the ordered list of preferred servers for the selected policy. The policy gives
preference to the servers in this list when activating group members. If there are no preferred servers in
the list or none of the servers in the list are active (able to accept work), any available application server
will be designated by the coordinator for the high availability group associated with this policy. The
coordinator activates and deactivates high availability group members based on the policy that is in effect
for that group.

To view this administrative console page, you must be working with a policy that has a policy type of M of
N or One of N. If your policy has one of these policy types, click Servers > Core groups > Core group
settings > New > or select an existing core group > Policies > New > or select an existing policy. Under
Additional Properties, select Preferred Servers.

Use Add and Remove to move servers into and out of the list of preferred servers. Use Move up and
Move down to adjust the order within the list of preferred servers. Make sure that the most preferred
server is at the top of the list and the least preferred server is at the bottom.

Click OK to make your changes effective. Click Save to save and synchronize your changes with all
managed nodes.

Changes to the preferred servers list take affect as soon as they are saved and synchronized. You do not
have to stop and restart the affected application servers.

Preferred coordinator servers

Use this page to define the ordered list of core group servers on which the coordinator servers reside.

To view this administrative console page, click Servers > Core groups > Core group settings > New >
or select an existing core group > Preferred coordinator servers.

Use Add and Remove to move servers into and out of the list of core group servers on which coordinator
servers reside. Use Move up and Move down to adjust the order within this list. Make sure that the most
preferred server is at the top of the list and the least preferred server is at the bottom.

Click OK to make your changes effective. Click Save to save and synchronize your changes with all
managed nodes.

Matching criteria collection

Use this page to view criteria that are defined for a policy.

322 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this administrative console page, click Servers > Core groups > Core group settings > New >
or select an existing core group > Policies > New or select an existing policy > Match Criteria.

Click New to create a new match criteria for the policy. Click the name of a match criteria to change any of
that criterion’s properties.

Name Specifies the name of the match criterion.

Value Specifies the value that is paired with the name.
Description A description of the match criterion. For example, if you
have your own service integration bus policy, the
description for the match criterion for that policy might be
″My Service Integration Bus Match Criterion.″

Match criteria settings

Use this page to view match criterion defined for a policy.

To view this administrative console page, click Servers > Core groups > Core group settings > New >
or select an existing core group > Policies > New or select an existing policy > Match Criteria > criterion
name.

Use the name, value, and description fields to define a match criterion for the policy. The name and value
fields should match a name=value attribute included in the name of a high availability group that you want
associated with this policy.

Name Specify the name of the match criterion. Create

meaningful and consistent criterion names to help define
their use.
Value The required value field specifies the value that is paired
with the name to determine a match in a policy test.
Description Use the optional description field as a complement to the
name field. This field can be particularly useful in
environments with multiple system administrators who can
describe the test that the criterion is performing.

Click Apply to define the criterion. Click Save and synchronize changes with nodes after defining new
criteria.

Static group servers collection

Use this page to designate which servers will be made active for the high availability groups associated
with a policy that has Static for its policy type.

This option is available under Additional Properties only if Static is selected as the policy type. To view
this administrative console page, click Servers > Core groups > Core group settings >
existing_core_group > Policies > static_policy_name > Static group servers.

Use Add and Remove to move servers into and out of the list of servers that are designated as static
group servers.

Click Apply to make your changes effective. Click Save to save and synchronize your changes with all
managed nodes.

Changing the policy of a high availability group

Important:

Chapter 3. Setting up the application serving environment 323

 v Do not change any of the default policies that are shipped with the WebSphere Application
Server product. If you need to use different polices, create new policies and specify a
match criterion that matches multiple attributes contained in the name of the high availability
group. A policy with a greater number of match criterion matches overrides the IBM
provided default policies. The IBM provided policies are still available for your use if you
encounter a problem with the policies you create.
v Before changing the policy type for a high availability group, make sure you fully understand
how the application server processes that are contained in that high availability group are
configured and how they will be affected by the policy change. You must also verify that the
component that uses that particular high availability group supports the new policy type. For
example, if the high availability group for the service integration bus is using a one of N
policy, because it only wants one server to be active at any given point in time, and you
change the policy associated with that group to All Active, the service integration bus high
availability support no longer functions properly and data corruption might occur.
v Adhere to the following requirements for matching a high availability group to a policy:
– A single high availability group cannot match to more than one policy. If the same match
criteria is used for multiple policies, the high availability groups with names that match
this criteria do not activate when the server is started and an error message, indicating
that multiple policies match this group, is logged.
– The same policy can be used for multiple high availability groups.
– A hierarchy is used when matching a high availability group to a policy. If multiple
properties are used for the match criteria, the policy that has the most matches with the
high availability group name is the policy that is used.

Example: If you have two policies, Policy A and Policy B, and

v The match criteria for policy A is type=WAS_TRANSACTIONS.
v The match criteria for policy B is both type=WAS_TRANSACTIONS and IBM_hc=TestCluster.
v When the transaction manager high availability group is created, it is automatically associated with
Policy B because it has the closet match to the group name, which is
GN_PS=carbideCell\carbide\ServerA IBM_hc=TestCluster type=WAS_TRANSACTIONS

To change the policy for a high availability group:

1. Determine if there are any policy restrictions for this high availability group. “Core group policies” on
page 319 includes information about any policy restrictions for the IBM provided high availability
groups.
2. Create a new policy that has an approved policy type and configuration.
3. Use the Core Group Runtime panel in the administrative console to see a list of high availability
groups exist for this core group and determine which ones need a new policy. While looking at this
panel, you should note the group name properties for all of the groups you are changing.
4. Update the match criteria for each new policy so that it matches the original match criteria and at least
one other attribute from the name of the high availability group with which you want to associate the
new policy. Two policies can not have exactly the same match criteria because only one policy can be
associated with a given high availability group.
5. Click Save, select Synchronize changes with Nodes and then click Save again to save your
changes.

Adding members to a core group

Two or more core groups must be defined for a single cell.

You might need to perform this task after you perform one of the following tasks:

324 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v You create a new core group and want to move some of the members of another core group into this
new core group.
v You create a new application server and want to move it to a core group other than the default core
group. When a new application server is created, it is automatically added to the default core group.

When adding new members to a core group, remember that:

v All server processes and Java virtual machines (JVMs), including the node agents on all managed
nodes, the deployment manager, and application servers within a cell, can only belong to one core
group.
v Core groups cannot overlap each other. If a cluster is defined for the cell, all of the cluster members
must belong to the same core group.
1. In the administrative console, click Servers > Core groups > Core group settings
>core_group_name > Core group servers.
2. In the Select column, select the application servers that you want to move.
3. Click Move. The Core groups > DefaultCoreGroup > Core group servers > Move administrative
console panel is displayed showing the application servers you want to move and the core group to
which these application servers currently belong.
4. Indicate in the To core group field the core group to which you want these application servers moved.
5. Click Apply.
6. Click Synchronize changes with Nodes and then Save to save your changes.

The appropriate application servers reside in each core group defined for the cell.

Core group servers

A core group server is an application server, a deployment manager, or a node agent that is a member of
a high availability core group. Use this page to move servers into a different core group. All members of a
cluster must be in the same core group. If you select one or more members of a cluster, all of the
members of that cluster must be moved.

To view this administrative console page, click Servers > Core groups > Core group settings > New or
Select an existing core group for editing > Core group servers.

Name Specifies the names of the servers in the core group. This
field is read-only. Click on this field to the specify custom
properties for this server.
Node Specifies the node that contains the core group server.
This field is read-only.
Version Specifies the product version of the node in the cell. A
Version 6 deployment manager node can own a Version 5
managed node. Version 5 managed nodes are easily
identified in this field. This field is read-only.
Type Identifies the server process type, which can be either
deployment manager, node agent, or application server.
Standalone application servers in the cell, managed
nodes, and cluster members all display as application
server types. This field is read-only.
Cluster Name Specifies the cluster name if the core group server is part
of a cluster. If the core group server does not belong to a
cluster, this field is blank. This field is read-only.

To move one or more servers to another core group, select the check box next to the names of the
servers that you want to move and click Move.

Chapter 3. Setting up the application serving environment 325

Core group server settings
Use this page to create or change custom properties for a server in a core group.

To view this administrative console page, click Servers > Core groups > Core group settings > Select
an existing core group > Core group servers > Select an existing server.

Extended information about the fields on the panel:

Node Displays the name of the node that contains the core
group server. This field is read-only.
Name Displays the name of the core group server. This field is
read-only.
Custom Properties Click on this field to define or edit a custom property for
the core group server.

Core group server move settings

Use this page to move one or more servers into a different core group.

Servers, other than the node agent and deployment manager servers, can be moved from one core group
to another. However all members of a cluster must be in the same core group. If one or more of the
servers you are moving belongs to a cluster, you must move all of the members of that cluster. To view
this administrative console page, click Servers > Core groups > Core group settings >core_group >
Core group servers. Select the servers to be moved and then click Move.

Extended information about the core group fields:

Move selected servers This field lists the servers that you selected to be moved.
It can not be edited.
From core group This field specifies the name of the core group that you
are moving the servers from. It can not be edited.
To core group From the pull-down list, select the core group that these
servers will be moved into.

Click Apply to make your changes effective. Click Save and save and synchronize your changes with all
managed nodes.

Routing high availability group work to a different server

How you route work items for a high availability resource to a different application server during runtime
depends on how your application server environment is configured.

You might need to perform this task if you have to change the application server that is handling work
items for a high availability resource, such as the service integration bus. For example, if a core group
includes a cluster of application servers, and a messaging engine is configured for that cluster, any of the
servers in that cluster can handle work items for the messaging engine. However, if the high availability
group with which the messaging engine is associated is governed by a One of N policy, only one of these
application servers can be active at a given point in time.

If you are using the WebSphere Application Server default configuration for a high availability environment,
you can change the application server that is handling the work items for a high availability resource. This
change can be performed as a run-time operation (the change exists only in memory) or it can be done as
a permanent configuration change. To make this change a permanent configuration change, perform one
of the following steps:

326 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
1. Create a preferred servers list for the policy that governs the high available group. In the administrative
console, you can click Show groups on the Runtime tab for your core group if you need to determine
the high availability group name for the resource that is involved in the change.
For example, to change which server is handling the work items for the service integration bus, create
a preferred servers list for the Default SIBus Policy, which is the default policy for the service
integration bus high availability group.
a. To view this administrative console page, click Servers > Core groups > Core group settings >
DefaultCoreGroup > Policies > Default SIBus Policy > Preferred servers
b. Add the desired servers to the Preferred servers list.
c. Click Save, select Synchronize changes with Nodes and then click Save again to save your
changes.
As soon as you save your changes, all work items for the service integration bus will be routed to the
new preferred server.
2. Create a new static policy for the high availability group to which the resource belongs. Make sure that
the match criteria you specify for this new policy includes at least two of the properties specified as
part of that high availability group name. To determine the high availability group name for a resource,
make sure the application server that is currently handling the work items for the resource is active,
and then click Show groups on the Runtime tab, in the administrative console, for your core group
and enter an asterisk (*) in the Group name properties field.
For example, to move a messaging engine, create a new policy for the messaging engine high
availability group that has Static as the policy type. The match criteria for this policy must include at
least two of the properties that are contained in that high availability group name. The two property
match will cause the new policy to be used instead of the default policy for this group.
a. Determine the high availability group name for the messaging engine you want to move. In the
administrative console, click Core groups > Core group settings > DefaultCoreGroup, and then
click on the Runtime tab. Enter an asterisk (*) in the Group name properties field. A list of the high
availability groups that are contained in that core group are displayed in an administrative console
panel. An example of a group name that might display on this list follows. The name is split here
for printing.:
IBM_hc=AcceptanceCluster,WSAF_SIB_BUS=SSS_Bus,WSAF_SIB_MESSAGING_ENGINE=
AcceptanceCluster.000-SSS_Bus,temp_property=WSAF_TEMP,type=jms
b. Create a new static policy. In the administrative console:
1) Click Core groups > Core group settings > DefaultCoreGroup > Policies > New
2) Select Static Policy for the policy type and click Next.
3) Enter a policy name.
4) Enter a policy description.
5) Default isAlive timer setting should be 0.
6) Do not select Quorum.
7) Click Apply to save the new policy.
8) Under Additional Properties, select Match Criteria and specify at least two of the properties
that exist in the name of the high availability group for the messaging engine. Using the
preceding group name, you might specify the following two match criteria:
WSAF_SIB_MESSAGING_ENGINE=AcceptanceCluster.000-SSS_Bus
type=jms
9) Under Additional Properties, select Static group servers and specify the name of the
application server on which you want the messaging engine to be active.
10) Click OK and Save to save your changes.

New work items for the high availability group are now routed to a different server.

Chapter 3. Setting up the application serving environment 327

Configuring the core group bridge service
The core group bridge service can be configured for communication between core groups. A core group is
a statically defined component of the high availability manager. To configure communication between core
groups, use an access point group. An access point group is a collection of core groups that communicate
with each other.

Configure two or more core groups that need to communicate with each other. For more information about
core groups, see “Core groups” on page 305. To configure core groups, see “Creating a new core group”
on page 303.

You must configure the core group bridge service whenever two or more core groups are configured in the
same cell. You can also configure the core group bridge to share traffic among core groups that are in
different cells. Configure the core group bridge to communicate between cells only when the service is
required by another WebSphere Application Server component. By configuring the core group bridge
service, the availability status of the servers in each core group is shared among all the configured core
groups. For more information, see “Core group communications using the core group bridge service.” You
can configure core groups to communicate in the following ways:
v Configure core group communication between core groups that are in the same cell. Configuring
communication between any core groups that are in the same cell is required. For more information,
see “Configuring communication between core groups that are in the same cell” on page 333.
v Configure core group communication between core groups that are in different cells. You can configure
each cell to communicate with one or more other cells. For more information, see “Configuring
communication between core groups that are in different cells” on page 338.
v Configure communication between core groups using a proxy peer access point. Sometimes, your core
group might not have access to the core group that you want to communicate with. However, if you can
access a core group that can communicate with the inaccessible core group, you can create a proxy
peer access point. For more information, see “Configuring core group communication using a proxy
peer access point” on page 345.

Multiple core groups can communicate with each other.

Continue configuring the high availability environment. See “Setting up a high availability environment” on
page 298 for more information.

Core group communications using the core group bridge service

The core group bridge service can be configured to share availability information about internal
WebSphere Application Server components between core groups. For example, by configuring the core
group bridge service, each core group can be aware of the status of all of the application servers that are
configured in all of the core groups. Use access point groups to define the core groups that communicate.
Do not use the core group bridge service to share application information among core groups.

A core group is a statically defined component of the high availability manager. Each cell must have at
least one core group. WebSphere Application Server creates a default core group called
DefaultCoreGroup for each cell. For more information about core groups, see “Core groups” on page
305. Two or more core groups can be set up to communicate with each other and share workload
management information by defining access point groups. The core groups that communicate can be in
the same cell or in different cells.

Core group bridge overview

To configure communication between core groups, you must configure an access point group. An access
point group is a collection of the core groups that communicate with each other. Add a core group access
point to the access point group for each core group that needs to communicate.

328 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
A core group access point is a collection of server, node, and transport channel chain combinations that
communicate for the core group. Each core group has one or more defined core group access points. The
DefaultCoreGroup has one default core group access point. However, you might consider configuring
more than one core group access point for a core group if that particular core group needs to be
connected to other core groups that are on different networks.

The node, server, and transport channel chain combinations that are in a core group access point are
called bridge interfaces. A server that hosts the bridge interfaces is a core group bridge server. The
transport channel chain defines the set of channels that are used to communicate with other core group
bridge servers. Each transport channel chain has a configured port that the core group bridge uses to
listen for messages from other core group bridge servers.

Each core group bridge server must have at least one bridge interface for each core group access point.
However, to prevent failure of your configuration, configure multiple bridge interfaces for each core group
access point. Then, if one server in one of the bridge interfaces fails, the other bridge interface can still
receive information and the core group access point remains functional.

If you are configuring communication between core groups that are in the same cell, create one access
point group and add a core group access point for each core group that needs to communicate. The
following diagram shows an example configuration in a single cell:

cell_1
core group bridge servers core group bridge servers
core_group_access_point_1 core_group_access_point_2

core_group_1 core_group_2

ports bridge interfaces bridge interfaces ports

access point group

Figure 2. Core group bridge configuration in a single cell

If you are configuring the core group bridge between core groups that are in different cells, you still use an
access point group. However, you must create and configure the access point group for each cell. Each
cell has an access point group that contains a core group access point for the core group that is in the
cell, and a peer access point for each peer cell.

A peer access point references a core group access point that is configured in a different cell. Each
access point group must have one peer access point for each different cell. Do not configure multiple peer
access points that reference the same cell.

Each peer access point has one or more peer ports or one proxy peer access point.

A peer port corresponds to a bridge interface that is defined in the peer cell. You can define several peer
ports for each peer access point.

Chapter 3. Setting up the application serving environment 329

Define a proxy peer access point if the peer access point cannot be reached directly by using a peer port,
but can be reached by using another peer access point. The proxy peer access point specifies a peer
access point that can communicate with the peer core group that cannot be reached directly. The proxy
peer must have defined peer ports. Specify one proxy peer or one or more peer ports, but not both.

The following diagram shows a core group bridge configuration between two different cells that is using
peer access points with peer ports.

cell_1 cell_2
core group bridge servers core group bridge servers
core_group_access_point_1 core_group_access_point_2

core_group_1 core_group_2

ports bridge interfaces bridge interfaces ports

The access point group

in cell_1 contains access point group
core_group_access_point_1
and a peer access point that The access point group in cell_2
refers to contains
core_group_access_point_2. The access point core_group_access_point_2
The ports for the peer access group name must and a peer access point that refers
point must equal a port that is be the same in to core_group_access_point_1.
specified for one of the bridge both cells. The ports for the peer access
interfaces in point must equal a port that is
core_group_access_point_2. specified for one of the bridge
interfaces in
core_group_access_point_1.

Figure 3. Core group bridge configuration in two different cells

Configuration scenarios

You can configure core groups to communicate in the following ways:

v “Communication between core groups that are in the same cell”
v “Communication between core groups that are in different cells” on page 331
v “Communication between core groups across different networks” on page 331
v “Communication between core groups using a proxy peer access point” on page 332

Communication between core groups that are in the same cell

All core groups that are in the same cell must be configured to communicate with each other. To configure
core group communication within a cell, create one access point group with one core group access point
for each core group. Select one or more servers to be core group bridge servers, and define a bridge
interface for each server. The following image shows an example of three core groups that are in the
same cell and are connected by one access point group. The sample configuration shows how
communication between core groups in the same cell is configured in the administrative console.

330 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
cell_x

core group access points

x_core_group_1 x_core_group_2

x_access_point_group

x_core_group_3

Sample configuration:
Access point groups
- x_access_point_group

- Core Group x_core_group_1

+ Core Group Access Point x_core_group_ap_1

- Core Group x_core_group_2

+ Core Group Access Point x_core_group_ap_2

- Core Group x_core_group_3

+ Core Group Access Point x_core_group_ap_3

Figure 4. Communication between core groups that are in the same cell

See “Configuring communication between core groups that are in the same cell” on page 333 for more
information.

Communication between core groups that are in different cells

When two core groups in different cells need to communicate, add peer access points to the access point
groups. To configure the core group in cell_x to communicate with the core group in cell_y, add a peer
access point to the access point group in cell_x. The peer access point is equal to the core group access
point for cell_y. Configure an access point group that has the same name for cell_y that contains the core
group access point for the core group in cell_y and a peer access point that corresponds to the core group
access point for the core group in cell_x. Each peer access point also contains peer ports that identify
bridge interfaces in the opposite cells. See “Configuring communication between core groups that are in
different cells” on page 338 for more information.

Communication between core groups across different networks

In this scenario, one core group is configured to communicate with two or more core groups in different
cells across two or more networks. For example, a core group in cell_x needs to communicate with core
groups in cell_y and cell_z. Create two access point groups in cell_x. The first access point group,
access_point_group_xy, in cell_x contains a core group access point and a peer access point for the core
group in cell_y. The second access point group in cell_x, access_point_group_xz, contains a core group

Chapter 3. Setting up the application serving environment 331

access point and a peer access point for the core group in cell_z. Cell_y has an access point group
named access_point_group_xy, which has a core group access point and a peer access point for cell_x.
Cell_z has an access point group named access_point_group_xz which has a core group access point
and a peer access point for cell_x.

Configuring access point groups across multiple networks

Network 1

cell_x cell_y

access_point_group_xy
Network 2 access_point_group_xz
cell_z

See “Configuring communication between core groups that are in different cells” on page 338 for more
information.

Communication between core groups using a proxy peer access point

Use a proxy peer when the core groups cannot directly communicate. The two core groups must have
access to a single core group that can pass information between the two core groups. To understand what
a proxy peer access point does, consider a connecting flight when flying on an airplane. To fly from
Pittsburgh to London you first have to fly to New York City, where you change planes and then fly to
London. New York City is the proxy peer access point for London.

When defining a proxy peer, x_core_group_2 in cell_x cannot communicate directly with the core group in
cell_z. However, both core groups can communicate with the core group in cell_y. To configure
communication between cell_x and cell_z, you must configure two access point groups. The core group
access point in cell_y is in both of these access point groups, named access_point_group_xy and
access_point_group_yz. The following image shows an overview of a proxy peer configuration.

332 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 cell_z

access_point_group_xy access_point_group_yz
Network 2

cell_x cell_y

cell_x does not

have access to
Network 2 and
cell_z does not
have access to
Network 1

Network 1

Figure 5. Core group communication using a proxy peer access point

See “Configuring core group communication using a proxy peer access point” on page 345 for more
information.

Configuring communication between core groups that are in the same cell
Use this task to configure communication between core groups that are in the same cell.

Configure two core groups with application servers that are in the same cell. For more information about
when and how to configure multiple core groups, see “Creating a new core group” on page 303. Any time
you configure multiple core groups that are in the same cell, you must configure communication between
the core groups.

Each core group has one or more defined core group access points. A core group access point is a
collection of network entry points for the core group. The network entry points that are in a core group
access point are called bridge interfaces. An application server that hosts the bridge interfaces is called a
core group bridge server.

To configure communication between core groups, define an access point group. An access point group
defines the core groups that can communicate with each other. Each access point group has one core
group access point for each core group. Select one or more servers to be core group bridges, and define
a bridge interface for each server.

See “Core group communications using the core group bridge service” on page 328 for more information
about the core group bridge service.
1. Configure an access point group to define the core groups that need to communicate. An access point
group contains the core group access points for the core groups that need to communicate. Core
group access points define the set of servers that provide access to the core group. To configure
communication between core groups that are in the same cell, you can choose an existing access
point group or create a new access point group. To create an access point, complete the following
steps:

Chapter 3. Setting up the application serving environment 333

 a. In the administrative console, click Servers > Core groups > Core group bridge settings >
Access point groups > New.
b. Enter a name for the access point group that is unique within the cell.
c. Add core group access points to your access point group. Choose any available core group access
points for the core groups that need to communicate in the cell. A default core group access point
is created whenever a core group is created. The access point group that you create must have a
core group access point for each core group in the cell.

Restriction: Do not add any peer access points. Add peer access points only if you are configuring
communication with a core group in a different cell. If you need to communicate with core
groups that are outside of the cell, you must create another access point group that has
one core group access point and one or more peer access points. See “Configuring
communication between core groups that are in different cells” on page 338 for more
information.
If you use an existing access point group, choose an access point group that does not have peer
access points. To configure an existing access point group, perform the following steps:
a. In the administrative console, click Servers > Core groups > Core group bridge settings. Your
current configuration with any existing access point groups is displayed.
b. Verify that the access point group does not have any peer access points. Peer access point groups
are used for communication between core groups in different cells. Click the access point group
you want to configure and ensure that no peer access points are listed.
c. Click Access point groups > access_point_group_name > Core group access points.
d. Add core group access points to your access point group. Choose any available core group access
points for the core groups that need to communicate. The access point group you create should
have a core group access point for each core group in the cell.
2. Create bridge interfaces for each core group access point. The bridge interfaces that you add provide
access to the core group. Create at least one bridge interface for each core group access point. To
back up your configuration, you should configure two or more bridge interfaces for each core group
access point. If a core group has multiple core group access points, each core group access point
must contain the same number of bridge interfaces for the same set of servers. To configure bridge
interfaces, perform the following steps:
a. In the administrative console, click Servers > Core groups > Core group bridge settings >
Access point groups > access_point_group_name > Core group access points.
b. Click a core group access point in the access point group. Click Show Detail.
c. To create a new bridge interface, click Bridge interfaces > New.
d. Select a node, server, and transport channel chain combination for the bridge interface. Click OK.
All the core group access points in the access point group must have transport channel chains with
the same port name. The transport channel chain can be the DCS or DCS-secure channel chains
that are created for the DCS_UNICAST_ADDRESS transport chain.
e. Consider creating at least two bridge interfaces for each access point. If one bridge interface fails,
the other can still be active.
f. Repeat these steps to create bridge interfaces for each core group access point in your access
point group.

The core groups that are in the same cell and configured in an access point group can communicate.

In cell_x, there are three core groups: x_core_group_1, x_core_group_2, and x_core_group_3. Each core
group already has a core group access point. The following image shows an access point group between
the core groups in cell_x and an example of the configuration in the administrative console.

334 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
cell_x

core group access points

x_core_group_1 x_core_group_2

x_access_point_group

x_core_group_3

Sample configuration:
Access point groups
- x_access_point_group

- Core Group x_core_group_1

+ Core Group Access Point x_core_group_ap_1

- Core Group x_core_group_2

+ Core Group Access Point x_core_group_ap_2

- Core Group x_core_group_3

+ Core Group Access Point x_core_group_ap_3

Perform the following steps to configure communication between the three core groups in cell_x:
1. Create an access point group named x_access_point_group. Add a core group access point to the
access point group for each core group that is in the cell. In this example, add x_core_group_ap_1,
x_core_group_ap_2, and x_core_group_ap_3 to x_access_point_group.

Chapter 3. Setting up the application serving environment 335

2. Create bridge interfaces for each core group access point. The following diagram shows the bridge
interfaces for x_core_group_ap_2:

Sample configuration:
Access point groups
- x_access_point_group

+ Core Group x_core_group_1

- Core Group x_core_group_2

- Core Group Access Point x_core_group_ap_2

- Bridge Interface - node your_node_1, server your_server_1, chain DCS - Secure

Port yoursite.yourcompany.com, 9352

- Bridge Interface - node your_node_2, server your_server_2, chain DCS - Secure

Port yoursite.yourcompany.com, 9355 cell_x

+ Core Group x_core_group_3

Create two or more bridge interfaces for each core group access point.

By creating an access point group and adding all core groups in the cell to the access point group, you
enabled communication between all the core groups that are in cell_x.

You can configure this cell to communicate with core groups in other cells. See “Configuring
communication between core groups that are in different cells” on page 338 and “Configuring core group
communication using a proxy peer access point” on page 345 for more information.

Core group access point settings:

Use this page to configure your core group access points. The core group access point defines the set of
core group bridge servers that provide access to the core group. A core group bridge server is an
application server that is configured to run the core group bridge service. Define unique core group access
points for each different network over which you want the core group in this cell to connect to other core
groups that are defined in another cells. The core group access point has a collection of bridge interfaces.
Each server that is used as a bridge must have a unique bridge interface for every core group access
point in the core group.

For example if you define access points access_point_a and access_point_b and servers server_x and
server_y are configured as core group bridges in a core group, server_x must have unique bridge
interfaces for both access_point_a and access_point_b. The server_y server must also have unique bridge
interfaces for both access_point_a and access_point_b.

When a you create a core group, a core group access point is automatically created. Do not delete the
last access point in a core group.

The core group access point that is automatically defined belongs to a default access point group. You can
use the default core group access point and access point group to configure communication between core
groups. You must create and configure bridge interfaces for the default core group access point. See
“Bridge interface settings” on page 337 for more information about bridge interfaces.

336 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To access this administrative console page, click Servers > Core groups > Core group bridge settings
> Access point groups >access_point_group_name > Core group access points
>core_group_access_point_name >Show detail.

Name:

Specifies the name for the core group access point.

Core group:

Specifies the core group that is associated with this core group access point.

Core group access point collection:

Use this page to configure your set of core group access points. Core group access points define the set
of servers that provide access to the core group. At least one core group access point must be defined for
each core group in the local cell.

To access this administrative console page, click Servers > Core groups > Core group bridge settings
> Access point groups >access_point_group_name > Core group access points.

Available core group access points:

A list of core group access points that are available to add to the access point group.

Core group access points in access point group:

A list of core group access points that are in the specified access point group.

Bridge interface collection:

Each core group access point has a collection of bridge interfaces. This collection defines the interfaces
on the set of servers that provide access to the core group. All the servers in this collection have the core
group bridge service enabled. The core group bridge service provides communication between core
groups. A bridge interface defines the node, the server, and the chain for the core group access point. The
chain defines the transport channels that are used by the server for receiving information.

To access this administrative console page, click Servers > Core groups > Core group bridge settings
> Access point groups >access_point_group_name > Core group access points >access_point_name
> Show detail > Bridge interfaces.

Server:

Specifies the node and the server combinations that are bridge interfaces for the core group access point.

Chain:

Specifies the transport channel chain that is used for transport by the bridge interface. For all the core
group access points in an access point group, the transport channel chains must resolve to the same host.
To ensure that the transport channel chains resolve to the same host, use the same chain for all of the
core group access points in an access point group.

Bridge interface settings:

A bridge interface is a particular node and server that runs the core group bridge service. The core group
bridge service is the service that provides communication between core groups. A bridge interface is

Chapter 3. Setting up the application serving environment 337

defined by a unique combination of a node, server, and transport chain. You cannot configure a cluster of
servers to run the same bridge interface. A transport chain represents a network protocol stack that is
operating within an application server.

To access this administrative console page, click Servers > Core groups > Core group bridge settings
> Access point groups >access_point_group_name > Core group access points
>access_point_access_point_name > Show detail > Bridge interfaces >server_node.

Bridge interfaces: Displays a list of server, node, and chain combinations that are available to become
bridge interfaces for your core group access point.

Node: Displays the node on which the core group bridge service is running.

Server:

Displays the application server on which the core group bridge service is running. The server you select
can have other responsibilities as well as being a core group bridge server. The server does not have to
be running as a standalone node.

Chain:

Displays the transport channel chain that is used by the core group bridge service for this core group
access point. Transport channel chains contain hosts and ports. The host and port names must be
identical for all chains in all core group access points in an access point group. The transport channel
chain can be the DCS or DCS-secure channel chains that are created for the DCS_UNICAST_ADDRESS
transport chain for each application server.

Bridge interface creation:

A bridge interface specifies a particular node and server that runs the core group bridge service. A bridge
interface is defined by a unique combination of a node, a server, and a transport chain. A transport chain
represents a network protocol stack that is operating within an application server.

To access this administrative console page, click Servers > Core groups > Core group bridge settings
> Access point groups >access_point_group_name > Core group access points >access_point_name
> Show detail > Bridge interfaces > New.

Available bridge interfaces:

Specifies the node, server and transport channel chain combinations that are available to become bridge
interfaces for this core group access point. Only bridge interfaces with transport chains that contain
Transmission Control Protocol (TCP) inbound channels using the same port name as existing bridge
interfaces in this core group access point are displayed. The bridge interfaces that are already used by
any core group access point are not displayed.

Configuring communication between core groups that are in different cells

Use this task to configure core group communication between core groups that are in different cells.

A core group is a statically defined component of the high availability manager. For more information about
core groups, see “Core groups” on page 305. For this task, configure core groups that are in different
cells. For more information about when and how to create multiple core groups, see “Creating a new core
group” on page 303. Before you configure a core group to communicate outside a cell, enable core group
communication between the core groups that are within each cell. For more information, see “Configuring
communication between core groups that are in the same cell” on page 333.

338 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configure the core group bridge service between cells to share the availability status of the servers in
each core group among all the configured core groups. Enable the core group bridge service to
communicate between cells only when it is required by another WebSphere Application Server component.

The core group bridge service is a requirement when configuring an Enterprise JavaBeans (EJB) backup
cluster. Configure a backup EJB cluster in a different cell to continue servicing requests when the primary
cluster fails. See “Creating backup clusters” on page 278 for more information.

When you configure communication between core groups that are in different cells, you must configure an
access point group that has the same name in each cell. Each access point group has exactly one core
group access point and one or more peer access points. The peer access point corresponds to the core
group access point that is in the other cell. Configure one access point group between the cells. Do not
create multiple access point groups that allow communication between the same two cells.

Access point groups and access points are abstractions. Therefore, they are not considered a point of
failure. An access point fails only if all of servers fail that are specified in the bridge interfaces for that
access point. Create one or more bridge interfaces for each core group access point to prevent failure of
access point groups. See “Configuring communication between core groups that are in the same cell” on
page 333 for more details about bridge interfaces.

Create separate access point groups for each unique network over which the core groups communicate.
1. Configure an access point group that has peer access points for a core group in a different cell. You
can select an access point group or create a new access point group. To create a new access point
group perform the following steps:
a. In the administrative console, click Servers > Core groups > Core group bridge settings >
Access point groups > New.
b. Type a Name for the access point group that is unique within both of the cells.
c. Add one core group access point for the core group in the local cell. When configuring an access
point group that communicates outside of the cell, always configure exactly one core group access
point and one or more peer access points.
d. Add an existing peer access point for the core group in the remote cell.
e. Confirm the changes to save your new access point group.
To add peer access points to an existing access point group, perform the following steps:
a. In the administrative console, click Servers > Core groups > Core group bridge settings >
Access point groups > access_point_group_name > Core group access points. Check that this
access point group contains only one core group access point. You cannot configure an access
point group that communicates both inside and outside of the cell. Any access point group for core
group communication outside of the cell must contain one core group access point and one or
more peer access points.
b. Add existing peer access points or create a new peer access point. In the administrative console,
click Servers > Core groups > Core group bridge settings > Access point groups >
access_point_group_name > Peer access points. To add an existing peer access point, move the
peer access point to your access point group. To create a new peer access point, click New. The
name that you enter for the peer access point must be unique in the cell. To create new peer
access points, you must have the following configuration information for the core group in the
remote cell:
v The name of the cell for the core group
v The name of the core group
v The core group access point for that core group
v The host and port information for the core group
When you save the new peer access point, it is automatically added to your access point group.

Chapter 3. Setting up the application serving environment 339

2. Configure peer ports for each peer access point. A peer port identifies the host name and port of an
application server that is defined as a bridge interface in the other cell, so find the host name and port
information before completing this step.
a. In the administrative console, click Servers > Core groups > Core group communications >
Access point groups >access_point_group_name > Peer access points. Select a peer access
point that is in your access point group and click Show Detail.
b. Enable this peer access point to use peer ports. Select Use peer ports.
c. Configure the peer ports. Click Peer ports. You can select and remove exiting peer ports, or create
new peer ports.
Configure only one peer access point for each cell that you need to communicate with. Do not
configure multiple peer access points in one cell that correspond to the same remote cell.
3. Repeat these steps for the core group in the other cell. The access point group that you create must
have the same name as the access point group that you defined in the first cell. The peer access
points that you create in this access point group correspond to the core group access point in the first
access point group.

When you configure core groups in different cells to communicate with each other, all the core groups in
each cell receive information from the core groups in the other cells.

Following is an example of a configuration between three core groups that are in three different cells. Each
cell has one access point group for communication between core groups in the cell. Each cell also has a
defined access point group, access_point_group_xyz, which contains one core group access point group
for the core group that is in the cell, and one core group access point for each of the core groups in the
other two cells.

340 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Sample configuration in cell_x:
Access point groups
+ x_access_point_group

- access_point_group_xyz

- Core Group x_core_group_2

+ Core Group Access Point x_core_group_ap_2

- Peer Core Group y_core_group_1

+ Cell cell_y, Core Group Access Point y_core_group_ap_1

- Peer Core Group z_core_group_1

+ Cell cell_z, Core Group Access Point z_core_group_ap_1

Sample configuration in cell_y:

Access point groups
+ y_access_point_group

- access_point_group_xyz

- Core Group y_core_group_1

+ Core Group Access Point y_core_group_ap_1

- Peer Core Group x_core_group_2

+ Cell cell_x, Core Group Access Point x_core_group_ap_2

- Peer Core Group z_core_group_1

+ Cell cell_z, Core Group Access Point z_core_group_ap_1

cell_x cell_y

access_point_group_xyz

cell_z

Sample configuration in cell_z:

Access point groups
- access_point_group_xyz

- Core Group z_core_group_1

+ Core Group Access Point z_core_group_ap_1

- Peer Core Group y_core_group_1

+ Cell cell_y, Core Group Access Point y_core_group_ap_1

- Peer Core Group x_core_group_2

+ Cell cell_x, Core Group Access Point x_core_group_ap_2

The following sample shows the relationship between bridge interfaces and peer ports for the
communication between cell_x and cell_z. In cell_x, there are two bridge interfaces defined. In cell_z,

Chapter 3. Setting up the application serving environment 341

there is a peer access point for x_core_group_ap_2 that has peer ports defined that correspond to the
bridge interface information that is defined in cell_x.

Sample configuration in cell_x:

Access point groups
+ x_access_point_group

- access_point_group_xyz

- Core Group x_core_group_2

- Core Group Access Point x_core_group_ap_2

- Bridge Interface - node your_node_1, server your_server_1, chain DCS - Secure

Port yoursite.yourcompany.com, 9352

- Bridge Interface - node your_node_2, server your_server_2, chain DCS - Secure

Port yoursite.yourcompany.com, 9355

+ Peer Core Group y_core_group_1

- Peer Core Group z_core_group_1

- Cell cell_z, Core Group Access Point z_core_group_ap_1

Port zsite.yourcompany.com, 9090

Sample configuration in cell_z:

Access point groups

- access_point_group_xyz

- Core Group z_core_group_1

- Core Group Access Point z_core_group_ap_1

- Bridge Interface - node z_node_1, server z_server_1, chain DCS - Secure

Port zsite.yourcompany.com, 9090

+ Peer Core Group y_core_group_1

- Peer Core Group z_core_group_1

- Cell cell_x, Core Group Access Point x_core_group_ap_2

Port yoursite.yourcompany.com, 9352

Port yoursite.yourcompany.com, 9355

cell_x

cell_z

As a result, core_group_x , core_group_y and core_group_z can communicate with each other.

342 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Continue configuring core group communication and setting up the high availability environment. See
“Configuring the core group bridge service” on page 328 and “Setting up a high availability environment”
on page 298 for more information. To configure a backup EJB cluster, see “Creating backup clusters” on
page 278.

Peer access point settings:

Each peer access point is used to communicate with core groups in other cells. A peer access point
corresponds to a core group access point in the peer cell. The peer access point communication settings
are specified by using one or more peer end points or a proxy peer.

A peer access point must contain either peer ports or a proxy peer access point, but not both. When the
peer access point is directly accessible within its access point group, specify peer ports. When the peer
access point can be reached only indirectly, use a proxy peer access point. A proxy peer access point is
used to identify the communication settings for the peer access point that cannot be accessed directly. The
proxy peer access point specifies a peer access point that can communicate with the appropriate
destination core group. The specified proxy peer access point must be a peer access point that has
defined ports.

To view this administrative console page, click Servers > Core groups > Core group bridge settings >
Access point groups > access_point_group_name > Peer access points >peer_access_point_name >
Show detail.

Name:

Specifies the name of the peer access point. The name must be unique within the local cell.

Cell:

Specifies the cell in which the peer access point resides.

Core group:

Specifies the core group in which the peer access point resides.

Core group access point:

Specifies the name of the core group access point that is in the peer cell.

default defaultCoreGroupAccessPoint

Use peer ports:

Specifies that you are using peer ports instead of a proxy peer access point. Use peer ports when the
peer access point is directly accessible within its access point group. Click Peer ports to specify the peer
ports for the peer access point.

Use proxy peer access point:

Specifies that you are using a proxy peer access point instead of peer ports. A proxy peer is defined when
the peer access point can be reached only indirectly through another peer access point. A proxy peer is
used to identify the communication settings for the peer access point that cannot be accessed directly. The
proxy peer specifies a peer access point that can communicate with the destination core group. The
specified proxy peer must be a peer access point that has defined peer ports.

Proxy peer access point:

Chapter 3. Setting up the application serving environment 343

Specifies the specific peer access point that is used to access a core group.

Peer access point collection:

Peer access points are used to communicate with core groups that are in other cells. A peer access point
collection is the set of peer access points that are used to communicate with the core group access point
in this access point group. Specify a single peer access point for each remote cell. This collection cannot
contain two peer access points for the same cell.

To view this administrative console page, click Servers > Core groups > Core group bridge settings >
Access point groups > access_point_group_name > Peer access points.

Available peer access points:

A list of peer access points that are available to join the access point group.

Peer access points in access_point_group: A list of peer access points that are in the selected access
point group.

Peer port settings:

Use this page to define a peer port. A peer port identifies the host name and port of an application server
that is a bridge interface in another cell. This application server is using the core group bridge service to
communicate with other core groups. Each peer access point can have one or more peer ports. Each port
identifies a bridge interface of a core group bridge service in the peer cell.

To view this administrative console page, click Servers > Core groups > Core group bridge settings >
Access point groups > access_point_group_name > Peer access points > peer_access_point_name >
Show detail > Peer ports > peer_port_name.

Host:

Specifies the host name on which the core group bridge in the remote cell is listening.

Port:

Specifies the port number that is associated with the host on which the core group bridge in the remote
cell is listening.

Peer port collection:

Use this page to define the peer ports for the peer access point. Each peer port identifies a bridge
interface of a core group bridge service in the peer cell. Each peer access point that does not have a
proxy peer must have one or more peer ports.

To view this administrative console page, click Servers > Core groups > Core group bridge settings >
Access point groups > access_point_group_name > Peer access points > peer_access_point_name >
Show detail > Peer ports.

Host:

Specifies the host name that is used by the bridge interface in the remote cell.

Port:

Specifies the port that is used by the bridge interface in the remote cell.

344 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring core group communication using a proxy peer access point
Use this task to configure communication between two core groups when they cannot communicate with
each other directly through peer ports.

Configure a proxy peer access point to communicate with a core group if you cannot use peer ports. Use
a core group that has configured a peer access point with peer ports to the core group that you want to
communicate with. Before completing this task, make sure that you have access to a core group that can
communicate with the core group that you cannot communicate with directly. To configure communication
between core groups that are in different cells, see “Configuring communication between core groups that
are in different cells” on page 338. If there are multiple core groups in each of the cells, they must be
configured to communicate with each other. See “Configuring communication between core groups that
are in the same cell” on page 333 for more information.

Use a proxy peer to communicate with a core group that you cannot access directly. This task describes
how to configure a proxy peer with three core groups that are each in different cells. Core_group_x and
core_group_y can communicate directly with each other through peer ports. Core_group_y and
core_group_z can also communicate with each other though peer ports. However, core_group_x cannot
communicate with core_group_z. To establish that communication, core_group_x has a peer access point
that is a proxy peer. The proxy peer is the peer access point to core_group_y. For more information, see
“Core group communications using the core group bridge service” on page 328.
1. Configure core_group_x and core_group_y to communicate with each other by creating an access
point group. For more information, see “Configuring communication between core groups that are in
different cells” on page 338.
2. Configure core_group_y and core_group_z to communicate with each other by creating another access
point group. For more information, see “Configuring communication between core groups that are in
different cells” on page 338. When you do this step, create a second access point group in cell 2.
Core_group_2 communicates with both cell_x and cell_z over two different networks.
3. Configure a peer access point that has a proxy peer. Create a new peer access point in the access
point group that you created between core_group_x and core_group_y.
a. In the administrative console, click Servers > Core groups > Core group bridge settings >
Access point groups >access_point_group_name> Peer access points. Create a new peer
access point, or select an existing access point.
b. Enter a unique name for the peer access point. For the other cell, core group, and core group
access point values, use the properties of core_group_z.
c. Click Use a proxy peer access point. Select the proxy peer access point that is the peer access
point that you created in cell_x that refers to the core group access point in cell_y.

Core_group_x can communicate with core_group_z by using a proxy peer.

The following example shows the configurations in each cell when you configure communication between
cell_x and cell_z using a proxy peer access point:

Chapter 3. Setting up the application serving environment 345

 cell_z

Sample proxy peer configuration

cell_x cell_y

Sample configuration in cell_z:

Access point groups

- access_point_group_yz

- Core Group z_core_group_1

+ Core Group Access Point z_core_group_ap_1

- Peer Core Group y_core_group_1

+ Cell cell_y, Core Group Access Point y_core_group_ap_1

Sample configuration in cell_y:

Access point groups
+ y_access_point_group

- access_point_group_xy

- Core Group y_core_group_1

+ Core Group Access Point y_core_group_ap_1

- Peer Core Group x_core_group_2

+ Cell cell_x, Core Group Access Point x_core_group_ap_2

- access_point_group_yz

- Core Group y_core_group_1

+ Core Group Access Point y_core_group_ap_1

- Peer Core Group z_core_group_1

+ Cell cell_z, Core Group Access Point z_core_group_ap_1

Sample configuration in cell_x:

Access point groups

+ x_access_point_group

- access_point_group_xy

- Core Group x_core_group_2

+ Core Group Access Point x_core_group_ap_2

- Peer Core Group y_core_group_1

+ Cell cell_y, Core Group Access Point y_core_group_ap_1

- Peer Core Group z_core_group_1

Proxy peer core group y_core_group_1

By completing this task, you enabled one-way communication between core_group_x and core_group_z. If
you want to configure communication both ways, you must repeat these steps, configuring a peer access
point in core_group_z that contains a proxy peer.

346 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Core group communication
The core group bridge is the service that enables communication between core groups. A core group is a
statically defined component of the high availability manager. Use this page to view the structure of your
access point groups. Access point groups link core groups that are in the same cell or in different cells and
allow the core groups to communicate with each other.

To view this administrative console page, click Servers > Core groups > Core group bridge settings.

Each access point group is a collection of core group access points. If you are configuring communication
between core groups that are in the same cell, configure an access point group with a core group access
point for each core group in the cell. If you are configuring communication between core groups in different
cells, configure an access point group that has one core group access point for the local cell and a peer
access point for each other cell.

Each core group access point has one or more bridge interfaces. Each peer access point has a proxy
peer or one or more peer ports. A bridge interface is a server that is configured to communicate with other
core groups by using a particular transport channel chain. Click Access point groups to configure the
settings for each access point group that is configured.
v Access point group - An access point group defines the core groups that communicate with each
other. Each access point group consists of a collection of core groups.
– Core group - Specifies a core group that is in this access point group. Core groups are referenced
by core group access points.
- Core group access point - The core group access point defines the set of servers that provide
access to the core group. Bridge interfaces define the servers that are in the core group access
point.
v Bridge interface - A bridge interface defines a node, server, and chain for the core group
access point. The chain defines the transport channels that the server uses for receiving
information. Typically, all the bridge interfaces in a core group access point use the same chain.
– Peer core group - Specifies a core group in a different cell. Define peer access points to
communicate with peer core groups.
- Peer access point - Each peer access point is used to communicate a core group in a different
cell. Each peer access point corresponds to a core group access point that is in the peer cell. Use
one or more peer ports or one proxy peer to define the communication settings.
v Peer port - Each peer port identifies a bridge interface of a core group bridge in the peer cell.
v Proxy peer - A proxy peer is used to identify the communication settings for a peer access
point that cannot be accessed directly through peer ports. A proxy peer specifies a peer access
point that can communicate with the destination core group. The specified proxy peer must be a
peer access point that has defined ports.

Access point group collection

Use this page to view the sets of access point groups. Access point groups define the set of core groups
that communicate with each other. Access point groups that connect multiple cells must have one core
group access point and a single peer access point for each remote cell. Access point groups that provide
communications between core groups in the same cell must contain only core group access points.

To view this administrative console page, click Servers > Core groups > Core group bridge settings >
Access point groups.

Name:

Specifies the name of the access point group. The access point group name must be unique within the
cell.

Chapter 3. Setting up the application serving environment 347

Access point group settings
Use this page to modify the core group access points and the peer access points that belong to this
access point group. An access point group defines the set of core groups that communicate with each
other. Group the access points to support communication. Access points can be either peer access points
or core group access points. Define core group access points so that core groups in the same cell can
communicate. Define peer access points so that core groups in different cells can communicate.

To view this administrative console page, click Servers > Core groups > Core group bridge settings >
Access point groups >access_point_group_name.

From this page, you can edit the core group access points or the peer access points that belong to the
access point group.

Name:

Specifies the name of the access point group. The access point name must be unique within a cell.

348 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 4. Using the administrative clients
The product provides a variety of administrative clients for deploying and administering your applications
and application serving environment, including configurations and logical administrative domains.
v “Using the administrative console”
The administrative console is a graphical, browser-based tool.
v “Getting started with scripting” on page 365
Scripting is a non-graphical alternative that you can use to configure and administer your applications
and application serving environment. The WebSphere Application Server wsadmin tool provides the
ability to run scripts. The wsadmin tool supports a full range of product administrative activities.
v “Using Ant to automate tasks” on page 809
To support using Apache Ant with Java 2 Platform, Enterprise Edition (J2EE) applications running on
IBM WebSphere Application Server, the product provides a copy of the Ant tool and a set of Ant tasks
that extend the capabilities of Ant to include product-specific functions.
v “Using administrative programs (JMX)” on page 810
The product supports access to the administrative functions through a set of Java classes and methods,
under the Java Management Extensions (JMX) specification. You can write a Java program that
performs any of the administrative features of the other administrative clients. You also can extend the
basic product administrative system to include your own managed resources.
v “Using command line tools” on page 852
Several command-line tools are available that you can use to start, stop, and monitor WebSphere
server processes and nodes. These tools work on local servers and nodes only. They cannot operate
on a remote server or node.

Using the administrative console

The administrative console is a Web-based tool that you use to manage the IBM WebSphere Application
Server product as well as the Network Deployment product. The administrative console supports a full
range of product administrative activities.
1. Distributed platforms: Start the server for the administrative console.For the Network Deployment
product, the administrative console belongs to the deployment manager (dmgr) process, which you
start with the startmanager command.
2. Access the administrative console.
3. Change the session timeout for the administrative console. (Optional)
4. Browse the administrative console.
5. Specify console preferences.
6. Access help.

Starting and stopping the administrative console

This topic describes how to set up the administrative console environment, to access the administrative
console, and to log out of the administrative console.

To access the administrative console, you must start it and then log in. After you finish working in the
console, save your work and log out.
1. Start the administrative console.
a. Distributed platforms: Verify that the administrative console runs on the server1 application server
for the WebSphere base product. Verify that the administrative console runs on the deployment
manager for the Network Deployment product. Use the wasadmin startManager command to start
the deployment manager.

© Copyright IBM Corp. 2004 349

 b. Enable cookies in the Web browser that you use to access the administrative console for the
administrative console to work correctly.
c. Distributed platforms: In the same Web browser, type
http://your_fully_qualified_server_name:9060/ibm/console, where
your_fully_qualified_server_name is the fully qualified host name for the machine that contains the
administrative server. When the administrative console is on the local machine,
your_fully_qualified_server_name can be localhost unless security is enabled. On Windows
platforms, use the actual host name if localhost is not recognized. If security is enabled, your
request is redirected to https://your_fully_qualified_server_name:9043/ibm/console, where
your_fully_qualified_server_name is the fully qualified host name for the machine that contains the
administrative server.
For a listing of supported Web browsers, see WebSphere Application Server system requirements
at
http://www.ibm.com/software/webservers/
appserv/doc/latest/prereq.html
The Web address appears on two lines for printing purposes. Enter the Web address on one line in
your browser.
d. Wait for the console to load into the browser. A Login page is displayed after the console starts.
If you cannot start the administrative console because the console port conflicts with an application
that is already running on the machine, change the port number in the install_root/profiles/profile
name/config/cells/cell_name/ nodes/node_name/servers/server_name/server.xml file and the
install_root/profiles/profile name/config/cells/cell_name/virtualhosts.xml files. Change all the
occurrences of port 9060 (or the port that is selected during profile creation for WebSphere Application
Server) to the port for the console. Alternatively, shut down the other application that uses the
conflicting port before starting the WebSphere Application Server product.
2. Log into the console.
a. Enter your user name or user ID.
The user ID lasts only for the duration of the session for which it was used to log in.
Changes made to server configurations are saved to the user ID. Server configurations also are
saved to the user ID if a session timeout occurs.
If you enter an ID that is already in use (and in session), you are prompted to do one of the
following actions:
v Force the existing user ID out of session. The configuration file that is used by the existing user
ID is saved in the temporary area.
v Wait for the existing user ID to log out or time out of the session.
v Specify a different user ID.
b. If the console is secure, you must also enter a password for the user name. The console is secure
if someone has taken the following actions for the console:
v Specified security user IDs and passwords
v Enabled global security
c. Click OK.
3. Stop the administrative console. Click System administration > Save changes to Master Repository
> Save to save work. Then click Logout to exit the console.
If you close the browser before saving your work, when you next log in under the same user ID, you
can recover any unsaved changes.

Login settings
Use this page to specify the user for the WebSphere Application Server administrative console. If you are
using global security, then you must also specify a password.

When you specify a user, you can resume work done previously with the product. After you type in a user
ID, and password if you are using global security, click OK to proceed to the next page and access the
administrative console.
350 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this page, start the administrative console.

Logging into the administrative console: When you log into the administrative console, you can
optionally specify a user ID if the console is not secure. If the administrative console is secure, you must
specify a user ID and password.

User ID

Specifies a string that identifies the user. The user ID must be unique to the administrative server.
Concurrent administrative console sessions must use unique user IDs.

Work that you do with the product and then save before exiting the product is saved to a configuration that
is identified by the user ID that you enter. To later access work done under that user ID, specify the same
user ID in the Login page.

Data type String

Password

If you use global security, specify a password.

Resolving conflicts during login: Conflicts can result if you log into the administrative console with a
user ID that is already in use.

Another user is currently logged in with the same user name

Specifies whether to log out the user and to continue work with the user ID that is specified, or to return to
the Login page and specify a different user ID, or wait for the user to log out.

This field is displayed if:

v The user closed a Web browser while browsing the administrative console and did not first log out, then
opened a new browser and tried to access the administrative console with the same user ID.
v The user opened a Web browser to access the administrative console while accessing the
administrative console in another open Web browser with the same user ID.
v The user opens a Web browser and attempts to log into the console with the same user ID that is
already in use by another user who logged into the console from another Web browser on another
computer.

Recovering prior changes: You can either recover changes that you made to the configuration from a
prior session or use the master configuration. The default is to recover changes from a prior session.

Recover changes made in a prior session

When enabled, this setting specifies that you want to use the same administrative configuration used for
the last user’s session. This option recovers changes made by the user since the last saving of the
administrative configuration for the user’s session.

This field is displayed only if the user changed the administrative configuration and then logged out without
saving the changes.

Work with the master configuration

When enabled, this setting specifies to use the default administrative configuration instead of the
configuration that was last used for the user’s session. Changes that are made to the user’s session since
the last saving of the administrative configuration are lost.

Chapter 4. Using the administrative clients 351

This field is displayed only if the user changed the administrative configuration and then logged out without
saving the changes.

Resolving login failures: When the administrative console is enabled with global security, you must type
in a valid user ID and password. If the user ID, password, or both are not valid, you receive the following
message:
Unable to process login. Please check User ID and password and try again.

Resolve the problem by entering a valid user ID and password as defined in the WebSphere Application
Server security documentation.

Save changes to the master configuration

Use this page to update the master repository with your administrative console changes, to discard your
administrative console changes and continue working with the master repository, or to continue working
with your administrative console changes that are not saved to the master repository.

Until you save changes to the master repository, the administrative console uses a local workspace to
track your changes.

Total changed documents: Specifies the total number of documents that you changed for your session,
but that are not saved to the master repository. By clicking the +/- toggle key, you can see additional
information about the changed documents:
v Changed items
When you change your local configuration, each path and configuration file that you can apply the
update to in the master repository is displayed in the list.
v Status
Can contain the following options:
– Added: If you save your changes to the master repository, a new configuration file is created on the
indicated path.
– Updated: If you save your changes to the master repository, an existing configuration file is updated
on the indicated path.
– Deleted: If you save your changes to the master repository, an existing configuration file is deleted
on the indicated path.

Synchronize changes with nodes: Specifies whether you want to force node synchronization at the
time that you save your changes to the master repository rather than when node synchronization normally
occurs.

Setting the session timeout for the administrative console

This topic describes how to change the session timeout from the default value for the administrative
console.

Ensure that you have the proper permissions to change the

${WAS_HOME}/systemApps/adminconsole.ear/deployment.xml file.

Determine whether the default session timeout value of 30 minutes is acceptable. Some reasons that you
might change the default value are:
v Users in secure environments might need shorter session timeout periods to ensure security, encase
they leave their machine and forget to log off the console.
v Users might need longer session timeout periods if they respond slower than typical users for
accessibility reasons.
v Users in secure environments might not want the administrative console timeout value to conflict with
Lightweight Third-Party Authentication (LTPA) cookie timeouts

352 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Do the following actions to change the timeout value:
1. Edit the ${WAS_HOME}/systemApps/adminconsole.ear/deployment.xml file in a text editor.
2. Locate the xml statement <tuningParams xmi:id="TuningParams_1088453565469"
maxInMemorySessionCount="1000" allowOverflow="true" writeFrequency="TIME_BASED_WRITE"
writeInterval="10" writeContents="ONLY_UPDATED_ATTRIBUTES" invalidationTimeout="30">
3. Change the invalidationTimeout value to the desired session timeout. The default is 30.
4. Save the ${WAS_HOME}/systemApps/adminconsole.ear/deployment.xml file.
5. Restart the console.

Once you restart the console, the change takes effect.

Manage WebSphere Application Server through the administrative console.

Administrative console areas

Use the administrative console to create and manage objects in the WebSphere Application Server
configuration such as resources, applications, and servers. Additionally, use the administrative console to
view product messages. This topic describes the main areas that display on the administrative console.

To view the administrative console, ensure that the application server for the administrative console is
running. Point a Web browser at the Web address for the administrative console, enter your user ID and, if
needed, a password on the Login page.

You can resize the width of the navigation tree and workspace simultaneously by dragging the border
between them to the left or the right. The change in width does not persist between administrative console
user sessions.

The console has the following main areas.

Taskbar
The taskbar offers options for logging out of the console, accessing product information, and accessing
support.

Navigation tree
The navigation tree on the left side of the console offers links to console pages that you use to create and
manage components in a WebSphere Application Server administrative cell.

Click a plus sign (+) beside a tree folder or item to expand the tree for the folder or item. Click a minus
sign (-) to collapse the tree for the folder or item. Click an item in the tree view to toggle its state between
expanded and collapsed.

Workspace
The workspace on the right side of the console contains pages that you use to create and manage
configuration objects such as servers and resources. Click links in the navigation tree to view the different
types of configured objects. Within the workspace, click configured objects to view their configurations,
run-time status, and options. Click Welcome in the navigation tree to display the workspace Home page,
which contains links to information on using the WebSphere Application Server product.

Administrative console buttons

This page describes the button choices that are available on various pages of the administrative console,
depending on which product features you enable.
v Check all. Selects each resource that is listed on the administrative console panel, in preparation for
performing an action against the selected resources.
v Uncheck all. Removes all the listed resources from each selection so that no action is performed
against any of the resources.

Chapter 4. Using the administrative clients 353

v Filter the view. Produces a dialog box for specifying the resources to view in the table on this
administrative console page.
Hide the filter view. Hides the dialog box for specifying the resources to view in the table on this
administrative console page.
When you produce the dialog box, select the column to filter and enter the filter criteria.
Column to filter
Select the column to filter from the drop-down list. When you apply the filter, only those items in
the selected column that meet the filter criteria are displayed.
For example, select Names to enter criteria by which to filter application server names.
Filter criteria
Enter a string that must be found in the name of a collection entry to qualify the entry to display
in the collection table. The string can contain percent sign (%), asterisk (*), or question mark (?)
symbols as wildcard characters. For example, enter *App* to find any application server whose
name contains the string App.
Prefix each of the following characters ( ) ^ * % { } \ + $ with a backslash (\) so that the
regular expression engine performing the search correctly matches the search criteria. For
example, to search for all Java DataBase Connectivity (JDBC) providers containing (XA) in the
provider name, specify the following string:
*\(XA\)
v Clear filter criteria. Clears your filter changes and restores the most recently saved values.
v Abort. Stops a transaction that is not yet in the prepared state. All operations that the transaction
completed are undone.
v Activate. Activates a group member.
v Add. Adds the selected or typed item to a list, or produces a dialog for adding an item to a list.
v Add Node. Displays the Add Node page, in which you specify the host name and SOAP connector port
for a node that you want added to a cell.
v Apply. Saves your changes to a page without exiting the page.
v Back. Displays the previous page or item in a sequence. The administrative console does not support
using the Back and Forward options of a browser, which can cause intermittent problems. Use Back or
Cancel on the administrative console panels instead.
v Balance. Balances active members in high availability groups across servers that host the high
availability groups. The administrator must first determine which groups have active members and select
those groups before selecting Balance.
v Browse. Opens a dialog that enables you to look for a file on your system.
v Calculate groups. Calculates the number of high availability groups that are returned based on the
match set.
v Cancel. Exits the current page or dialog, discarding unsaved changes. The administrative console does
not support using the Back and Forward options of a browser, which can cause intermittent problems.
Use Cancel on the administrative console panels instead.
v Change. In the context of security, you can search the user registry for a user ID for an application to
run under. In the context of container properties, you can change the data source that the container is
using.
v Clear. Clears your changes and restores the most recently saved values.
v Clear selections. Clears any selected cells in the tables on this tabbed page.
v Close. Exits the dialog.
v Commit. Releases all locks that are held by a prepared transaction and forces the transaction to
commit.
v Copy. Creates copies of the selected application servers.
v Create. Saves your changes to all the tabbed pages in a dialog and exits the dialog.
v Create tables. Develops scheduler database tables.
v Deactivate. Deactivates a group member. The group member must be in the active state to be
deactivated. The deactivate option causes the group member to move to the idle state. The group policy

354 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 overrides which members are activated and deactivated for a group. The policy is enforced for every
member state change. If the deactivate option conflicts with the group policy, the policy resets who is
the active member of the group.
v Delete. Removes the selected instance.
v Details. Shows the details about a transaction.
v Disable. Disables a group or group member. When you disable a group or group member, the active
group or group member is first deactivated. If the deactivate option is successful, the group or group
member moves to the disable state. A disabled group or group member cannot be activated.
v Done. Saves your changes to all the tabbed pages in a dialog and exits the dialog.
v Down. Moves through a list.
v Drop tables. Removes scheduler database tables.
v Dump. Activates a dump of a traced application server.
v Edit. Lets you edit the selected item in a list, or produces a dialog box for editing the item.
v Enable. Enables a group or a group member.
v Export. Accesses a page for exporting enterprise archive (EAR) files for an enterprise application.
v Export DDL. Accesses a page for exporting data definition language (DDL) files for an enterprise
application.
v Export Keys. Exports Lightweight Third-Party Authentication (LTPA) keys to other domains.
v Export route table. Exports the route table information for a selected cluster to a binary file in the
configuration.
v Filter. Produces a dialog box for specifying the resources to view in the tables on this tabbed page.
v Finish. Forces a transaction to finish, regardless of whether its outcome has been reported to all
participating applications.
v First. Displays the first record in a series of records.
v Full resynchronize. Synchronizes the user’s configuration immediately. Click full resynchronize on the
Nodes page if automatic configuration synchronization is disabled, or if the synchronization interval is
set to a long time, and a configuration change is made to the cell repository that needs to be replicated
to that node. Clicking this option clears all synchronization optimization settings and performs
configuration synchronization again, so no mismatches occur between node and cell configuration after
this operation is performed. This operation can take awhile to perform.
v Force delete. Forces the removal of a node that is not removed properly from the cell in the master
repository. The Remove node action is preferred over the Force delete action to delete a node from
the configuration. If you click Force delete, but the node still exists in the configuration, uninstall the
node or run the removeNode command by using the -force parameter on that node. Force delete
action is equivalent to running the cleanupNode command at the deployment manager.
v Generate keys. Generates new LTPA keys. When security is turned on for the first time with LTPA as
the authentication mechanism, LTPA keys are automatically generated with the password entered in the
panel. To generated new keys, use this option after the server is up with security turned on. Clicking this
option generates the keys and propagates them to all active servers (cell, node, and application
servers). The new keys can be used to encrypt and decrypt the LTPA tokens. Click Save on the console
taskbar to save the new keys and the password in the repository.
v Immediate stop. Stops the server, but bypasses the normal server quiesce process that supports
in-flight requests to complete before shutting down the entire server process. This shutdown mode is
faster than the normal server stop processing, but some application clients can receive exceptions.
v Import keys. Imports new LTPA keys from other domains. To support single signon (SSO) in
WebSphere Application Server across multiple WebSphere domains (cells), share LTPA keys and a
password among the domains. After exporting the keys from one of the cells into a file, click this option
to import the keys into all the active servers (cell, node, and application servers). The new keys can be
used to encrypt and decrypt the LTPA token. Click Save on the console taskbar to save the new keys
and the password in the repository.
v Install. Displays the Preparing for application installation page, which you use to deploy an application,
an enterprise bean, or a Web component onto an application server.
v Install RAR. Opens a dialog that is used to install a Java 2 Platform, Enterprise Edition Connector
Architecture (JCA) connector and to create a resource adapter.
v Manage transactions. Displays a list of active transactions running on a server. You can forcibly finish
any transaction that has stopped processing because a transactional resource is not available.

Chapter 4. Using the administrative clients 355

v Modify. Opens a dialog that is used to change a specification.
v Move. Moves the selected application servers to a different location in the administrative cell. When
prompted, specify the target location.
v Move down. Moves downward through a list.
v Move up. Moves upward through a list.
v New. Displays a page that you use to define a new instance. For example, clicking New on the
Application Servers page displays a page on which you can configure a new application server.
v Next. Displays the next page, frame, or item in a sequence.
v OK. Saves your changes and exits the page.
v Ping. Attempts to contact selected application servers.
v Previous. Displays the previous page, frame, or item in a sequence.
v Quit. Exits a dialog box and discards any unsaved changes.
v Refresh. Refreshes the view of data for instances that are currently listed on this tabbed page.
v Regenerate encryption key. Regenerates a key for global data replication. If you are using the DES or
TRIPLE_DES encryption type, regenerate a key at regular intervals (for example, monthly) to enhance
security.
v Remove. Deletes the selected item.
v Remove file. Removes the specified file from the selected application or module.
v Remove node. Deletes the selected node.
v Reset. Clears your changes on the tab or page and restores the most recently saved values.
v Restart. Stops the selected objects and starts them again.
v Restart all servers on node. Stops all application servers on the node and starts them again.
v Retrieve new. Retrieves a new record.
v Rollout update. Sequentially updates an application that is installed on multiple cluster members
across a cluster. After you update application files or a configuration, click Rollout update to install the
configuration or the updated files for an application on all the cluster members of a cluster on which the
application is installed. The Rollout update option applies the following steps to each cluster member in
sequence:
1. Saves an updated configuration.
2. Stops the cluster member.
3. Updates the application on the node by synchronizing the configuration.
4. Restarts the cluster member.
This action enables you to update an application on multiple cluster members while providing
continuous availability of the application.
v Save. Saves the changes in your local configuration to the master configuration.
v Select. For resource analysis, lets you select a scope in which to monitor resources.
v Set. Saves your changes to settings in a dialog.
v Settings. Displays a dialog for editing servlet-related resource settings.
v Settings in use. Displays a dialog showing the settings in use.
v Show groups. Displays a collection of high availability groups, based on the match set.
v Show servers. Displays a collection of servers that are contained in the high availability groups that
match the match set.
v Start. In the context of application servers, starts selected application servers. In the context of data
collection, starts collecting data for the tables on this tabbed page.
v Stop. In the context of server components such as application servers, stops the selected server
components. In the context of a data collection, stops collecting data for the tables on a tabbed page. In
the context of nodes, stops servers on the selected nodes. In the context of deployment managers,
stops the deployment manager server.
v Synchronize. Synchronizes the user’s configuration immediately. Click Synchronize on the Nodes page
if automatic configuration synchronization is disabled, or if the synchronization interval is set to a long
time, and a configuration change is made to the cell repository that needs replicating to that node. A
node synchronization operation is performed using the normal synchronization optimization algorithm.
This operation is fast, but might not fix problems from manual file edits that occur on the node. It is
possible for the node and cell configuration to be out of synchronization after this operation is
performed. If problems persist, use Full Resynchronize.

356 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Terminate. Deletes the Application Server process or another process that cannot be stopped by the
Stop or Immediate Stop commands. Some application clients can receive exceptions. Always attempt
an immediate stop before using this option.
v Test connection After you define and save a data source, you can select this option to ensure that the
parameters in the data source definition are correct. On the Collection panel, you can select multiple
data sources and test them simultaneously.
v Uninstall. Deletes a deployed application from the WebSphere Application Server configuration
repository. Also deletes application binary files from the file system.
v Update. Replaces an application that is deployed on a server with an updated application. As part of
the updating, you might need to complete steps on the Preparing for application installation and Update
application pages.
v Update resource list. Updates the data on a table. Discovers and adds new instances to the table.
v Use cell CSI. Enables Object Management Group (OMG) Common Secure Interoperability (CSI)
protocol.
v Use cell SAS. Enables IBM Secure Authentication Service (SAS).
v Use cell Security. Enables cell security.
v Verify tables. Validates the mapping between the table names, scheduler resource, and data sources.
v View. Opens a dialog on a file.

Administrative console page features

This topic provides information about the basic elements of an administrative console page, such as the
various tabs.

Administrative console pages are arranged in a few basic patterns. Understanding their layout and
behavior will help you use them more easily.

Collection pages

Use collection pages to manage a collection of existing administrative objects. A collection page typically
contains one or more of the following elements:
Scope and Preferences
These are described in “Administrative console scope settings” on page 361 and “Administrative
console preference settings” on page 361.
Table of existing objects
The table displays existing administrative objects of the type specified by the collection page. The
table columns summarize the values of the key settings for these objects. If no objects exist yet,
an empty table is displayed. Use the available buttons to create a new object.
Buttons for performing actions
The available buttons are described on the Administrative console buttons help panel. In most
cases, you need to select one or more of the objects in the table, then click a button. The action
will be applied to the selected objects.
Sort toggle buttons
Following column headings in the table are icons for sort ascending (^) and sort descending (v).
By default, items such as names are sorted in descending order (alphabetically). To enable
another sorting order, click on the icons for the column whose items you want sorted.

Detail pages

Use detail pages to configure specific administrative objects, such as an application server. A detail page
typically contains one or more of the following elements:
Configuration tabbed page
This tabbed page is for modifying the configuration of an administrative object. Each configuration
page has a set of general properties specific to the administrative object. Other sets of properties
display on the page, but vary depending on the administrative object.

Chapter 4. Using the administrative clients 357

Runtime tabbed page
This tabbed page displays the configuration that is currently in use for the administrative object. It
is read-only in most cases. Some detail pages do not have runtime tabs.
Local Topology tabbed page
This tabbed page displays the topology that is currently in use for the administrative object. View
the topology by expanding and collapsing the different levels of the topology. Some detail pages
do not have local topology tabs.
Buttons for performing actions
Buttons to perform specific actions display on the configuration tabbed page and the runtime
tabbed page. The displayed buttons vary based on the administrative object. The available buttons
are described on the Administrative console buttons help panel.

Wizard pages

Use wizard pages to complete a configuration process comprised of several steps. Be aware that wizards
show or hide certain steps depending on the characteristics of the specific object you are configuring.

Administrative console navigation tree actions

Use the navigation tree of the administrative console to access pages for creating and managing servers,
applications, resources, and other components.

To view the navigation tree, go to the WebSphere Application Server administrative console and look at
the tree on the left side of the console. The tree provides navigation to configuration tasks and run-time
information. The main topics available on the navigation tree are detailed in the following section. To use
the tree, expand a main topic and select an item from the expanded list to display a page on which you
can perform the administrative task.

Servers:

Configure application servers, clusters, generic servers, Web servers, and core groups.

Applications:

Install applications onto servers and manage the installed applications.

Resources:

Configure resources and to view information on resources that exist in the administrative cell.

Security:

Access the Security Center, which you use to secure applications and servers.

Environment:

Configure hosts, WebSphere Application Server variables, and other components.

System Administration:

Configure console settings, and manage components and users of a Network Deployment product.

Troubleshooting:

Check for configuration errors and problems, view log files, and enable and disable tracing on a distributed
platform.

Monitoring and Tuning:

358 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Monitor and tune your Application Server performance and analyze performance data.

Service Integration:

Iimplement message-oriented and service-oriented applications.

UDDI:

Publish and discover information about Web services.

Administrative console taskbar actions

Use the taskbar of the administrative console to log out of the administrative console and to access the
console help.

To view the taskbar, go to the WebSphere Application Server administrative console and look at the
horizontal bar near the top of the console. The taskbar provides the following actions.

Logout: Logs you out of the administrative console session and displays the Login page. If you made
changes to the administrative configuration since last saving the configuration to the master repository, the
Save page is displayed before returning to the Login page.
v Click Save to save the changes to the master repository.
v Click Discard to exit the session without saving changes.
v Click Logout to exit the session without saving changes but with the opportunity to recover your
changes when you return to the console.

Help: Opens a new Web browser to online help for the WebSphere Application Server product.

Support: Displays support links that vary based on the products that extend the WebSphere Application
Server. Use the support page to access product information such as Frequently Asked Questions (FAQs),
technical notes (Technotes), hints and tips, and news. You can additionally install the Support Advisor
Search application so that when you click on the support link, a new Web browser that contains the
Support Advisor Search application opens. The Support Advisor Search application displays the support
links on the support page, but additionally provides federated search capabilities into IBM knowledge
databases.

Specifying console preferences

Use this topic to customize how much data displays on an administrative console panel.

Throughout the administrative console are pages that have Preferences fields, Scope fields, and Filter
radio buttons. By selecting these fields and radio buttons you can customize how much data is shown.

For example, examine the Preferences field for the Enterprise Applications page:
1. Go to the navigation tree of the administrative console and click Applications > Enterprise
Applications.
2. Expand Preferences.
3. For the Maximum rows field, specify the maximum number of rows to display when the collection is
large. The default is 20. Rows that exceed the maximum number display on subsequent pages.
4. Select Retain filter criteria if you want to retain the last filter criteria that is entered in the filter
function. When you return to the Applications page, the page initially uses the retained filter criteria to
display the collection of applications in the table following the preferences. Otherwise, clear Retain
filter criteria and the last filter criteria is not retained.
5. Click Apply to apply your selections or click Reset to return to the default values. The default is not to
enable (not have a check mark beside) Retain filter criteria.

Chapter 4. Using the administrative clients 359

Other pages have similar fields and radio buttons that you can use to specify console preferences. While
Preferences fields, Scope fields, and Filter buttons control how much data is shown in the console, the
Preferences option controls general behavior of the console. Click System administration > Console
settings > Preferences to view the Preferences page.

Preferences settings
Use the Preferences page to specify whether you want the administrative console workspace to refresh
automatically after changes, the default scope to be the administrative console node, confirmation dialogs
to display, and the workspace banner and descriptions to display.

To view this administrative console page, click System administration > Console settings >
Preferences.

Turn on workSpace auto-refresh:

Specifies whether you want the administrative console workspace to redraw automatically after the
administrative configuration changes.

The default is for the workspace to redraw automatically. If you direct the console to create a new instance
of, for example, an application server, the Application Servers page refreshes automatically and shows the
new server name in the collection of servers.

Specifying that the workspace not redraw automatically means that you must access a page again by
clicking the console navigation tree or links on collection pages to see the changes that are made to the
administrative configuration.

Default true (selected)

No confirmation on workspace discard:

Specifies whether the confirmation dialog is displayed after a request is receive to discard the workspace.
The default is to display confirmation dialogs.

Default false (cleared)

Use default scope (administrative console node):

Specifies whether the default scope is the administrative console node. The default scope not is not the
console node.

Default false (cleared)

Show banner:

Specifies whether the WebSphere Application Server banner along the top of the administrative console is
displayed. The default is for the banner to display.

Default true (selected)

Show Descriptions:

Specifies whether information on the right of the console is shown. The default is to show the information.

Data type Boolean

360 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Default true

Administrative console preference settings

Use the preference settings to specify how you want information displayed on an administrative console
page.

Maximum rows: Indicates the maximum number of rows to display per page when the collection is large.

Filter history: Indicates whether to use the same filter criteria to display this page the next time you visit
it.

Select the Retain filter criteria check box to retain the last filter criteria entered. When you return to the
page, retained filter criteria control the application collection that is displayed n the table.

Show confirmation for stop command: Select the check box if you want a confirmation that the stop
command is successful.

Show confirmation for immediate stop command: Select the check box if you want a confirmation that
the immediate stop command is successful.

Show confirmation for terminate command: Select the check box if you want a confirmation that the
terminate command is successful.

Administrative console scope settings

Use this page to specify the level at which a resource is visible on the administrative console panel. A
resource can be visible in the administrative console collection table at the cell, node, cluster, or server
scope. By changing the value for Scope you can see other variables that apply to a resource and might
change the contents of the collection table.

Click Browse next to a field to see choices for limiting the scope of the field. If a field is read-only, you
cannot change the scope. For example, if only one server exists, you cannot switch the scope to a
different server.

You always create resources at the current scope that is selected in the administrative console panel,
even though the resources might be visible at more than one scope.

Resources such as JDBC providers, namespace bindings, or shared libraries can be defined at multiple
scopes. Resources that are defined at more specific scopes override duplicate resources that are defined
at more general scopes.
v The application scope has precedence over all the scopes.
v The server scope has precedence over the node, cell, and cluster scopes.
v The cluster scope has precedence over the node and cell scopes.
v The node scope has precedence over the cell scope.

Despite the scope of a defined resource, the resource properties only apply at an individual server level.
For example, if you define the scope of a data source at the cell level, all the users in that cell can look up
and use that data source, which is unique within that cell. However, resource property settings are local to
each server in the cell. For example, if you define the maximum connections as 10, then each server in
that cell can have 10 connections.

The cell scope is the most general scope and does not override any other scope. The recommendation is
that you generally specify a more specific scope than the cell scope. When you define a resource at a

Chapter 4. Using the administrative clients 361

more specific scope, you provide greater isolation for the resource. When you define a resource at a more
general scope, you provide less isolation. Greater exposure to cross-application conflicts occur for a
resource that you define at a more general scope.
Cell Limits the visibility to all servers on the named cell. The resource factories within the cell scope
are:
v Defined for all servers within this cell
v Overridden by any resource factories that are defined within application, server, cluster and
node scopes that are in this cell and have the same Java Naming and Directory Interface
(JNDI) name
The resource providers that are required by the resource factories must be installed on every node
within the cell before applications can bind or use them.
Cluster
Limits the visibility to all the servers on the named cluster. All cluster members must at least be at
Version 6 to use cluster scope for the cluster. The resource factories that are defined within the
cluster scope:
v Are available for all the members of this cluster to use
v Override any resource factories that have the same JNDI name that is defined within the cell
scope
The resource factories that are defined within the cell scope are available for this cluster to use, in
addition to the resource factories, that are defined within this cluster scope.
Node Limits the visibility to all the servers on the named node. The node scope is the default scope for
most resource types. The resource factories that are defined within the node scope:
v Are available for servers on this node to use
v Override any resource factories that have the same JNDI name defined within the cell scope
The resource factories that are defined within the cell scope are available for servers on this node
to use, in addition to the resource factories that are defined within this node scope.
Server
Limits the visibility to the named server. The server scope is the most specific scope for defining
resources. The resource factories that are defined within the server scope:
v Are available for applications that are deployed on this server
v Override any resource factories that have the same JNDI name defined within the node and cell
scopes
The resource factories that are defined within the node and cell scopes are available for this
server to use, in addition to the resource factories that are defined within this server scope.
Application
Limits the visibility to the named application. Application scope resources cannot be configured
from the console. Use the WebSphere Application Server Toolkit (AST) or the wsadmin tool to
view or modify the application scope resource configuration. The resource factories that are
defined within the application scope are available for this application to use only. The application
scope overrides all other scopes.

You can configure resources and WebSphere Application Server variables under all five scopes. You can
configure namespace bindings and shared libraries only under cell, node, and server scopes.

Accessing help and product information from the administrative

console
This topic describes how to use administrative console help and how to link to product documentation from
the administrative console.

You must have a connection to the Internet to access information about WebSphere Application Server
from the Welcome page of the administrative console.

362 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
All of the helps panels that you can access from the administrative console, you can access from the
WebSphere Application Server Information Center. This article describes how to access the help panels,
the information center, and other product documentation from the administrative console.
v Click Welcome on the administrative console navigation tree. In the workspace to the right of the
navigation tree, select the appropriate links to access the WebSphere Application Server Information
Center, the WebSphere Application Server product information, and the WebSphere Application Server
technical information on developerWorks.
v Access help in the following ways:
– Click Help on the administrative console task bar to open a new Web browser for online help.
- Click on the Help index tab and select from the list of help panels to view administrative console
help information.
- Click on the Search tab, provide search terms, and then click Search. Under Results, select a
help panel that contains the search information.
– Click the ? icon on the task bar for the particular administrative console panel to open a new Web
browser and view the help panel for the corresponding administrative console panel. The help panel
is displayed in the Help index for the administrative console.
– In the help portal that is on the right side of the administrative console panel, do one or all of the
following tasks:
- Click a field label or a list marker in the administrative console panel for the help to display under
Field help. Alternatively, place the cursor over the field label or the list marker for the
corresponding help to display at the cursor.
- Click the link under Page help to access the help panel for the administrative console panel. The
help panel is the same help panel that displays when you click the ? icon.
- Expand the task help to view related tasks.

You can continue to access help information from the administrative console. Alternatively, you can access
the help information from the WebSphere Application Server Information Center.

You can continue to access the WebSphere Application Server Information Center, the WebSphere
Application Server product information, and the WebSphere Application Server technical information on
developerWorks from the administrative console. Alternatively you can access the information from the
IBM Web site.

Administrative console: Resources for learning

Use the following links to find relevant supplemental information about the IBM WebSphere Application
Server administrative console. The information resides on IBM and non-IBM Internet sites, whose
sponsors control the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

View links to additional information:

Administration
v IBM WebSphere Application Server Redbooks
This site contains a listing of all WebSphere Application Server Redbooks.
v IBM developerWorks WebSphere
This site is the home of technical information for developers working with WebSphere products. You can
download WebSphere software, take a fast path to developerWorks zones, such as VisualAge Java or
WebSphere Application Server, learn about WebSphere products through a newcomers page, tutorials,

Chapter 4. Using the administrative clients 363

 technology previews, training, and Redbooks, get answers to questions about WebSphere products, and
join the WebSphere community, where you can keep up with the latest developments and technical
papers.
v WebSphere Application Server Support page
Take advantage of the Web-based Support and Service resources from IBM to quickly find answers to
your technical questions. You can easily access this extensive Web-based support through the IBM
Software Support portal at URL http://www-3.ibm.com/software/support/ and search by product
category, or by product name. For example, if you are experiencing problems specific to WebSphere
Application Server, click WebSphere Application Server in the product list. The WebSphere Application
Server Support page appears.

Using scripting (wsadmin)

The WebSphere administrative (wsadmin) scripting program is a powerful, non-graphical command
interpreter environment enabling you to run administrative operations in a scripting language. The wsadmin
tool is intended for production environments and unattended operations. You can use the wsadmin tool to
perform the same tasks that you can perform using the administrative console.

The following list highlights the topics and tasks available with scripting:
v Getting started with scripting Provides an introduction to WebSphere Application Server scripting and
information about using the wsadmin tool. Topics include information about the scripting languages and
the scripting objects, and instructions for starting the wsadmin tool.
v Deploying applications Provides instructions for deploying and uninstalling applications. For example,
stand-alone Java archive files and Web archive files, the administrative console, remote Enterprise
Archive (EAR) files, file transfer applications, and so on.
v Managing deployed applications Includes tasks that you perform after the application is deployed. For
example, starting and stopping applications, checking status, modifying listener address ports, querying
application state, configuring a shared library, and so on.
v Configuring servers Provides instructions for configuring servers, such as creating a server, modifying
and restarting the server, configuring the Java virtual machine, disabling a component, disabling a
service, and so on.
v Configuring connections to Web servers Includes topics such as regenerating the plug-in, creating new
virtual host templates, modifying virtual hosts, and so on.
v Managing servers Includes tasks that you use to manage servers. For example, stopping nodes,
starting and stopping servers, querying a server state, starting a listener port, and so on.
v Clustering servers Includes topics about clusters, such as creating clusters, creating cluster members,
querying a cluster state, removing clusters, and so on.
v Configuring security Includes security tasks, for example, enabling and disabling global security,
enabling and disabling Java 2 security, and so on.
v Configuring data access Includes topics such as configuring a Java DataBase Connectivity (JDBC)
provider, defining a data source, configuring connection pools, and so on.
v Configuring messaging Includes topics about messaging, such as Java Message Service (JMS)
connection, JMS provider, WebSphere queue connection factory, MQ topics, and so on.
v Configuring mail, URLs, and resource environment entries Includes topics such as mail providers, mail
sessions, protocols, resource environment providers, referenceables, URL providers, URLs, and so on.
v Troubleshooting Provides information about how to troubleshoot using scripting. For example, tracing,
thread dumps, profiles, and so on.
v Scripting reference material Includes all of the reference material related to scripting. Topics include the
syntax for the wsadmin tool and for the administrative command framework, explanations and examples
for all of the scripting object commands, the scripting properties, and so on.

364 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Getting started with scripting
Scripting is a non-graphical alternative that you can use to configure and manage WebSphere Application
Server. The WebSphere Application Server wsadmin tool provides the ability to run scripts. The wsadmin
tool supports a full range of product administrative activities.

The following figure illustrates the major components involved in a wsadmin scripting solution:
Java virtual machine
Resources

M Beans
External tools Connector
M Bean
and programs Server
M Beans

Figure 1: A WebSphere Application Server scripting solution

The wsadmin tool supports two scripting languages: Jacl and Jython. Five objects are available when you
use scripts:
v AdminControl: Use to run operational commands.
v AdminConfig: Use to run configurational commands to create or modify WebSphere Application Server
configurational elements.
v AdminApp: Use to administer applications.
v AdminTask: Use to run administrative commands.
v Help: Use to obtain general help.

The scripts use these objects to communicate with MBeans that run in WebSphere Application Server
processes. MBeans are Java objects that represent Java Management Extensions (JMX) resources. JMX
is an optional package addition to Java 2 Platform Standard Edition (J2SE). JMX is a technology that
provides a simple and standard way to manage Java objects.

To perform a task using scripting, you must first perform the following steps:
1. Choose a scripting language. The wsadmin tool only supports Jacl and Jython scripting languages.
Jacl is the language specified by default. If you want to use the Jython scripting language, use the
-lang option or specify it in the wsadmin.properties file.
2. Start the wsadmin scripting client interactively, as an individual command, in a script, or in a profile.

Before you perform any task using scripting, make sure that you are familiar with the following concepts:
v Java Management Extensions (JMX)
v WebSphere Application Server configuration model
v wsadmin tool
v Jacl syntax or Jython syntax
v Scripting objects

Optionally, you can customize your scripting environment. For more information, see Scripting environment
properties.

After you become familiar with the scripting concepts, choose a scripting language, and start the scripting
client, you are ready to perform tasks using scripting.

Chapter 4. Using the administrative clients 365

Java Management Extensions (JMX)
Java Management Extensions (JMX) is a framework that provides a standard way of exposing Java
resources, for example, application servers, to a system management infrastructure. Using the JMX
framework, a provider can implement functions, such as listing the configuration settings, and editing the
settings. This framework also includes a notification layer that management applications can use to
monitor events such as the startup of an application server.

JMX key features

The key features of the WebSphere Application Server Version 6 implementation of JMX include:
v All processes that run the JMX agent.
v All run-time administration that is performed through JMX operations.
v Connectors that are used to connect a JMX agent to a remote JMX-enabled management application.
The following connectors are supported:
– SOAP JMX Connector
– Remote Method Invocation over the Internet Inter-ORB Protocol (RMI-IIOP) JMX Connector
v Protocol adapters that provide a management view of the JMX agent through a given protocol.
Management applications that connect to a protocol adapter are usually specific to a given protocol.
v The ability to query and update the configuration settings of a run-time object.
v The ability to load, initialize, change, and monitor application components and resources during
run-time.

JMX architecture

The JMX architecture is structured into three layers:

v Instrumentation layer - Dictates how resources can be wrapped within special Java beans, called
managed beans (MBeans).
v Agent layer - Consists of the MBean server and agents, which provide a management infrastructure.
The services that are implemented include:
– Monitoring
– Event notification
– Timers
v Management layer - Defines how external management applications can interact with the underlying
layers in terms of protocols, APIs, and so on. This layer uses an implementation of the distributed
services specification (JSR-077), which is not yet part of the Java 2 platform, Enterprise Edition (J2EE)
specification.

The layered architecture of JMX is summarized in the following figure:

366 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Management Application

Connector Adapter

Agent Layer

MBean Server

Agent Agent Agent Services

services services (as MBeans)

Java virtual machine Instrumentation Layer

Resource 1 Resource 2
MBean MBean

Manages Manages

Resource 1 Resource 2 Managed Resources

Figure 1: JMX architecture

JMX distributed administration

The following figure shows how the JMX architecture fits into the overall distributed administration topology
of a Network Deployment environment:

Clients, Multi-cell,
management, & other EMS
(Tivoli, BMC)
Deployment Manager

JMX
MBean Connector
Server
MBeans
MBean MBean MBeans
Proxy Proxy

Node Agent
Configuration
JMX Repository Service
MBean Connector To other
Server Nodes Master
MBeans files
MBean MBeans
To Other MBean
Proxy Proxy
Application Servers

Application Server
Configuration
JMX Distribution Service
MBean Connector
Configuration
Server
files

MBeans EAR
MBeans files

Figure 2: WebSphere Application Server distributed administration of JMX

The key points of this distributed administration architecture include:

Chapter 4. Using the administrative clients 367

v Internal MBeans that are local to the Java virtual machine (JVM) register with the local MBean server.
v External MBeans have a local proxy to their MBean server. The proxy registers with the local MBean
server. Using the MBean proxy the local MBean server can pass the message to an external MBean
server that is located on:
– A node agent that has an MBean proxy for all the servers within its node. The MBean proxies for
other nodes are not used.
– The deployment manager has MBean proxies for all the node agents in the cell.

JMX Mbeans

WebSphere Application Server provides a number of MBeans, each of which have different functions and
operations available. For example, an application server MBean can expose operations such as start and
stop. An application MBean can expose operations such as install and uninstall. Some JMX usage
scenarios that you can encounter include:
v External programs that are written to control the Network Deployment run time and its WebSphere
resources by programmatically accessing the JMX API.
v Third-party applications that include custom JMX MBeans as part of the deployed code, supporting the
JMX API management of application components and resources.

The following example illustrates how to obtain an MBean:

Using Jacl:
set am [$AdminControl queryNames type=ApplicationManager,process=server1,*]

Using Jacl:
am = AdminControl.queryNames(’type=ApplicationManager,process=server1,*’)

Each WebSphere Application Server runtime MBean may have attributes, operations, and notifications.
The complete documentation for each MBean supplied with WebSphere Application Server is available in
an html table that is installed in each copy of the WebSphere Application Server product. Under the main
install directory for the product, there is a directory named web. And under that directory is another
directory called mbeanDocs. In the mbeanDocs directory are several html files, one for each supplied with
WebSphere Application Server. There is also an index.html file that ties all the individual MBean files
together in a top-level navigation tree. Each MBean provides summary of its attributes, operations, and
notifications.

JMX benefits

The use of JMX for management functions in WebSphere Application Server provides the following
benefits:
v Enables the management of Java applications without significant investment.
v Relies on a core-managed object server that acts as a management agent.
v Java applications can embed a managed object server and make some of its functionality available as
one or several MBeans that are registered with the object server.
v Provides a scalable management architecture.
v Every JMX agent service is an independent module that can be plugged into the management agent.
v The API is extensible, allowing new WebSphere Application Server and custom application features to
be easily added and exposed through this management interface.
v Integrates existing management solutions.
v JMX smart agents are capable of being managed through HTML browsers or by various management
protocols such as Web services, Java Message Service (JMS), and Simple Network Management
Protocol (SNMP).

368 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Each process is self sufficient when it comes to the management of its resources. No central point of
control exists. In principle, a JMX-enabled management client can be connected to any managed
process and interact with the MBeans that are hosted by that process.
v JMX provides a single, flat, domain-wide approach to system management. Separate processes interact
through MBean proxies that support a single management client to seamlessly navigate through a
network of managed processes.
v Defines the interfaces that are necessary for management only.
v Provides a standard API for exposing application and administrative resources to management tools.

WebSphere Application Server configuration model

Configuration data is stored in several XML files. The server runtime reads these files when started and
responds to the component settings stored there. The configuration data includes settings for the runtime
itself, such as JVM options, thread pool sizes, container setting, and port numbers the server will use.
Other configuration files define J2EE resources to which the server will connect to obtain data needed by
the application logic. Security settings are stored in a separate document from the server and resource
configuration. Applcation-specific configuration, such as deployment target lists, session configuration, and
cache settings, are stored in files under the root directory of each application.

The configuration model for WebSphere Application Server is large and complex. When viewing the XML
data in the various configuration files, you can discern relationship between the configuration objects.
Understanding these relationships between configuration objects is essential when writing wsadmin scripts
that perform configuration functions.

Full documentation of all of the WebSphere configuration objects is available in an html table that is
installed in each copy of the WebSphere product. Under the main install directory for the product, there is
a directory named web. And under that directory is another directory called configDocs. In the configDocs
directory are several subdirectories, one for each configuration package in the model. There is also an
index.html file that ties all the individual configuration packages together in a top-level navigation tree.
Each configuration package lists all the supported configuration classes. Each configuration class lists all
the supported properties. Properties with names that end with the special @ character imply that property
is actually a reference to some other configuration object within the configuration data. Properties with
names that end with an * imply that property is actaully a list of other configuration objects.

Jacl
Jacl is an alternate implementation of TCL, and is written entirely in Java code.

The wsadmin tool uses Jacl V1.3.1. The following information is a basic summary of the Jacl syntax:

Basic syntax:

The basic syntax for a Jacl command is the following:

Command arg1 arg2 arg3 ...

The command is either the name of a built-in command or a Jacl procedure. For example:
puts stdout {Hello, world!}
=> Hello, world!

In this example, the command is puts which takes two arguments, an I/O stream identifier and a string.
The puts command writes the string to the I/O stream along with a trailing new line character. The
arguments are interpreted by the command. In the example, stdout is used to identify the standard output
stream. The use of stdout as a name is a convention employed by the puts command and the other I/O
commands. stderr identifies the standard error output, and stdin identifies the standard input.

Variables

Chapter 4. Using the administrative clients 369

The set command assigns a value to a variable. This command takes two arguments: the name of the
variable and the value. Variable names can be any length and are case sensitive. You do not have to
declare Jacl variables before you use them. The interpreter will create the variable when it is first assigned
a value. For example:
set a 5
=> 5
set b $a
=> 5

The second example assigns the value of variable a to variable b. The use of dollar sign ($) is indicates
variable substitution. You can delete a variable with the unset command, for example:
unset varName1 varName2 ...

You can pass any number of variables to the unset command. The unset command will give error if a
variable is not already defined. You can delete an entire array or just a single array element with the unset
command. Using the unset command on an array is a easy way to clear out a big data structure. The
existence of a variable can be tested with the info exists command. You may have to test for the
existence of the variable because the incr parameter requires that a variable exist first, for example:
if ![info exists foobar] {set foobar 0} else {incr foobar}

Command substitution:

The second form of substitution is command substitution. A nested command is delimited by square
brackets, [ ]. The Jacl interpreter evaluates everything between the brackets and evaluates it as a
command. For example:
set len [string length foobar]
=> 6

In this example, the nested command is the following: string length foobar. The string command
performs various operations on strings. In this case, the command asks for the length of the string foobar.
If there are several cases of command substitution within a single command, the interpreter processes
them from left bracket to right bracket. For example:
set number "1 2 3 4"
=> 1 2 3 4
set one [lindex $number 0]
=> 1
set end [lindex $number end]
=> 4
set another {123 456 789}
=> 123 456 789
set stringLen [string length [lindex $another 1]]
=> 3
set listLen [llength [lindex $another 1]
=> 1

Math expressions:

The Jacl interpreter does not evaluate math expressions. Use the expr command to evaluate math
expressions. The interpreter treats the expr command similar to other commands and leaves the
expression parsing up the expr command implementation. The implementation of the expr command
takes all arguments, concatenates them into a single string, and parses the string as a math expression.
After the expr command computes the answer, it his formatted into a string and returned. For example:
expr 7.2 / 3
=> 2.4

Backslash substitution:

370 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The final type of substitution done by the Jacl interpreter is backslash substitution. Use this to quote
characters that have special meaning to the interpreter. For example, you can specify a literal dollar sign,
brace, or bracket by quoting it with a backslash. If you are using lots of backslashes, instead you can
group things with curly braces to turn off all interpretation of special characters. There are cases where
backslashes are required. For example:
set dollar "This is a string \$contain dollar char"
=> This is a string $contain dollar char

set x $dollar
=> This is a string $contain dollar char

set group {$ {} [] { [ } ]}
=> $ {} [] { [ } ]

You can also use backslashes to continue long commands on multiple lines. A new line without the
backslash terminates a command. A backslashes that are the last character on a line convert into a space.
For example:
set totalLength [expr [string length "first string"] + \
[string length "second string"]]
=> 25

Grouping with braces and double quotes:

Use double quotes and curly braces to group words together. Quotes allow substitutions to occur in the
group and curly braces prevent substitution. This rule applies to command, variable, and backslash
substitutions. For example:
set s Hello
=> Hello

puts stdout "The length of $s is [string length $s]."

=> The length of Hello is 5.

puts stdout {The length of $s is [string length $s].}

=> The length of $s is [string length $s].

In the second example, the Jacl interpreter performs variable and command substitution on the second
argument from the puts command. In the third command, substitutions are prevented so the string is
printed as it is.

On distributed systems, special care must also be taken with path descriptions because the Jacl language
uses the backslash character (\) as an escape character. To fix this, either replace each backslash with a
forward slash, or use double backslashes in distributed path statements. For example: C:/ or C:\\

Procedures and scope:

Jacl uses the proc command to define procedures. The basic syntax to define a procedure is the
following:
proc name arglist body

The first argument is the name of the procedure being defined. The name is case sensitive, and in fact it
can contain any characters. Procedure names and variable names do not conflict with each other. The
second argument is a list of parameters to the procedures. The third argument is a command, or more
typically a group of commands that form the procedure body. Once defined, a Jacl procedure is used just
like any of the built-in commands. For example:
proc divide {x y} {
set result [expr x/y]
puts $result
}

Chapter 4. Using the administrative clients 371

Inside the script, this is how to call devide procedure:
divide 20 5

And it will give the result like below:

4

It is not really necessary to use the variable c in this example. The procedure body could also written as:
return [expr sqrt($a * $a + $b * $b)]

The return command is optional in this example because the Jacl interpreter returns the value of the last
command in the body as the value of the procedure. So, the procedure body could be reduced to:
expr sqrt($a * $a + $b * $b)

The result of the procedure is the result returned by the last command in the body. The return command
can be used to return a specific value.

There is a single, global scope for procedure names. You can define a procedure inside another
procedure, but it is visible everywhere. There is a different name space for variables and procedures
therefore you may have a procedure and a variable with the same name without a conflict. Each
procedure has a local scope for variables. Variables introduced in the procedures only exist for the
duration of the procedure call. After the procedure returns, those variables are undefined. If the same
variable name exists in an outer scope, it is unaffected by the use of that variable name inside a
procedure. Variables defined outside the procedure are not visible to a procedure, unless the global scope
commands are used.
v global command - Global scope is the top level scope. This scope is outside of any procedure. You
must make variables defined at the global scope accessible to the commands inside procedure by using
the global command. The syntax for the global command is the following:
global varName1 varName2 ...

Comments

Use the pound character (#) to make comments.

Command line arguments

The Jacl shells pass the command line arguments to the script as the value of the argv variable. The
number of command line arguments is given by argc variable. The name of the program, or script, is not
part of argv nor is it counted by argc. Instead, it is put into the argv0 variable. The argv variable is a list.
Use the lindex command to extract items from the argument list, for example:
set first [lindex $argv 0]
set second [lindex $argv 1]

Strings and pattern matching

String are the basic data item in the Jacl language. There are multiple commands that you can use to
manipulate strings. The general syntax of the string command is the following:
string operation stringvalue otherargs

The operation argument determines the action of the string. The second argument is a string value. There
may be additional arguments depending on the operation.

The following table includes a summary of the string command:

Command Description

372 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
string compare str1 str2 Compares strings lexicographically. Returns 0 if equal, -1
if str1 sorts before str2, else1.
string first str1 str2 Returns the index in str2 of the first occurrences of str1,
or -1 if str1 is not found.
string index string index Returns the character at the specified index.
string last str1 str2 Returns the index in str2 of the last occurence of str1, or
-1 if str1 is not found.
string length string Returns the number of character in string.
string match pattern str Returns 1 if str matches the pattern, else 0.
string range str i j Returns the range of characters in str from i to j
string tolower string Returns string in lower case.
string toupper string Returns string in upper case.
string trim string ?chars? Trims the characters in chars from both ends of string.
chars defaults to white space.
string trimleft string ?chars? Trims the characters in chars from the beginning of string.
chars defaults to white space.
string trimright string ?chars? Trims the characters in chars from the end of string.
chars defaults to white space.
string wordend str ix Returns the index in str of the character after the word
containing the character at index ix.
string wordstart str ix Returns the index in str of the first character in the word
containing the character at index ix.

The append command

The first argument of the append command is a variable name. It concatenates the remaining arguments
onto the current value of the named variable. For example:
set foo z
=> z

append foo a b c
=> zabc

The regexp command

The regexp command provides direct access to the regular expression matcher. The syntax is the
following:
regexp ?flags? pattern string ?match sub1 sub2 ...?

The return value is 1 if some part of the string matches the pattern. Otherwise, the return value will be 0.
The pattern does not have to match the whole string. If you need more control than this, you can anchor
the pattern to the beginning of the string by starting the pattern with ^, or to the end of the string by ending
the pattern with dollar sign, $. You can force the pattern to match the whole string by using both
characters. For example:
set text1 "This is the first string"
=> This is the first string

regexp "first string" $text1

=> 1

regexp "second string" $text1

=> 0

Chapter 4. Using the administrative clients 373

Jacl data structures

The basic data structure in the Jacl language is a string. There are two higher level data structures: lists
and arrays. Lists are implemented as strings and the structure is defined by the syntax of the string. The
syntax rules are the same as for commands. Commands are a particular instance of lists. Arrays are
variables that have an index. The index is a string value so you can think of arrays as maps from one
string (the index) to another string (the value of the array element).

Jacl lists

The lists of the Jacl language are strings with a special interpretation. In the Jacl language, a list has the
same structure as a command. A list is a string with list elements separated by white space. You can use
braces or quotes to group together words with white space into a single list element.

The following table includes commands that are related to lists:

Command Description
list arg1 arg2 Creates a list out of all its arguments.
lindex list i Returns the i’th element from list.
llength list Returns the number of elements in list.
lrange list i j Returns the i’th through j’th elements from list.
lappend listVar arg arg ... Appends elements to the value of listVar
linsert list index arg arg ... Inserts elements into list before the element at position
index. Returns a new list.
lreplace list i j arg arg ... Replaces elements i through j of list with the args. Return
a new list.
lsearch mode list value Returns the index of the element in list that matches the
value according to the mode, which is -exact, -glob, or
-regexp, -glob is the default. Return -1 if not found.
lsort switches list Sorts elements of the list according to the switches:
-ascii, -integer, -real, -increasing, -decreasing, -command
command. Return a new list.
concat arg arg arg ... Joins multiple lists together into one list.
join list joinString Merges the elements of a list together by separating them
with joinString.
split string splitChars Splits a string up into list elements, using (and discarding)
the characters in splitChars as boundaries between list
elements.

Arrays

Arrays are the other primary data structure in the Jacl language. An array is a variable with a string-valued
index, so you can think of an array as a mapping from strings to strings. Internally an array is implemented
with a hash table. The cost of accessing each element is about the same. The index of an array is
delimited by parentheses. The index can have any string value, and it can be the result of variable or
command substitution. Array elements are defined with the set command, for example:
set arr(index) value

Substitute the dollar sign ($) to obtain the value of an array element, for example:
set foo $arr(index)

For example:

374 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
set fruit(best) kiwi
=> kiwi

set fruit(worst) peach

=> peach

set fruit(ok) banana

=> banana

array get fruit

=> ok banana worst peach best kiwi

array exists fruit

=> 1

The following table includes array commands:

Command Description
array exists arr Returns 1 if arr is an array variable.
array get arr Returns a list that alternates between an index and the
corresponding array value.
array names arr ?pattern? Return the list of all indices defined for arr, or those that
match the string match pattern.
array set arr list Initializes the array arr from list, which should have the
same form as the list returned by get.
array size arr Returns the number of indices defined for arr.
array startsearch arr Returns a search token for a search through arr.
array nextelement arr id Returns the value of the next element in array in the
search identified by the token id. Returns an empty string
if no more elements remain in the search.
array anymore arr id Returns 1 if more elements remain in the search.
array donesearch arr id Ends the search identified by id.

Control flow commands

The following looping commands exist:

v while
v foreach
v for

The following are conditional commands:

v if
v switch

The following is an error handling command:

v catch

The following commands fine-tune control flow:

v break
v continue
v return
v error

Chapter 4. Using the administrative clients 375

If Then Else

The if command is the basic conditional command. If an expression is true, then execute one command
body, otherwise execute another command body. The second command body (the else clause) is optional.
The syntax of the command is the following:
if boolean then body1 else body2

The then and else keywords are optional. For example:

if {$x == 0} {
puts stderr "Divide by zero!"
} else {
set slope [expr $y/$x]
}

Switch

Use the switch command to branch to one of many commands depending on the value of an expression.
You can choose based on pattern matching as well as simple comparisons. Any number of pattern-body
pairs can be specified. If multiple patterns match, only the body of the first matching pattern is evaluated.
The general form of the command is the following:
switch flags value pat1 body1 pat2 body2 ...

You can also group all the pattern-body pairs into one argument:
switch flags value {pat1 body1 pat2 body2 ...}

There are four possible flags that determines how value is matched.
v -exact Matches the value exactly to one of the patterns.
v -glob Uses glob-style pattern matching.
v -regexp Uses regular expression pattern matching.
v -- No flag (or end of flags). Useful when value can begin with a dash (-).

For example:
switch -exact -- $value {
foo {doFoo; incr count(foo)}
bar {doBar; return $count(foo)}
default {incr count(other)}
}

If the pattern that is associated with the last body is default, then the command body is started if no other
patterns match. The default keyword only works on the last pattern-body pair. If you use the default
pattern on an earlier body, it will be treated as a pattern to match the literal string default.

Foreach

The foreach command loops over a command body and assigns a loop variable to each of the values in a
list. The syntax is the following:
foreach loopVar valueList commandBody

The first argument is the name of a variable. The command body runs one time for each element in the
loop with the loop variable having successive values in the list. For example:
set numbers {1 3 5 7 11 13}
foreach num $numbers {
puts $num
}

376 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The result from the previous example will be the following output, assuming that only one server exists in
the environment. If there is more than one server, the information for all servers returns:
1
3
5
7
11
13

While

The while command takes two arguments; a test and a command body, for example:
while booleanExpr body

The while command repeatedly tests the boolean expression and runs the body if the expression is true
(non-zero). For example:
set i 0
while {$i < 5} {
puts "i is $i"
incr i}

The result from the previous example will be like the following output, assuming that there is only one
server. If there is more then one servers, it will print all of the servers:
i is 0
i is 1
i is 2
i is 3
i is 4

For

The for command is similar to the C language for statement. It takes four arguments, for example:
for initial test final body

The first argument is a command to initialize the loop. The second argument is a boolean expression
which determines if the loop body will run. The third argument is a command that runs after the loop body:
For example:
set numbers {1 3 5 7 11 13}
for {set i 0} {$i < [llength $numbers]} {incr i 1} {
puts "i is $i"
}

The result from previous example will be like the following output, assuming that there is only one server
in the environment. If there is more then one server, it will print all of the servers:
i is 1
i is 3
i is 5
i is 7
i is 11
i is 13

Break and continue

You can control loop execution with the break and continue commands. The break command causes an
immediate exit from a loop. The continue command causes the loop to continue with the next iteration.

Catch

Chapter 4. Using the administrative clients 377

An error will occur if you call a command with the wrong number of arguments or if the command detects
some error condition particular to its implementation. An uncaught error prevents a script from running.
Use the catch command trap such errors. The catch command takes two arguments, for example:
catch command ?resultVar?

The first argument is a command body. The second argument is the name of a variable that will contain
the result of the command or an error message if the command raises an error. The catch command
returns a value of zero if no error was caught or a value of one if the command catches an error. For
example:
catch {expr 20 / 5} result
==> 0
puts $result
==> 4
catch {expr text / 5} result
==> 1
puts $result
==> syntax error in expression "text / 5"

Return

The return command is used to return from a procedure. It is needed if you want something to return
before the end of the procedure body or if a contrast value needs to be returned.

Namespaces

Jacl keeps track of named entities such as variables, in namespaces. The wsadmin tool also adds entries
to the global namespace for the scripting objects, such as, the AdminApp object

When you run a proc command, a local namespace is created and initialized with the names and the
values of the parameters in the proc command. Variables are held in the local namespace while you run
the proc command. When you stop the proc command, the local namespace is erased. The local
namespace of the proc command implements the semantics of the automatic variables in languages such
as C and Java.

While variables in the global namespace are visible to the top level code, they are not visible by default
from within a proc command. To make them visible, declare the variables globally using the global
command. For the variable names that you provide, the global command creates entries in the local
namespace that point to the global namespace entries that actually define the variables.

If you use a scripting object provided by the wsadmin tool in a proc, you must declare it globally before
you can use it, for example:
proc { ... } {
global AdminConfig
... [$AdminConfig ...]
}

For more information about Jacl, see the Scripting: Resources for Learning article.

Jython
Jython is an alternate implementation of Python, and is written entirely in Java.

The wsadmin tool uses Jython V2.1. The following information is a basic summary of the Jython syntax:

Basic function

The function is either the name of a built-in function or a Jython function. For example:

378 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
print "Hello, World!"
=> Hello, World!

import sys
sys.stdout.write("Hello World!\n")
=> Hello World!

In the example, print identifies the standard output stream. You can use the built-in module by running
import statements such as the previous example. The statement import runs the code in a module as part
of the importing and returns the module object. sys is a built-in module of the Python language. In the
Python language, modules are name spaces which are places where names are created. Names that
reside in modules are called attributes. Modules correspond to files and the Python language creates a
module object to contain all the names defined in the file. In other words, modules are name spaces.

Variable

To assign objects to names, the target of an assignment should be on the left side of an equal sign (=)
and the object that you are assigning on the right side. The target on the left side can be a name or object
component, and the object on the right side can be an arbitrary expression that computes an object. The
following rules exist for assigning objects to names:
v Assignments create object references.
v Names are created when you assign them.
v You must assign a name before referencing it.

Variable name rules are similar to the rules for the C language, for example:
v An underscore character (_) or a letter plus any number of letters, digits or underscores

The following reserved words can not be used for variable names:
and assert break class continue
def del elif else except
exec inally for from global
if importin is lambda
not or pass print raise
return try while

For example:
a = 5
print a
=> 5

b = a
print b
=> 5

text1, text2, text3, text4 = ’good’, ’bad’, ’pretty’, ’ugly’

print text3
=> pretty

The second example assigns the value of variable a to variable b.

Types and operators

The following list contains a few of the built-in object types:

v Numbers. For example:

Chapter 4. Using the administrative clients 379

 8, 3.133, 999L, 3+4j

num1 = int(10)
print num1
=> 10
v Strings. For example:
’name’, "name’s", ’’

print str(12345)
=> ’12345’
v Lists. For example:
x = [1, [2, ’free’], 5]
y = [0, 1, 2, 3]
y.append(5)
print y
=> [0, 1, 2, 3, 5]

y.reverse()
print y
=> [5, 3, 2, 1, 0]

y.sort()
print y
=> [0, 1, 2, 3, 5]

print list("apple")
=> [’a’, ’p’, ’p’, ’l’, ’e’]

print list((1,2,3,4,5))
=> [1, 2, 3, 4, 5]

test = "This is a test"

test.index("test")
=> 10

test.index(’s’)
=> 3

The following list contains a few of the operators:

v x or y
y is evaluated only if x is false. For example:
print 0 or 1
=> 1
v x and y
y is evaluated only if x is true. For example:
print 0 and 1
=> 0
v x +y , x - y
Addition and concatenation, subtraction. For example:
print 6 + 7
=> 13

text1 = ’Something’
text2 = ’ else’
print text1 + text2
=> Something else

list1 = [0, 1, 2, 3]
list2 = [4, 5, 6, 7]
print list1 + list2

380 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 => [0, 1, 2, 3, 4, 5, 6, 7]

print 10 - 5
=> 5
v x * y, x / y, x % y
Multiplication and repetition, division, remainder and format. For example:
print 5 * 6
=> 30

print ’test’ * 3
=> test test test

print 30 / 6
=> 5

print 32 % 6
=> 2
v x[i], x[i:j], x(...)
Indexing, slicing, function calls. For example:
test = "This is a test"
print test[3]
=> s

print test[3:10]
=> s is a

print test[5:]
=> is a test

print x[:-4]
=> This is a print len(test)
=> 14
v <, <=, >, >=, ==, <>, !=, is is not
Comparison operators, identity tests. For example:
l1 = [1, (’a’, 3)]
l2 = [1, (’a’, 2)]
l1 < l2, l1 == l2, l1 > l2, l1 <> l2, l1 != l2, l1 is l2, l1 is not l2
=> (0, 0, 1, 1, 1, 0, 1)

Backslash substitution

If a statement needs to span multiple lines, you can also add a black slash (\) at the end of the previous
line to indicate you are continuing on the next line. For example:
text = "This is a tests of a long lines" \
" continuing lines here."
print text
=> This is a tests of a long lines continuing lines here.

Functions and scope

Jython uses the def statement to define functions. Functions related statements include:
v def, return
The def statement creates a function boject and assigns it to a name. Thereturn statement sends a
result object back to the caller. This is optional, and if it is not present, a function exits so that control
flow falls off the end of the function body.
v global

Chapter 4. Using the administrative clients 381

 The global statement declares module-level variables that are to be assigned. By default, all names
assigned in a function are local to that function and exist only while the function runs. To assign a name
in the enclosing module, list functions in a global statement.

The basic syntax to define a function is the following:

def name (arg1, arg2, ... ArgN):
statements
return value

where name is the name of the function being defined. It is followed by an open parenthesis, a close
parenthesis and a colon. The arguments inside parenthesis include a list of parameters to the procedures.
The next line after the colon is the body of the function. A group of commands that form the body of the
function. After you define a Jython function, it is used just like any of the built-in functions. For example:
def intersect(seq1, seq2):
try:
res = []
for x in seq1:
if x in seq2:
res.append(x)
return res
except:

To call the function above, use the following command:

s1 = "SPAM"
s2 = "SCAM"
intersect(s1, s2)
=> [S, A, M]

intersect([1,2,3], (1.4))
=> [1]

Comments

Make comments in the Jython language with the pound character (#).

Command line arguments

The Jython shells pass the command line arguments to the script as the value of the sys.argv. The name
of the program, or script, is not part of sys.argv. sys.argv is an array, so you use the index command to
extract items from the argument list, for example:
import sys
first = sys.argv[0]
second = sys.argv[1]
arglen = len(sys.argv)

Basic statements

There are two looping statements: while and for. The conditional statement is if. The error handling
statement is try. Finally, there are some statements to fine-tune control flow: break, continue and pass.
The following is a list of syntax rules in Python:
v Statements run one after another until you say otherwise. Statements normally end at the end of the
line they appear on. When statements are too long to fit on a single line you can also add a back sash
(\) at the end of the prior line to indicate you are continuing on the next line.
v Block and statement boundaries are detected automatically. There are no braces, or begin or end
delimiter, around blocks of code. Instead, the Python language uses the indentation of statements under
a header in order to group the statements in a nested block. Block boundaries are detected by line
indentation. All statements indented the same distance to the right belong to the same block of code
until that block is ended by a line less indented.

382 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Compound statements = header; ’:’, indented statements. All compound statements in the Python
language follow the same pattern: a header line terminated with a colon, followed by one or more
nested statements indented under the header. The indented statements are called a block.
v Spaces and comments are usually ignored. Spaces inside statements and expressions are almost
always ignored (except in string constants and indentation), so are comments.

If

The if statement selects actions to perform. The if statement may contain other statements, including
other if statements. The if statement can be followed by one or more optional elif statements and ends
with an optional else block.

The general format of an if looks like the following:

if test1
statements1
elif test2
statements2
else test3
statements3

For example:
weather = ’sunny’
if weather == ’sunny’:
print "Nice weather"
elif weather == ’raining’:
print "Bad weather"
else:
print "Uncertain, don’t plan anything"

While

The while statement consists of a header line with a test expression, a body of one or more indented
statements, and an optional else statement that runs if control exits the loop without running into a break
statement. The while statement repeatedly executes a block of indented statements as long as a test at
the top keeps evaluating a true value. The general format of an while looks like the following:
while test1
statements1
else
statements2

For example:
a = 0; b = 10
while a < b:
print a
a = a + 1

For

The for statement begins with a header line that specifies an assignment target or targets, along with an
object you want to step through. The header is followed by a block of indented statements which you want
to repeat.

The general format of an while looks like the following:

for target in object:
statements
else:
statements

Chapter 4. Using the administrative clients 383

It assigns items in the sequence object to the target, one by one, and runs the loop body for each. The
loop body typically uses the assignment target to refer to the current item in the sequence as if it were a
cursor stepping through the sequence. For example:
sum = 0
for x in [1, 2, 3, 4]:
sum = sum + x

Break, continue, and pass

You can control running a loop the break, continue and pass statements. The break statement jumps out
of the closest enclosing loop (past the entire loop statement). The continue statements jumps to the top of
the closest enclosing loop (to the header line of the loop), and the pass statement is an empty statement
placeholder.

Try

A statement will raise an error if it is called with the wrong number of arguments, or if it detects some error
condition particular to its implementation. An uncaught error aborts execution of a script. The try statement
is used to trap such errors. Python try statements come in two flavors, one that handles exceptions and
one that executes finalization code whether exceptions occur or not. The try, except, else statement
starts with a try header line followed by a block of indented statements, then one or more optional except
clauses that name exceptions to be caught, and an optional else clause at the end. The try, finally
statements starts with a try header line followed by a block of indented statements, then finally clause that
always runs on the way out whether an exception occurred while the try block was running or not.

The general format of the try, except, else function looks like the following:
try:
statements
except name:
statements
except name, data:
statements
else
statements

For example:
try:
myfunction()
except:
import sys
print ’uncaught exception’, sys.exc_type, sys.exc_value

try:
myfilereader()
except EOFError:
break
else:
process next line here

The general format of a try and finally looks like the following:
try:
statements
finally:
statements

For example:
def divide(x, y):
return x / y

384 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
def tester(y):
try:
print divide(8, y)
finally:
print ’on the way out...’

For more information about the Jython language, see the Scripting: Resources for Learning article.

Scripting objects
The wsadmin tool operates on configurations and running objects through the following set of management
objects: AdminConfig, AdminControl, AdminApp, AdminTask, and Help. Each of these objects has
commands that you can use to perform administrative tasks. To use the scripting objects, specify the
scripting object, a command, and command parameters. For example:

Using Jacl:
$AdminConfig attributes ApplicationServer

Using Jython:
print AdminConfig.attributes(’ApplicationServer’)

where AdminConfig is the scripting object, attributes is the command, and ApplicationServer is the
command parameter.

To find out more specific information about each of the scripting objects, including command and
command parameter information, see AdminConfig, AdminApp, AdminControl, AdminTask, or Help.

WebSphere Application Server system management separates administrative functions into two categories:
functions that work with the configuration of WebSphere Application Server installations, and functions that
work with the currently running objects in WebSphere Application Server installations.

Scripts work with both categories of objects. For example, an application server is divided into two distinct
entities. One entity represents the configuration of the server that resides persistently in a repository on
permanent storage. You can create, query, change, or remove this configuration without starting an
application server process. The AdminConfig object, the AdminTask object, and the AdminApp object
handle configuration functionality. You can invoke configuration functions with or without being connected
to a server.

The second entity represents the running instance of an application server by a Java Management
Extensions (JMX) MBean. This instance can have attributes that you can interrogate and change, and
operations that you can invoke. These operational actions taken against a running application server do
not have an effect on the persistent configuration of the server. The attributes that support manipulation
from an MBean differ from the attributes that the corresponding configuration supports. The configuration
can include many attributes that you cannot query or set from the running object. The WebSphere
Application Server scripting support provides functions to locate configuration objects, and running objects.
Objects in the configuration do not always represent objects that are currently running. The AdminControl
object manages running objects.

You can use the Help object to obtain information about the AdminConfig, AdminApp, AdminControl, and
AdminTask objects, to obtain interface information about running MBeans, and to obtain help for warnings
and error messages.

Help object for scripted administration: The Help object provides general help, online information
about running MBeans, and help on messages.

Chapter 4. Using the administrative clients 385

Use the Help object to obtain general help for the other objects supplied by the wsadmin tool for scripting:
the AdminApp, AdminConfig, AdminTask, and AdminControl objects. For example, using Jacl, $Help
AdminApp or using Jython, Help.Adminapp(), provides information about the AdminApp object and the
available commands.

The Help object also to provides interface information about MBeans running in the system. The
commands that you use to get online information about the running MBeans include: all, attributes,
classname, constructors, description, notification, operations.

You can also use the Help object to obtain information about messages using the message command.
The message command provides aid to understand the cause of a warning or error message and find a
solution for the problem. For example, you receive a WASX7115E error when running the AdminApp install
command to install an application, use the following example:

Using Jacl:
$Help message WASX7115E

Using Jython:
print Help.message(’WASX7115E‘)

Example output:
Explanation: wsadmin failed to read an ear file when
preparing to copy it to a temporary location for AdminApp
processing. User action: Examine the wsadmin.traceout
log file to determine the problem; there may be file permission problems.

The user action specifies the recommended action to correct the problem. It is important to understand
that in some cases the user action may not be able to provide corrective actions to cover all the possible
causes of an error. It is an aid to provide you with information to troubleshoot a problem.

To see a list of all available commands for the Help object, see the Commands for the Help object article
or you can also use the Help command, for example:

Using Jacl:
$Help help

Using Jython:
print Help.help()

AdminApp object for scripted administration: Use the AdminApp object to manage applications. This
object communicates with the WebSphere Application Server run time application management object to
make application inquires and changes, for example:
v Installing and uninstalling applications
v Listing applications
v Editing applications or modules

Since applications are part of configuration data, any changes that you make to an application is kept in
the configuration session, similar to other configuration data. Be sure to save your application changes so
that the data transfers from the configuration session to the master repository.

With the application already installed, the AdminApp object can update application metadata, map virtual
hosts to Web modules, and map servers to modules. You must perform any other changes, such as,
specifying a library for the application to use or setting session management configuration properties,
using the AdminConfig object.

386 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
You can run the commands for the AdminApp object in local mode. If a server is running, it is not
recommended that you run the scripting client in local mode because any configuration changes that are
made in local mode will not be reflected in the running server configuration and vice versa. If you save a
conflicting configuration, you could corrupt the configuration. In a deployment manager environment,
configuration updates are available only if a scripting client is connected to a deployment manager. When
connected to a node agent or a managed application server, you will not be able to update the
configuration because the configuration for these server processes are copies of the master configuration
which resides in the deployment manager. The copies are created on a node machine when a
configuration synchronization occurs between the deployment manager and the node agent. Make
configuration changes to the server processes by connecting a scripting client to a deployment manager.
For this reason, to change a configuration, do not run a scripting client in local mode on a node machine.
It is not a supported configuration.

To see a list of all available commands for the AdminApp object, see the Commands for the AdminApp
object article or you can also use the Help command, for example:

Using Jacl:
$AdminApp help

Using Jython:
print AdminApp.help()

Listing applications with the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Query the configuration and create a list of installed applications, for example:
v Using Jacl:
$AdminApp list
v Using Jython:
AdminApp.list()
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object allowing application objects management
list is an AdminApp command

Example output:
DefaultApplication
SampleApp
app1serv2

Editing application configurations with the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.
1. Edit the entire application or a single application module. Use one of the following commands:
v The following command uses the installed application and the command option information to edit
the application:
– Using Jacl:

Chapter 4. Using the administrative clients 387

 $AdminApp edit appname {options}
– Using Jython list:
AdminApp.edit(’appname’, [’options’])
– Using Jython string:
AdminApp.edit(’appname’, ’[options]’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object allowing application objects management
edit is an AdminApp command
appname is the name of application or application module to edit.
For the application module name, use the module name
returned from listModules command as the value.
{options} is a list of edit options and tasks similar to the ones for
the install command

v The following command changes the application information by prompting you through a series of
editing tasks:
– Using Jacl:
$AdminApp editInteractive appname
– Using Jython:
AdminApp.editInteractive(’appname’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object allowing application objects management
editInteractive is an AdminApp command
appname is the name of application or application module to edit.
For the application module name, use the module name
returned from listModules command as the value.

2. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
3. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

AdminControl object for scripted administration: The AdminControl scripting object is used for
operational control. It communicates with MBeans that represent live objects running a WebSphere server
process. It includes commands to query existing running objects and their attributes and invoke operation
on the running objects. In addition to the operational commands, the AdminControl object supports
commands to query information on the connected server, convenient commands for client tracing,
reconnecting to a server, and start and stop server for network deployment environment.

Many of the operational commands have two sets of signatures so that they can either invoke using string
based parameters or using Java Management Extension (JMX) objects as parameters. Depending on the
server process to which a scripting client is connected, the number and type of MBeans available varies. If
a scripting client is connected to a deployment manager, then all MBeans in all server processes are
visible. If a scripting client is connected to a node agent, all MBeans in all server processes on that node
are accessible. When connected to an application server, only MBeans running in that application server
are visible.

388 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The following steps provide a general method to manage the cycle of an application:
v Install the application.
v Edit the application.
v Update the application.
v Uninstall the application.

To see a list of all available commands for the AdminControl object, see the Commands for the
AdminControl object article or you can also use the Help command, for example:

Using Jacl:
$AdminControl help

Using Jython:
print AdminControl.help()

ObjectName, Attribute, and AttributeList classes:

WebSphere Application Server scripting commands use the underlying Java Management Extensions
(JMX) classes, ObjectName, Attribute, and AttributeList, to manipulate object names, attributes and
attribute lists respectively.

The WebSphere Application Server ObjectName class uniquely identifies running objects. The ObjectName
class consists of the following elements:
v The domain name WebSphere.
v Several key properties, for example:
– type - Indicates the type of object that is accessible through the MBean, for example,
ApplicationServer, and EJBContainer.
– name - Represents the display name of the particular object, for example, MyServer.
– node - Represents the name of the node on which the object runs.
– process - Represents the name of the server process in which the object runs.
– mbeanIdentifier - Correlates the MBean instance with corresponding configuration data.

When ObjectName classes are represented by strings, they have the following pattern:
[domainName]:property=value[,property=value]*

For example, you can specify WebSphere:name=″My Server″,type=ApplicationServer,node=n1,* to specify

an application server named My Server on node n1. (The asterisk (*) is a wildcard character, used so that
you do not have to specify the entire set of key properties.) The AdminControl commands that take strings
as parameters expect strings that look like this example when specifying running objects (MBeans). You
can obtain the object name for a running object with the getObjectName command.

Attributes of these objects consist of a name and a value. You can extract the name and value with the
getName and the getValue methods that are available in the javax.management.Attribute class. You can
also extract a list of attributes.

Example: Collecting arguments for the AdminControl object: Verify that the arguments parameter is a
single string. Each individual argument in the string can contain spaces. Collect each argument that
contains spaces in some way.
v An example of how to obtain an MBean follows:
Using Jacl:
set am [$AdminControl queryNames type=ApplicationManager,process=server1,*]
Using Jython:
am = AdminControl.queryNames(’type=ApplicationManager,process=server1,*’)
v Multiple ways exist to collect arguments that contain spaces. Choose one of the following alternatives:

Chapter 4. Using the administrative clients 389

 Using Jacl:
– $AdminControl invoke $am startApplication {″JavaMail Sample″}
– $AdminControl invoke $am startApplication {{JavaMail Sample}}
– $AdminControl invoke $am startApplication ″\″JavaMail Sample\″″
Using Jython:
– AdminControl.invoke(am, ’startApplication’, ’[JavaMail Sample]’)
– AdminControl.invoke(am, ’startApplication’, ’\″JavaMail Sample\″’)

Example: Identifying running objects: In the WebSphere Application Server, MBeans represent running
objects. You can interrogate the MBean server to see the objects it contains. Use the AdminControl object
to interact with running MBeans.
v Use the queryNames command to see running MBean objects. For example:
Using Jacl:
$AdminControl queryNames *
Using Jython:
print AdminControl.queryNames(’*’)

This command returns a list of all MBean types. Depending on the server to which your scripting client
attaches, this list can contain MBeans that run on different servers:
– If the client attaches to a stand-alone WebSphere Application Server, the list contains MBeans that
run on that server.
– If the client attaches to a node agent, the list contains MBeans that run in the node agent and
MBeans that run on all application servers on that node.
– If the client attaches to a deployment manager, the list contains MBeans that run in the deployment
manager, all of the node agents communicating with that deployment manager, and all application
servers on the nodes served by those node agents.
v The list that the queryNames command returns is a string representation of JMX ObjectName objects. For
example:
WebSphere:cell=MyCell,name=TraceService,mbeanIdentifier=TraceService,type=TraceService,node=MyNode,process=server1

This example represents a TraceServer object that runs in server1 on MyNode.

v The single queryNames argument represents the ObjectName object for which you are searching. The
asterisk (″*″) in the example means return all objects, but it is possible to be more specific. As shown in
the example, ObjectName has two parts: a domain, and a list of key properties. For MBeans created by
the WebSphere Application Server, the domain is WebSphere. If you do not specify a domain when you
invoke queryNames, the scripting client assumes the domain is WebSphere. This means that the first
example query above is equivalent to:
Using Jacl:
$AdminControl queryNames WebSphere:*
Using Jython:
AdminControl.queryNames(’WebSphere:*’)
v WebSphere Application Server includes the following key properties for the ObjectName object:
– name
– type
– cell
– node
– process
– mbeanIdentifier
These key properties are common. There are other key properties that exist. You can use any of these
key properties to narrow the scope of the queryNames command. For example:
Using Jacl:
$AdminControl queryNames WebSphere:type=Server,node=myNode,*
Using Jython:

390 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 AdminControl.queryNames(’WebSphere:type=Server,node=myNode,*’)

This example returns a list of all MBeans that represent server objects running the node myNode. The,
* at the end of the ObjectName object is a JMX wildcard designation. For example, if you enter the
following:
Using Jacl:
$AdminControl queryNames WebSphere:type=Server,node=myNode
Using Jython:
print AdminControl.queryNames(’WebSphere:type=Server,node=myNode’)

you get an empty list back because the argument to queryNames is not a wildcard. There is no Server
MBean running that has exactly these key properties and no others.
v If you want to see all the MBeans representing applications running on a particular node, invoke the
following example:
Using Jacl:
$AdminControl queryNames WebSphere:type=Application,node=myNode,*
Using Jython:
print AdminControl.queryNames(’WebSphere:type=Application,node=myNode,*’)

Specifying running objects using the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to specify running objects:

1. Obtain the configuration ID with one of the following ways:
v Obtain the object name with the completeObjectName command, for example:
– Using Jacl:
set var [$AdminControl completeObjectName template]
– Using Jython:
var = AdminControl.completeObjectName(template)
where:

set is a Jacl command

var is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
template is a string containing a segment of the object name to be
matched. The template has the same format as an object
name with the following pattern:
[domainName]:property=value[,property=value]*. See
Object name, Attribute, Attribute list for more information.

If there are several MBeans that match the template, the completeObjectName command only
retuns the first match. The matching MBean object name is then assigned to a variable.
To look for server1 MBean in mynode, use the following example:
– Using Jacl:
set server1 [$AdminControl completeObjectName node=mynode,type=Server,name=server1,*]
– Using Jython:

Chapter 4. Using the administrative clients 391

 server1 = AdminControl.completeObjectName(’node=mynode,type=Server,name=server1,*’)
v Obtain the object name with the queryNames command, for example:
– Using Jacl:
set var [$AdminControl queryNames template]
– Using Jython:
var = AdminControl.queryNames(template)
where:

set is a Jacl command

var is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere Application server process.
queryNames is an AdminControl command
template is a string containing a segment of the object name to be
matched. The template has the same format as an object
name with the following pattern:
[domainName]:property=value[,property=value]*

2. If there are more than one running objects returned from the queryNames command, the objects are
returned in a list syntax. One simple way to retrieve a single element from the list is to use the lindex
command in Jacl and split command in Jython. The following example retrieves the first running object
from the server list:
v Using Jacl:
set allServers [$AdminControl queryNames type=Server,*]
set aServer [lindex $allServers 0]
v Using Jython:
allServers = AdminControl.queryNames(’type=Server,*’)

# get line separator

import java
lineSeparator = java.lang.System.getProperty(’line.separator’)

aServer = allServers.split(lineSeparator)[0]
For other ways to manipulate the list and then perform pattern matching to look for a specified
configuration object, refer to the Jacl syntax.

You can now use the running object in with other AdminControl commands that require an object name as
a parameter.

Identifying attributes and operations for running objects with the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the Help object attributes or operations commands to find information on a running MBean in the
server.
1. Specify a running object.
2. Use the attributes command to display the attributes of the running object:
v Using Jacl:
$Help attributes MBeanObjectName
v Using Jython:

392 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Help.attributes(MBeanObjectName)
where:

$ is a Jacl operator for substituting a variable name with its

value
Help is the object that provides general help and information
for running MBeans in the connected server process
attributes is a Help command
MBeanObjectName is the string representation of the MBean object name
obtained in step 2

3. Use the operations command to find out the operations supported by the MBean:
v Using Jacl:
$Help operations MBeanObjectname
or
$Help operations MBeanObjectname operationName
v Using Jython:
Help.operations(MBeanObjectname)
or
Help.operations(MBeanObjectname, operationName)
where:

$ is a Jacl operator for substituting a variable name with its

value
Help is the object that provides general help and information
for running MBeans in the connected server process
operations is a Help command
MBeanObjectname is the string representation of the MBean object name
obtained in step number 2
operationName (optional) is the specified operation for which you want to
obtain detailed information

If you do not provide the operationName, all operations supported by the MBean return with the
signature for each operation. If you specify operationName, only the operation that you specify returns
and it contains details which include the input parameters and the return value. To display the
operations for the server MBean, use the following example:
v Using Jacl:
set server [$AdminControl completeObjectName type=Server,name=server1,*]
$Help operations $server
v Using Jython:
server = AdminControl.completeObjectName(’type=Server,name=server1,*’)
print Help.operations(server)
To display detailed information about the stop operation, use the following example:
v Using Jacl:
$Help operations $server stop
v Using Jython:
print Help.operations(server, ’stop’)

Performing operations on running objects using the wsadmin tool:

Chapter 4. Using the administrative clients 393

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to perform operations on running objects:

1. Obtain the object name of the running object. For example:
v Using Jacl:
$AdminControl completeObjectName name
v Using Jython:
AdminControl.completeObjectName(name)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
name is a fragment of the object name. It is used to find the
matching object name. For example:
type=Server,name=serv1,*. It can be any valid
combination of domain and key properties. For example,
type, name, cell, node, process, etc.

2. Set the s1 variable to the running object, for example:

v Using Jacl:
set s1 [$AdminControl completeObjectName type=Server,name=server1,*]
v Using Jython:
s1 = AdminControl.completeObjectName(’type=Server,name=server1,*’)
where:

set is a Jacl command

s1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
type is the object name property key
Server is the name of the object
name is the object name property key
server1 is the name of the server where the operation will be
invoked

3. Invoke the operation. For example:

v Using Jacl:
$AdminControl invoke $s1 stop
v Using Jython:
AdminControl.invoke(s1, ’stop’)

394 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
invoke is an AdminControl command
s1 is the ID of the server specified in step number 3
stop is an operation to be invoked on the server

The following example is for operations that require parameters:

v Using Jacl:
set traceServ [$AdminControl completeObjectName type=TraceService,process=server1,*]
$AdminControl invoke $traceServ appendTraceString "com.ibm.ws.management.*=all=enabled"
v Using Jython:
traceServ = AdminControl.completeObjectName(’type=TraceService,process=server1,*’)
AdminControl.invoke(traceServ, ’appendTraceString’, "com.ibm.ws.management.*=all=enabled")

Modifying attributes on running objects with the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to modify attributes on running objects:

1. Obtain the name of the running object, for example:
v Using Jacl:
$AdminControl completeObjectName name
v Using Jython:
AdminControl.completeObjectName(name)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
name is a fragment of the object name. It is used to find the
matching object name. For example:
type=TraceService,node=mynode,*. It can be any valid
combination of domain and key properties. For example,
type, name, cell, node, process, etc.

2. Set the ts1 variable to the running object, for example:

v Using Jacl:
set ts1 [$AdminControl completeObjectName name]
v Using Jython:
ts1 = AdminControl.completeObjectName(name)
where:

set is a Jacl command

Chapter 4. Using the administrative clients 395

ts1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
name is a fragment of the object name. It is used to find the
matching object name. For example:
type=TraceService,node=mynode,*. It can be any valid
combination of domain and key properties. For example,
type, name, cell, node, process, etc.

3. Modify the running object, for example:

v Using Jacl:
$AdminControl setAttribute $ts1 ringBufferSize 10
v Using Jython:
AdminControl.setAttribute(ts1, ’ringBufferSize’, 10)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
setAttribute is an AdminControl command
ts1 evaluates to the ID of the server specified in step number
3
ringBufferSize is an attribute of modify objects
10 is the value of the ringBufferSize attribute

You can also modify multiple attribute name and value pairs, for example:
v Using Jacl:
set ts1 [$AdminControl completeObjectName type=TraceService,process=server1,*]
$AdminControl setAttributes $ts1 {{ringBufferSize 10} {traceSpecification com.ibm.*=all=disabled}}
v Using Jython list:
ts1 = AdminControl.completeObjectName(’type=TraceService,process=server1,*’)
AdminControl.setAttributes(ts1, [[’ringBufferSize’, 10], [’traceSpecification’, ’com.ibm.*=all=disabled’]])
v Using Jython string:
ts1 =AdminControl.completeObjectName(’type=TraceService,process=server1,*’)
AdminControl.setAttributes(ts1, ’[[ringBufferSize 10] [traceSpecification com.ibm.*=all=disabled]]’)
The new attribute values are returned to the command line.

Synchronizing nodes with the wsadmin tool:

This article only applies to network deployment installations. A node synchronization is necessary in order
to propagate configuration changes to the affected node or nodes. By default this occurs periodically, as
long as the node can communicate with the deployment manager. It is possible to cause this to happen
explicitly by performing the following steps:
1. Set the variable for node synchronize.
v Using Jacl:
set Sync1 [$AdminControl completeObjectName type=NodeSync,node=myNodeName,*]

396 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jython:
Sync1 = AdminControl.completeObjectName(’type=NodeSync,node=myNodeName,*’)
where:

set is a Jacl command

Sync1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
type=NodeSync,node=myNodeName is a fragment of the object name whose complete name
is returned by this command. It is used to find the
matching object name which is, in this case, the
SyncNode object for the node myNodeName, where
myNodeName is the name of the node that you use to
synchronize configuration changes. For example:
type=Server, name=serv1. It can be any valid
combination of domain and key properties. For example,
type, name, cell, node, process, etc.

Example output:
WebSphere:platform=common,cell=myNetwork,version=5.0,name=node
Sync,mbeanIdentifier=nodeSync,type=NodeSync,node=myBaseNode,
process=nodeagent
2. Synchronize by issuing the following command:
v Using Jacl:
$AdminControl invoke $Sync1 sync
v Using Jython:
AdminControl.invoke(Sync1, ’sync’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
invoke is an AdminControl command
Sync1 evaluates to the ID of the server specified in step number
7
sync is an attribute of modify objects

Example output:
true
You will receive an output value of true if the synchronization completes.

When the synchronization is complete, the files created in the c:/WebSphere/DeploymentManager/config

directory now exists on the mynode node in the c:/WebSphere/AppServer/config directory.

AdminConfig object for scripted administration: Use the AdminConfig object to manage the
configuration information that is stored in the repository. This object communicates with the WebSphere

Chapter 4. Using the administrative clients 397

Application Server configuration service component to make configuration inquires and changes. You can
use it to query existing configuration objects, create configuration objects, modify existing objects, remove
configuration objects, and obtain help.

Updates to the configuration through a scripting client are kept in a private temporary area called a
workspace and are not copied to the master configuration repository until you run a save command. The
workspace is a temporary repository of configuration information that administrative clients including the
administrative console use. The workspace is kept in the wstemp subdirectory of your WebSphere
Application Server installation. The use of the workspace allows multiple clients to access the master
configuration. If the same update is made by more than one client, it is possible that updates made by a
scripting client will not save because there is a conflict. If this occurs, the updates will not be saved in the
configuration unless you change the default save policy with the setSaveMode command.

The AdminConfig commands are available in both connected and local modes. If a server is currently
running, it is not recommended that you run the scripting client in local mode because the configuration
changes made in the local mode is not reflected in the running server configuration and vice versa. In
connnected mode, the availability of the AdminConfig commands depend on the type of server to which a
scripting client is connected in a Network Deployment installation.

The AdminConfig commands are available only if a scripting client is connected to a deployment manager.
When connected to a node agent or an application server, the AdminConfig commands will not be
available because the configuration for these server processes are copies of the master configuration that
resides in the deployment manager. The copies are created in a node machine when configuration
synchronization occurs between the deployment manager and the node agent. You should make
configuration changes to the server processes by connecting a scripting client to a deployment manager.
For this reason, to change a configuration, do not run a scripting client in local mode on a node machine.
It is not a supported configuration.

The following steps provide a general method to update a configuration object:

v Identify the configuration type and the corresponding attributes.
v Query an existing configuration object to obtain a configuration ID to use.
v Modify the existing configuration object or create a one.
v Save the configuration.

To see a list of all available commands for the AdminConfig object, see the Commands for the
AdminConfig object article or you can also use the Help command, for example:

Using Jacl:
$AdminConfig help

Using Jython:
print AdminConfig.help()

Creating configuration objects using the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform this task if you want to create an object. To create new objects from the default template, use the
create command. Alternatively, you can create objects using an existing object as a template with the
createUsingTemplate command.
1. Use the AdminConfig object listTemplates command to list available templates:
v Using Jacl:
$AdminConfig listTemplates JDBCProvider

398 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jython:
AdminConfig.listTemplates(’JDBCProvider’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
listTemplates is an AdminConfig command
JDBCProvider is an object type

2. Assign the ID string that identifies the existing object to which the new object is added. You can add
the new object under any valid object type. The following example uses a node as the valid object
type:
v Using Jacl:
set n1 [$AdminConfig getid /Node:mynode/]
v Using Jython:
n1 = AdminConfig.getid(’/Node:mynode/’)
where:

set is a Jacl command

$ is a Jacl operator for substituting a variable name with its
value
n1 is a variable name
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Node is an object type
mynode is the host name of the node where the new object is
added

3. Specify the template that you want to use:

v Using Jacl:
set t1 [$AdminConfig listTemplates JDBCProvider "DB2 JDBC Provider (XA)"]
v Using Jython:
t1 = AdminConfig.listTemplates(’JDBCProvider’, ’DB2 JDBC Provider (XA)’)
where:

set is a Jacl command

$ is a Jacl operator for substituting a variable name with its
value
t1 is a variable name
AdminConfig is an object representing the WebSphere Application
Server configuration
listTemplates is an AdminConfig command
JDBCProvider is an object type
DB2 JDBC Provider (XA) is the name of the template to use for the new object

If you supply a string after the name of a type, you get back a list of templates with display names that

Chapter 4. Using the administrative clients 399

 contain the string you supplied. In this example, the AdminConfig listTemplates command returns the
JDBCProvider template whose name matches DB2 JDBC Provider (XA). This example assumes that
the variable that you specify here only holds one template configuration ID. If the environment contains
multiple templates with the same string, for example, DB2 JDBC Provider (XA), the variable will hold
the configuration IDs of all of the templates. Be sure to identify the specific template that you want to
use before you perform the next step, creating an object using a template.
4. Create the object with the following command:
v Using Jacl:
$AdminConfig createUsingTemplate JDBCProvider $n1 {{name newdriver}} $tl
v Using Jython:
AdminConfig.createUsingTemplate(’JDBCProvider’, n1, [[’name’, ’newdriver’]], t1)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
createUsingTemplate is an AdminConfig command
JDBCProvider is an object type
n1 evaluates the ID of the host node specified in step
number 3
name is an attribute of JDBCProvider objects
newdriver is the value of the name attribute
t1 evaluates the ID of the template specified in step number
4

All create commands use a template unless there are no templates to use. If a default template exists,
the command creates the object.
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Interpreting the output of the AdminConfig attributes command using scripting:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

The attributes command is a wsadmin tool on-line help feature. When you issue the attributes command,
the information that displays does not represent a particular configuration object. It represents information
about configuration object types, or object metadata. This article discusses how to interpret the attribute
type display.
v Simple attributes
Using Jacl:
$AdminConfig attributes ExampleType1
"attr1 String"
Types do not display as fully qualified names. For example, String is used for java.lang.String. There
are no ambiguous type names in the model. For example, x.y.ztype and a.b.ztype. Using only the
final portion of the name is possible, and it makes the output easier to read.
v Multiple attributes
Using Jacl:

400 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 $AdminConfig attributes ExampleType2
"attr1 String" "attr2 Boolean" "attr3 Integer"
All input and output for the scripting client takes place with strings, but attr2 Boolean indicates that
true or false are appropriate values. The attr3 Integer indicates that string representations of
integers (″42″) are needed. Some attributes have string values that can take only one of a small
number of predefined values. The wsadmin tool distinguishes these values in the output by the special
type name ENUM, for example:
Using Jacl:
$AdminConfig attributes ExampleType3
"attr4 ENUM(ALL, SOME, NONE)"
where: attr4 is an ENUM type. When you query or set the attribute, one of the values is ALL, SOME, or
NONE. The value A_FEW results in an error.
v Nested attributes
Using Jacl:
$AdminConfig attributes ExampleType4
"attr5 String" "ex5 ExampleType5"
The ExampleType4 object has two attributes: a string, and an ExampleType5 object. If you do not know
what is contained in the ExampleType5 object, you can use another attributes command to find out.
The attributes command displays only the attributes that the type contains directly. It does not
recursively display the attributes of nested types.
v Attributes that represent lists
The values of these attributes are object lists of different types. The * character distinguishes these
attributes, for example:
Using Jacl:
$AdminConfig attributes ExampleType5
"ex6 ExampleType6*"
In this example, objects of the ExampleType5 type contain a single attribute, ex6. The value of this
attribute is a list of ExampleType6 type objects.
v Reference attributes
An attribute value that references another object. You cannot change these references using modify
commands, but these references display because they are part of the complete representation of the
type. Distinguish reference attributes using the @ sign, for example:
Using Jacl:
$AdminConfig attributes ExampleType6
"attr7 Boolean" "ex7 ExampleType7@"
ExampleType6 objects contain references to ExampleType7 type objects.
v Generic attributes
These attributes have generic types. The values of these attributes are not necessarily this generic type.
These attributes can take values of several different specific types. When you use the AdminConfig
attributes command to display the attributes of this object, the various possibilities for specific types are
shown in parentheses, for example:
Using Jacl:
$AdminConfig attributes ExampleType8
"name String" "beast AnimalType(HorseType, FishType, ButterflyType)"
In this example, the beast attribute represents an object of the generic AnimalType. This generic type is
associated with three specific subtypes. The wsadmin tool gives these subtypes in parentheses after the
name of the base type. In any particular instance of ExampleType8, the beast attribute can have a value
of HorseType, FishType, or ButterflyType. When you specify an attribute in this way, using a modify or
create command, specify the type of AnimalType. If you do not specify the AnimalType, a generic
AnimalType object is assumed (specifying the generic type is possible and legitimate). This is done by
specifying beast:HorseType instead of beast.

Chapter 4. Using the administrative clients 401

Specifying configuration objects using the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

To manage an existing configuration object, identify the configuration object and obtain configuration ID of
the object to be used for subsequent manipulation.
1. Obtain the configuration ID with one of the following ways:
v Obtain the ID of the configuration object with the getid command, for example:
– Using Jacl:
set var [$AdminConfig getid /type:name/]
– Using Jython:
var = AdminConfig.getid(’/type:name/’)
where:

set is a Jacl command

var is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
/type:name/ is the hierarchical containment path of the configuration
object
type is the object type
Note: The name of the object type that you input here is
the one based on the XML configuration files and does
not have to be the same name that the administrative
console displays.
name is the optional name of the object

You can specify multiple /type:name/ in the string, for example, /type:name/type:name/type:name/.
If you just specify the type in the containment path without the name, include the colon, for example,
/type:/. The containment path must be a path containing the correct hierarchical order. For
example, if you specify /Server:server1/Node:node/ as the containment path, you will not receive a
valid configuration ID because Node is parent of Server and should come before Server in the
hierarchy.
This command returns all the configuration IDs that match the representation of the containment and
assigns them to a variable.
To look for all the server configuration IDs resided in mynode, use the following example:
– Using Jacl:
set nodeServers [$AdminConfig getid /Node:mynode/Server:/]
– Using Jython:
nodeServers = AdminConfig.getid(’/Node:mynode/Server:/’)
To look for server1 configuration ID resided in mynode, use the following example:
– Using Jacl:
set server1 [$AdminConfig getid /Node:mynode/Server:server1/]
– Using Jython:
server1 = AdminConfig.getid(’/Node:mynode/Server:server1/’)
To look for all the server configuration IDs, use the following example:
– Using Jacl:

402 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set servers [$AdminConfig getid /Server:/]
– Using Jython:
servers = AdminConfig.getid(’/Server:/’)
v Obtain the ID of the configuration object with the list command, for example:
– Using Jacl:
set var [$AdminConfig list type]

or
set var [$AdminConfig list type scopeId]
– Using Jython:
var = AdminConfig.list(’type’)
or
var = AdminConfig.list(’type’, ’scopeId’)
where:

set is a Jacl command

var is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
list is an AdminConfig command
type is the object type
Note: The name of the object type that you input here is
the one based on the XML configuration files and does
not have to be the same name that the administrative
console displays.
scopeId is the configuration ID of a cell, node, or server object

This command returns a list of configuration object IDs of a given type. If you specify the scopeId,
the list of objects returned is within the scope specified. The list returned is assigned to a variable.
To look for all the server configuration IDs, use the following example:
– Using Jacl:
set servers [$AdminConfig list Server]
– Using Jython:
servers = AdminConfig.list(’Server’)
To look for all the server configuration IDs in mynode, use the following example:
– Using Jacl:
set scopeid [$AdminConfig getid /Node:mynode/]
set nodeServers [$AdminConfig list Server $scopeid]
– Using Jython:
scopeid = AdminConfig.getid(’/Node:mynode/’)
nodeServers = AdminConfig.list(’Server’, scopeid)
2. If there are more than more configuration IDs returned from the getid or list command, the IDs are
returned in a list syntax. One way to retrieve a single element from the list is to use the lindex
command. The following example retrieves the first configuration ID from the server object list:
v Using Jacl:
set allServers [$AdminConfig getid /Server:/]
set aServer [lindex $allServers 0]
v Using Jython:

Chapter 4. Using the administrative clients 403

 allServers = AdminConfig.getid(’/Server:/’)

# get line separator

import java
lineSeparator = java.lang.System.getProperty(’line.separator’)

arrayAllServers = allServers.split(lineSeparator)
aServer = arrayAllServers[0]
For other ways to manipulate the list and then perform pattern matching to look for a specified
configuration object, refer to the Jacl syntax.

You can now use the configuration ID in any subsequent AdminConfig commands that require a
configuration ID as a parameter.

Listing attributes of configuration objects using the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to create a list of attributes of configuration objects:

1. List the attributes of a given configuration object type, using the attributes command, for example:
v Using Jacl:
$AdminConfig attributes type
v Using Jython:
AdminConfig.attributes(’type’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
attributes is an AdminConfig command
type is an object type

This command returns a list of attributes and its data type.

To get a list of attributes for the JDBCProvider type, use the following example command:
v Using Jacl:
$AdminConfig attributes JDBCProvider
v Using Jython:
AdminConfig.attributes(’JDBCProvider’)
2. List the required attributes of a given configuration object type, using the required command, for
example:
v Using Jacl:
$AdminConfig required type
v Using Jython:
AdminConfig.required(’type’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration

404 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
required is an AdminConfig command
type is an object type

This command returns a list of required attributes.

To get a list of required attributes for the JDBCProvider type, use the following example command:
v Using Jacl:
$AdminConfig required JDBCProvider
v Using Jython:
AdminConfig.required(’JDBCProvider’)
3. List attributes with defaults of a given configuration object type, using the defaults command, for
example:
v Using Jacl:
$AdminConfig defaults type
v Using Jython:
AdminConfig.defaults(’type’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
defaults is an AdminConfig command
type is an object type

This command returns a list of all attributes, types, and defaults.

To get a list of attributes with defaults displayed for the JDBCProvider type, use the following example
command:
v Using Jacl:
$AdminConfig defaults JDBCProvider
v Using Jython:
AdminConfig.defaults(’JDBCProvider’)

Modifying configuration objects with the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to modify a configuration object:

1. Retrieve the configuration ID of the objects that you want to modify, for example:
v Using Jacl:
set jdbcProvider1 [$AdminConfig getid /JDBCProvider:myJdbcProvider/]
v Using Jython:
jdbcProvider1 = AdminConfig.getid(’/JDBCProvider:myJdbcProvider/’)
where:

set is a Jacl command

jdbcProvider1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value

Chapter 4. Using the administrative clients 405

AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
/JDBCProvider:myJdbcProvider/ is the hierarchical containment path of the configuration
object
JDBCProvider is the object type
myJdbcProvider is the optional name of the object

2. Show the current attribute values of the configuration object with the show command, for example:
v Using Jacl:
$AdminConfig show $jdbcProvider1
v Using Jython:
AdminConfig.show(jdbcProvider1)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
show is an AdminConfig command
jdbcProvider1 evaluates to the ID of host node specified in step number
2

3. Modify the attributes of the configuration object, for example:

v Using Jacl:
$AdminConfig modify $jdbcProvider1 {{description "This is my new description"}}
v Using Jython list:
AdminConfig.modify(jdbcProvider1, [[’description’, "This is my new description"]])
v Using Jython string:
AdminConfig.modify(jdbcProvider1, ’[[description "This is my new description"]]’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
modify is an AdminConfig command
jdbcProvider1 evaluates to the ID of host node specified in step number
3
description is an attribute of server objects
This is my new description is the value of the description attribute

You can also modify several attributes at the same time. For example:
v Using Jacl:
{{name1 val1} {name2 val2} {name3 val3}}
v Using Jython list:
[[’name1’, ’val1’], [’name2’, ’val2’], [’name3’, ’val3’]]
v Using Jython string:

406 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 ’[[name1 val1] [name2 val2] [name3 val3]]’
4. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
5. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Removing configuration objects with the wsadmin tool:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use this task to delete a configuration object from the configuration repository. This action only affects the
configuration. If there is a running instance of a configuration object when you remove the configuration,
the change has no effect on the running instance.
1. Assign the ID string that identifies the server you want to remove:
Using Jacl:
set s1 [$AdminConfig getid /Node:mynode/Server:myserver/]
Using Jython:
s1 = AdminConfig.getid(’/Node:mynode/Server:myserver/’)

where:

set is a Jacl command

s1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Node is an object type
mynode is the host name of the node from which the server is
removed
Server is an object type
myserver is the name of the server to remove

2. Remove the configuration object. For example:

v Using Jacl:
$AdminConfig remove $s1
v Using Jython:
AdminConfig.remove(s1)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
remove is an AdminConfig command
s1 evaluates the ID of the server specified in step number 2

Chapter 4. Using the administrative clients 407

3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

The WebSphere Application Server configuration no longer contains a specific server object. Running
servers are not affected.

Changing the WebSphere Application Server configuration using wsadmin:

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information. For this task, the wsadmin scripting client must be connected to
the deployment manager server in a network deployment environment.

You can use the wsadmin AdminConfig and AdminApp objects to make changes to the WebSphere
Application Server configuration. The purpose of this article is to illustrate the relationship between the
commands used to change the configuration and the files used to hold configuration data. This discussion
assumes that you have a network deployment installation, but the concepts are very similar for a
WebSphere Application Server installation.
1. Set a variable for creating a server:
v Using Jacl:
set n1 [$AdminConfig getid /Node:mynode/]
v Using Jython:
n1 = AdminConfig.getid(’/Node:mynode/’)
where:

set is a Jacl command

n1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Node is the object type
mynode is the name of the object that will be modified

2. Create a server with the following command:

v Using Jacl:
set serv1 [$AdminConfig create Server $n1 {{name myserv}}]
v Using Jython list:
serv1 = AdminConfig.create(’Server’, n1, [[’name’, ’myserv’]])
v Using Jython string:
serv1 = AdminConfig.create(’Server’, n1, ’[[name myserv]]’)
where:

set is a Jacl command

serv1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value

408 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
AdminConfig is an object representing the WebSphere Application
Server configuration
create is an AdminConfig command
Server is an AdminConfig object
n1 evaluates to the ID of host node specified in step number
2
name is an attribute
myserv is the value of the name attribute

After this command completes, some new files can be seen in a workspace used by the deployment
manager server on behalf of this scripting client. A workspace is a temporary repository of configuration
information that administrative clients use. Any changes made to the configuration by an administrative
client are first made to this temporary workspace. For scripting, only when a save command is invoked
on the AdminConfig object, these changes are transferred to the real configuration repository.
Workspaces are kept in the wstemp subdirectory of a WebSphere Application Server installation.
3. Make a configuration change to the server with the following command:
v Using Jacl:
$AdminConfig modify $serv1 {{stateManagement {{initialState STOP}}}}
v Using Jython list:
AdminConfig.modify(serv1, [[’stateManagement’, [[’initialState’, ’STOP’]]]])
v Using Jython string:
AdminConfig.modify(serv1, ’[[stateManagement [[initialState STOP]]]]’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
modify is an AdminConfig command
serv1 evaluates to the ID of host node specified in step number
3
stateManagement is an attribute
initialState is a nested attribute within the stateManagement attribute
STOP is the value of the initialState attribute

This command changes the initial state of the new server. After this command completes, one of the
files in the workspace is changed.
4. Install an application on the server.
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Modifying nested attributes with the wsadmin tool:

The attributes for a WebSphere Application Server configuration object are often deeply nested. For
example, a JDBCProvider object has an attribute factory, which is a list of the J2EEResourceFactory type
objects. These objects can be DataSource objects that contain a connectionPool attribute with a
ConnectionPool type that contains a variety of primitive attributes.
1. Invoke the AdminConfig object commands interactively, in a script, or use the wsadmin -c commands
from an operating system command prompt.

Chapter 4. Using the administrative clients 409

2. Obtain the configuration ID of the object, for example:
Using Jacl:
set t1 [$AdminConfig getid /DataSource:TechSamp/]
Using Jython:
t1=AdminConfig.getid(’/DataSource:TechSamp/’)

where:

set is a Jacl command

t1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
DataSource is the object type
TechSamp is the name of the object that will be modified

3. Modify one of the object parents and specify the location of the nested attribute within the parent, for
example:
Using Jacl:
$AdminConfig modify $t1 {{connectionPool {{reapTime 2003}}}}
Using Jython list:
AdminConfig.modify(t1, [["connectionPool", [["reapTime", 2003]]]])
Using Jython string:
AdminConfig.modify(t1, ’[[connectionPool [[reapTime 2003]]]]’)

where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
modify is an AdminConfig command
t1 evaluates to the configuration ID of the datasource in step
number 2
connectionPool is an attribute
reapTime is a nested attribute within the connectionPool attribute
2003 is the value of the reapTime attribute

4. Save the configuration by issuing an AdminConfig save command. For example:

Using Jacl:
$AdminConfig save
Using Jython:
AdminConfig.save()

Use the reset command of the AdminConfig object to undo changes that you made to your workspace
since your last save.

An alternative way to modify nested attributes is to modify the nested attribute directly, for example:

410 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Using Jacl:
set techsamp [$AdminConfig getid /DataSource:TechSamp/]
set pool [$AdminConfig showAttribute $techsamp connectionPool]
$AdminConfig modify $pool {{reapTime 2003}}

Using Jython list:

techsamp=AdminConfig.getid(’/DataSource:TechSamp/’)
pool=AdminConfig.showAttribute(techsamp,’connectionPool’)
AdminConfig.modify(pool,[[’reapTime’,2003]])

Using Jython string:

techsamp=AdminConfig.getid(’/DataSource:TechSamp/’)
pool=AdminConfig.showAttribute(techsamp,’connectionPool’)
AdminConfig.modify(pool,’[[reapTime 2003]]’)

In this example, the first command gets the configuration id of the DataSource, and the second command
gets the connectionPool attribute. The third command sets the reapTime attribute on the ConnectionPool
object directly.

Saving configuration changes with the wsadmin tool:

The wsadmin tool uses the workspace to hold configuration changes. You must save your changes to
transfer the updates to the master configuration repository. If a scripting process ends and you have not
saved your changes, the changes are discarded. Use the following commands to save the configuration
changes:
v Using Jacl:
$AdminConfig save
v Using Jython:
AdminConfig.save()

where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
save is an AdminConfig command

If you are using interactive mode with the wsadmin tool, you will be prompted to save your changes before
they are discarded. If you are using the -c option with the wsadmin tool, changes are automatically saved.

You can use the reset command of the AdminConfig object to undo changes that you made to your
configuration since your last save.

AdminTask object for scripted administration: Use the AdminTask object to access a set of
administrative commands that provide an alternative way to access the configuration commands and the
running object management commands. The administrative commands run simple and complex
commands. They provide more user friendly and task-oriented commands. The administrative commands
are discovered dynamically when you start a scripting client. The set of available administrative commands
depends on the edition of WebSphere Application Server you install. You can use the AdminTask object
commands to access these commands.

Administrative commands are grouped based on their function. You can use administrative command
groups to find related commands. For example, the administrative commands that are related to server
management are grouped into a server management command group. The administrative commands that

Chapter 4. Using the administrative clients 411

are related to the security management are grouped into a security management command group. An
administrative command can be associated with multiple command groups because it can be useful for
multiple areas of system management. Both administrative commands and administrative command
groups are uniquely identified by their name.

Two run modes are always available for each administrative command, namely the batch and interactive
mode. When you use an administrative command in interactive mode, you go through a series of steps to
collect your input interactively. This process provides users a text-based wizard and a similar user
experience to the wizard in the administrative console. You can also use the help command to obtain help
for any administrative command and the AdminTask object.

The administrative commands do not replace any existing configuration commands or running object
management commands but provide a way to access these commands and organize the inputs.
Depending on the administrative command, it can be available in connected or local mode. The set of
available administrative commands is determined when you start a scripting client in connected or local
mode. If a server is running, it is not recommended that you run the scripting client in local mode because
any configuration changes made in local mode are not reflected in the running server configuration and
vice versa. If you save a conflicting configuration, you could corrupt the configuration. In a deployment
manager environment, configuration updates are available only if a scripting client is connected to a
deployment manager. When connected to a node agent or a managed application server, you will not be
able to update the configuration because the configuration for these server processes are copies of the
master configuration which resides in the deployment manager. The copies are created on a node
machine when a configuration synchronization occurs between the deployment manager and the node
agent. Make configuration changes to the server processes by connecting a scripting client to a
deployment manager. For this reason, to change a configuration, do not run a scripting client in local mode
on a node machine. It is not a supported configuration.

Obtaining online help using scripting:

There are three levels of online help available with the administrative commands. The top level help
provides general information for the AdminTask object and the commands associated with it. The second
level help provides information about all of the available administrative commands and command groups.
The third level help provides specific help on a command group, a command, or a step. Command group
specific help provides descriptions for the command group that you specify and the commands that belong
to the associated group. Command specific help provides description for the specified command, its
parameters, and steps, if any. Step specific help provides a description for the specified step and the
associated parameters. For command and step specific help, required parameters are marked with a * in
the help output.
v To obtain general help, use the following examples:
Using Jacl:
$AdminTask help
Using Jython:
print AdminTask.help()
Example output:
WASX8001I: The AdminTask object enables the execution of available
admin commands. AdminTask commands operate in two modes:
the default mode is one which AdminTask communicates with the
WebSphere server to accomplish its task. A local mode is also
available in which no server communication takes place. The local
mode of operation is invoked by bringing up the scripting client
using the command line "-conntype NONE" option or setting the
"com.ibm.ws.scripting.connectiontype=NONE" property in
wsadmin.properties file.

The number of admin commands varies and depends on your WebSphere install.
Use the following help commands to obtain a list of supported commands
and their parameters:

412 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 help -commands
list all the admin commands
help -commandGroups
list all the admin command groups
help commandName
display detailed information for
the specified command
help commandName stepName
display detailed information for
the specified step belonging to
the specified command
help commandGroupName
display detailed information for
the specified command group

There are various flavors to invoke an admin command:

commandName
invokes an admin command that does not require any argument.

commandName targetObject
invokes an admin command with the specified target object
string, for example, the configuration object name of a
resource adapter. The expected target object varies with
the admin command invoked. Use help command to get
information on the target object of an admin command.

commandName options
invokes an admin command with the specified option
strings. This invocation syntax is used to invoke an
admin command that does not require a target object. It
is also used to enter interactive mode if "-interactive"
mode is included in the options string.

commandName targetObject options

invokes an admin command with the specified target
object and options strings. If "-interactive" is
included in the options string, then interactive mode
is entered. The target object and options strings vary
depending on the admin command invoked. Use help
command to get information on the target
object and options.
v To list the available command groups, use the following examples:
Using Jacl:
$AdminTask help -commandGroups
Using Jython:
print AdminTask.help(’-commandGroups‘)
Example output:
WASX8005I: Available admin command groups:

ClusterConfigCommands - Commands for configuring application

server clusters and cluster members.
JCAManagement - A group of admin commands that helps to configure
Java2 Connector Architecture(J2C) related resources.
v To list the available commands, use the following examples:
Using Jacl:
$AdminTask help -commands
Using Jython:
print AdminTask.help(’-commands‘)
Example output:

Chapter 4. Using the administrative clients 413

 WASX8004I: Available administrative commands:

copyResourceAdapter - copy the specified J2C resource adapter to the specified scope
createCluster - Creates a new application server cluster.
createClusterMember - Creates a new member of an application server cluster.
createJ2CConnectionFactory - Create a J2C connection factory
deleteCluster - Delete the configuration of an application server cluster.
deleteClusterMember - Deletes a member from an application server cluster.
listConnectionFactoryInterfaces - list all of the
defined connection factory interfaces on the
specified J2C resource adapter.
listJ2CConnectionFactories - List J2C connection factories that have a specified
connection factory interface defined in the specified J2C resouce adapter
createJ2CAdminObject - Create a J2C administrative object.
listAdminObjectInterfaces - List all the defined administrative object interfaces
on the specified J2C resource adapter.
interface on the specified J2C resource adapter.
listJ2CAdminObjects - List the J2C administrative objects that have a specified
administrative object interface defined in the specified J2C resource adapter.
createJ2CActivationSpec - Create a J2C activation specification.
listMessageListenerTypes - list all of the defined messageListener
type on the specified J2C resource adapter.
listJ2CActivationSpecs - List the J2C activation specifications that have a
specified message listener type defined in the specified J2C resource adapter.
v To obtain help about a command group, use the following examples:
Using Jacl:
$AdminTask help JCAManagement
Using Jython:
print AdminTask.help(’JCAManagement‘)
Example output:
WASX8007I: Detailed help for command group: JCAManagement

Description: A group of administrative commands that help to

configure Java 2 Connector Architecture (J2C)-related resources.

Commands:
createJ2CConnectionFactory - Create a J2C connection factory
listConnectionFactoryInterfaces - list all of the defined connection
factory interfaces on the specified J2C resource adapter.
listJ2CConnectionFactories - List J2C connection factories that have
a specified connection factory interface defined in the
specified J2C resouce adapter.
createJ2CAdminObject - Create a J2C administrative object.
listAdminObjectInterfaces - List all the defined administrative
object interfaces on the specified J2C resource adapter.
listJ2CAdminObjects - List the J2C administrative objects that have a
specified adminstrative object interface defined in the
specified J2C resource adapter.
createJ2CActivationSpec - Create a J2C activation specification.
listMessageListenerTypes - list all of the defined
message listener types on the specified J2C resource adapter.
listJ2CActivationSpecs - List the J2C activation specifications that
have a specified message listener type defined in the
specified J2C resource adapter.
copyResourceAdapter - copy the specified J2C resource
adapter to the specified scope.
v Obtaining help about an administrative command:
Using Jacl:
$AdminTask help createJ2CConnectionFactory
Using Jython:
print AdminTask.help(’createJ2CConnectionFactory‘)

414 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Example output:
WASX8006I: Detailed help for command: createJ2CConnectionFactory

Description: Create a J2C connection factory

*Target object: The parent J2C resource adapter of the created J2C connection factory.

Arguments:
*connectionFactoryInterface - A connection factory interface that is defined in the deployment
description of the parent J2C resource adapter.
*name - The name of the J2C connection factory.
*jndiName - The JNDI name of the created J2C connection factory.
description - The description for the created J2C connection factory.
authDataAlias - the authentication data alias of the created J2C connection factory.

Steps:
None
In the command specific help output previously listed, an administrative command is divided into three
input areas: target object, arguments, and steps. Each area can require input depending on the
administrative command. If an area requires input, each input is described by its name and a
description; except for the target object area which only contains the description of the target object.
When you use an administrative command in batch mode, you can use any input name that resides in
the argument area as the argument name. If an input is required, a * will be before the name. If an area
does not require an input, it is marked None. The following example uses the help output for the
createJ2CConnectionFactory command:
– Target object area requires the configuration object name of a J2CResourceAdapter to be provided.
– In the arguments area, there are five inputs with three being required inputs. The argument names
are connectionFactoryInterface, name, jndiName, description, and authDataAlias. These names are
used as the parameter names in the option string to execute an admin command in batch mode, for
example:
-connectionFactoryInterface javax.resource.cci.ConnectionFactory -name newConnectionFactory
-jndiName CF/newConnectionFactory

See “Administrative command invocation syntax” on page 806 for more information about specifying
argument options.
– There is no step associated with this administrative command.
v Obtain help on a command step.
Step specific help provides the following:
– A description for the command step.
– Information indicating if this step supports collection. A collection includes objects of the same type.
In a command step, a collection contains objects that have the same set of parameters.
– Information regarding each step parameter with its name and description. If a step parameter is
required, a * exists in front of the name.
The following example obtain help on a command step:
Using Jacl:
$AdminTask help createCluster clusterConfig
Using Jython:
print AdminTask.help(’createCluster‘, ’clusterConfig‘)
Example output:
WASX8013I: Detailed help for step: clusterConfig

Description: Specifies the configuration of the new server cluster.

Collection: No

Chapter 4. Using the administrative clients 415

 Arguments:
*clusterName - Name of server cluster.
preferLocal - Enables node-scoped routing optimization for the cluster.
This example indicates the following:
– It does not support collection. Only one set of parameter values for the clusterName and perferLocal
parameters is allowed.
– It contains two input arguments with one argument indicated as required. The required arguments is
clusterName and the non-required parameter is perferLocal. The syntax to provide step parameter
values is different from the command argument values. You have to provide all argument values of a
step and provide them in the exact order as displayed in the step specific help. For any optional
argument that you do not want to specify a value, put double quotes (″″) in place of a value. If a
command step is a collection type, for example, it can contain multiple objects where each object
has the same set of arguments, you can specify multiple objects with each object enclosed by its
own pair of braces. To execute an administrative command in batch mode and to include this step in
the option string, use the following syntax:
Using Jacl:
-clusterConfig {{newCluster false}}
Using Jython:
-clusterConfig [[newCluster false]]

See “Administrative command invocation syntax” on page 806 for more information about specifying
parameter options.

Invoking an administrative command in batch mode:

Perform the following steps to invoke an administrative command in batch mode. To invoke an
administrative command in interactive mode, see “Invoking an administrative command in interactive
mode” on page 421.
1. Invoke the AdminTask object commands interactively, in a script, or use the wsadmin -c command
from an operating system command prompt.
2. Issue one of the following commands:
v If an administrative command does not have a target object and an argument, use the following
command:
Using Jacl:
$AdminTask commandName
Using Jython:
AdminTask.commandName()
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked

v If an administrative command includes a target object but does not include any arguments or steps,
use the following command:
Using Jacl:
$AdminTask commandName targetObject
Using Jython:
AdminTask.commandName(targetObject)

416 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked
targetObject is the target object string for the invoked administrative
command. The expect target object varies with each
administrative command. View the online help for the
invoked administrative command to learn more about
what you should specify as the target object.

v If an administrative command includes an argument or a step but does not include a target object,
use the following command:
Using Jacl:
$AdminTask commandName options
Using Jython:
AdminTask.commandName(options)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked

Chapter 4. Using the administrative clients 417

options is the option string for the invoked administrative
command. Depending on which administrative command
you are invoking, the administrative command can have
required or optional option values. The options string is
different for each administrative command. View the
online help for the invoked administrative command to
obtain more information about which options are
available. Arguments and steps listed on the online
administrative command help are specified as options in
the option string. Each option consists of a dash followed
immediately by an option name, and then followed by an
option value if the option requires a value. If the invoked
administrative command includes target objects,
arguments, or steps, then the –interactive option is
available to enter interactive mode. For example, using
the output of the following online help for listDataSource:
WASX8006I: Detailed help for command: exportServer

Description: export the configuration

of a server to a config archive.

Target object: None

Arguments:
*serverName - the name of a server
*nodeName - the name of a node. This parameter
becomes optional if the specified server name
is unique across the cell.
*archive - the fully qualified file path of a config
archive.

Steps:
None

Option names are specified with a dash before the

names. There are three required options for this
administrative command. The required options are
-serverName, -nodename, and -archive. In addition, the
-interactive option is available. Options are specified in
the option string which is enclosed by a pair of {} in Jacl
and a pair of [] in Jython.

v If an administrative command includes a target object, and arguments or steps:

Using Jacl:
$AdminTask commandName targetObject options
Using Jython:
AdminTask.commandName(targetObject, options)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked

418 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
targetObject is the target object string for the invoked administrative
command. The expected target object varies with each
administrative command. View the online help for the
invoked administrative command to obtain information
about what to specify as a target object. For example,
using the output of the following online help for
createJ2CConnectionFactory:
WASX8006I: Detailed help for command:
createJ2CConnectionFactory

Description: Create a J2C connection factory

*Target object: The parent J2C resource adapter of

the created J2C connection factory.

Arguments:
*connectionFactoryInterface - A connection factory
interface that is defined in the deployment description
of the parent J2C resource adapter.
*name - The name of the J2C connection factory.
*jndiName - The JNDI name of the created J2C
connection factory.
description - The description for the created J2C
connection factory.
authDataAlias - the authentication data alias of the
created J2C connection factory.

Steps:
None

The target object is a configuration object name of a

J2CResourceAdapter.

Chapter 4. Using the administrative clients 419

options is the option string for the invoked administrative
command. Depending on which administrative command
you are invoking, the administrative command can have
required or optional option values. The options string is
different for each administrative command. View the
online help for the invoked administrative command to
obtain more information about which options are
available. Arguments and steps listed on the online
administrative command help are specified as options in
the option string. Each option consists of a dash followed
immediately by an option name, and then followed by an
option value if the option requires a value. If the invoked
administrative command includes target objects,
arguments, or steps, then the –interactive option is
available to enter interactive mode. For example, using
the output of the following online help for listDataSource:
WASX8006I: Detailed help for command:
createJ2CConnectionFactory

Description: Create a J2C connection factory

*Target object: The parent J2C resource adapter

of the created J2C connection factory.

Arguments:
*connectionFactoryInterface - A connection factory
interface that is defined in the deployment description
of the parent J2C resource adapter.
*name - The name of the J2C connection factory.
*jndiName - The JNDI name of the created J2C
connection factory.
description - The description for the created J2C
connection factory.
authDataAlias - the authentication data alias of the
created J2C connection factory.

Steps:
None

Option names are specified with a dash before the

names. There are three required options for this
administrative command. The required options are
-connectionFactoryInterface, -name, and -jndiName.
There are two optional options. They are -description and
-authDataAlias. In addition, the -interactive option is
available. Options are specified in the option string which
is enclosed by a pair of {} in Jacl and a pair of [] in
Jython.

v The following example invokes an administrative command with no target object, argument, or step:
Using Jacl:
$AdminTask listNodes
Using Jython:
print AdminTask.listNodes()
Example output:
myNode
v The following example invokes an administrative command with a target object string:
Using Jacl:

420 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set s1 [$AdminConfig getid /Server:server1/]
$AdminTask showServerInfo $s1
Using Jython:
s1 = AdminConfig.getid(’/Server:server1/’)
print AdminTask.showServerInfo(s1)
Example output:
{cell myCell}
{serverType APPLICATION_SERVER}
{com.ibm.websphere.baseProductVersion 6.0.0.0}
{node myNode}
{server server1}
v The following example invokes an administrative command with an option string:
Using Jacl:
$AdminTask getNodeMajorVersion {-nodeName myNode}
Using Jython:
print AdminTask.getNodeMajorVersion(’[-nodeName myNode]’)
Example output:
6
v The following example invokes an administrative command with target object and non-step option
strings:
Using Jacl:
set ra [$AdminConfig getid /J2CResourceAdapter:myResourceAdapter/]
$AdminTask createJ2CConnectionFactory
$ra {-name myJ2CCF -jndiName j2c/cf -connectionFactoryInterface javax.resource.cci.ConnectionFactory}
Using Jython:
ra = AdminConfig.getid(’/J2CResourceAdapter:myResourceAdapter/‘)
AdminTask.createJ2CConnectionFactory(ra,
’[-name myJ2CCF -jndiName j2c/cf -connectionFactoryInterface javax.resource.cci.ConnectionFactory]‘)
Example output:
myJ2CCF(cells/myCell/nodes/myNode|resources.xml#J2CConnectionFactory_1069690568269)
v The following example invokes an administrative command with a target object and a step option:
Using Jacl:
set serverCluster [$AdminConfig getid /ServerCluster:myCluster/]
$AdminTask createClusterMember $serverCluster {-memberConfig {{myNode myClusterMember "" "" false false}}}
Using Jython:
serverCluster = AdminConfig.getid(’/ServerCluster:myCluster/‘)
AdminTask.createClusterMember(serverCluster, ’[-memberConfig [[myNode myClusterMember "" "" false false]]]’)
Example output:
myClusterMember(cells/myCell/nodes/myNode|cluster.xml#ClusterMember_3673839301876)

Invoking an administrative command in interactive mode:

Perform the following steps to invoke an administrative command in interactive mode. To invoke an
administrative command in batch mode, see “Invoking an administrative command in batch mode” on page
416.
1. Invoke the AdminTask object commands interactively, in a script, or use the wsadmin -c command
from an operating system command prompt.
2. Invoke an administrative command in interactive mode by issuing one of the following commands:
v Use the following command invocation to enter interactive mode without providing another input in
the command invocation:
Using Jacl:
$AdminTask commandName {-interactive}

Chapter 4. Using the administrative clients 421

 Using Jython:
AdminTask.commandName(’[-interactive]‘)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked
-interactive is the interactive option

v Use the following command invocation to enter interactive mode using an administrative command
that takes a target object. You do not have to provide a target object to enter interactive mode.
Target objects provided in the command invocation will be applied to the command and displayed as
the current target object value during interactive prompting.
Using Jacl:
$AdminTask commandName targetObject {-interactive}
Using Jython:
AdminTask.commandName(targetObject, ’[-interactive]‘)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked
targetObject is the target object string for the invoked administrative
command. The target object is different for each
administrative command. View the online help for the
invoked administrative command to learn more about
what to specify as a target object.
-interactive is the interactive option

v Use the following command invocation to enter interactive mode for an administrative command that
takes options. You do not have to provide other options to enter interactive mode. Options provided
in the command invocation are applied to the command and the option values will be displayed as
the current values during interactive prompting.
Using Jacl:
$AdminTask commandName {-interactive commandOptions}
Using Jython:
AdminTask.commandName(’[-interactive commandOptions]‘)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked
-interactive is the interactive option

422 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
commandOptions is the command option available for the associated
administrative command. Available command options are
different for each administrative command. View the
online help for the invoked administrative command to
obtain more information about which options are
available. Arguments and steps listed on the online
administrative command help are specified as command
options. Each option consists of a dash followed
immediately by an option name, and then followed by an
option value if the option requires a value. For example,
using the output of the following online help for
createJ2CConnectionFactory:
WASX8006I: Detailed help for command: createJ2CConnectionFactory

Description: Create a J2C connection factory

*Target object: The parent J2C resource adapter of the created J2C

Arguments:
*connectionFactoryInterface - A connection factory interface that i
*name - The name of the J2C connection factory.
*jndiName - The JNDI name of the created J2C connection factory.
description - The description for the created J2C connection factor
authDataAlias - the authentication data alias of the created J2C co

Steps:
None

In this example, there are five options available:

v -connectionFactoryInterface
v -name
v -jndiName
v -description
v -authDataAlias
Each requires an option value. Only three of the options
are required and are denoted with a *.

v Use the following command invocation to enter interactive mode for an administrative command that
has a target object and options. You do not have to specify a target object to enter interactive mode.
The values specified are applied to the command before the command data is displayed. As a
result, the values specified will be displayed as the current values during interactive prompting.
Using Jacl:
$AdminTask commandName targetObject {-interactive commandOptions}
Using Jython:
AdminTask.commandName(targetObject, ’[-interactive commandOptions]‘)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminTask is an object allowing administrative command
management
commandName is the name of the administrative command being invoked

Chapter 4. Using the administrative clients 423

targetObject is the target object string for the invoked admin
command. The expect target object varies with each
admin command. Consult the on-line help on the invoked
admin command to learn more about what to specify as
target object.
-interactive is the interactive option
commandOptions is the command option available for the associated
administrative command. Available command options are
different for each administrative command. View the
online help for the invoked administrative command to
obtain more information about which options are
available. Arguments and steps listed on the online
administrative command help are specified as command
options. Each option consists of a dash followed
immediately by an option name, and then followed by an
option value if the option requires a value. For example,
using the output of the following online help for
createJ2CConnectionFactory:
WASX8006I: Detailed help for command: createJ2CConnectionFactory

Description: Create a J2C connection factory

*Target object: The parent J2C resource adapter of the created J2C co

Arguments:
*connectionFactoryInterface - A connection factory interface that is
*name - The name of the J2C connection factory.
*jndiName - The JNDI name of the created J2C connection factory.
description - The description for the created J2C connection factory.
authDataAlias - the authentication data alias of the created J2C conn

Steps:
None

In this example, there are five options available:

v -connectionFactoryInterface
v -name
v -jndiName
v -description
v -authDataAlias
Each requires an option value. Only three of the options
are required and are denoted with a *.

v The following example invokes an administrative command in interactive mode by specifying the
-interactive option:
Using Jacl:
$AdminTask createJ2CConnectionFactory {-interactive}
Using Jython:
AdminTask.createJ2CConnectionFactory(’[-interactive]’)
Example output:
Create a J2C connection factory

*The J2C resource adapter: "WebSphere Relational ResourceAdapter

(cells/myCell/nodes/myNode|resources.xml#builtin_rra)"

A connection factory
interface (connectionFactoryInterface):javax.resource.cci.ConnectionFactory

424 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 *Name (name): myJ2CCF
*The JNDI name (jndiName): j2c/cf
Description (description):
authentication data alias (authDataAlias):

create J2C connection factory

F (Finish)
C (Cancel)

Select [F, C]: [F]

myJ2CCF(cells/myCell/nodes/myNode|resources.xml#J2CConnectionFactory_1069690568269)
v The following example invokes an administrative command using the –interactive option with a target
object specified in the command invocation:
Using Jacl:
set ra [$AdminConfig getid /J2CResourceAdapter:myResourceAdapter/]
$AdminTask createJ2CConnectionFactory $ra {-interactive}
Using Jython:
ra = AdminConfig.getid(’/J2CResourceAdapter:myResourceAdapter/’)
AdminTask.createJ2CConnectionFactory(ra, ’[-interactive]‘)
Example output:
Create a J2C connection factory

*The J2C resource adapter: ["WebSphere Relational ResourceAdapter

(cells/myCell/nodes/myNode|resources.xml#builtin_rra)"]

A connection factory interface (connectionFactoryInterface):

javax.resource.cci.ConnectionFactory
*Name (name): myJ2CCF
*The JNDI name (jndiName): j2c/cf
Description (description):
authentication data alias (authDataAlias):

create J2C Connection Factory

F (Finish)
C (Cancel)

Select [F, C]: [F]

myJ2CCF(cells/myCell/nodes/myNode|resources.xml#J2CConnectionFactory_1069690568269)
v The following example invokes an administrative command using the –interactive option where both the
target object and the additional command options are specified in the command invocation:
Using Jacl:
set ra [$AdminConfig getid /J2CResourceAdapter:myResourceAdapter/]
$AdminTask createJ2CConnectionFactory $ra {-name myNewCF -interactive}
Using Jython:
ra = AdminConfig.getid(’/J2CResourceAdapter:myResourceAdapter/’)
AdminTask.createJ2CConnectionFactory(ra, ’[-name myNewCF -interactive]‘)
Example output:
Create a J2C connection factory

*The J2C resource adapter: ["WebSphere Relational ResourceAdapter

(cells/myCell/nodes/myNode|resources.xml#builtin_rra)"]

A connection factory interface (connectionFactoryInterface):javax.resource.cci.ConnectionFactory

*Name (name): [myNewCF]
*The JNDI name (jndiName): j2c/cf
Description (description):

Chapter 4. Using the administrative clients 425

 authentication data alias (authDataAlias):

create J2C Connection Factory

F (Finish)
C (Cancel)

Select [F, C]: [F]

myNewCF(cells/myCell/nodes/myNode|resources.xml#J2CConnectionFactory_3839439380269)

Administrative command interactive mode environment: An administrative command can be run in

interactive mode by providing the -interactive option in the options string when invoking the command. You
can still provide other options, even when using the interactive option. The options values that are
specified are applied to the command before the command data is displayed. Whether or not other options
are specified, the wsadmin tool steps the user through the command to collect command information.

The general interactive flow sequence is:

1. Collect user inputs for target object and parameters
2. If the command does not include a step, the command execution menu displays to run or cancel the
command.
3. If the command includes a step, the menu to select the step displays. When all the required inputs are
entered, the menu includes command execution.
4. When a step is selected, if the step supports collection, then the menu to select an object in the
collection displays and you can exit the step. If you exit the step, repeat steps 3-5.
5. Collect user inputs for the selected step or for an object in the collection
6. Repeat steps 4 and 5 if from the collection step menu
7. Repeat steps 3-5 if from step selection menu

Depending on what input area is enabled by an administrative command, you can go through part or all of
the interactive flow sequence. If an administrative command is run in interactive mode, the syntax to run
the command except for the deletion of collection object in batch mode is generated and logged as a
WASX7278I message in both the interactive session and in the wsadmin trace file.

Collect user inputs for target object and parameters

The following interactive prompt is used to collect inputs for the Target object and Arguments input areas
that are displayed in the command-specific help:
Command title

Command Description

*target object title [current or default value]:

*param1 title (param1 name) [choice1, choice2, ...]: [current/default value]
param2 title (param2 name) [choice1, choice2, ...]: [current/default value]
...

This screen is usually the first interactive screen that is displayed when an administrative command is
invoked interactively unless the invoked command does not contain any target object and non-step
command parameters.If a command does not have a target object, then the prompt for the target object is
skipped. The number of parameters depends on the number of arguments in the Argument area of the
command-specific help. If an input is required, then an asterisk (*) is placed in front of the title. The
parameter name is displayed for information and is the name that is used to set this parameter in batch
mode. If a parameter value is restricted to a set of values, then the valid choices are displayed. If current
or default value is available, it is displayed. You can accept the existing value by clicking Enter. To add or
change an existing value, enter a new value and click Enter.

426 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Display command execution menu

If an administrative command does not contain a step, you are presented with the following menu after
collecting values for target object and parameters:
Command title

F (Finish)
C (Cancel)

Select [F, C]: F

The Finish option runs the command and the Cancel option cancels the command. The default selection is
F (Finish). This menu is the last menu that is displayed for a non-step command to exit interactive mode
by either canceling or running the command.

Display command step selection and execution menu

If an administrative command contains a step, the following menu is displayed after collecting values for
target object and parameters:
Command title
Command description
-> *1. step1 title (step1 name)
2. step2 title (step2 name)
*3. step3 title (step3 name)
(4. step4 title (step4 name))
...
n. stepn title (stepn name)

S (Select)
N (Next)
P (Previous)
F (Finish)
C (Cancel)
H (Help)

Select [S, N, P, F, C, H]: S

The number of steps that is displayed in the menu depends on the adminstative command. The step name
is displayed for information and is the name that is used to set data in this step in batch mode. The
following notations are used to describe a step:
v A “->” before the step indicates the current step position.
v A “*” before the step indicates a required step.
v A ( ) enclosing the entire step indicates a disabled step. You cannot navigate to this step by using the
Next or Previous options.

Using the menu, you can navigate through steps sequentially by selecting Previous or Next. Select selects
the current step, Finish runs the command, Cancel cancels the command, and Help provides on-line help
for the command. Not all menu choices are available. Previous is not available if current step is the first
step. Next is not be available if current step is the last step. Finish is not available if still steps are still
missing required inputs. The default selection is S (Select) if the current step is a valid step and there are
still steps missing required inputs. Default selection is F (Finish) if there is no missing required input in any
step.

For commands with steps, this is the menu to exit interactive mode by either canceling or executing the
command.

Display collection step menu

Chapter 4. Using the administrative clients 427

A step might or might not support collection. A collection refers to objects of the same type. In an
administrative command, a collection contains objects with each having the same set of parameters. If a
step supporting collection is selected, the wsadmin tool displays the following menu to add and select an
object in the collection:
Step title (step name)
| key param1 title (key param1 name), key param2 title (key param2 name), ...
---------------------------------------------------------------------------
-> | object1 key param1 value, key param2 value, ...
*| object2 key param1 value, key param2 value, ...
...
key param1 title, key param2 title, ... must be provided to specify a row in batch row.

S (Select Row)
N (Next)
P (Previous)
A (Add Row or Add Row Before)
D (Delete Row)
F (Finish)
H (Help)

Select [S, N, P, A, D, F, H]: F

The number of objects that display in the menu depends on the command step. Key parameters are
identified by the step to use to uniquely identify an object in a collection. Key parameter values are
displayed so as to identify an object to select. As with the command step selection menu, an arrow (->) is
used to indicate the current object position, and a asterisk (*) is used to indicate that required input is
missing in the object.

Use the menu to navigate through objects sequentially by selecting Previous or Next. Select Row selects
the current object, Add Row adds a new object, Add Row Before adds a new object before the current
object, Delete Row deletes the current object, Finish returns control back to the step selection and
execution menu, and Help provides on-line help for the step. Not all menu choices are available. Previous
is not available if there is no object in the collection or the first object is the current object. Next is not
available if there is no object in the collection or the last object is the current object. Select Row is
available only if there is a current object. Add Row is provided only if there is no object in the collection
and the step supports new object to be added. Add Row Before is provided if the step supports new object
to be added and there are existing objects in the collection. Delete Row is provided only if there is a
current object and the step allows object to be deleted. Finish is not available if there are still objects
missing required inputs. Default selection is A (Add Row) when there is no object in the collection and the
step supports objects to be added. Default selection is S (Select Row) if there is a current object and there
are still objects missing required inputs. Default selection is F (Finish) if there is no required input missing
in any object.

Collect user inputs for parameters of a collection object

After a collection object is selected, the parameter value for each parameter is prompted sequentially as
shown in the following example:
*param1 title (param1 name) [choice1, choice2, ...]: [current/default value]
param2 title (param2 name) [choice1, choice2, ...]: [current/default value]
...

The number of parameters depends on the number of arguments in the “Argument” area of the command
step specific help. The same “*” notation is used to denote required parameter. If a parameter value is
restricted to a set of values, then the valid choices are displayed. If current or default value is available, it
is displayed. For each writable parameter, you can accept the existing value by pressing the Enter key. To
add or change an existing value, user simply enters a new value and then presses Enter. For a read-only
parameter, the parameter and its value are displayed. However, user is not given the prompt to modify its
value. Once user steps through all the parameters, wsadmin leads user back to the collection step menu.

428 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Collect user inputs for non-collection step

There are two parts for this step. The first part is to display the current or default parameter values for the
selected step as shown below:
Step title (step name)

*param1 title (param1 name) [choice1, choice2, ...]: [current/default value]

param2 title (param2 name) [choice1, choice2, ...]: [current/default value]
...

Select [C (Cancel), E (Edit)]: [E]

There is no prompting in this part. Instead, this part is more like a help providing parameter information on
the selected step. The number of parameters depends on the number of arguments in the argument area
of the command step specific help. The asterisk (*) notation denotes a required parameter. If a parameter
value is restricted to a set of values, then the valid choices will be displayed. If current or default value is
available, it is displayed. You can choose to cancel the step or continue to the next part to provide
parameter inputs. The default selection is Edit. Since it is possible that you are seeing default values
assigned to a new piece of data that is not yet set in the step, you should always accept the default
selection to continue to the next part. Otherwise, if there is no data in the selected step, selecting Cancel
will not result in creating the data.

If you accept the default Edit selection, collect user inputs for parameters sequentially just like “Collect
user inputs for parameters of a collection object”.
*param1 title (param1 name) [choice1, choice2, ...]: [current/default value]
param2 title (param2 name) [choice1, choice2, ...]: [current/default value]
...

For each writable parameter, you can accept the existing value by clicking Enter. To add or change an
existing value, enter a new value and then press Enter. For a read-only parameter, the parameter and its
value are displayed. You will not be given the prompt to modify the value of the parameter. As soon as you
step through all the parameters, the wsadmin tool will lead you back to the command step selection and
execution menu.

Starting the wsadmin scripting client

The WebSphere Application Server wsadmin tool provides the ability to run scripts. You can use the
wsadmin tool to manage a WebSphere Application Server V6.0 installation, as well as configuration,
application deployment, and server run-time operations. The WebSphere Application Server only supports
the Jacl and Jython scripting languages.

The wsadmin launcher makes several WebSphere Application Server scripting objects available:
AdminConfig, AdminControl, AdminApp, AdminTask, and Help. Scripts use these objects for application
management, configuration, operational control, and for communication with MBeans that run in
WebSphere Application Server processes.

You must start the wsadmin scripting client before you perform any other task using scripting.
1. Locate the command that starts the wsadmin scripting client.
The command for invoking a scripting process is located in the install_root/profiles/profile_name/bin
directory. Use the wsadmin.bat file for a Windows system, and the wsadmin.sh file for a Linux or a
UNIX system.
2. Start the wsadmin scripting client. You can start the wsadmin scripting client in several different ways.
To specify the method for running scripts, perform one of the following wsadmin tool options:

Option for starting the Explanation: Examples:

wsadmin scripting client:

Chapter 4. Using the administrative clients 429

Run scripting commands Run wsadmin with an option Using Jacl on Windows systems:
interactively other than -f or -c or without an wsadmin.bat
option.
Using Jacl on Unix systems:
An interactive shell is displayed
wsadmin.sh
with a wsadmin prompt. From
the wsadmin prompt, enter any If security is enabled:
Jacl or Jython command. You
can also invoke commands using wsadmin.sh -user wsadmin -password wsadmin
the AdminControl, AdminApp,
Using Jython on Windows systems:
AdminConfig, AdminTask, or
Help wsadmin objects. wsadmin.bat -lang jython

To leave an interactive scripting Using Jython on Unix systems:

session, use the quit or exit wsadmin.sh -lang jython
commands. These commands do
not take any arguments. By default security is enabled:
wsadmin.sh -lang jython -user wsadmin
-password wsadmin

Example output:
WASX7209I: Connected to process server1 on
node myhost using SOAP connector;
The type of process is: UnManagedProcess
WASX7029I: For help, enter: "$Help help"
wsadmin>$AdminApp list
adminconsole
DefaultApplication
ivtApp
wsadmin>exit
Run scripting commands as Run the wsadmin tool with the -c Using Jacl on Windows systems:
individual commands option. wsadmin -c "$AdminApp list"

Using Jacl on Unix systems:

wsadmin.sh -c "\$AdminApp list"

or
wsadmin.sh -c ’$AdminApp list’

Using Jython on Windows systems:

wsadmin -lang jython
-c "AdminApp.list()"

Using Jython on Linux or Unix systems:

wsadmin.sh -lang jython -c ’AdminApp.list()’

Example output:
WASX7209I: Connected to process "server1"
on node myhost using SOAP connector;
The type of process is: UnManagedProcess
adminconsole
DefaultApplication
ivtApp

430 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Run scripting commands in Run the wsadmin tool with the -f Using Jacl on Windows systems:
a script option, and place the commands wsadmin -f al.jacl
that you want to run into the file.
Using Jacl on Unix systems:
wsadmin.sh -f al.jacl

where the al.jacl file contains the following

commands:
set apps [$AdminApp list]
puts $apps

Using Jython on Windows systems:

wsadmin -lang jython -f al.py

Using Jython on Unix systems:

wsadmin.sh -lang jython -f al.py

where the al.py file contains the following

commands:
apps = AdminApp.list()
print apps

Example output:
WASX7209I: Connected to process "server1"
on node myhost using SOAP connector;
The type of process is: UnManagedProcess
adminconsole
DefaultApplication
ivtApp

Chapter 4. Using the administrative clients 431

Run scripting commands in A profile script is a script that Using Jacl on Windows systems:
a profile script runs before the main script, or wsadmin.bat -profile alprof.jacl
before entering interactive mode.
You can use profile scripts to set Using Jacl on Linux or Unix systems:
up a scripting environment that is wsadmin.sh -profile alprof.jacl
customized for the user or the
installation. where the alprof.jacl file contains the following
commands:
To run scripting commands in a
profile script, run the wsadmin set apps [$AdminApp list]
puts "Applications currently
tool with the -profile option, and
installed:\n$apps"
include the commands that you
want to run into the profile script. Example output:
To customize the script WASX7209I: Connected to process "server1"
environment, specify one or on node myhost using SOAP connector;
The type of process is: UnManagedProcess
more profile scripts to run.
Applications currently installed:
adminconsole
DefaultApplication
ivtApp
WASX7029I: For help, enter: "$Help help"
wsadmin>

Using Jython on Windows systems:

wsadmin.bat -lang jython -profile alprof.py

Using Jython on Linux or Unix systems:

wsadmin.sh -lang jython -profile alprof.py

where the alprof.py file contains the following

commands:
apps = AdminApp.list()
print "Applications currently installed:\n "
+ apps

Example output:
WASX7209I: Connected to process "server1" on
node myhost using SOAP connector;
The type of process is: UnManagedProcess
Applications currently installed:
adminconsole
DefaultApplication
ivtApp
WASX7029I: For help, enter: "Help.help()"
wsadmin>

Scripting: Resources for learning

Use the following links to find relevant supplemental information about the Jacl and Jython scripting
languages, and about using scripting with WebSphere Application Server. The information resides on IBM
and non-IBM Internet sites, whose sponsors control the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

Programming instructions and examples

v Java command language
v Jacl: A Tcl implementation in Java

432 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Charming Jython
v Jython
v Sample scripts for WebSphere Application Server

Deploying applications using scripting

This topic contains the following tasks:
v Installing applications
v Uninstalling applications

Installing applications with the wsadmin tool

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

On a single server installation, the server must be running before you install an application. See the
“Starting servers using scripting” on page 481 article for more information. On a network deployment
installation, the deployment manager must be running before you install an application. See the
“startManager command” on page 855article for more information.

You can install the application in batch mode, using the install command, or you can install the application
in interactive mode using the installinteractive command. Interactive mode prompts you through a series
of tasks to provide information. Both the install command and the installinteractive command support a
set of options. See the “Options for the AdminApp object install, installInteractive, edit, editInteractive,
update, and updateInteractive commands” on page 620 article for a list of valid options for the install and
installinteractive commands. You can also obtain a list of supported options for an Enterprise Archive
(EAR) file using the options command, for example:

Using Jacl:
$AdminApp options

Using Jython:
AdminApp.options()

For more information for the options, install, or installinteractive commands, see the “Commands for the
AdminApp object” on page 598 article.

The application that you install must be an enterprise archive file (EAR), a Web archive (WAR) file, or a
Java archive (JAR) file. The archive file must end in .ear, .jar or .war for the wsadmin tool to be able to
install it. The wsadmin tool uses these extensions to figure out the archive type. If the file is a WAR or JAR
file, it will be automatically wrapped as an EAR file.

If you are installing an application that has the AdminApp useMetaDataFromBinary option specified, then
you can only install this application on a WebSphere Application Server V6.x deployment target. This also
applies to editing the application, using the AdminApp edit command, after you install it. If you use the
V5.x wsadmin tool to install or edit an application on a WebSphere Application Server V6.x cell, only the
steps available for the V5.x wsadmin tool will be shown.

Perform the following steps to install an application into the run time:
1. Install the application.
v Using batch mode:
– For a single server installation only, the following example uses the EAR file and the command
option information to install the application:
- Using Jacl:

Chapter 4. Using the administrative clients 433

 $AdminApp install c:/MyStuff/application1.ear {-server serv2}
- Using Jython list:
AdminApp.install(’c:/MyStuff/application1.ear’, [’-server’, ’serv2’])
- Using Jython string:
AdminApp.install(’c:/MyStuff/application1.ear’, ’[-server serv2]’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object supporting application object management
install is an AdminApp command
MyStuff/application1.ear is the name of the application to install
server is an installation option
serv2 is the value of the server option

– For a network deployment installation only, the following command uses the EAR file and the
command option information to install the application on a cluster:
- Using Jacl:
$AdminApp install c:/MyStuff/application1.ear {-cluster cluster1}
- Using Jython list:
AdminApp.install(’c:/MyStuff/application1.ear’, [’-cluster’, ’cluster1’])
- Using Jython string:
AdminApp.install(’c:/MyStuff/application1.ear’, ’[-cluster cluster1]’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object allowing application objects to be managed
install is an AdminApp command
MyStuff/application1.ear is the name of the application to install
cluster is an installation option
cluster1 the value of the cluster option which will be cluster name

v Using interactive mode, the following command changes the application information by prompting
you through a series of installation tasks:
– Using Jacl:
$AdminApp installInteractive c:/MyStuff/application1.ear
– Using Jython:
AdminApp.installInteractive(’c:/MyStuff/application1.ear’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object allowing application objects to be managed
installInteractive is an AdminApp command
MyStuff/application1.ear is the name of the application to install

2. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
434 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
3. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Uninstalling applications with the wsadmin tool

Before starting this task, the wsadmin tool must be running. See “Starting the wsadmin scripting client” on
page 429 for more information.

Steps to uninstall an application follow:

1. Uninstall the application:
Specify the name of the application you want to uninstall, not the name of the Enterprise ARchive
(EAR) file.
v Using Jacl:
$AdminApp uninstall application1
v Using Jython:
AdminApp.uninstall(’application1’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object supporting application objects management
uninstall is an AdminApp command
application1 is the name of the application to uninstall

2. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
3. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Uninstalling an application removes it from the WebSphere Application Server configuration and from all
the servers that the application was installed on. The application binaries (EAR file contents) are deleted
from the installation directory. This occurs when the configuration is saved for single server WebSphere
Application Server editions or when the configuration changes are synchronized from deployment manager
to the individual nodes for network deployment configurations.

Managing deployed applications using scripting

This topic contains the following tasks:
v “Starting applications with scripting” on page 436
v “Updating installed applications with the wsadmin tool” on page 437
v “Stopping applications with scripting” on page 440
v “Listing the modules in an installed application with scripting” on page 441
v “Querying application state using scripting” on page 445
v “Disabling application loading in deployed targets using scripting” on page 446
v “Configuring applications for session management using scripting” on page 447
v “Configuring applications for session management in Web modules using scripting” on page 450
v “Exporting applications using scripting” on page 454
v “Configuring a shared library using scripting” on page 454
v “Configuring a shared library for an application using scripting” on page 458
v “Setting background applications using scripting” on page 461

Chapter 4. Using the administrative clients 435

Starting applications with scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Before starting an application, it must be installed. See the “Installing applications with the wsadmin tool”
on page 433 article for more information.

Perform the following steps to start an application:

1. Identify the application manager MBean for the server where the application resides and assign it the
appManager variable. The following example returns the name of the application manager MBean.
v Using Jacl:
set appManager [$AdminControl queryNames cell=mycell,node=mynode,type=ApplicationManager,
process=server1,*]
v Using Jython:
appManager = AdminControl.queryNames(’cell=mycell,node=mynode,type=ApplicationManager,
process=server1,*’)
print appManager
where:

set is a Jacl command

appManager is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
queryNames is an AdminControl command
cell=mycell,node=mynode,type=ApplicationManager, is the hierarchical containment path of the configuration
object
process=server1
print is a Jython command

Example output:
WebSphere:cell=mycell,name=ApplicationManager,mbeanIdentifier=ApplicationManager,type=ApplicationManager,
node=mynode,process=server1
2. Start the application. The following example invokes the startApplication operation on the MBean,
providing the application name that you want to start.
v Using Jacl:
$AdminControl invoke $appManager startApplication myApplication
v Using Jython:
AdminControl.invoke(appManager, ’startApplication’, ’myApplication’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
invoke is an AdminControl command
appManager evaluates to the ID of the server specified in step number
1
startApplication is an attribute of modify objects

436 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
myApplication is the value of the startApplication attribute

Updating installed applications with the wsadmin tool

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Before starting an application, it must be installed. See the “Installing applications with the wsadmin tool”
on page 433 article for more information.

Both the update command and the updateinteractive command support a set of options. See the
“Options for the AdminApp object install, installInteractive, edit, editInteractive, update, and
updateInteractive commands” on page 620 article for a list of valid options for the update and
updateinteractive commands. You can also obtain a list of supported options for an Enterprise Archive
(EAR) file using the options command, for example:

Using Jacl:
$AdminApp options

Using Jython:
print AdminApp.options()

For more information for the options, update, or updateinteractive commands, see the “Commands for
the AdminApp object” on page 598 article. Perform the following steps to update an application:
1. Update the installed application using one of the following options:
v The following command updates a single file in a deployed application:
– Using Jacl:
$AdminApp update app1 file {-operation update -contents c:/apps/app1/my.xml
-contenturi app1.jar/my.xml}
– Using Jython string:
AdminApp.update(’app1‘, ’file‘, ’[-operation update -contents c:/apps/app1/my.xml
-contenturi app1.jar/my.xml]‘)
– Using Jython list:
AdminApp.update(’app1‘, ’file‘, [’-operation‘, ’update‘, ’-contents‘, ’c:/apps/app1/my.xml‘,
’-contenturi‘, ’app1.jar/my.xml‘])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object supporting application objects management
update is an AdminApp command
app1 is the name of the application to update
file is the content type value
operation is an option of the update command
update is the value of the operation option
contents is an option of the update command
/apps/app1/my.xml is the value of the contents option
contenturi is an option of the update command
app1.jar/my.xml is the value of the contenturi option

Chapter 4. Using the administrative clients 437

 v The following command adds a module to the deployed application, if the module does not exist.
Otherwise, the existing module will be updated.
– Using Jacl:
$AdminApp update app1 modulefile {-operation addupdate -contents
c:/apps/app1/Increment.jar -contenturi Increment.jar -nodeployejb
-BindJndiForEJBNonMessageBinding {{"Increment Enterprise Java Bean"
Increment Increment.jar,META-INF/ejb-jar.xml Inc}}}
– Using Jython string:
AdminApp.update(’app1‘, ’modulefile‘, ’[-operation addupdate -contents
c:/apps/app1/Increment.jar -contenturi Increment.jar -nodeployejb
-BindJndiForEJBNonMessageBinding [["Increment Enterprise Java Bean
" Increment Increment.jar,META-INF/ejb-jar.xml Inc]]]’)
– Using Jython list:
bindJndiForEJBValue = [["Increment Enterprise Java Bean",
"Increment", " Increment.jar,
META-INF/ejb-jar.xml", "Inc"]]

AdminApp.update(’app1‘, ’modulefile‘, [’-operation‘, ’addupdate‘, ’-contents‘,

’c:/apps/app1/Increment.jar‘, ’-contenturi‘,’Increment.jar‘ ’-nodeployejb’,
`-BindJndiForEJBNonMessageBinding’, bindJndiForEJBValue])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object supporting application objects management
update is an AdminApp command
app1 is the name of the application to update
modulefile is the content type value
operation is an option of the update command
addupdate is the value of the operation option
contents is an option of the update command
/apps/app1/Increment.jar is the value of the contents option
contenturi is an option of the update command
Increment.jar is the value of the contenturi option
nodeployejb is an option of the update command
BindJndiForEJBNonMessageBinding is an option of the update command
″Increment Enterprise Java Bean″ Increment is the value of the BindJndiForEJBNonMessageBinding
Increment.jar,META-INF/ejb-jar.xml Inc option
bindJndiForEJBValue is a Jython variable containing the value of the
BindJndiForEJBNonMessageBinding option

v The following command uses a partial application to update a deployed application:

– Using Jacl:
$AdminApp update app1 partialapp {-contents c:/apps/app1/app1Partial.zip}
– Using Jython string:
AdminApp.update(’app1‘, ’partialapp‘, ’[-contents c:/apps/app1/app1Partial.zip]’)
– Using Jython list:
AdminApp.update(’app1‘, ’partialapp‘, [’-contents‘, ’c:/apps/app1/app1Partial.zip‘])

438 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object supporting application objects management
update is an AdminApp command
app1 is the name of the application to update
partialapp is the content type value
contents is an option of the update command
/apps/app1/app1Partial.zip is the value of the contents option

v The following command updates the entire deployed application:

– Using Jacl:
$AdminApp update app1 app {-operation update -contents c:/apps/app1/newApp1.jar
-usedefaultbindings -nodeployejb -BindJndiForEJBNonMessageBinding
{{"Increment Enterprise Java Bean" Increment Increment.jar,META-INF/ejb-jar.xml Inc}}}
– Using Jython string:
AdminApp.update(’app1‘, ’app‘, ’[-operation update -contents c:/apps/app1/newApp1.ear
-usedefaultbindings -nodeployejb -BindJndiForEJBNonMessageBinding
[["Increment Enterprise Java Bean" Increment Increment.jar,META-INF/ejb-jar.xml Inc]]]’)
– Using Jython list:
bindJndiForEJBValue = [["Increment Enterprise Java Bean", "Increment", " Increment.jar,
META-INF/ejb-jar.xml", "Inc"]]

AdminApp.update(’app1‘, ’app‘, [’-operation‘, ’update‘, ’-contents‘,

’c:/apps/app1/NewApp1.ear‘, ’-usedefaultbindings‘, ’-nodeployejb’,
`-BindJndiForEJBNonMessageBinding’, bindJndiForEJBValue])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object supporting application objects management
update is an AdminApp command
app1 is the name of the application to update
app is the content type value
operation is an option of the update command
update is the value of the operation option
contents is an option of the update command
/apps/app1/newApp1.ear is the value of the contents option
usedefaultbindings is an option of the update command
nodeployejb is an option of the update command
BindJndiForEJBNonMessageBinding is an option of the update command
″Increment Enterprise Java Bean″ Increment is the value of the BindJndiForEJBNonMessageBinding
Increment.jar,META-INF/ejb-jar.xml Inc option
bindJndiForEJBValue is a Jython variable containing the value of the
BindJndiForEJBNonMessageBinding option

2. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.

Chapter 4. Using the administrative clients 439

3. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Stopping applications with scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

The following example stops all running applications on a server:

1. Identify the application manager MBean for the server where the application resides, and assign it to
the appManager variable.
v Using Jacl:
set appManager [$AdminControl queryNames cell=mycell,node=mynode,type=ApplicationManager,
process=server1,*]
v Using Jython:
appManager = AdminControl.queryNames(’cell=mycell, node=mynode,type=ApplicationManager,
process=server1,*’)
print appManager
where:

set is a Jacl command

appManager is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
queryNames is an AdminControl command
cell=mycell,node=mynode,type=ApplicationManager, is the hierarchical containment path of the configuration
object
process=server1
print is a Jython command

This command returns the application manager MBean.

Example output:
WebSphere:cell=mycell,name=ApplicationManager,mbeanIdentifier=ApplicationManager,type=ApplicationManager,
node=mynode,process=server1
2. Query the running applications belonging to this server and assign the result to the apps variable.
v Using Jacl:
set apps [$AdminControl queryNames cell=mycell,node=mynode,type=Application,process=server1,*]
v Using Jython:
# get line separator
import java.lang.System as sys
lineSeparator = sys.getProperty(’line.separator’)

apps = AdminControl.queryNames(’cell=mycell,node=mynode,type=Application,process=server1,*’).split(lineSeparator)
print apps
where:

set is a Jacl command

apps is a variable name
$ is a Jacl operator for substituting a variable name with its
value

440 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
queryNames is an AdminControl command
cell=mycell,node=mynode,type=ApplicationManager, is the hierarchical containment path of the configuration
object
process=server1
print is a Jython command

This command returns a list of application MBeans.

Example output:
WebSphere:cell=mycell,name=adminconsole,mbeanIdentifier=deployment.xml#ApplicationDeployment_1,
type=Application,node=mynode,Server=server1,process=server1,J2EEName=adminconsole
WebSphere:cell=mycell,name=filetransfer,mbeanIdentifier=deployment.xml#ApplicationDeployment_1,
type=Application,node=mynode,Server=server1,process=server1,J2EEName=filetransfer
3. Stop all the running applications.
v Using Jacl:
foreach app $apps {
set appName [$AdminControl getAttribute $app name]
$AdminControl invoke $appManager stopApplication $appName}
v Using Jython:
for app in apps:
appName = AdminControl.getAttribute(app, ’name’)
AdminControl.invoke(appManager, ’stopApplication’, appName)
This command stops all the running applications by invoking the stopApplication operation on the
MBean, passing in the application name to stop.

Once you complete the steps for this task, all running applications on the server are stopped.

Listing the modules in an installed application with scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the AdminApp object listModules command to list the modules in an installed application. For
example:
v Using Jacl:
$AdminApp listModules DefaultApplication -server
v Using Jython:
print AdminApp.listModules(’DefaultApplication’, ’-server’)

where:

$ is a Jacl operator for substituting a variable name with its

value
print is a Jython command
AdminApp is an object supporting application object management
listmodules is an AdminApp command
DefaultApplication is the name of the application
-server is an optional option specified

Example output:

Chapter 4. Using the administrative clients 441

DefaultApplication#IncCMP11.jar+META-INF/ejb-jar.xml#WebSphere:cell=mycell,node=mynode,server=myserver
DefaultApplication#DefaultWebApplication.war+WEB-INF/web.xml#WebSphere:cell=mycell,node=mynode,server=myserver

Example: Listing the modules in an application server: The following example lists all modules on all
enterprise applications installed on server1 in node1:

Note: * means that the module is installed on server1 node node1 and other node and/or server.

+ means that the module is installed on server1 node node1 only means that the module is not
installed on server1 node node1.
1 #----------------------------------------------------------------------------
2 # setting up variables to keep server name and node name
3 #----------------------------------------------------------------------
4 set serverName server1
5 set nodeName node1
6 #--------------------------------------------------------------------------
7 # setting up 2 global lists to keep the modules
8 #--------------------------------------------------------------------------
9 set ejbList {}
10 set webList {}
11
12 #---------------------------------------------------------------------------------
13 # gets all deployment objects and assigned it to deployments variable
14 #---------------------------------------------------------------------------------
15 set deployments [$AdminConfig getid /Deployment:/]
16
17 #--------------------------------------------------------------------------------------
18 # lines 22 thru 148 Iterates through all the deployment objects to get the modules
19 # and perform filtering to list application that has at least one module installed
20 # in server1 in node myNode
21 #--------------------------------------------------------------------------------------
22 foreach deployment $deployments {
23
24 # ---------------------------------------------------------------------------------
25 # reset the lists that hold modules for each application
26 #----------------------------------------------------------------------------------
27 set webList {}
28 set ejbList {}
29
30 #------------------------------------------
31 # get the application name
32 #------------------------------------------
33 set appName [lindex [split $deployment (] 0]
34
35 #------------------------------------------
36 # get the deployedObjects
37 #------------------------------------------
38 set depObject [$AdminConfig showAttribute $deployment deployedObject]
39
40 #--------------------------------------------
41 # get all modules in the application
42 #---------------------------------------------
43 set modules [lindex [$AdminConfig showAttribute $depObject modules] 0]
44
45 #-----------------------------------------------------------------------------------------------
46 # initialize lists to save all the modules in the appropriate list to where they belong
47 #-----------------------------------------------------------------------------------------------
48 set modServerMatch {}
49 set modServerMoreMatch {}
50 set modServerNotMatch {}
51
52 #-------------------------------------------------------------------------------------------
53 # lines 55 to 112 iterate through all modules to get the targetMappings
54 #-------------------------------------------------------------------------------------------
55 foreach module $modules {

442 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
56 #-----------------------------------------------------------------------------------------
57 # setting up some flag to do some filtering and get modules for server1 on node1
58 #-----------------------------------------------------------------------------------------
59 set sameNodeSameServer "false"
60 set diffNodeSameServer "false"
61 set sameNodeDiffServer "false"
62 set diffNodeDiffServer "false"
63
64 #--------------------------------------------
65 # get the targetMappings
66 #--------------------------------------------
67 set targetMaps [lindex [$AdminConfig showAttribute $module targetMappings] 0]
68
69 #--------------------------------------------------------------------------------------------
70 # lines 72 to 111 iterate through all targetMappings to get the target
71 #--------------------------------------------------------------------------------------------
72 foreach targetMap $targetMaps {
73 #------------------------------
74 # get the target
75 #------------------------------
76 set target [$AdminConfig showAttribute $targetMap target]
77
78 #--------------------------------------------------
79 # do filtering to skip ClusteredTargets
80 #--------------------------------------------------
81 set targetName [lindex [split $target #] 1]
82 if {[regexp "ClusteredTarget" $targetName] != 1} {
83 set sName [$AdminConfig showAttribute $target name]
84 set nName [$AdminConfig showAttribute $target nodeName]
85
86 #----------------------------------------------
87 # do the server name match
88 #----------------------------------------------
89 if {$sName == $serverName} {
90 if {$nName == $nodeName} {
91 set sameNodeSameServer "true"
92 } else {
93 set diffNodeSameServer "true"
94 }
95 } else {
96 #---------------------------------------
97 # do the node name match
98 #---------------------------------------
99 if {$nName == $nodeName} {
100 set sameNodeDiffServer "true"
101 } else {
102 set diffNodeDiffServer "true"
103 }
104 }
105
106 if {$sameNodeSameServer == "true"} {
107 if {$sameNodeDiffServer == "true" || $diffNodeDiffServer == "true" ||
$diffNodeSameServer == "true"} {
108 break
109 }
110 }
111 }
112 }
113
114 #---------------------------------------------
115 # put it in the appropriate list
116 #---------------------------------------------
117 if {$sameNodeSameServer == "true"} {
118 if {$diffNodeDiffServer == "true" || $diffNodeSameServer == "true" || $sameNodeDiffServer == "true"}
{
119 set modServerMoreMatch [linsert $modServerMoreMatch end [$AdminConfig showAttribute
$module uri]]

Chapter 4. Using the administrative clients 443

120 } else {
121 set modServerMatch [linsert $modServerMatch end [$AdminConfig showAttribute $module uri]]
122 }
123 } else {
124 set modServerNotMatch [linsert $modServerNotMatch end [$AdminConfig showAttribute $module uri]]
125 }
126 }
127
128
129 #----------------------------------------------------------------
130 # print the output with some notation as a mark
131 #----------------------------------------------------------------
132 if {$modServerMatch != {} || $modServerMoreMatch != {}} {
133 puts stdout "\tApplication name: $appName"
134 }
135
136 #---------------------------------------------------------
137 # do grouping to appropriate module and print
138 #---------------------------------------------------------
139 if {$modServerMatch != {}} {
140 filterAndPrint $modServerMatch "+"
141 }
142 if {$modServerMoreMatch != {}} {
143 filterAndPrint $modServerMoreMatch "*"
144 }
145 if {($modServerMatch != {} || $modServerMoreMatch != {}) "" $modServerNotMatch != {}} {
146 filterAndPrint $modServerNotMatch ""
147 }
148}
149
150
151 proc filterAndPrint {lists flag} {
152 global webList
153 global ejbList
154 set webExists "false"
155 set ejbExists "false"
156
157 #-----------------------------------------------------------------------------------------
158 # If list already exists, flag it so as not to print the title more then once
159 # and reset the list
160 #-----------------------------------------------------------------------------------------
161 if {$webList != {}} {
162 set webExists "true"
163 set webList {}
164 }
165 if {$ejbList != {}} {
166 set ejbExists "true"
167 set ejbList {}
168 }
169
170 #------------------------------------------------------------------
171 # do some filtering for web modules and ejb modules
172 #------------------------------------------------------------------
173 foreach list $lists {
174 set temp [lindex [split $list .] 1]
175 if {$temp == "war"} {
176 set webList [linsert $webList end $list]
177 } elseif {$temp == "jar"} {
178 set ejbList [linsert $ejbList end $list]
179 }
180 }
181
182 #---------------------------------------
183 # sort the list before printing
184 #---------------------------------------
185 set webList [lsort -dictionary $webList]
186 set ejbList [lsort -dictionary $ejbList]

444 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 187
188 #----------------------------------------------------------------
189 # print out all the web modules installed in server1
190 #----------------------------------------------------------------
191 if {$webList != {}} {
192 if {$webExists == "false"} {
193 puts stdout "\t\tWeb Modules:"
194 }
195 foreach web $webList {
196 puts stdout "\t\t\t$web $flag"
197 }
198 }
199
200 #--------------------------------------------------------------
201 # print out all the ejb modules installed in server1
202 #--------------------------------------------------------------
203 if {$ejbList != {}} {
204 if {$ejbExists == "false"} {
205 puts stdout "\t\tEJB Modules:"
206 }
207 foreach ejb $ejbList {
208 puts stdout "\t\t\t$ejb $flag"
209 }
210 }
211}

Example output for server1 on node node1:

Application name: TEST1
EJB Modules:
deplmtest.jar +
Web Modules:
mtcomps.war *
Application name: TEST2
Web Modules:
mtcomps.war +
EJB Modules:
deplmtest.jar +
Application name: TEST3
Web Modules:
mtcomps.war *
EJB Modules:
deplmtest.jar *
Application name: TEST4
EJB Modules:
deplmtest.jar *
Web Modules:
mtcomps.war

Querying application state using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

The following example queries for the presence of Application MBean to find out whether the application is
running.

Using Jacl:
$AdminControl completeObjectName type=Application,name=myApplication,*

Using Jython:
print AdminControl.completeObjectName(’type=Application,name=myApplication,*’)

Chapter 4. Using the administrative clients 445

where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
type=Application,name=myApplication is the hierarchical containment path of the configuration
object
print is a Jython command

If myApplication is running, then there should be an MBean created for it. Otherwise, the command returns
nothing. If myApplication is running, the following is the example output:
WebSphere:cell=mycell,name=myApplication,mbeanIdentifier=cells/mycell/applications/myApplication.ear/deployments/myApplicat

Disabling application loading in deployed targets using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

The following example uses the AdminConfig object to disable application loading in deployed targets:
1. Obtain the deployment object for the application and assign it to the deployments variable, for example:
v Using Jacl:
set deployments [$AdminConfig getid /Deployment:myApp/]
v Using Jython:
deployments = AdminConfig.getid("/Deployment:myApp/")
where:

set is a Jacl command

deployments is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Deployment is an attribute
myApp is the value of the attribute

Example output:
myApp(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#Deployment_1)
2. Obtain the target mappings in the application and assign them to the targetMappings variable, for
example:
v Using Jacl:
set deploymentObj1 [$AdminConfig showAttribute $deployments deployedObject]
set targetMap1 [lindex [$AdminConfig showAttribute $deploymentObj1 targetMappings] 0]
Example output:
(cells/mycell/applications/ivtApp.ear/deployments/ivtApp|deployment.xml#DeploymentTargetMapping_1)
v Using Jython:

446 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 deploymentObj1 = AdminConfig.showAttribute(deployments, ’deployedObject’)
targetMap1 = AdminConfig.showAttribute(deploymentObj1, ’targetMappings’)
targetMap1 = targetMap1[1:len(targetMap1)-1].split(" ")
print targetMap1
Example output:
[’(cells/mycell/applications/ivtApp.ear/deployments/ivtApp|deployment.xml#DeploymentTargetMapping_1)’]
where:

set is a Jacl command

deploymentObj1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
showAttribute is an AdminConfig command
deployments evaluates to the ID of the deployment object specified in
step number 1
deployedObject is an attribute
targetMap1 a variable name
targetMappings is an attribute
lindex a Jacl command
print a Jython command

3. Disable the loading of the application on each deployed target, for example:
v Using Jacl:
foreach tm $targetMap1 {
$AdminConfig modify $tm {{enable false}}
}
v Using Jython:
for targetMapping in targetMap1:
AdminConfig.modify(targetMapping, [["enable", "false"]])
4. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
5. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring applications for session management using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

You can use the AdminApp object to set configurations in an application. Some configuration settings are
not available through the AdminApp object. The following example uses the AdminConfig object to
configure session manager for the application.
1. Identify the deployment configuration object for the application and assign it to the deployment
variable. For example:
v Using Jacl:
set deployments [$AdminConfig getid /Deployment:myApp/]
v Using Jython:
deployments = AdminConfig.getid(’/Deployment:myApp/’)
print deployment

Chapter 4. Using the administrative clients 447

 where:

set is a Jacl command

deployments is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Deployment is an attribute
myApp is the value of the attribute

Example output:
myApp(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#Deployment_1)
2. Retrieve the applicaton deployment and assign it to the appDeploy variable. For example:
v Using Jacl:
set appDeploy [$AdminConfig showAttribute $deployments deployedObject]
v Using Jython:
appDeploy = AdminConfig.showAttribute(deployments, ’deployedObject’)
print appDeploy
where:

set is a Jacl command

appDeploy is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
showAttribute is an AdminConfig command
deployments evaluates to the ID of the deployment object specified in
step number 1
deployedObject is an attribute

Example output:
(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#ApplicationDeployment_1)
3. To obtain a list of attributes you can set for session manager, use the attributes command. For
example:
v Using Jacl:
$AdminConfig attributes SessionManager
v Using Jython:
print AdminConfig.attributes(’SessionManager’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
attributes is an AdminConfig command
SessionManager is an attribute

448 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Example output:
"accessSessionOnTimeout Boolean"
"allowSerializedSessionAccess Boolean"
"context ServiceContext@"
"defaultCookieSettings Cookie"
"enable Boolean"
"enableCookies Boolean"
"enableProtocolSwitchRewriting Boolean"
"enableSSLTracking Boolean"
"enableSecurityIntegration Boolean"
"enableUrlRewriting Boolean"
"maxWaitTime Integer"
"properties Property(TypedProperty)*"
"sessionDRSPersistence DRSSettings"
"sessionDatabasePersistence SessionDatabasePersistence"
"sessionPersistenceMode ENUM(DATABASE, DATA_REPLICATION, NONE)"
"tuningParams TuningParams"
4. Set up the attributes for the session manager. The following example sets three top level attributes in
the session manager. You can modify the example to set other attributes of session manager including
the nested attributes in Cookie, DRSSettings, SessionDataPersistence, and TuningParms object types.
To list the attributes for those object types, use the attributes command of the AdminConfig object.
v Using Jacl:
set attr1 [list enableSecurityIntegration true]
set attr2 [list maxWaitTime 30]
set attr3 [list sessionPersistenceMode NONE]
set attrs [list $attr1 $attr2 $attr3]
set sessionMgr [list sessionManagement $attrs]
Example output using Jacl:
sessionManagement {{enableSecurityIntegration true} {maxWaitTime 30} {sessionPersistenceMode NONE}}
v Using Jython:
attr1 = [’enableSecurityIntegration’, ’true’]
attr2 = [’maxWaitTime’, 30]
attr3 = [’sessionPersistenceMode’, ’NONE’]
attrs = [attr1, attr2, attr3]
sessionMgr = [[’sessionManagement’, attrs]]
Example output using Jython:
[[sessionManagement, [[enableSecurityIntegration, true], [maxWaitTime, 30], [sessionPersistenceMode, NONE]]]
where:

set is a Jacl command

attr1, attr2, attr3, attrs, sessionMgr are variable names
$ is a Jacl operator for substituting a variable name with its
value
enableSecurityIntegration is an attribute
true is a value of the enableSecurityIntegration attribute
maxWaitTime is an attribute
30 is a value of the maxWaitTime attribute
sessionPersistenceMode is an attribute
NONE is a value of the sessionPersistenceMode attribute

5. Create the session manager for the application. For example:

v Using Jacl:
$AdminConfig create ApplicationConfig $appDeploy [list $sessionMgr]

Chapter 4. Using the administrative clients 449

 v Using Jython:
print AdminConfig.create(’ApplicationConfig’, appDeploy, sessionMgr)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
create is an AdminConfig command
ApplicationConfig is an attribute
appDeploy evaluates to the ID of the deployed application specified
in step number 2
list is a Jacl command
sessionMgr evaluates to the ID of the session manager specified in
step number 4

Example output:
(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#ApplicationConfig_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring applications for session management in Web modules using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

You can use the AdminApp object to set configurations in an application. Some configuration settings are
not available through the AdminApp object. This example uses the AdminConfig object to configure
session manager for Web module in the application.
1. Identify the deployment configuration object for the application and assign it to the deployment
variable. For example:
v Using Jacl:
set deployments [$AdminConfig getid /Deployment:myApp/]
v Using Jython:
deployments = AdminConfig.getid(’/Deployment:myApp/’)
print deployments
where:

set is a Jacl command

deployments is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Deployment is an attribute
myApp is the value of the attribute

Example output:

450 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 myApp(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#Deployment_1)
2. Get all the modules in the application and assign it to the modules variable. For example:
v Using Jacl:
set appDeploy [$AdminConfig showAttribute $deployments deployedObject]
set mod1 [$AdminConfig showAttribute $appDeploy modules]
Example output:
(cells/mycell/applications/myApp.ear/deployments/myApp:deployment.xml#WebModuleDeployment_1)
(cells/mycell/applications/myApp.ear/deployments/myApp:deployment.xml#EJBModuleDeployment_1)
(cells/mycell/applications/myApp.ear/deployments/myApp:deployment.xml#WebModuleDeployment_2)
v Using Jython:
appDeploy = AdminConfig.showAttribute(deployments, ’deployedObject’)
mod1 = AdminConfig.showAttribute(appDeploy, ’modules’)
print mod1
Example output:
[(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#WebModuleDeployment_1)
(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#EJBModuleDeployment_1)
(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#EJBModuleDeployment_2)]
where:

set is a Jacl command

appDeploy is a variable name
mod1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
showAttribute is an AdminConfig command
deployments evaluates to the ID of the deployment object specified in
step number 1
deployedObject is an attribute

3. To obtain a list of attributes you can set for session manager, use the attributes command. For
example:
v Using Jacl:
$AdminConfig attributes SessionManager
v Using Jython:
print AdminConfig.attributes(’SessionManager’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
attributes is an AdminConfig command
SessionManager is an attribute

Example output:
"accessSessionOnTimeout Boolean"
"allowSerializedSessionAccess Boolean"
"context ServiceContext@"
"defaultCookieSettings Cookie"
"enable Boolean"

Chapter 4. Using the administrative clients 451

 "enableCookies Boolean"
"enableProtocolSwitchRewriting Boolean"
"enableSSLTracking Boolean"
"enableSecurityIntegration Boolean"
"enableUrlRewriting Boolean"
"maxWaitTime Integer"
"properties Property(TypedProperty)*"
"sessionDRSPersistence DRSSettings"
"sessionDatabasePersistence SessionDatabasePersistence"
"sessionPersistenceMode ENUM(DATABASE, DATA_REPLICATION, NONE)"
"tuningParams TuningParams"
4. Set up the attributes for session manager. The following example sets four top level attributes in the
session manager. You can modify the example to set other attributes in the session manager including
the nested attributes in Cookie, DRSSettings, SessionDataPersistence, and TuningParms object types.
To list the attributes for those object types, use the attributes command of AdminConfig object.
v Using Jacl:
set attr0 [list enable true]
set attr1 [list enableSecurityIntegration true]
set attr2 [list maxWaitTime 30]
set attr3 [list sessionPersistenceMode NONE]
set attr4 [list enableCookies true]
set attr5 [list invalidationTimeout 45]
set tuningParmsDetailList [list $attr5]
set tuningParamsList [list tuningParams $tuningParmsDetailList]
set pwdList [list password 95ee608]
set userList [list userId Administrator]
set dsNameList [list datasourceJNDIName jdbc/session]
set dbPersistenceList [list $dsNameList $userList $pwdList]
set sessionDBPersistenceList [list $dbPersistenceList]
set sessionDBPersistenceList [list sessionDatabasePersistence $dbPersistenceList]
set kuki [list maximumAge 1000]
set cookie [list $kuki]
set cookieSettings [list defaultCookieSettings $cookie]
set sessionManagerDetailList [list $attr0 $attr1 $attr2 $attr3 $attr4 $cookieSettings
$tuningParamsList $sessionDBPersistenceList]
set sessionMgr [list sessionManagement $sessionManagerDetailList]
set id [$AdminConfig create ApplicationConfig $appDeploy [list $sessionMgr] configs]
set targetMappings [lindex [$AdminConfig showAttribute $appDeploy targetMappings] 0]
set attrs [list config $id]
$AdminConfig modify $targetMappings [list $attrs]
Example output using Jacl:
sessionManagement {{enableSecurityIntegration true} {maxWaitTime 30} {sessionPersistenceMode NONE} {enabled true}}
v Using Jython:
attr0 = [’enable’, ’true’]
attr1 = [’enableSecurityIntegration’, ’true’]
attr2 = [’maxWaitTime’, 30]
attr3 = [’sessionPersistenceMode’, ’NONE’]
attr4 = [’enableCookies’, ’true’]
attr5 = [’invalidationTimeout’, 45]
tuningParmsDetailList = [attr5]
tuningParamsList = [’tuningParams’, tuningParmsDetailList]
pwdList = [’password’, ’95ee608’]
userList = [’userId’, ’Administrator’]
dsNameList = [’datasourceJNDIName’, ’jdbc/session’]
dbPersistenceList = [dsNameList, userList, pwdList]
sessionDBPersistenceList = [dbPersistenceList]
sessionDBPersistenceList = [’sessionDatabasePersistence’, dbPersistenceList]
kuki = [’maximumAge’, 1000]
cookie = [kuki]
cookieSettings = [’defaultCookieSettings’, cookie]
sessionManagerDetailList = [attr0, attr1, attr2, attr3, attr4, cookieSettings, tuningParamsList,
sessionDBPersistenceList]
sessionMgr = [’sessionManagement’, sessionManagerDetailList]

452 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 id = AdminConfig.create(’ApplicationConfig’, appDeploy,[sessionMgr], ’configs’)
targetMappings = AdminConfig.showAttribute(appDeploy, ’targetMappings’)
targetMappings = targetMappings[1:len(targetMappings)-1]
print targetMappings
attrs = [’config’, id]
AdminConfig.modify(targetMappings,[attrs])
Example output using Jython:
[sessionManagement, [[enableSecurityIntegration, true], [maxWaitTime, 30], [sessionPersistenceMode, NONE]]
5. Set up the attributes for Web module. For example:
v Using Jacl:
set nameAttr [list name myWebModuleConfig]
set descAttr [list description "Web Module config post create"]
set webAttrs [list $nameAttr $descAttr $sessionMgr]
Example output:
{name myWebModuleConfig} {description {Web Module config post create}}
{sessionManagement {{enableSecurityIntegration true} {maxWaitTime 30}
{sessionPersistenceMode NONE} {enabled true}}}
v Using Jython:
nameAttr = [’name’, ’myWebModuleConfig’]
descAttr = [’description’, "Web Module config post create"]
webAttrs = [nameAttr, descAttr, sessionMgr]
Example output:
[[name, myWebModuleConfig], [description, "Web Module config post create"],
[sessionManagement, [[enableSecurityIntegration, true], [maxWaitTime, 30],
[sessionPersistenceMode, NONE], [enabled, true]]]]
where:

set is a Jacl command

nameAttr, descAttr, webAttrs are variable names
$ is a Jacl operator for substituting a variable name with its
value
name is an attribute
myWebModuleConfig is a value of the name attribute
description is an attribute
Web Module config post create is a value of the description attribute

6. Create the session manager for each Web module in the application. You can modify the following
example to set other attributes of session manager in Web module configuration.
v Using Jacl:
foreach module $mod1 {
if ([regexp WebModuleDeployment $module] == 1} {
$AdminConfig create WebModuleConfig $module $webAttrs
$AdminConfig save
}
}
v Using Jython:
arrayModules = mod1[1:len(mod1)-1].split(" ")
for module in arrayModules:
if module.find(’WebModuleDeployment’) != -1:
AdminConfig.create(’WebModuleConfig’, module, webAttrs)
Adminconfig.save()
Example output:
myWebModuleConfig(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#WebModuleConfiguration_1)

Chapter 4. Using the administrative clients 453

7. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
8. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Exporting applications using scripting

You can export your applications before you update installed applications or before you migrate to a
different version of the WebSphere Application Server product.

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Exporting applications enables you to back them up and preserve their binding information.
v Export an enterprise application to a location of your choice, for example:
– Using Jacl:
$AdminApp export app1 C:/mystuff/exported.ear
– Using Jython:
AdminApp.export(’app1’, ’C:/mystuff/exported.ear’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object allowing application objects management
export is an AdminApp command
app1 is the name of the application that will be exported
/mystuff/exported.ear is the name of the file where the exported application will
be stored

v Export Data Definition Language (DDL) files in the enterprise bean module of an application to a
destination directory, for example:
– Using Jacl:
$AdminApp exportDDL app1 C:/mystuff
– Using Jython:
AdminApp.exportDDL(’app1’, ’C:/mystuff’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminApp is an object allowing application objects management
exportDDL is an AdminApp command
app1 is the name of the application whose DDL files will be
exported
/mystuff is the name of the directory where the DDL files export
from the application

Configuring a shared library using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

454 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Perform the following steps to configure an application server to use a shared library.
1. Identify the server and assign it to the server variable. For example:
v Using Jacl:
set serv [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
serv = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print serv
where:

set is a Jacl command

serv is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Cell is an attribute
mycell is the value of the attribute
Node is an attribute
mynode is the value of the attribute
Server is an attribute
server1 is the value of the attribute

Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Create the shared library in the server. For example:
v Using Jacl:
$AdminConfig create Library $serv {{name mySharedLibrary}
{classPath c:/mySharedLibraryClasspath}}
v Using Jython:
print AdminConfig.create(’Library’, serv, [[’name’, ’mySharedLibrary’],
[’classPath’, ’c:/mySharedLibraryClasspath’]])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
create is an AdminConfig command
Library is an attribute
serv evaluates the ID of the server specified in step number 1
name is an attribute
mySharedLibrary is a value of the name attribute
classPath is an attribute
/mySharedLibraryClasspath is the value of the classpath attribute
print is a Jython command

Example output:

Chapter 4. Using the administrative clients 455

 MysharedLibrary(cells/mycell/nodes/mynode/servers/server1|libraries.xml#Library_1)
3. Identify the application server from the server and assign it to the appServer variable. For example:
v Using Jacl:
set appServer [$AdminConfig list ApplicationServer $serv]
v Using Jython:
appServer = AdminConfig.list(’ApplicationServer’, serv)
print appServer
where:

set is a Jacl command

appServer is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
list is an AdminConfig command
ApplicationServer is an attribute
serv evaluates the ID of the server specified in step number 1
print is a Jython command

Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#ApplicationServer_1
4. Identify the class loader in the application server and assign it to the classLoader variable. For
example:
v To use the existing class loader associated with the server, the following commands use the first
class loader:
– Using Jacl:
set classLoad [$AdminConfig showAttribute $appServer classloaders]
set classLoader1 [lindex $classLoad 0]
– Using Jython:
classLoad = AdminConfig.showAttribute(appServer, ’classloaders’)
cleanClassLoaders = classLoad[1:len(classLoad)-1]
classLoader1 = cleanClassLoaders.split(’ ’)[0]
where:

set is a Jacl command

classLoad, classLoader1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
showAttribute is an AdminConfig command
appServer evaluates the ID of the application server specified in step
number 3
classloaders is an attribute
print is a Jython command

v To create a new class loader, do the following step:

– Using Jacl:

456 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set classLoader1 [$AdminConfig create Classloader $appServer {{mode PARENT_FIRST}}]
– Using Jython:
classLoader1 = AdminConfig.create(’Classloader’, appServer, [[’mode’, ’PARENT_FIRST’]])
where:

set is a Jacl command

classLoader1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
create is an AdminConfig command
Classloader is an attribute
appServer evaluates the ID of the application server specified in step
number 3
mode is an attribute
PARENT_FIRST is the value of the attribute
print is a Jython command

Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#Classloader_1)
5. Associate the created shared library with the application server through the class loader. For example:
v Using Jacl:
$AdminConfig create LibraryRef $classLoader1 {{libraryName MyshareLibrary} {sharedClassloader true}}
v Using Jython:
print AdminConfig.create(’LibraryRef’, classLoader1, [[’libraryName’, ’MyshareLibrary’],
[’sharedClassloader’, ’true’]])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
create is an AdminConfig command
LibraryRef is an attribute
classLoader1 evaluates the ID of the class loader specified in step
number 4
libraryName is an attribute
MyshareLibrary is the value of the attribute
sharedClassloader is an attribute
true is the value of the attribute
print is a Jython command

Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#LibraryRef_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.

Chapter 4. Using the administrative clients 457

7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring a shared library for an application using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

You can use the AdminApp object to set certain configurations in the application. This example uses the
AdminConfig object to configure a shared library for an application.
1. Identify the shared library and assign it to the library variable. You can either use an existing shared
library or create a new one, for example:
v To create a new shared library, perform the following steps:
a. Idenitfy the node and assign it to a variable, for example:
– Using Jacl:
set n1 [$AdminConfig getid /Cell:mycell/Node:mynode/]
– Using Jython:
n1 = AdminConfig.getid(’/Cell:mycell/Node:mynode/’)
print n1
where:

set is a Jacl command

n1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Cell is the object type
mycell is the name of the object that will be modified
Node is the object type
mynode is the name of the object that will be modified

Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
b. Create the shared library in the node. The following example creates a new shared library in the
node scope. You can modify it to use the cell or server scope.
– Using Jacl:
set library [$AdminConfig create Library $n1 {{name mySharedLibrary} {classPath c:/mySharedLibraryClasspath}}]
– Using Jython:
library = AdminConfig.create(’Library’, n1, [[’name’, ’mySharedLibrary’], [’classPath’, ’c:/mySharedLibraryCla
print library
where:

set is a Jacl command

library is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
create is an AdminConfig command

458 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Library is an AdminConfig object
n1 evaluates to the ID of host node specified in step number
1
name is an attribute
mySharedLibrary is the value of the name attribute
classPath is an attribute
/mySharedLibraryClasspath is the value of the classPath attribute

Example output:
MySharedLibrary(cells/mycell/nodes/mynode|libraries.xml#Library_1)
v To use an existing shared library, issue the following command:
– Using Jacl:
set library [$AdminConfig getid /Library:mySharedLibrary/]
– Using Jython:
library = AdminConfig.getid(’/Library:mySharedLibrary/’)
print library
where:

set is a Jacl command

library is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Library is an attribute
mySharedLibrary is the value of the Library attribute

Example output:
MySharedLibrary(cells/mycell/nodes/mynode|libraries.xml#Library_1)
2. Identify the deployment configuration object for the application and assign it to the deployment
variable. For example:
v Using Jacl:
set deployment [$AdminConfig getid /Deployment:myApp/]
v Using Jython:
deployment = AdminConfig.getid(’/Deployment:myApp/’)
print deployment
where:

set is a Jacl command

deployment is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Deployment is an attribute
myApp is the value of the Deployment attribute
print is a Jython command

Chapter 4. Using the administrative clients 459

 Example output:
myApp(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#Deployment_1)
3. Retrieve the application deployment and assign it to the appDeploy variable. For example:
v Using Jacl:
set appDeploy [$AdminConfig showAttribute $deployment deployedObject]
v Using Jython:
appDeploy = AdminConfig.showAttribute(deployment, ’deployedObject’)
print appDeploy
where:

set is a Jacl command

appDeploy is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
showAttribute is an AdminConfig command
deployment evaluates the ID of the deployment configuration object
specified in step number 2
deployedObject is an attribute of modify objects
print is a Jython command

Example output:
(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#ApplicationDeployment_1)
4. Identify the class loader in the application deployment and assign it to the classLoader variable. For
example:
v Using Jacl:
set classLoad1 [$AdminConfig showAttribute $appDeploy classloader]
v Using Jython:
classLoad1 = AdminConfig.showAttribute(appDeploy, ’classloader’)
print classLoad1
where:

set is a Jacl command

classLoad1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
showAttribute is an AdminConfig command
appDeploy evaluates the ID of the application deployment specified
in step number 3
classLoader is an attribute of modify objects
print is a Jython command

Example output:
(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#Classloader_1)
5. Associate the shared library in the application through the class loader. For example:

460 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jacl:
$AdminConfig create LibraryRef $classLoad1 {{libraryName MyshareLibrary} {sharedClassloader true}}
v Using Jython:
print AdminConfig.create(’LibraryRef’, classLoad1, [[’libraryName’, ’MyshareLibrary’], [’sharedClassloader’, ’tru
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
create is an AdminConfig command
LibraryRef is an AdminConfig object
classLoad1 evaluates to the ID of class loader specified in step
number 4
libraryName is an attribute
MyshareLibrary is the value of the libraryName attribute
sharedClassloader is an attribute
true is the value of the sharedClassloader attribute

Example output:
(cells/mycell/applications/myApp.ear/deployments/myApp|deployment.xml#LibraryRef_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Setting background applications using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to enable or disable a background application. Background applications specify
whether the application must initialize fully before the server starts. The default setting is false and this
indicates that server startup will not complete until the application starts. If you set the value to true, the
application starts on a background thread and server startup continues without waiting for the application
to start. The application may not ready for use when the application server starts.
1. Locate the application deployment object for the application. For example:
v Using Jacl:
set applicationDeployment [$AdminConfig getid /Deployment:adminconsole/ApplicationDeployment:/]
v Using Jython:
applicationDeployment = AdminConfig.getid(’/Deployment:adminconsole/ApplicationDeployment:/’)
where:

set is a Jacl command

applicationDeployment is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command

Chapter 4. Using the administrative clients 461

Deployment is a type
ApplicationDeployment is a type
adminconsole is the name of the application

2. Enable the background application. For example:

v Using Jacl:
$AdminConfig modify $applicationDeployment "{backgroundApplication true}"
v Using Jython:
AdminConfig.modify(applicationDeployment, [’backgroundApplication’, ’true’])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
modify is an AdminConfig command
applicationDeployment is a variable name that was set in step 1
backgroundApplication is an attribute
true is the value of the backgroundApplication attribute

3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring servers with scripting

This topic contains the following tasks:
v “Creating a server using scripting”
v “Configuring the Java virtual machine using scripting” on page 463
v “Configuring enterprise bean containers using scripting” on page 463
v “Configuring a Performance Manager Infrastructure service using scripting” on page 467
v “Limiting the growth of Java virtual machine log files using scripting” on page 469
v “Configuring an ORB service using scripting” on page 471
v “Configuring for processes using scripting” on page 472
v “Configuring transaction properties for a server using scripting” on page 474
v “Setting port numbers kept in the serverindex.xml file using scripting” on page 475
v “Disabling components using scripting” on page 476
v “Disabling services using scripting” on page 477
v “Dynamic caching with scripting” on page 478

Creating a server using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Creating an application server involves a configuration command. Perform the following steps to create a
server:
1. Obtain the configuration ID of the object and assign it to the node variable, for example:

462 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Using Jacl:
set node [$AdminConfig getid /Node:mynode/]
Using Jython:
node = AdminConfig.getid(’/Node:mynode/’)
2. Create the server using the node that you specified in the first step:
Using Jacl:
$AdminConfig create Server $node {{name myserv} {outputStreamRedirect {{fileName myfile.out}}}}
Using Jython:
AdminConfig.create(’Server’, node, [[’name’, ’myserv’], [’outputStreamRedirect’, [[’fileName’, ’myfile.out’]]]])
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring the Java virtual machine using scripting

An example modifying the Java virtual machine (JVM) of a server to turn on debug follows:
v Identify the server and assign it to the server1 variable.
Using Jacl:
set server1 [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
Using Jython:
server1 = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print server1
Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
v Identify the JVM belonging to this server and assign it to the jvm variable.
Using Jacl:
set jvm [$AdminConfig list JavaVirtualMachine $server1]
Using Jython:
jvm = AdminConfig.list(’JavaVirtualMachine’, server1)
print jvm
Example output:
(cells/mycell/nodes/mynode/servers/server1:server.xml#JavaVirtualMachine_1)
v Modify the JVM to turn on debug.
Using Jacl:
$AdminConfig modify $jvm {{debugMode true} {debugArgs "-Djava.compiler=NONE -Xdebug -Xnoagent
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7777"}}
Using Jython:
AdminConfig.modify(jvm, [[’debugMode’, ’true’], [’debugArgs’, "-Djava.compiler=NONE -Xdebug -Xnoagent
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7777"]])
v Save the changes with the following command:
Using Jacl:
$AdminConfig save
Using Jython:
AdminConfig.save()

Configuring enterprise bean containers using scripting

Before starting this task, the wsadmin tool must be running. See “Starting the wsadmin scripting client” on
page 429 for more information.

Chapter 4. Using the administrative clients 463

Perform the following steps to configure an enterprise bean container:
1. Identify the application server and assign it to the serv1 variable. For example:
v Using Jacl:
set serv1 [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
serv1 = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print serv1
where:

set is a Jacl command

serv1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
/Cell:mycell/Node:mynode/Server:server1/ is the hierarchical containment path of the configuration
object
Cell is the object type
mycell is the optional name of the object
Node is the object type
mynode is the optional name of the object
Server is the object type
server1 is the optional name of the object

Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Identify the EJB container belonging to the server and assign it to the ejbc1 variable. For example:
v Using Jacl:
set ejbc1 [$AdminConfig list EJBContainer $serv1]
v Using Jython:
ejbc1 = AdminConfig.list(’EJBContainer’, serv1)
print ejbc1
where:

set is a Jacl command

ejbc1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
list is an AdminConfig command
EJBContainer is the object type
Note: The name of the object type that you input here is
the one based on the XML configuration files and does
not have to be the same name that the administrative
console displays.

464 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
serv1 evaluates to the ID of the server specified in step number
1

Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#EJBContainer_1)
3. View all the attributes of the enterprise bean container.
v The following example command does not show nested attributes:
– Using Jacl:
$AdminConfig show $ejbc1
Example output:
{cacheSettings (cells/mycell/nodes/mynode/servers/server1|server.xml#EJBCache_1)}
{components {}}
{inactivePoolCleanupInterval 30000}
{parentComponent (cells/mycell/nodes/mynode/servers/server1|server.xml#ApplicationServer_1)
{passivationDirectory ${USER_INSTALL_ROOT}/temp}
{properties {}}
{services {(cells/mycell/nodes/mynode/servers/server1|server.xml#MessageListenerService_1)}
{stateManagement (cells/mycell/nodes/mynode/servers/server1|server.xml#StateManageable_10)}
– Using Jython:
print AdminConfig.show(ejbc1)
Example output:
[cacheSettings (cells/mycell/nodes/myode/servers/server1|server.xml#EJBCache_1)]
[components []]
[inactivePoolCleanupInterval 30000]
[parentComponent (cells/mycell/nodes/myode/servers/server1|server.xml#ApplicationServer_1)
[passivationDirectory ${USER_INSTALL_ROOT}/temp]
[properties []]
[services [(cells/mycell/nodes/myode/servers/server1|server.xml#MessageListenerService_1)]
[stateManagement (cells/mycell/nodes/mynode/servers/server1|server.xml#StateManageable_10)]
where:

$ is a Jacl operator for substituting a variable name with its

value
print is a Jython command
AdminConfig is an object representing the WebSphere Application
Server configuration
showall is an AdminConfig command
ejbc1 evaluates to the ID of the enterprise bean container
specified in step number 2

v The following command example includes nested attributes:

– Using Jacl:
$AdminConfig showall $ejbc1
Example output:
{cacheSettings {{cacheSize 2053}
{cleanupInterval 3000}}}
{components {}}
{inactivePoolCleanupInterval 30000}
{parentComponent (cells/mycell/nodes/mynode/servers/server1|server.xml#ApplicationServer_1)}
{passivationDirectory ${USER_INSTALL_ROOT}/temp}
{properties {}}
{services {{{context (cells/mycell/nodes/mynode/servers/server1|server.xml#EJBContainer_1)}
{listenerPorts {}}
{properties {}}
{threadPool {{inactivityTimeout 3500}

Chapter 4. Using the administrative clients 465

 {isGrowable false}
{maximumSize 50}
{minimumSize 10}}}}}}
{stateManagement {{initialState START}
{managedObject (cells/mycell/nodes/mynode/servers/server1|server.xml#EJBContainer_1)}}}
– Using Jython:
print AdminConfig.showall(ejbc1)
Example output:
[cacheSettings [[cacheSize 2053]
[cleanupInterval 3000]]]
[components []]
[inactivePoolCleanupInterval 30000]
[parentComponent (cells/mycell/nodes/mynode/servers/server1|server.xml#ApplicationServer_1)]
[passivationDirectory ${USER_INSTALL_ROOT}/temp]
[properties []]
[services [[[context (cells/mycell/nodes/mynode/servers/server1|server.xml#EJBContainer_1)]
[listenerPorts []]
[properties []]
[threadPool [[inactivityTimeout 3500]
[isGrowable false]
[maximumSize 50]
[minimumSize 10]]]]]]
[stateManagement {{initialState START]
[managedObject (cells/mycell/nodes/mynode/servers/server1|server.xml#EJBContainer_1)]]]
where:

$ is a Jacl operator for substituting a variable name with its

value
print is a Jython command
AdminConfig is an object representing the WebSphere Application
Server configuration
showall is an AdminConfig command
ejbc1 evaluates to the ID of the enterprise bean container
specified in step number 2

4. Modify the attributes.

v The following example modifies the enterprise bean cache settings and it includes nested attributes:
– Using Jacl:
$AdminConfig modify $ejbc1 {{cacheSettings {{cacheSize 2500} {cleanupInterval 3500}}}}
– Using Jython:
AdminConfig.modify(ejbc1, [[’cacheSettings’, [[’cacheSize’, 2500], [’cleanupInterval’, 3500]]]])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
modify is an AdminConfig command
ejbc1 evaluates to the ID of the enterprise bean container
specified in step number 2
cacheSettings is an attribute of modify objects
cacheSize is an attribute of modify objects
2500 is the value of the cacheSize attribute

466 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
cleanupInterval is an attribute of modify objects
3500 is the value of the cleanupInterval attribute

v The following example modifies the cleanup interval attribute:

– Using Jacl:
$AdminConfig modify $ejbc1 {{inactivePoolCleanupInterval 15000}}
– Using Jython:
AdminConfig.modify(ejbc1, [[’inactivePoolCleanupInterval’, 15000]])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
modify is an AdminConfig command
ejbc1 evaluates to the ID of the enterprise bean container
specified in step number 2
inactivePoolCleanupInterval is an attribute of modify objects
15000 is the value of the inactivePoolCleanupInterval attribute

5. Save the changes. For example:

v Using Jacl:
$AdminConfig save
v Using Jython:
AdminConfig.save()
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
save is an AdminConfig command

Configuring a Performance Manager Infrastructure service using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the following steps to configure the Performance Manager Infrastructure (PMI) service for an
application server:
1. Identify the application server and assign it to the s1 variable, for example:
v Using Jacl:
set s1 [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
s1 = AdminConfig.getid(’Cell:mycell/Node:mynode/Server:server1/’)
where:

set is a Jacl command

Chapter 4. Using the administrative clients 467

s1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Cell is an attribute
mycell is the value of the Cell attribute
Node is an attribute
mynode is the value of the Node attribute
Server is an attribute
server1 is the value of the Server attribute

Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Identify the PMI service that belongs to the server and assign it to the pmi variable, for example:
v Using Jacl:
set pmi [$AdminConfig list PMIService $s1]
v Using Jython:
pmi = AdminConfig.list(’PMIService’, s1)
print pmi
where:

set is a Jacl command

pmi is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
list is an AdminConfig command
PMIService is an AdminConfig object
s1 evaluates to the ID of the application server specified in
step number 1

Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#PMIService_1)
3. Modify the attributes, for example:
v Using Jacl:
$AdminConfig modify $pmi {{enable true}
{initialSpecLevel beanModule=H:cacheModule=H:connectionPoolModule=
H:j2cModule=H:jvmRuntimeModule=H:orbPerfModule=H:servletSessionsModule
=H:systemModule=H:threadPoolModule=H:transactionModule=H:
webAppModule=H:webServicesModule=H:wlmModule=H:wsgwModule=H}}
v Using Jython:
AdminConfig.modify(pmi, [[’enable’, ’true’],
[’initialSpecLevel’, ’beanModule=H:cacheModule=H:connectionPoolModule=
H:j2cModule=H:jvmRuntimeModule=H:orbPerfModule=H:servletSessionsModule=
H:systemModule=H:threadPoolModule=H:transactionModule=H:webAppModule=H:
webServicesModule=H:wlmModule=H:wsgwModule=H’]])

468 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 This example enables PMI service and sets the specification levels for all of components in the server.
The following are the valid specification levels for the components:

N represents none
L represents low
M represents medium
H represents high
X represents maximum

4. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
5. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Limiting the growth of Java virtual machine log files using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the following example to configure the rotation policy settings for Java virtual machine (JVM) logs:
1. Identify the application server and assign it to the server1 variable, for example:
v Using Jacl:
set s1 [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
s1 = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print s1
where:

set is a Jacl command

s1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Cell is the object type
mycell is the name of the object that will be modified
Node is the object type
mynode is the name of the object that will be modified
Server is the object type
server1 is the name of the object that will be modified
print a Jython command

Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Identify the stream log and assign it to the log variable, for example:
v The following example identifies the output stream log:
– Using Jacl:
set log [$AdminConfig showAttribute $s1 outputStreamRedirect]

Chapter 4. Using the administrative clients 469

 – Using Jython:
log = AdminConfig.showAttribute(s1, ’outputStreamRedirect’)
v The following example identifies the error stream log:
– Using Jacl:
set log [$AdminConfig showAttribute $s1 errorStreamRedirect]
– Using Jython:
log = AdminConfig.showAttribute(s1, ’errorStreamRedirect’)
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#StreamRedirect_2)
3. List the current values of the stream log, for example:
v Using Jacl:
$AdminConfig show $log
v Using Jython:
AdminConfig.show(log)
Example output:
{baseHour 24}
{fileName ${SERVER_LOG_ROOT}/SystemOut.log}
{formatWrites true}
{maxNumberOfBackupFiles 1}
{messageFormatKind BASIC}
{rolloverPeriod 24}
{rolloverSize 1}
{rolloverType SIZE}
{suppressStackTrace false}
{suppressWrites false}
4. Modify the rotation policy for the stream log.
v The following example sets the rotation log file size to two megabytes:
– Using Jacl:
$AdminConfig modify $log {{rolloverSize 2}}
– Using Jython:
AdminConfig.modify(log, [’rolloverSize’, 2])
v The following example sets the rotation policy to manage itself. It is based on the age of the file with
the rollover algorithm loaded at midnight, and the log file rolling over every 12 hours:
– Using Jacl:
$AdminConfig modify $log {{rolloverType TIME} {rolloverPeriod 12} {baseHour 24}}
– Using Jython:
AdminConfig.modify(log, [[’rolloverType’, ’TIME’] [’rolloverPeriod’, 12] [’baseHour’, 24]])
v The following example sets the log file to roll over based on both time and size:
– Using Jacl:
$AdminConfig modify $log {{rolloverType BOTH} {rolloverSize 2} {rolloverPeriod 12} {baseHour 24}}
– Using Jython:
AdminConfig.modify(log, [[’rolloverType’, ’BOTH’] [’rolloverSize’, 2] [’rolloverPeriod’, 12] [’baseHour’, 24]])
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

470 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring an ORB service using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to modify the Object Request Broker (ORB) service for an application server:
1. Identify the application server and assign it to the server variable:
v Using Jacl:
set s1 [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
s1 = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print s1
where:

set is a Jacl command

s1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command
Cell is the object type
mycell is the name of the object that will be modified
Node is the object type
mynode is the name of the object that will be modified
Server is the object type
server1 is the name of the object that will be modified
print a Jython command

Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Identify the ORB belonging to the server and assign it to the orb variable:
v Using Jacl:
set orb [$AdminConfig list ObjectRequestBroker $s1]
v Using Jython:
orb = AdminConfig.list(’ObjectRequestBroker’, s1)
print orb
where:

set is a Jacl command

orb is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
list is an AdminConfig command
ObjectRequestBroker is an AdminConfig object
s1 evaluates to the ID of server specified in step number 1

Chapter 4. Using the administrative clients 471

print a Jython command

Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#ObjectRequestBroker_1)
3. Modify the attributes. The following example modifies the connection cache maximum and pass by
value attributes. You can modify the example to change the value of other attributes.
v Using Jacl:
$AdminConfig modify $orb {{connectionCacheMaximum 252} {noLocalCopies true}}
v Using Jython:
AdminConfig.modify(orb, [[’connectionCacheMaximum’, 252], [’noLocalCopies’, ’true’]])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminConfig is an object representing the WebSphere Application
Server configuration
modify is an AdminConfig command
orb evaluates to the ID of ORB specified in step number 2
connectionCacheMaximum is an attribute
252 is the value of the connectionCacheMaximum attribute
noLocalCopies is an attribute
true is the value of the noLocalCopies attribute

4. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
5. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring for processes using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a process:

1. Identify the server and assign it to the s1 variable. For example:
v Using Jacl:
set s1 [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
s1 = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print s1
where:

set is a Jacl command

s1 is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminConfig is an object representing the WebSphere Application
Server configuration
getid is an AdminConfig command

472 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Cell is the object type
mycell is the name of the object that will be modified
Node is the object type
mynode is the name of the object that will be modified
Server is the object type
server1 is the name of the object that will be modified
print a Jython command

Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Identify the process definition belonging to this server and assign it to the processDef variable. For
example:
v Using Jacl:
set processDef [$AdminConfig list JavaProcessDef $s1]
set processDef [$AdminConfig showAttribute $s1 processDefinition]
v Using Jython:
processDef = AdminConfig.list(’JavaProcessDef’, s1)
print processDef
processDef = AdminConfig.showAttribute(s1, ’processDefinition’)
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#JavaProcessDef_1)
3. Change the attributes.
v On distributed systems, the following example changes the working directory.
– Using Jacl:
$AdminConfig modify $processDef {{workingDirectory c:/temp/user1}}
– Using Jython:
AdminConfig.modify(processDef, [[’workingDirectory’, ’c:/temp/user1’]])
v The following example modifies the stderr file name:
– Using Jacl:
set errFile [list stderrFilename \${LOG_ROOT}/server1/new_stderr.log]
set attr [list $errFile]
$AdminConfig modify $processDef [subst {{ioRedirect {$attr}}}]
– Using Jython:
errFile = [’stderrFilename’, ’\${LOG_ROOT}/server1/new_stderr.log’]
attr = [errFile]
AdminConfig.modify(processDef, [[’ioRedirect’, [attr]]])
v The following example modifies the process priority:
– Using Jacl:
$AdminConfig modify $processDef {{execution {{processPriority 15}}}}
– Using Jython:
AdminConfig.modify(processDef, [[’execution’, [[’processPriority’, 15]]]])
v The following example changes the maximum startup attempts. You can modify this example to
change other attributes in the process definition object.
– Using Jacl:
$AdminConfig modify $processDef {{monitoringPolicy {{maximumStartupAttempts 1}}}}
– Using Jython:
AdminConfig.modify(processDef, [[’monitoringPolicy’, [[’maximumStartupAttempts’, 1]]]])
4. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
5. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Chapter 4. Using the administrative clients 473

Configuring transaction properties for a server using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure the runtime transaction properties for an application server.
1. Identify the transaction service MBean for the application server. The following command returns the
transaction service MBean for server1.
v Using Jacl:
set ts [$AdminControl completeObjectName cell=mycell,node=mynode,process=server1,type=TransactionService,*]
v Using Jython:
ts = AdminControl.completeObjectName(’cell=mycell,node=mynode,process=server1,type=TransactionService,*’)
print ts
where:

set is a Jacl command

ts is a variable name
$ is a Jacl operator for substituting a variable name with its
value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
completeObjectName is an AdminControl command
cell=mycell,node=mynode,process=server1, is a fragment of the object name whose complete name
is returned by this command. It is used to find the
type=TransactionService matching object name which is, in this case, the
transaction object MBean for the node mynode, where
mynode is the name of the node that you use to
synchronize configuration changes. For example:
type=TransactionService, process=server1. It can be
any valid combination of domain and key properties. For
example, type, name, cell, node, process, etc.

Example output:
WebSphere:cell=mycell,name=TransactionService,mbeanIdentifier=TransactionService,type=TransactionService,
node=mynode,process=server1
2. Modify the attributes.
v Using Jacl:
$AdminControl invoke $ts {{transactionLogDirectory c:/WebSphere/AppServer/tranlog/server1}
{clientInactivityTimeout 30} {totalTranLifetimeTimeout 180}}
v Using Jython:
AdminControl.invoke(ts, [[’transactionLogDirectory’, ’c:/WebSphere/AppServer/tranlog/server1’],
[’clientInactivityTimeout’, 30], [’totalTranLifetimeTimeout’, 180]])
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
invoke is an AdminControl command
ts evaluates to the ID of the transaction service specified in
step number 1
transactionLogDirectory is an attribute

474 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
c:/WebSphere/AppServer/tranlog/server1 is the value of the transactionLogDirectory attribute
clientInactivityTimeout is an attribute
30 is the value of the clientInactivityTimeout attribute
specified in seconds. A value of 0 means that there is no
timeout limit.
totalTranLifetimeTimeout is an attribute
180 is the value of the totalTranLifetimeTimeout attribute
specified in milliseconds. A value of 0 means that there is
no timeout limit.

Setting port numbers kept in the serverindex.xml file using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

This topic provides reference information about modifying port numbers in the serverindex.xml file. The
end points of the serverindex.xml file are part of different objects in the configuration.

Use the following attributes to modify the end point information of the end point attributes for a process:
v BOOTSTRAP_ADDRESS of server1 process
An attribute of the NameServer object that exists inside the server. It is used by the naming client to
specify the naming server to look up the initial context. To modify its end point, obtain the ID of the
NameServer object and issue a modify command, for example:
– Using Jacl:
set s [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
set ns [$AdminConfig list NameServer $s]
$AdminConfig modify $ns {{BOOTSTRAP_ADDRESS {{port 2810} {host myhost}}}}
– Using Jython:
s = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
ns = AdminConfig.list(’NameServer’, s)
AdminConfig.modify(ns, [[’BOOTSTRAP_ADDRESS’, [[’host’, ’myhost’], [’port’, 2810]]]])
v SOAP_CONNECTOR-ADDRESS of server1 process
An attribute of the SOAPConnector object that exists inside the server. It is the port that is used by
HTTP transport for incoming SOAP requests. To modify its end point, obtain the ID of the
SOAPConnector object and issue a modify command, for example:
– Using Jacl:
set s [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
set soap [$AdminConfig list SOAPConnector $s]
$AdminConfig modify $soap {{SOAP_CONNECTOR_ADDRESS {{host myhost} {port 8881}}}}
– Using Jython:
s = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
soap = AdminConfig.list(’SOAPConnector’, s)
AdminConfig.modify(soap, [[’SOAP_CONNECTOR_ADDRESS’, [[’host’, ’myhost’], [’port’, 8881]]]])
v DRS_CLIENT_ADDRESS of server1 process
An attribute of the SystemMessageServer object that exists inside the server. It is the port used to
configure the Data Replication Service (DRS) which is a JMS-based message broker system for
dynamic caching. The DRS_CLIENT_ADDRESS attribute is not available if a replication domain and a
replicator entry have not been added to the server.
To modify the end point of the DRS_CLIENT_ADDRESS attribute, obtain the ID of the
SystemMessageServer object and issue a modify command, for example:
– Using Jacl:
set s [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
set sms [$AdminConfig list SystemMessageServer $s]
$AdminConfig modify $sms {{DRS_CLIENT_ADDRESS {{host myhost} {port 7874}}}}

Chapter 4. Using the administrative clients 475

 – Using Jython:
s = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
sms = AdminConfig.list(’SystemMessageServer’, s)
AdminConfig.modify(sms, [[’DRS_CLIENT_ADDRESS’, [[’host’, ’myhost’], [’port’, 7874]]]])
v JMSSERVER_QUEUED_ADDRESS and JMSSERVER_DIRECT_ADDRESS of server1 process
An attribute of the JMSServer object that exists inside the server. These are ports used to configure the
WebSphere Application Server JMS provider topic connection factory settings. To modify its end point,
obtain the ID of the JMSServer object and issue a modify command, for example:
– Using Jacl:
set s [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
set jmss [$AdminConfig list JMSServer $s]
$AdminConfig modify $jmss {{JMSSERVER_QUEUED_ADDRESS {{host myhost} {port 5560}}}}
$AdminConfig modify $jmss {{JMSSERVER_DIRECT_ADDRESS {{host myhost} {port 5561}}}}
– Using Jython:
s = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
jmss = AdminConfig.list(’JMSServer’, s)
AdminConfig.modify(jmss, [[’JMSSERVER_QUEUED_ADDRESS’, [[’host’, ’myhost’], [’port’, 5560]]]])
AdminConfig.modify(jmss, [[’JMSSERVER_DIRECT_ADDRESS’, [[’host’, ’myhost’], [’port’, 5561]]]])
v NODE_DISCOVERY_ADDRESS of nodeagent process
An attribute of the NodeAgent object that exists inside the server. It is the port used to receive the
incoming process discovery messages inside a node agent process. To modify its end point, obtain the
ID of the NodeAgent object and issue a modify command, for example:
– Using Jacl:
set nodeAgentServer [$AdminConfig getid /Cell:mycell/Node:mynode/Server:nodeagent/]
set nodeAgent [$AdminConfig list NodeAgent $nodeAgentServer]
$AdminConfig modify $nodeAgent {{NODE_DISCOVERY_ADDRESS {{host myhost} {port 7272}}}}
– Using Jython:
nodeAgentServer = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:nodeagent/’)
nodeAgent = AdminConfig.list(’NodeAgent’, nodeAgentServer)
AdminConfig.modify(nodeAgent, [[’NODE_DISCOVERY_ADDRESS’, [[’host’, ’myhost’], [’port’, 7272]]]])
v CELL_DISCOVERY_ADDRESS of dmgr process
An attribute of the deploymentManager object that exists inside the server. It is the port used to receive
the incoming process discovery messages inside a deployment manager process. To modify its end
point, obtain the ID of the deploymentManager object and issue a modify command, for example:
– Using Jacl:
set netmgr [$AdminConfig getid /Cell:mycell/Node:managernode/Server:dmgr/]
set deploymentManager [$AdminConfig list CellManager $netmgr]
$AdminConfig modify $deploymentManager {{CELL_MULTICAST_DISCOVERY_ADDRESS {{host myhost} {port 7272}}}}
$AdminConfig modify $deploymentManager {{CELL_DISCOVERY_ADDRESS {{host myhost} {port 7278}}}}
– Using Jython:
netmgr = AdminConfig.getid(’/Cell:mycell/Node:managernode/Server:dmgr/’)
deploymentManager = AdminConfig.list(’CellManager’, netmgr)
AdminConfig.modify(deploymentManager, [[’CELL_MULTICAST_DISCOVERY_ADDRESS’, [[’host’, ’myhost’], [’port’, 7272]]]])
AdminConfig.modify(deploymentManager, [[’CELL_DISCOVERY_ADDRESS’, [[’host’, ’myhost’], [’port’, 7278]]]])

Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on page
411 article for more information.

In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with the
wsadmin tool” on page 396 article for more information.

Disabling components using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

476 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Perform the following steps to disable the name server component of a configured server. You can modify
this example to disable a different component.
1. Identify the server component and assign it to the nameServer variable.
v Using Jacl:
set nameServer [$AdminConfig list NameServer $server]
v Using Jython:
nameServer = AdminConfig.list(’NameServer’, server)
print nameServer
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#NameServer_1)
2. List the components belonging to the server and assign them to the components variable.
v Using Jacl:
set components [$AdminConfig list Component $server]
v Using Jython:
components = AdminConfig.list(’Component’, server)
print components
The components variable contains a list of components.
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#ApplicationServer_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#EJBContainer_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#NameServer_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#WebContainer_1)
3. Identify the name server component and assign it to the nameServer variable.
Since the name server component is the third element in the list, retrieve this element by using index
2.
v Using Jacl:
set nameServer [lindex $components 2]
v Using Jython:
# get line separator
import java
lineSeparator = java.lang.System.getProperty(’line.separator’)
arrayComponents = components.split(lineSeparator)
nameServer = arrayComponents[2]
print nameServer
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#NameServer_1)
4. Disable the name server component by changing the nested initialState attribute belonging to the
stateManagement attribute. For example:
v Using Jacl:
$AdminConfig modify $nameServer {{stateManagement {{initialState STOP}}}}
v Using Jython:
AdminConfig.modify(nameServer, [[’stateManagement’, [[’initialState’, ’STOP’]]]])
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Disabling services using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Chapter 4. Using the administrative clients 477

Perform the following steps to disable the trace service of a configured server. You can modify this
example to disable a different service.
1. Identify the server and assign it to the server variable. For example:
v Using Jacl:
set server [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
server = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print server
Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. List all the services belonging to the server and assign them to the services variable. The following
example returns a list of services:
v Using Jacl:
set services [$AdminConfig list Service $server]
v Using Jython:
services = AdminConfig.list(’Service’, server)
print services
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#AdminService_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#DynamicCache_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#MessageListenerService_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#ObjectRequestBroker_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#PMIService_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#RASLoggingService_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#SessionManager_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#TraceService_1)
(cells/mycell/nodes/mynode/servers/server1|server.xml#TransactionService_1)
3. Identify the trace service and assign it to the traceService variable.
Since trace service is the 7th element in the list, retrieve this element by using index 6.
v Using Jacl:
set traceService [$AdminConfig list TraceService $server]
v Using Jython:
traceService = AdminConfig.list(’TraceService’, server)
print traceService
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#TraceService_1)
4. Disable the trace service by modifying the enable attribute. For example:
v Using Jacl:
$AdminConfig modify $traceService {{enable false}}
v Using Jython:
AdminConfig.modify(traceService, [[’enable’, ’false’]])
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Dynamic caching with scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

To see a list of parameters associated with dynamic caching, use the attributes command. For example:

478 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
$AdminConfig attributes DynamicCache

Perform the following steps to enable servlet caching:

1. Locate the server object. The following example selects the first server found:
Using Jacl:
set s1 [$AdminConfig getid /Server:server1/]
Using Jython:
s1 = AdminConfig.getid(’/Server:server1/’)
2. List the web containers and assign them to the wc variable, for example:
Using Jacl:
set wc [$AdminConfig list WebContainer $s1]
Using Jython:
wc = AdminConfig.list(’WebContainer’, s1)
3. Set the enableServletCaching attribute to true and assign it to the serEnable variable, for example:
Using Jacl:
set serEnable "{enableServletCaching true}"
Using Jython:
serEnable = [[’enableServletCaching’, ’true’]]
4. Enable caching, for example:
Using Jacl:
$AdminConfig modify $wc $serEnable
Using Jython:
AdminConfig.modify(wc, serEnable)

Configuring connections to Webservers with scripting

This topic contains the following tasks:
v “Regenerating the node plug-in configuration using scripting”
v “Creating new virtual hosts using templates with scripting” on page 480

Regenerating the node plug-in configuration using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to regenerate the node plug-in configuration:

1. Identify the plug-in and assign it to the generator variable, for example:
Using Jacl:
set generator [$AdminControl completeObjectName type=PluginCfgGenerator,node=mynode,*]
Using Jython:
generator = AdminControl.completeObjectName(’type=PluginCfgGenerator,node=mynode,*’)
2. Regenerate the node plug-in:
Using Jacl:
$AdminControl invoke $generator generate "c:/WebSphere/DeloymentManager/config mycell mynode null plugin-cfg.xml"
Using Jython:
AdminControl.invoke(generator, ’generate’, "c:/WebSphere/DeloymentManager/config mycell mynode null plugin-cfg.xml")

Chapter 4. Using the administrative clients 479

Creating new virtual hosts using templates with scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Some configuration object types have templates that you can use when you create a virtual host. You can
create a new virtual host using a preexisting template or by creating a new custom template. Perform the
following steps to create a new virtual host using a template:
1. If you want to create a new custom template, perform the following steps:
a. Copy and paste the following file into a new file, myvirtualhostname.xml:
<WAS-ROOT>\config\templates\default\virtualhosts.xml
b. Edit and customize the new myvirtualhostname.xml file.
c. Place the new file in the following directory:
<WAS-ROOT>\config\templates\custom\
If you want the new custom template to appear with the list of templates, restart the deployment
manager on a network deployment edition, or use the AdminConfig object reset command. For
example:
v Using Jacl:
$AdminConfig reset
v Using Jython:
AdminConfig.reset()
The administrative console does not support the use of custom templates. The new template that you
create will not be visible in the administrative console panels.
2. Use the AdminConfig object listTemplates command to list available templates, for example:
v Using Jacl:
$AdminConfig listTemplates VirtualHost
v Using Jython:
print AdminConfig.listTemplates(’VirtualHost’)
Example output:
default_host(templates/default:virtualhosts.xml#VirtualHost_1)
my_host(templates/custom:virtualhostname.xml#VirtualHost_1)
3. Create a new virtual host. For example:
v Using Jacl:
set cell [$AdminConfig getid /Cell:NetworkDeploymentCell/]
set vtempl [$AdminConfig listTemplates VirtualHost my_host]
$AdminConfig createUsingTemplate VirtualHost $cell {{name newVirHost}} $vtempl
v Using Jython:
cell = AdminConfig.getid(’/Cell:NetworkDeploymentCell/’)
vtempl = AdminConfig.listTemplates(’VirtualHost’, ’my_host’)
AdminConfig.createUsingTemplate(’VirtualHost’, cell, [[’name’, ’newVirHost’]], vtempl)
4. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
5. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Managing servers with scripting

This topic contains the following tasks:
v “Stopping a node using scripting” on page 481
v “Starting servers using scripting” on page 481

480 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v “Stopping servers using scripting” on page 482
v “Querying server state using scripting” on page 483
v “Listing running applications on running servers using scripting” on page 483
v “Starting listener ports using scripting” on page 485
v “Managing generic servers using scripting” on page 486
v “Setting development mode for server objects using scripting” on page 487
v “Disabling parallel startup using scripting” on page 487
v “Removing multicast endpoints using scripting” on page 488
v “Obtaining server version information with scripting” on page 488

Stopping a node using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Stopping the node agent on a remote machine process is an asynchronous action where the stop is
initiated, and then control returns to the command line. Perform the following task to stop a node:
1. Identify the node that you want to stop and assign it to a variable:
Using Jacl:
set na [$AdminControl queryNames type=NodeAgent,node=mynode,*]
Using Jython:
na = AdminControl.queryNames(’type=NodeAgent,node=mynode,*’)
2. Stop the node:
Using Jacl:
$AdminControl invoke $na stopNode
Using Jython:
AdminControl.invoke(na, ’stopNode’)

Starting servers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the startServer command to start the server. This command has several syntax options. For
example:
v To start a server on a WebSphere Application Server single server edition, choose one of the following
options:
– The following examples specify the server name only:
Using Jacl:
$AdminControl startServer serverName
Using Jython:
AdminControl.startServer(’serverName’)
– The following example starts an application server with the node specified:
- Using Jacl:
$AdminControl startServer server1 mynode
- Using Jython:
print AdminControl.startServer(’server1’, ’mynode’)
Example output:

Chapter 4. Using the administrative clients 481

 WASX7319I: The serverStartupSyncEnabled attribute is set to false. A start
will be attempted for server "server1" but the configuration information for
node "mynode" may not be current.
WASX7262I: Start completed for server "server1" on node "mynode"
– The following example specify the server name and wait time:
- Using Jacl:
$AdminControl startServer serverName 10
- Using Jython:
AdminControl.startServer(’serverName’, 10)
where 10 is the number of milliseconds that the process should wait before starting the server.
v To start a server on a WebSphere Application Server network deployment edition, choose one of the
following options:
– The following example specifies the server name and the node name:
- Using Jacl:
$AdminControl startServer serverName nodeName
- Using Jython:
AdminControl.startServer(’serverName’, ’nodeName’)
– The following example specifies the server name, the node name, and the wait time:
- Using Jacl:
$AdminControl startServer serverName nodeName 10
- Using Jython:
AdminControl.startServer(’serverName’, ’nodeName’, 10)
where 10 is the number of milliseconds that the process should wait before starting the server.

Stopping servers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the stopServer command to stop the server. This command has several syntax options. For example:
v To stop a server on a WebSphere Application Server single server edition, choose one of the following
options:
– The following examples specify the server name only:
Using Jacl:
$AdminControl stopServer serverName
Using Jython:
AdminControl.stopServer(’serverName’)
– The following examples stop an application server with the node specified:
- Using Jacl:
$AdminControl stopServer serverName mynode
- Using Jython:
print AdminControl.stopServer(’serverName’, ’mynode’)
Example output:
WASX7337I: Invoked stop for server "serverName" Waiting for stop completion.
WASX7264I: Stop completed for server "serverName" on node "mynode"
– The following examples specify the server name and immediate:
- Using Jacl:
$AdminControl stopServer serverName immediate
- Using Jython:

482 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 AdminControl.stopServer(’serverName’, immediate)
v To stop a server on a WebSphere Application Server network deployment edition, choose one of the
following options:
– The following example specifies the server name and the node name:
- Using Jacl:
$AdminControl stopServer serverName nodeName
- Using Jython:
AdminControl.stopServer(’serverName’, ’nodeName’)
– The following example specifies the server name, the node name, and immediate:
- Using Jacl:
$AdminControl stopServer serverName nodeName immediate
- Using Jython:
AdminControl.stopServer(’serverName’, ’nodeName’, immediate)

Querying server state using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to query the server state:

1. Identify the server and assign it to the server variable. The following example returns the server
MBean that matches the partial object name string:
v Using Jacl:
set server [$AdminControl completeObjectName cell=mycell,node=mynode,name=server1,type=Server,*]
v Using Jython:
server = AdminControl.completObjectName(’cell=mycell,node=mynode,name=server1,type=Server,*’)
print server
Example output:
WebSphere:cell=mycell,name=server1,mbeanIdentifier=server.xml#Server_1,type=Server,node=mynode,
process=server1,processType=ManagedProcess
2. Query for the state attribute. For example:
v Using Jacl:
$AdminControl getAttribute $server state
v Using Jython:
print AdminControl.getAttribute(server, ’state’)
The getAttribute command returns the value of a single attribute.
Example output:
STARTED

Listing running applications on running servers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the following example to list all the running applications on all the running servers on each node of
each cell:
v Using Jacl:
*Provide this example as a Jacl script file and run it with the "-f" option:
1 #----------------------------------------------------------------
2 # lines 4 and 5 find all the cell and process them one at a time
3 #----------------------------------------------------------------

Chapter 4. Using the administrative clients 483

 4 set cells [$AdminConfig list Cell]
5 foreach cell $cells {
6 #-----------------------------------------------------------------------
7 # lines 10 and 11 find all the nodes belonging to the cell and
8 # process them at a time
9 #-----------------------------------------------------------------------
10 set nodes [$AdminConfig list Node $cell]
11 foreach node $nodes {
12 #--------------------------------------------------------------
13 # lines 16-20 find all the running servers belonging to the cell
14 # and node, and process them one at a time
15 #--------------------------------------------------------------
16 set cname [$AdminConfig showAttribute $cell name]
17 set nname [$AdminConfig showAttribute $node name]
18 set servs [$AdminControl queryNames type=Server,cell=$cname,node=$nname,*]
19 puts "Number of running servers on node $nname: [llength $servs]"
20 foreach server $servs {
21 #---------------------------------------------------------
22 # lines 25-31 get some attributes from the server to display;
23 # invoke an operation on the server JVM to display a property.
24 #---------------------------------------------------------
25 set sname [$AdminControl getAttribute $server name]
26 set ptype [$AdminControl getAttribute $server processType]
27 set pid [$AdminControl getAttribute $server pid]
28 set state [$AdminControl getAttribute $server state]
29 set jvm [$AdminControl queryNames type=JVM,cell=$cname,node=$nname,process=$sname,*]
30 set osname [$AdminControl invoke $jvm getProperty os.name]
31 puts " $sname ($ptype) has pid $pid; state: $state; on $osname"
32
j3 #---------------------------------------------------------
34 # line 37-42 find the applications running on this server and
35 # display the application name.
35 #---------------------------------------------------------
37 set apps [$AdminControl queryNames type=Application,cell=$cname,node=$nname,process=$sname,*]
38 puts " Number of applications running on $sname: [llength $apps]"
39 foreach app $apps {
40 set aname [$AdminControl getAttribute $app name]
41 puts " $aname"
42 }
43 puts "----------------------------------------------------"
44 puts ""
45
46 }
47 }
48 }
v Using Jython:
* Provide this example as a Jython script file and run it with the "-f" option:

1 #----------------------------------------------------------------
2 # lines 7 and 8 find all the cell and process them one at a time
3 #----------------------------------------------------------------
4 # get line separator
5 import java.lang.System as sys
6 lineSeparator = sys.getProperty(’line.separator’)
7 cells = AdminConfig.list(’Cell’).split(lineSeparator)
8 for cell in cells:
9 #-----------------------------------------------------------------------
10 # lines 13 and 14 find all the nodes belonging to the cell and
11 # process them at a time
12 #-----------------------------------------------------------------------
13 nodes = AdminConfig.list(’Node’, cell).split(lineSeparator)
14 for node in nodes:
15 #--------------------------------------------------------------
16 # lines 19-23 find all the running servers belonging to the cell
17 # and node, and process them one at a time
18 #--------------------------------------------------------------
19 cname = AdminConfig.showAttribute(cell, ’name’)

484 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 20 nname = AdminConfig.showAttribute(node, ’name’)
21 servs = AdminControl.queryNames(’type=Server,cell=’ + cname + ’,node=’ + nname + ’,*’).
split(lineSeparator)
22 print "Number of running servers on node " + nname + ": %s \n" % (len(servs))
23 for server in servs:
24 #---------------------------------------------------------
25 # lines 28-34 get some attributes from the server to display;
26 # invoke an operation on the server JVM to display a property.
27 #---------------------------------------------------------
28 sname = AdminControl.getAttribute(server, ’name’)
29 ptype = AdminControl.getAttribute(server, ’processType’)
30 pid = AdminControl.getAttribute(server, ’pid’)
31 state = AdminControl.getAttribute(server, ’state’)
32 jvm = AdminControl.queryNames(’type=JVM,cell=’ +
cname + ’,node=’ + nname + ’,process=’ + sname + ’,*’)
33 osname = AdminControl.invoke(jvm, ’getProperty’, ’os.name’)
34 print " " + sname + " " + ptype + " has pid " + pid + "; state: " + state + "; on " +
osname + "\n"
35
36 #---------------------------------------------------------
37 # line 40-45 find the applications running on this server and
38 # display the application name.
39 #---------------------------------------------------------
40 apps = AdminControl.queryNames(’type=Application,cell=’ +
Cname + ’,node=’ + nname + ’,process=’ + sname + ’,*’).split(lineSeparator)
41 print "Number of applications running on " + sname + ": %s \n" % (len(apps))
42 for app in apps:
43 aname = AdminControl.getAttribute(app, ’name’)
44 print aname + "\n"
45 print "----------------------------------------------------"
46 print "\n"
v Example output:
Number of running servers on node mynode: 2
mynode (NodeAgent) has pid 3592; state: STARTED; on Windows 2000
Number of applications running on mynode: 0
----------------------------------------------------

server1 (ManagedProcess) has pid 3972; state: STARTED; on Windows 2000

Number of applications running on server1: 0
----------------------------------------------------

Number of running servers on node mynodeManager: 1

dmgr (DeploymentManager) has pid 3308; state: STARTED; on Windows 2000
Number of applications running on dmgr: 2
adminconsole
filetransfer
----------------------------------------------------

Starting listener ports using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to start a listener port on an application server. The following example returns
a list of listener port MBeans:
1. Identify the listener port MBeans for the application server and assign it to the lPorts variable.
v Using Jacl:
set lPorts [$AdminControl queryNames type=ListenerPort,cell=mycell,node=mynode,process=server1,*]
v Using Jython:
lPorts = AdminControl.queryNames(’type=ListenerPort,cell=mycell,node=mynode,process=server1,*’)
print lPorts
Example output:

Chapter 4. Using the administrative clients 485

 WebSphere:cell=mycell,name=ListenerPort,mbeanIdentifier=server.xml#ListenerPort_1,type=ListenerPort,
node=mynode,process=server1
WebSphere:cell=mycell,name=listenerPort,mbeanIdentifier=ListenerPort,type=server.xml#ListenerPort_2,
node=mynode,process=server1
2. Start the listener port if it is not started. For example:
v Using Jacl:
foreach lPort $lPorts {
set state [$AdminControl getAttribute $lport started]
if {$state == "false"} {
$AdminControl invoke $lPort start
}
}
v Using Jython:
# get line separator
import java
lineSeparator = java.lang.System.getProperty(’line.separator’)

lPortsArray = lPorts.split(lineSeparator)
for lPort in lPortsArray:
state = AdminControl.getAttribute(lPort, ’started’)
if state == ’false’:
AdminControl.invoke(lPort, ’start’)
These pieces of Jacl and Jython code loop through the listener port MBeans. For each listener port
MBean, get the attribute value for the started attribute. If the attribute value is set to false, then start
the listener port by invoking the start operation on the MBean.

Managing generic servers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

A generic server is a server that the WebSphere Application Server manages but did not supply. You can
use WebSphere Application Server to define, start, stop, and monitor generic servers.
v To define a generic server, use the following example:
– Using Jacl:
$AdminTask createGenericServer mynode {-name generic1 -ConfigProcDef
{{"/usr/bin/myStartCommand" "arg1 arg2" "" "" "/tmp/workingDirectory" "/tmp/stopCommand" "argy argz"}}}
$AdminConfig save
– Using Jython:
AdminTask.createGenericServer(’mynode’, ’[-name generic1 -ConfigProcDef
[[c:\tmp\myStartCommand.exe "a b c" "" "" C:\tmp\myStopCommand "x y z"]]]’)
AdminConfig.save()
v To start a generic server, use the launchProcess parameter, for example:
– Using Jacl:
set nodeagent [$AdminControl queryNames *:*,type=NodeAgent]
$AdminControl invoke $nodeagent launchProcess generic1
– Using Jython:
nodeagent = AdminControl.queryNames (’*:*,type=NodeAgent’)
AdminControl.invoke(nodeagent, ’launchProcess’, ’generic1’)
Example output:
true
or
false
v To stop a generic server, use the terminate parameter, for example:
– Using Jacl:

486 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set nodeagent [$AdminControl queryNames *:*,type=NodeAgent]
$AdminControl invoke $nodeagent terminate generic1
– Using Jython:
nodeagent = AdminControl.queryNames (’*:*,type=NodeAgent’)
AdminControl.invoke(nodeagent, ’terminate’, ’generic1’)
Example output:
true
or
false
v To monitor the server state, use the getProcessStatus parameter, for example:
– Using Jacl:
$AdminControl invoke $nodeagent getProcessStatus generic1
Using Jython:
AdminControl.invoke(nodeagent, ’getProcessStatus’, ’generic1’)
Example output:
RUNNING
or
STOPPED

Setting development mode for server objects using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to set the development mode for a server object:
1. Locate the server object. The following example selects the first server found:
v Using Jacl:
set server [$AdminConfig getid /Server:server1/]
v Using Jython:
server = AdminConfig.getid(’/Server:server1/’)
2. Enable development mode:
v Using Jacl:
$AdminConfig modify $server "{developmentMode true}"
v Using Jython:
AdminConfig.modify(server, [[’developmentMode’, ’true’]])
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Disabling parallel startup using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to disable parallel startup:

1. Locate the server object. The following example selects the first server found:
v Using Jacl:
set server[$AdminConfig getid /Server:server1/]
v Using Jython:

Chapter 4. Using the administrative clients 487

 server = AdminConfig.getid(’/Server:server1/’]
2. Enable development mode. For example:
v Using Jacl:
$AdminConfig modify $server "{parallelStartEnabled false}"
v Using Jython:
AdminConfig.modify(server, [[’parallelStartEnabled’, ’false’]])
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Removing multicast endpoints using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

WebSphere Application Server uses multicast broadcasting at the node level to allow a node agent to
discover the managed processes in the node. The IPv4 and IPv6 multicast addresses are not compatible.
Both the IPv4 and IPv6 multicast addresses are defined in the node agent configuration and when a node
agent starts both addresses will be tried in sequence. It is recommended that you disable one of the
multicast addresses after installation. By limiting multicast discovery to one protocol, the node agent will
run more efficiently. Perform the following steps to remove a multicast endpoint:
1. Remove the multicast end point:
v Using Jacl:
set se [$AdminConfig getid /Node:y2001/ServerIndex:/]
set eprs [lindex [$AdminConfig showAttribute $se endPointRefs] 0]
foreach ep $eprs {
set epName [$AdminConfig showAttribute $ep endPointName]
if {$epName == "NODE_MULTICAST_DISCOVERY_ADDRESS"} {
puts "Removing NODE_MULTICAST_DISCOVERY_ADDRESS..."
$AdminConfig remove $ep
}
}
v Using Jython:
se = AdminConfig.getid(’/Node:y2001/ServerIndex:/’)
import java
lineseparator = java.lang.System.getProperty(’line.separator’)
eprs = AdminConfig.showAttribute(se, [’endPointRefs’]).split(lineseparator)[0]
print eprs
for ep in eprs:
epName = AdminConfig.showAttribute(ep, [’endPointName’])
if (epName) == "[NODE_MULTICAST_DISCOVERY_ADDRESS]":
print "Removing NODE_MULTICAST_DISCOVERY_ADDRESS..."
AdminConfig.remove(ep)
2. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
3. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Obtaining server version information with scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to query the server version information:

1. Identify the server and assign it to the server variable.

488 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jacl:
set server [$AdminControl completeObjectName type=Server,name=server1,node=mynode,*]
v Using Jython:
server = AdminControl.completeObjectName(’type=Server,name=server1,node=mynode,*’)
print server
Example output:
WebSphere:cell=mycell,name=server1,mbeanIdentifier=server.xml#Server_1,type=Server,node=mynode,
process=server1,processType=ManagedProcess
2. Query the server version. The server version information is stored in the serverVersion attribute. The
getAttribute command returns the attribute value of a single attribute, passing in the attribute name.
v Using Jacl:
$AdminControl getAttribute $server1 serverVersion
v Using Jython:
print AdminControl.getAttribute(server1, ’serverVersion’)
Example output for a Network Deployment installation follows:
IBM WebSphere Application Server Version Report
---------------------------------------------------------------------------

Platform Information
------------------------------------------------------------------------

Name: IBM WebSphere Application Server

Version: 5.0

Product Information
------------------------------------------------------------------------

ID: BASE
Name: IBM WebSphere Application Server
Build Date: 9/11/02
Build Level: r0236.11
Version: 5.0.0

Product Information
------------------------------------------------------------------------

ID: ND
Name: IBM WebSphere Application Server for Network Deployment
Build Date: 9/11/02
Build Level: r0236.11
Version: 5.0.0

---------------------------------------------------------------------------
End Report
---------------------------------------------------------------------------

Clustering servers with scripting

This topic contains the following tasks:
v “Creating clusters using scripting” on page 490
v “Creating cluster members using scripting” on page 490
v “Starting a cluster using scripting” on page 491
v “Querying cluster state using scripting” on page 492
v “Stopping clusters using scripting” on page 492

Chapter 4. Using the administrative clients 489

Creating clusters using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to create a cluster:

1. Identify the server to convert to a cluster and assign it to the server variable:
Using Jacl:
set server [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
Using Jython:
server = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
2. Convert the existing server to a cluster by using the convertToCluster command passing in the
existing server and the cluster name:
Using Jacl:
$AdminConfig convertToCluster $server myCluster1
This command converts a cluster named myCluster with server1 as its member.
Using Jython:
print AdminConfig.convertToCluster(server, ’myCluster1’)
Example output:
myCluster1(cells/mycell/cluster/myCluster1|cluster.xml#ClusterMember_1)
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Creating cluster members using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

You can also use the AdminTask object to perform this task. For more about using the AdminTask object to
create cluster members, see the Commands for AdminTask object article. To create cluster members using
the AdminConfig object, perform the following steps:
1. Identify the existing cluster and assign it to the cluster variable:
v Using Jacl:
set cluster [$AdminConfig getid /ServerCluster:myCluster1/]
v Using Jython:
cluster = AdminConfig.getid(’/ServerCluster:myCluster1/’)
print cluster
Example output:
myCluster1(cells/mycell/cluster/myCluster1|cluster.xml#ServerCluster_1)
2. Identify the node to create the new server and assign it to the node variable:
v Using Jacl:
set node [$AdminConfig getid /Node:mynode/]
v Using Jython:
node = AdminConfig.getid(’/Node:mynode/’)
print node
Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
3. (Optional) Identify the cluster member template and assign it to the serverTemplate variable:

490 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jacl:
set serverTemplate [$AdminConfig listTemplates Server]
v Using Jython:
serverTemplate = AdminConfig.listTemplates(’Server’)
print serverTemplate
Example output:
server1(templates/default/nodes/servers/server1|server.xml#Server_1)
4. Create the new cluster member, by using the createClusterMember command.
v The following example creates the new cluster member, passing in the existing cluster configuration
ID, existing node configuration ID, and the new member attributes:
– Using Jacl:
$AdminConfig createClusterMember $cluster $node {{memberName clusterMember1}}
– Using Jython:
AdminConfig.createClusterMember(cluster, node, [[’memberName’, ’clusterMember1’]])
v The following example creates the new cluster member with a template, passing in the existing
cluster configuration ID, existing node configuration ID, the new member attributes, and the template
ID:
– Using Jacl:
$AdminConfig createClusterMember $cluster $node {{memberName clusterMember1}} $serverTemplate
– Using Jython:
print AdminConfig.createClusterMember(cluster, node, [[’memberName’, ’clusterMember1’]], serverTemplate)
Example output:
clusterMember1(cells/mycell/clusters/myCluster1|cluster.xml$ClusterMember_2)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Starting a cluster using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to start a cluster:

1. Identify the ClusterMgr MBean and assign it to the clusterMgr variable.
v Using Jacl:
set clusterMgr [$AdminControl completeObjectName cell=mycell,type=ClusterMgr,*]
v Using Jython:
clusterMgr = AdminControl.completeObjectName(’cell=mycell,type=ClusterMgr,*’)
print clusterMgr
This command returns the ClusterMgr MBean.
Example output:
WebSphere:cell=mycell,name=ClusterMgr,mbeanIdentifier=ClusterMgr,type=ClusterMgr,process=dmgr
2. Refresh the list of clusters.
v Using Jacl:
$AdminControl invoke $clusterMgr retrieveClusters
v Using Jython:
AdminControl.invoke(clusterMgr, ’retrieveClusters’)
This command calls the retrieveClusters operation on the ClusterMgr MBean.

Chapter 4. Using the administrative clients 491

3. Identify the Cluster MBean and assign it to the cluster variable.
v Using Jacl:
set cluster [$AdminControl completeObjectName cell=mycell,type=Cluster,name=cluster1,*
v Using Jython:
cluster = AdminControl.completeObjectName(’cell=mycell,type=Cluster,name=cluster1,*’)
print cluster
This command returns the Cluster MBean.
Example output:
WebSphere:cell=mycell,name=cluster1,mbeanIdentifier=Cluster,type=Cluster,process=cluster1
4. Start the cluster.
v Using Jacl:
$AdminControl invoke $cluster start
v Using Jython:
AdminControl.invoke(cluster, ’start’)
This command invokes the start operation on the Cluster MBean.

Querying cluster state using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to query cluster state:

1. Identify the Cluster MBean and assign it to the cluster variable.
v Using Jacl:
set cluster [$AdminControl completeObjectName cell=mycell,type=Cluster,name=cluster1,*
v Using Jython:
cluster = AdminControl.completeObjectName(’cell=mycell,type=Cluster,name=cluster1,*’)
print cluster
This command returns the Cluster MBean.
Example output:
WebSphere:cell=mycell,name=cluster1,mbeanIdentifier=Cluster,type=Cluster,process=cluster1
2. Query the cluster state.
v Using Jacl:
$AdminControl getAttribute $cluster state
v Using Jython:
AdminControl.getAttribute(cluster, ’state’)
This command returns the value of the run-time state attribute.

Stopping clusters using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to stop a cluster:

1. Identify the Cluster MBean and assign it to the cluster variable.
v Using Jacl:
set cluster [$AdminControl completeObjectName cell=mycell,type=Cluster,name=cluster1,*
v Using Jython:

492 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 cluster = AdminControl.completeObjectName(’cell=mycell,type=Cluster,name=cluster1,*’)
print cluster
This command returns the Cluster MBean.
Example output:
WebSphere:cell=mycell,name=cluster1,mbeanIdentifier=Cluster,type=Cluster,process=cluster1
2. Stop the cluster.
v Using Jacl:
$AdminControl invoke $cluster stop
v Using Jython:
AdminControl.invoke(cluster, ’stop’)
This command invokes the stop operation on the Cluster MBean.

Configuring security with scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

If you enable security for a WebSphere Application Server cell, supply authentication information to
communicate with servers.

The sas.client.props and the soap.client.props files are located in the properties directory for each
WebSphere Application Server profile, profilePath/properties.
v The nature of the properties file updates required for running in secure mode depend on whether you
connect with a Remote Method Invocation (RMI) connector, or a Simple Object Access Protocol (SOAP)
connector:
– If you use a Remote Method Invocation (RMI) connector, set the following properties in the
sas.client.props file with the appropriate values:
com.ibm.CORBA.loginUserid=
com.ibm.CORBA.loginPassword=

Also, set the following property:

com.ibm.CORBA.loginSource=properties

The default value for this property is prompt in the sas.client.props file. If you leave the default
value, a dialog box appears with a password prompt. If the script is running unattended, it appears to
hang.
– If you use a Simple Object Access Protocol (SOAP) connector, set the following properties in the
soap.client.props file with the appropriate values:
com.ibm.SOAP.securityEnabled=true
com.ibm.SOAP.loginUserid=
com.ibm.SOAP.loginPassword=
v To specify user and password information, choose one of the following methods:
– Specify user name and password on a command line, using the -user and -password commands.
For example:
wsadmin.sh -conntype RMI -port 2809 -user u1 -password secret1
– Specify user name and password in the sas.client.props file for a RMI connector or the
soap.client.props file for a SOAP connector.
If you specify user and password information on a command line and in the sas.client.props file or the
soap.client.props file, the command line information overrides the information in the props file.
Warning: On UNIX system, the use of -password option may result in security exposure as the
password information becomes visible to the system status program such as ps command which can be
invoked by other user to display all the running processes. Do not use this option if security exposure is

Chapter 4. Using the administrative clients 493

 a concern. Instead, specify user and password information in the soap.client.props file for SOAP
connector or sas.client.props file for RMI connector. The soap.client.props and sas.client.props files are
located in the properties directory of your WebSphere profile.

Enabling and disabling global security using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

The default profile sets up procedures so that you can enable and disable global security based on
LocalOS registry.
v You can use the help command to find out the arguments that you need to provide with this call, for
example:
– Using Jacl:
securityon help
Example output:
Syntax: securityon user password
– Using Jython:
securityon()
Example output:
Syntax: securityon(user, password)
v To enable global security based on the LocalOS registry, use the following procedure call and
arguments:
– Using Jacl:
securityon user1 password1
– Using Jython:
securityon(’user1’, ’password1’)
v To disable global security based on the LocalOS registry, use the following procedure call:
– Using Jacl:
securityoff
– Using Jython:
securityoff()

Enabling and disabling Java 2 security using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to enable or disable Java 2 security:

1. Identify the security configuration object and assign it to the security variable:
v Using Jacl:
set security [$AdminConfig list Security]
v Using Jython:
security = AdminConfig.list(’Security’)
print security
Example output:
(cells/mycell|security.xml#Security_1)
2. Modify the enforceJava2Security attribute to enable or disable Java 2 security. For example:
v To enable Java 2 security:
– Using Jacl:

494 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 $AdminConfig modify $security {{enforceJava2Security true}}
– Using Jython:
AdminConfig.modify(security, [[’enforceJava2Security’, ’true’]])
v To disable Java 2 security:
– Using Jacl:
$AdminConfig modify $security {{enforceJava2Security false}}
– Using Jython:
AdminConfig.modify(security, [[’enforceJava2Security’, ’false’]])
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring data access with scripting

This topic contains the following tasks:
v “Configuring a JDBC provider using scripting”
v “Configuring new data sources using scripting” on page 496
v “Configuring new connection pools using scripting” on page 497
v “Configuring new data source custom properties using scripting” on page 498
v “Configuring new J2CAuthentication data entries using scripting” on page 499
v “Configuring new WAS40 data sources using scripting” on page 500
v “Configuring new WAS40 connection pools using scripting” on page 500
v “Configuring new WAS40 custom properties using scripting” on page 502
v “Configuring new J2C resource adapters using scripting” on page 503
v “Configuring custom properties for J2C resource adapters using scripting” on page 504
v “Configuring new J2C connection factories using scripting” on page 505
v “Configuring new J2C authentication data entries using scripting” on page 506
v “Configuring new J2C administrative objects using scripting” on page 509
v “Configuring new J2C activation specs using scripting” on page 507
v “Testing data source connections using scripting” on page 510

Configuring a JDBC provider using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new JDBC provider:

1. Identify the parent ID and assign it to the node variable. The following example uses the node
configuration object as the parent. You can modify this example to use the cell, cluster, server, or
application configuration object as the parent.
v Using Jacl:
set node [$AdminConfig getid /Cell:mycell/Node:mynode/]
v Using Jython:
node = AdminConfig.getid(’/Cell:mycell/Node:mynode/’)
print node
Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
2. Identify the required attributes:

Chapter 4. Using the administrative clients 495

 v Using Jacl:
$AdminConfig required JDBCProvider
v Using Jython:
print AdminConfig.required(’JDBCProvider’)
Example output:
Attribute Type
name String
implementationClassName String
3. Set up the required attributes and assign it to the jdbcAttrs variable. You can modify the following
example to setup non-required attributes for JDBC provider.
v Using Jacl:
set n1 [list name JDBC1]
set implCN [list implementationClassName myclass]
set jdbcAttrs [list $n1 $implCN]
Example output:
{name {JDBC1}} {implementationClassName {myclass}}
v Using Jython:
n1 = [’name’, ’JDBC1’]
implCN = [’implementationClassName’, ’myclass’]
jdbcAttrs = [n1, implCN]
print jdbcAttrs
Example output:
[[’name’, ’JDBC1’], [’implementationClassName’, ’myclass’]]
4. Create a new JDBC provider using node as the parent:
v Using Jacl:
$AdminConfig create JDBCProvider $node $jdbcAttrs
v Using Jython:
AdminConfig.create(’JDBCProvider’, node, jdbcAttrs)
Example output:
JDBC1(cells/mycell/nodes/mynode|resources.xml#JDBCProvider_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new data sources using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new data source:

1. Identify the parent ID:
v Using Jacl:
set newjdbc [$AdminConfig getid /Cell:mycell/Node:mynode/JDBCProvider:JDBC1/]
v Using Jython:
newjdbc = AdminConfig.getid(’/Cell:mycell/Node:mynode/JDBCProvider:JDBC1/’)
print newjdbc
Example output:
JDBC1(cells/mycell/nodes/mynode|resources.xml#JDBCProvider_1)
2. Obtain the required attributes:
v Using Jacl:

496 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 $AdminConfig required DataSource
v Using Jython:
print AdminConfig.required(’DataSource’)
Example output:
Attribute Type
name String
3. Setting up required attributes:
v Using Jacl:
set name [list name DS1]
set dsAttrs [list $name]
v Using Jython:
name = [’name’, ’DS1’]
dsAttrs = [name]
4. Create a data source:
v Using Jacl:
set newds [$AdminConfig create DataSource $newjdbc $dsAttrs]
v Using Jython:
newds = AdminConfig.create(’DataSource’, newjdbc, dsAttrs)
print newds
Example output:
DS1(cells/mycell/nodes/mynode|resources.xml#DataSource_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new connection pools using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new connection pool:

1. Identify the parent ID:
v Using Jacl:
set newds [$AdminConfig getid /Cell:mycell/Node:mynode/JDBCProvider:JDBC1/DataSource:DS1/]
v Using Jython:
newds = AdminConfig.getid(’/Cell:mycell/Node:mynode/JDBCProvider:JDBC1/DataSource:DS1/’)
Example output:
DS1(cells/mycell/nodes/mynode|resources.xml$DataSource_1)
2. Creating connection pool:
v Using Jacl:
$AdminConfig create ConnectionPool $newds {}
v Using Jython:
print AdminConfig.create(’ConnectionPool’, newds, [])
Example output:
(cells/mycell/nodes/mynode|resources.xml#ConnectionPool_1)
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.
Chapter 4. Using the administrative clients 497
Configuring new data source custom properties using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new data source custom property:g
1. Identify the parent ID:
v Using Jacl:
set newds [$AdminConfig getid /Cell:mycell/Node:mynode/JDBCProvider:JDBC1/DataSource:DS1/]
v Using Jython:
newds = AdminConfig.getid(’/Cell:mycell/Node:mynode/JDBCProvider:JDBC1/DataSource:DS1/’)
print newds
Example output:
DS1(cells/mycell/nodes/mynode|resources.xml$DataSource_1)
2. Get the J2EE resource property set:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newds propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newds, ’propertySet’)
print propSet
Example output:
(cells/mycell/nodes/mynode|resources.xml#J2EEResourcePropertySet_8)
3. Get required attribute:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
4. Set up attributes:
v Using Jacl:
set name [list name RP4]
set rpAttrs [list $name]
v Using Jython:
name = [’name’, ’RP4’]
rpAttrs = [name]
5. Create a J2EE resource property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $rpAttrs
v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, rpAttrs)
Example output:
RP4(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_8)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

498 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring new J2CAuthentication data entries using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new J2CAuthentication data entry:

1. Identify the parent ID:
v Using Jacl:
set security [$AdminConfig getid /Cell:mycell/Security:/]
v Using Jython:
security = AdminConfig.getid(’/Cell:mycell/Security:/’)
print security
Example output:
(cells/mycell|security.xml#Security_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required JAASAuthData
v Using Jython:
print AdminConfig.required(’JAASAuthData’)
Example output:
Attribute Type
alias String
userId String
password String
3. Set up required attributes:
v Using Jacl:
set alias [list alias myAlias]
set userid [list userId myid]
set password [list password secret]
set jaasAttrs [list $alias $userid $password]
Example output:
{alias myAlias} {userId myid} {password secret}
v Using Jython:
alias = [’alias’, ’myAlias’]
userid = [’userId’, ’myid’]
password = [’password’, ’secret’]
jaasAttrs = [alias, userid, password]
print jaasAttrs
Example output:
[[’alias’, ’myAlias’], [’userId’, ’myid’], [’password’, ’secret’]]
4. Create JAAS auth data:
v Using Jacl:
$AdminConfig create JAASAuthData $security $jaasAttrs
v Using Jython:
print AdminConfig.create(’JAASAuthData’, security, jaasAttrs)
Example output:
(cells/mycell|security.xml#JAASAuthData_2)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Chapter 4. Using the administrative clients 499

Configuring new WAS40 data sources using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new WAS40 data source:

1. Identify the parent ID:
v Using Jacl:
set newjdbc [$AdminConfig getid "/JDBCProvider:Cloudscape JDBC Provider/"]
v Using Jython:
newjdbc = AdminConfig.getid(’/JDBCProvider:Cloudscape JDBC Provider/’)
print newjdbc
Example output:
JDBC1(cells/mycell/nodes/mynode|resources.xml$JDBCProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required WAS40DataSource
v Using Jython:
print AdminConfig.required(’WAS40DataSource’)
Example output:
Attribute Type
name String
3. Set up required attributes:
v Using Jacl:
set name [list name was4DS1]
set ds4Attrs [list $name]
v Using Jython:
name = [’name’, ’was4DS1’]
ds4Attrs = [name]
4. Create WAS40DataSource:
v Using Jacl:
set new40ds [$AdminConfig create WAS40DataSource $newjdbc $ds4Attrs]
v Using Jython:
new40ds = AdminConfig.create(’WAS40DataSource’, newjdbc, ds4Attrs)
print new40ds
Example output:
was4DS1(cells/mycell/nodes/mynode|resources.xml#WAS40DataSource_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new WAS40 connection pools using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new WAS40 connection pool:

1. Identify the parent ID:
v Using Jacl:

500 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set new40ds [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/JDBCProvider:JDBC1/WAS40DataSource:was4DS1
v Using Jython:
new40ds = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/JDBCProvider:JDBC1/WAS40DataSource:was4DS1/’)
print new40ds
Example output:
was4DS1(cells/mycell/nodes/mynodes:resources.xml$WAS40DataSource_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required WAS40ConnectionPool
v Using Jython:
print AdminConfig.required(’WAS40ConnectionPool’)
Example output:
Attribute Type
minimumPoolSize Integer
maximumPoolSize Integer
connectionTimeout Integer
idleTimeout Integer
orphanTimeout Integer
statementCacheSize Integer
3. Set up required attributes:
v Using Jacl:
set mps [list minimumPoolSize 5]
set minps [list minimumPoolSize 5]
set maxps [list maximumPoolSize 30]
set conn [list connectionTimeout 10]
set idle [list idleTimeout 5]
set orphan [list orphanTimeout 5]
set scs [list statementCacheSize 5]
set 40cpAttrs [list $minps $maxps $conn $idle $orphan $scs]
Example output:
{minimumPoolSize 5} {maximumPoolSize 30}
{connectionTimeout 10} {idleTimeout 5}
{orphanTimeout 5} {statementCacheSize 5}
v Using Jython:
minps = [’minimumPoolSize’, 5]
maxps = [’maximumPoolSize’, 30]
conn = [’connectionTimeout’, 10]
idle = [’idleTimeout’, 5]
orphan = [’orphanTimeout’, 5]
scs = [’statementCacheSize’, 5]
cpAttrs = [minps, maxps, conn, idle, orphan, scs]
print cpAttrs
Example output:
[[minimumPoolSize, 5], [maximumPoolSize, 30],
[connectionTimeout, 10], [idleTimeout, 5],
[orphanTimeout, 5], [statementCacheSize, 5]]
4. Create was40 connection pool:
v Using Jacl:
$AdminConfig create WAS40ConnectionPool $new40ds $40cpAttrs
v Using Jython:
print AdminConfig.create(’WAS40ConnectionPool’, new40ds, 40cpAttrs)
Example output:
(cells/mycell/nodes/mynode:resources.xml#WAS40ConnectionPool_1)

Chapter 4. Using the administrative clients 501

5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new WAS40 custom properties using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new WAS40 custom properties:

1. Identify the parent ID:
v Using Jacl:
set new40ds [$AdminConfig getid /Cell:mycell/Node:mynode/JDBCProvider:JDBC1/WAS40DataSource:was4DS1/]
v Using Jython:
new40ds = AdminConfig.getid(’/Cell:mycell/Node:mynode/JDBCProvider:JDBC1/WAS40DataSource:was4DS1/’)
print new40ds
Example output:
was4DS1(cells/mycell/nodes/mynodes|resources.xml$WAS40DataSource_1)
2. Get required attributes:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newds propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newds, ’propertySet’)
print propSet
Example output:
(cells/mycell/nodes/mynode|resources.xml#J2EEResourcePropertySet_9)
3. Get required attribute:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
4. Set up required attributes:
v Using Jacl:
set name [list name RP5]
set rpAttrs [list $name]
v Using Jython:
name = [’name’, ’RP5’]
rpAttrs = [name]
5. Create J2EE Resource Property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $rpAttrs
v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, rpAttrs)
Example output:
RP5(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_9)

502 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new J2C resource adapters using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new J2C resource adapter:

1. Identify the parent ID and assign it to the node variable. The following example uses the node
configuration object as the parent. You can modify this example to use the cell, cluster, server, or
application configuration object as the parent.
v Using Jacl:
set node [$AdminConfig getid /Cell:mycell/Node:mynode/]
v Using Jython:
node = AdminConfig.getid(’/Cell:mycell/Node:mynode/’)
print node
Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required J2CResourceAdapter
v Using Jython:
print AdminConfig.required(’J2CResourceAdapter’)
Example output:
Attribute Type
name String
3. Set up the required attributes:
v Using Jacl:
set rarFile c:/currentScript/cicseci.rar
set option [list -rar.name RAR1]
v Using Jython:
rarFile = ’c:/currentScript/cicseci.rar’
option = ’[-rar.name RAR1]’
4. Create a resource adapter:
v Using Jacl:
set newra [$AdminConfig installResourceAdapter $rarFile mynode $option]
v Using Jython:
newra = AdminConfig.installResourceAdapter(rarFile, ’mynode’, option)
print newra
Example output:
RAR1(cells/mycell/nodes/mynode|resources.xml#J2CResourceAdapter_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Chapter 4. Using the administrative clients 503

Configuring custom properties for J2C resource adapters using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new custom property for a J2C resource adapters:
1. Identify the parent ID and assign it to the newra variable.
v Using Jacl:
set newra [$AdminConfig getid /Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/]
v Using Jython:
newra = AdminConfig.getid(’/Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/’)
print newra
Example output:
RAR1(cells/mycell/nodes/mynode|resources.xml#J2CResourceAdapter_1)
2. Get the J2EE resource property set:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newra propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newra, ’propertySet’)
print propSet
Example output:
(cells/mycell/nodes/mynode|resources.xml#PropertySet_8)
3. Identify the required attributes:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
4. Set up the required attributes:
v Using Jacl:
set name [list name RP4]
set rpAttrs [list $name]
v Using Jython:
name = [’name’, ’RP4’]
rpAttrs = [name]
5. Create a J2EE resource property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $rpAttrs
v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, rpAttrs)
Example output:
RP4(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_8)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

504 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring new J2C connection factories using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new J2C connection factory:

1. Identify the parent ID and assign it to the newra variable.
v Using Jacl:
set newra [$AdminConfig getid /Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/]
v Using Jython:
newra = AdminConfig.getid(’/Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/’)
print newra
Example output:
RAR1(cells/mycell/nodes/mynode|resources.xml#J2CResourceAdapter_1)
2. There are two ways to configure a new J2C connection factory. Perform one of the following:
v Using the AdminTask object:
a. List the connection factory interfaces:
– Using Jacl:
$AdminTask listConnectionFactoryInterfaces $newra
– Using Jacl:
AdminTask.listConnectionFactoryInterfaces(newra)
Example output:
javax.sql.DataSource
b. Create a J2CConnectionFactory:
– Using Jacl:
$AdminTask createJ2CConnectionFactory $newra { -name cf1 -jndiName eis/cf1
-connectionFactoryInterface avax.sql.DataSource
– Using Jacl:
AdminTask.createJ2CConnectionFactory(newra, ’[’-name’, ’cf1’, ’-jndiName’, ’eis/cf1’,
’-connectionFactoryInterface’, ’avax.sql.DataSource’]’)
v Using the AdminConfig object:
a. Identify the required attributes:
– Using Jacl:
$AdminConfig required J2CConnectionFactory
– Using Jython:
print AdminConfig.required(’J2CConnectionFactory’)
Example output:
Attribute Type
connectionDefinition ConnectionDefinition@
b. If your resource adapter is JCA1.5 and you have multiple connection definitions defined, it is
required that you specify the ConnectionDefinition attribute. If your resource adapter is JCA1.5
and you have only one connection definition defined, it will be picked up automatically. If your
resource adapter is JCA1.0, you do not need to specify the ConnectionDefinition attribute.
Perform the following command to list the connection definitions defined by the resource
adapter:
– Using Jacl:
$AdminConfig list ConnectionDefinition $newra
– Using Jython:
print AdminConfig.list(’ConnectionDefinition’, $newra)

Chapter 4. Using the administrative clients 505

 c. Set up the required attributes:
– Using Jacl:
set name [list name J2CCF1]
set j2ccfAttrs [list $name]
set jname [list jndiName eis/j2ccf1]
– Using Jython:
name = [’name’, ’J2CCF1’]
j2ccfAttrs = [name]
jname = [’jndiName’, eis/j2ccf1]
d. If you are specifying the ConnectionDefinition attribute, also set up the following:
– Using Jacl:
set cdattr [list connectionDefinition $cd]
– Using Jython:
cdattr = [’connectionDefinition’, $cd]
e. Create a J2C connection factory:
– Using Jacl:
$AdminConfig create J2CConnectionFactory $newra $j2ccfAttrs
– Using Jython:
print AdminConfig.create(’J2CConnectionFactory’, newra, j2ccfAttrs)
Example output:
J2CCF1(cells/mycell/nodes/mynode|resources.xml#J2CConnectionFactory_1)
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new J2C authentication data entries using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new J2C authentication data entry:
1. Identify the parent ID and assign it to the security variable.
v Using Jacl:
set security [$AdminConfig getid /Security:mysecurity/]
v Using Jython:
security = AdminConfig.getid(’/Security:mysecurity/’)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required JAASAuthData
v Using Jython:
print AdminConfig.required(’JAASAuthData’)
Example output:
Attribute Type
alias String
userId String
password String
3. Set up the required attributes:
v Using Jacl:

506 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set alias [list alias myAlias]
set userid [list userId myid]
set password [list password secret]
set jaasAttrs [list $alias $userid $password]
Example output:
{alias myAlias} {userId myid} {password secret}
v Using Jython:
alias = [’alias’, ’myAlias’]
userid = [’userId’, ’myid’]
password = [’password’, ’secret’]
jaasAttrs = [alias, userid, password]
Example output:
[[alias, myAlias], [userId, myid], [password, secret]]
4. Create JAAS authentication data:
v Using Jacl:
$AdminConfig create JAASAuthData $security $jaasAttrs
v Using Jython:
print AdminConfig.create(’JAASAuthData’, security, jaasAttrs)
Example output:
(cells/mycell/nodes/mynode|resources.xml#JAASAuthData_2)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new J2C activation specs using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a J2C activation specs:

1. Identify the parent ID and assign it to the newra variable.
v Using Jacl:
set newra [$AdminConfig getid /Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/]
v Using Jython:
newra = AdminConfig.getid(’/Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/’)
print newra
Example output:
RAR1(cells/mycell/nodes/mynode|resources.xml#J2CResourceAdapter_1)
2. There are two ways to configure a new J2C administrative object. Perform one of the following:
v Using the AdminTask object:
a. List the administrative object interfaces:
Using Jacl:
$AdminTask listMessageListenerTypes $newra
Using Jython:
AdminTask.listMessageListenerTypes(newra)
Example output:
javax.jms.MessageListener
b. Create a J2C administrative object:
Using Jacl:

Chapter 4. Using the administrative clients 507

 $AdminTask createJ2CActivationSpec $newra { -name ac1 -jndiName eis/ac1
-message ListenerType javax.jms.MessageListener}
Using Jython:
AdminTask.createJ2CActivationSpec(newra, [’-name’, ’ao1’, ’-jndiName’, ’eis/ao1’, ’-message’,
’ListenerType’, ’javax.jms.MessageListener’])
v Using the AdminConfig object:
a. Using Jacl:
$AdminConfig required J2CActivationSpec
Using Jython:
print AdminConfig.required(’J2CActivationSpec’)
Example output:
Attribute Type
activationSpec ActivationSpec@
b. If your resource adapter is JCA V1.5 and you have multiple activation specs defined, it is
required that you specify the activation spec attribute. If your resource adapter is JCA V1.5 and
you have only one activation spec defined, it will be picked up automatically. If your resource
adapter is JCA V1.0, you do not need to specify the activationSpec attribute. Perform the
following command to list the activation specs defined by the resource adapter:
Using Jacl:
$AdminConfig list ActivationSpec $newra
Using Jython:
print AdminConfig.list(’ActivationSpec’, $newra)
c. Set the administrative object that you need to a variable:
Using Jacl:
set ac ActivationSpecID
set name [list name J2CAC1]
set jname [jndiName eis/j2cac1]
set j2cacAttrs [list $name $jname]
Using Jython:
ac = ActivationSpecID
name = [’name’, ’J2CAC1’]
jname = [’jndiName’, ’eis/j2cac1’]
j2cacAttrs = [name, jname]
d. If you are specifying the ActivationSpec attribute, also set up the following:
Using Jacl:
set cdcttr [list activationSpec $ac]
Using Jython:
cdattr = [’activationSpec’, ac]
e. Create a J2C activation spec object:
Using Jacl:
$AdminConfig create J2CActivationSpec $newra $j2cacAttrs
Using Jython:
print AdminConfig.create(’J2CActivationSpec’, newra,j2cacAttrs)
Example output:
J2CAC1(cells/mycell/nodes/mynode|resources.xml#J2CActivationSpec_1)
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

508 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring new J2C administrative objects using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a J2C administrative object:

1. Identify the parent ID and assign it to the newra variable.
v Using Jacl:
set newra [$AdminConfig getid /Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/]
v Using Jython:
newra = AdminConfig.getid(’/Cell:mycell/Node:mynode/J2CResourceAdapter:RAR1/’)
print newra
Example output:
RAR1(cells/mycell/nodes/mynode|resources.xml#J2CResourceAdapter_1)
2. There are two ways to configure a new J2C administrative object. Perform one of the following:
v Using the AdminTask object:
a. List the administrative object interfaces:
Using Jacl:
$AdminTask listAdminObjectInterfaces $newra
Using Jython:
AdminTask.listAdminObjectInterfaces(newra)
Example output:
com.ibm.test.message.FVTMessageProvider
b. Create a J2C administrative object:
Using Jacl:
$AdminTask createJ2CAdminObject $newra { -name ao1 -jndiName eis/ao1
-adminObjectInterface com.ibm.test.message.FVTMessageProvider }
Using Jython:
AdminTask.createJ2CAdminObject(newra, [’-name’, ’ao1’, ’-jndiName’, ’eis/ao1’, ’-adminObjectInterface’,
’com.ibm.test.message.FVTMessageProvider’])
v Using the AdminConfig object:
a. Using Jacl:
$AdminConfig required J2CAdminObject
Using Jython:
print AdminConfig.required(’J2CAdminObject’)
Example output:
Attribute Type
adminObject AdminObject@
b. If your resource adapter is JCA V1.5 and you have multiple administrative objects defined, it is
required that you specify the administrative object attribute. If your resource adapter is JCA V1.5
and you have only one administrative object defined, it will be picked up automatically. If your
resource adapter is JCA V1.0, you do not need to specify the administrative object attribute.
Perform the following command to list the administrative objects defined by the resource
adapter:
Using Jacl:
$AdminConfig list AdminObject $newra
Using Jython:
print AdminConfig.list(’AdminObject’, $newra)
c. Set the administrative objects that you need to a variable:

Chapter 4. Using the administrative clients 509

 Using Jacl:
set ao AdminObjectId
set name [list name J2CAO1]
set jname [jndiName eis/j2cao1]
set j2caoAttrs [list $name $jname]
Using Jython:
ao = AdminObjectId
name = [’name’, ’J2CAO1’]
set jname = [’jndiName’, eis/j2cao1]
j2caoAttrs = [name, jname]
d. If you are specifying the AdminObject attribute, also set up the following:
Using Jacl:
set cdattr [list adminObject $ao]
Using Jython:
cdattr = [’adminObject’, ao]
e. Create a J2C administrative object:
Using Jacl:
$AdminConfig create J2CAdminObject $newra $j2caoAttrs
Using Jython:
print AdminConfig.create(’J2CAdminObject’, newra, j2caoAttrs)
Example output:
J2CAO1(cells/mycell/nodes/mynode|resources.xml#J2CAdminObject_1)
3. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
4. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Testing data source connections using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to test a data source to ensure a connection to the database.
1. Identify the DataSourceCfgHelper MBean and assign it to the dshelper variable.
v Using Jacl:
set ds [$AdminConfig getid /DataSource:DS1/]
$AdminControl testConnection $ds
v Using Jython:
ds = AdminConfig.getid(’/DataSource:DS1/’)
AdminControl.testConnection(ds)
Example output:
WASX7217I: Connection to provided datasource was successful.
2. Test the connection. The following example invokes the testConnectionToDataSource operation on the
MBean, passing in the classname, userid, password, database name, JDBC driver class path,
language, and country.
v Using Jacl:
$AdminControl invoke $dshelper testConnectionToDataSource "COM.ibm.db2.jdbc.DB2XADataSource db2admin db2admin
{{databaseName sample}} c:/sqllib/java/db2java.zip en US"
v Using Jython:
print AdminControl.invoke(dshelper, ’testConnectionToDataSource’,
’COM.ibm.db2.jdbc.DB2XADataSource dbuser1 dbpwd1
"{{databaseName jtest1}}" c:/sqllib/java12/db \"\" \"\"’)

510 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Example output:
WASX7217I: Connection to provided data source was successful.

Configuring messaging with scripting

This topic contains the following tasks:
v “Configuring the message listener service using scripting”
v “Configuring new JMS providers using scripting” on page 512
v “Configuring new JMS destinations using scripting” on page 513
v “Configuring new JMS connections using scripting” on page 514
v “Configuring new WebSphere queue connection factories using scripting” on page 515
v “Configuring new WebSphere topic connection factories using scripting” on page 516
v “Configuring new WebSphere queues using scripting” on page 517
v “Configuring new WebSphere topics using scripting” on page 518
v “Configuring new MQ queue connection factories using scripting” on page 519
v “Configuring new MQ topic connection factories using scripting” on page 520
v “Configuring new MQ queues using scripting” on page 521
v “Configuring new MQ topics using scripting” on page 523

Configuring the message listener service using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure the message listener service for an application server:
1. Identify the application server and assign it to the server variable:
v Using Jacl:
set server [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
server = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print server
Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Identify the message listener service belonging to the server and assign it to the mls variable:
v Using Jacl:
set mls [$AdminConfig list MessageListenerService $server]
v Using Jython:
mls = AdminConfig.list(’MessageListenerService’, server)
print mls
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#MessageListenerService_1)
3. Modify various attributes with one of the following examples:
v This example command changes the thread pool attributes:
– Using Jacl:
$AdminConfig modify $mls {{threadPool {{inactivityTimeout 4000} {isGrowable true} {maximumSize 100}
{minimumSize 25}}}}
– Using Jython:
AdminConfig.modify(mls, [[’threadPool’, [[’inactivityTimeout’, 4000], [’isGrowable’, ’true’],
[’maximumSize’, 100], [’minimumSize’, 25]]]])

Chapter 4. Using the administrative clients 511

 v This example modifies the property of the first listener port:
– Using Jacl:
set lports [$AdminConfig showAttribute $mls listenerPorts]
set lport [lindex $lports 0]
$AdminConfig modify $lport {{maxRetries 2}}
– Using Jython:
lports = AdminConfig.showAttribute(mls, ’listenerPorts’)
cleanLports = lports[1:len(lports)-1]
lport = cleanLports.split(" ")[0]
AdminConfig.modify(lport, [[’maxRetries’, 2]])
v This example adds a listener port:
– Using Jacl:
set new [$AdminConfig create ListenerPort $mls {{name my} {destinationJNDIName di}
{connectionFactoryJNDIName jndi/fs}}]
$AdminConfig create StateManageable $new {{initialState START}}
– Using Jython:
new = AdminConfig.create(’ListenerPort’, mls, [[’name’, ’my’], [’destinationJNDIName’, ’di’],
[’connectionFactoryJNDIName’, ’jndi/fsi’]])
print new
print AdminConfig.create(’StateManageable’, new, [[’initialState’, ’START’]])
Example output:
my(cells/mycell/nodes/mynode/servers/server1:server.xml#ListenerPort_1079471940692)
(cells/mycell/nodes/mynode/servers/server1:server.xml#StateManageable_107947182623)
4. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
5. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new JMS providers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new JMS provider:

1. Identify the parent ID:
v Using Jacl:
set node [$AdminConfig getid /Cell:mycell/Node:mynode/]
v Using Jython:
node = AdminConfig.getid(’/Cell:mycell/Node:mynode/’)
print node
Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required JMSProvider
v Using Jython:
print AdminConfig.required(’JMSProvider’)
Example output:
Attribute Type
name String
externalInitialContextFactory String
externalProviderURL String
3. Set up required attributes:

512 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jacl:
set name [list name JMSP1]
set extICF [list externalInitialContextFactory "Put the external initial context factory here"]
set extPURL [list externalProviderURL "Put the external provider URL here"]
set jmspAttrs [list $name $extICF $extPURL]
v Using Jython:
name = [’name’, ’JMSP1’]
extICF = [’externalInitialContextFactory’, "Put the external initial context factory here"]
extPURL = [’externalProviderURL’, "Put the external provider URL here"]
jmspAttrs = [name, extICF, extPURL]
print jmspAttrs
Example output:
{name JMSP1} {externalInitialContextFactory {Put the external initial context factory here }}
{externalProviderURL {Put the external provider URL here}}
4. Create the JMS provider:
v Using Jacl:
set newjmsp [$AdminConfig create JMSProvider $node $jmspAttrs]
v Using Jython:
newjmsp = AdminConfig.create(’JMSProvider’, node, jmspAttrs)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new JMS destinations using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new JMS destination:

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:myNode/JMSProvider:JMSP1]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required GenericJMSDestination
v Using Jython:
print AdminConfig.required(’GenericJMSDestination’)
Example output:
Attribute Type
name String
jndiName String
externalJNDIName String
3. Set up required attributes:

Chapter 4. Using the administrative clients 513

 v Using Jacl:
set name [list name JMSD1]
set jndi [list jndiName jms/JMSDestination1]
set extJndi [list externalJNDIName jms/extJMSD1]
set jmsdAttrs [list $name $jndi $extJndi]
v Using Jython:
name = [’name’, ’JMSD1’]
jndi = [’jndiName’, ’jms/JMSDestination1’]
extJndi = [’externalJNDIName’, ’jms/extJMSD1’]
jmsdAttrs = [name, jndi, extJndi]
print jmsdAttrs
Example output:
{name JMSD1} {jndiName jms/JMSDestination1} {externalJNDIName jms/extJMSD1}
4. Create generic JMS destination:
v Using Jacl:
$AdminConfig create GenericJMSDestination $newjmsp $jmsdAttrs
v Using Jython:
print AdminConfig.create(’GenericJMSDestination’, newjmsp, jmsdAttrs)
Example output:
JMSD1(cells/mycell/nodes/mynode|resources.xml#GenericJMSDestination_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new JMS connections using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new JMS connection:

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:myNode/JMSProvider:JMSP1]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required GenericJMSConnectionFactory
v Using Jython:
print AdminConfig.required(’GenericJMSConnectionFactory’)
Example output:
Attribute Type
name String
jndiName String
externalJNDIName String
3. Set up required attributes:
v Using Jacl:

514 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set name [list name JMSCF1]
set jndi [list jndiName jms/JMSConnFact1]
set extJndi [list externalJNDIName jms/extJMSCF1]
set jmscfAttrs [list $name $jndi $extJndi]
Example output:
{name JMSCF1} {jndiName jms/JMSConnFact1} {externalJNDIName jms/extJMSCF1}
v Using Jython:
name = [’name’, ’JMSCF1’]
jndi = [’jndiName’, ’jms/JMSConnFact1’]
extJndi = [’externalJNDIName’, ’jms/extJMSCF1’]
jmscfAttrs = [name, jndi, extJndi]
print jmscfAttrs
Example output:
[[name, JMSCF1], [jndiName, jms/JMSConnFact1], [externalJNDIName, jms/extJMSCF1]]
4. Create generic JMS connection factory:
v Using Jacl:
$AdminConfig create GenericJMSConnectionFactory $newjmsp $jmscfAttrs
v Using Jython:
print AdminConfig.create(’GenericJMSConnectionFactory’, newjmsp, jmscfAttrs)
Example output:
JMSCF1(cells/mycell/nodes/mynode|resources.xml#GenericJMSConnectionFactory_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new WebSphere queue connection factories using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new WebSphere queue connection factory:
1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1/’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required WASQueueConnectionFactory
v Using Jython:
print AdminConfig.required(’WASQueueConnectionFactory’)
Example output:
Attribute Type
name String
jndiName String
3. Set up required attributes:
v Using Jacl:

Chapter 4. Using the administrative clients 515

 set name [list name WASQCF]
set jndi [list jndiName jms/WASQCF]
set mqcfAttrs [list $name $jndi]
Example output:
{name WASQCF} {jndiName jms/WASQCF}
v Using Jython:
name = [’name’, ’WASQCF’]
jndi = [’jndiName’, ’jms/WASQCF’]
mqcfAttrs = [name, jndi]
print mqcfAttrs
Example output:
[[name, WASQCF], [jndiName, jms/WASQCF]]
4. Create was queue connection factories:
v Using Jacl:
$AdminConfig create WASQueueConnectionFactory $newjmsp $mqcfAttrs
v Using Jython:
print AdminConfig.create(’WASQueueConnectionFactory’, newjmsp, mqcfAttrs)
Example output:
WASQCF(cells/mycell/nodes/mynode|resources.xml#WASQueueConnectionFactory_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new WebSphere topic connection factories using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new WebSphere topic connection factory:
1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1/’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required WASTopicConnectionFactory
v Using Jython:
print AdminConfig.required(’WASTopicConnectionFactory’)
Example output:
Attribute Type
name String
jndiName String
port ENUM(DIRECT, QUEUED)
3. Set up required attributes:
v Using Jacl:

516 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set name [list name WASTCF]
set jndi [list jndiName jms/WASTCF]
set port [list port QUEUED]
set mtcfAttrs [list $name $jndi $port]
Example output:
{name WASTCF} {jndiName jms/WASTCF} {port QUEUED}
v Using Jython:
name = [’name’, ’WASTCF’]
jndi = [’jndiName’, ’jms/WASTCF’]
port = [’port’, ’QUEUED’]
mtcfAttrs = [name, jndi, port]
print mtcfAttrs
Example output:
[[name, WASTCF], [jndiName, jms/WASTCF], [port, QUEUED]]
4. Create was topic connection factories:
v Using Jacl:
$AdminConfig create WASTopicConnectionFactory $newjmsp $mtcfAttrs
v Using Jython:
print AdminConfig.create(’WASTopicConnectionFactory’, newjmsp, mtcfAttrs)
Example output:
WASTCF(cells/mycell/nodes/mynode|resources.xml#WASTopicConnectionFactory_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new WebSphere queues using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new WebSphere queue:

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1/’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required WASQueue
v Using Jython:
print AdminConfig.required(’WASQueue’)
Example output:
Attribute Type
name String
jndiName String
3. Set up required attributes:
v Using Jacl:

Chapter 4. Using the administrative clients 517

 set name [list name WASQ1]
set jndi [list jndiName jms/WASQ1]
set wqAttrs [list $name $jndi]
Example output:
{name WASQ1} {jndiName jms/WASQ1}
v Using Jython:
name = [’name’, ’WASQ1’]
jndi = [’jndiName’, ’jms/WASQ1’]
wqAttrs = [name, jndi]
print wqAttrs
Example output:
[[name, WASQ1], [jndiName, jms/WASQ1]]
4. Create was queue:
v Using Jacl:
$AdminConfig create WASQueue $newjmsp $wqAttrs
v Using Jython:
print AdminConfig.create(’WASQueue’, newjmsp, wqAttrs)
Example output:
WASQ1(cells/mycell/nodes/mynode|resources.xml#WASQueue_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new WebSphere topics using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new WebSphere topic:

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1/’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required WASTopic
v Using Jython:
print AdminConfig.required(’WASTopic’)
Example output:
Attribute Type
name String
jndiName String
topic String
3. Set up required attributes:
v Using Jacl:

518 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 set name [list name WAST1]
set jndi [list jndiName jms/WAST1]
set topic [list topic "Put your topic here"]
set wtAttrs [list $name $jndi $topic]
Example output:
{name WAST1} {jndiName jms/WAST1} {topic {Put your topic here}}
v Using Jython:
name = [’name’, ’WAST1’]
jndi = [’jndiName’, ’jms/WAST1’]
topic = [’topic’, "Put your topic here"]
wtAttrs = [name, jndi, topic]
print wtAttrs
Example output:
[[name, WAST1], [jndiName, jms/WAST1], [topic, "Put your topic here"]]
4. Create was topic:
v Using Jacl:
$AdminConfig create WASTopic $newjmsp $wtAttrs
v Using Jython:
print AdminConfig.create(’WASTopic’, newjmsp, wtAttrs)
Example output:
WAST1(cells/mycell/nodes/mynode|resources.xml#WASTopic_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new MQ queue connection factories using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new MQ queue connection factory:

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required MQQueueConnectionFactory
v Using Jython:
print AdminConfig.required(’MQQueueConnectionFactory’)
Example output:
Attribute Type
name String
jndiName String
3. Set up required attributes:
v Using Jacl:

Chapter 4. Using the administrative clients 519

 set name [list name MQQCF]
set jndi [list jndiName jms/MQQCF]
set mqqcfAttrs [list $name $jndi]
Example output:
{name MQQCF} {jndiName jms/MQQCF}
v Using Jython:
name = [’name’, ’MQQCF’]
jndi = [’jndiName’, ’jms/MQQCF’]
mqqcfAttrs = [name, jndi]
print mqqcfAttrs
Example output:
[[name, MQQCF], [jndiName, jms/MQQCF]]
4. Set up a template:
v Using Jacl:
set template [lindex [$AdminConfig listTemplates MQQueueConnectionFactory] 0]
v Using Jython:
import java
lineseparator = java.lang.System.getProperty(’line.separator’)
template = AdminConfig.listTemplates(’MQQueueConnectionFactory’).split(lineseparator)[0]
print template
Example output:
Example non-XA WMQ QueueConnectionFactory(templates/
system:JMS-resource-provider-templates.xml
#MQQueueConnectionFactory_3)
5. Create MQ queue connection factory:
v Using Jacl:
$AdminConfig createUsingTemplate MQQueueConnectionFactory $newjmsp $mqqcfAttrs $template
v Using Jython:
print AdminConfig.createUsingTemplate(’MQQueueConnectionFactory’, newjmsp, mqqcfAttrs, template)
Example output:
MQQCF(cells/mycell/nodes/mynode:resources.xml#MQQueueConnectionFactory_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new MQ topic connection factories using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new MQ topic connection factory:

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode:resources.xml#JMSProvider_1)
2. Get required attributes:

520 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jacl:
$AdminConfig required MQTopicConnectionFactory
v Using Jython:
print AdminConfig.required(’MQTopicConnectionFactory’)
Example output:
Attribute Type
name String
jndiName String
3. Set up required attributes:
v Using Jacl:
set name [list name MQTCF]
set jndi [list jndiName jms/MQTCF]
set mqtcfAttrs [list $name $jndi]
Example output:
{name MQTCF} {jndiName jms/MQTCF}
v Using Jython:
name = [’name’, ’MQTCF’]
jndi = [’jndiName’, ’jms/MQTCF’]
mqtcfAttrs = [name, jndi]
print mqtcfAttrs
Example output:
[[name, MQTCF], [jndiName, jms/MQTCF]]
4. Set up a template:
v Using Jacl:
set template [lindex [$AdminConfig listTemplates MQTopicConnectionFactory] 0]
v Using Jython:
import java
lineseparator = java.lang.System.getProperty(’line.separator’)
template = AdminConfig.listTemplates(’MQTopicConnectionFactory’).split(lineseparator)[0]
print template
Example output:
Example non-XA WMQ TopicConnectionFactory(templates/system:
JMS-resource-provider-templates.xml
#MQTopicConnectionFactory_5)
5. Create mq topic connection factory:
v Using Jacl:
$AdminConfig create MQTopicConnectionFactory $newjmsp $mqtcfAttrs $template
v Using Jython:
print AdminConfig.create(’MQTopicConnectionFactory’, newjmsp, mqtcfAttrs, template)
Example output:
MQTCF(cells/mycell/nodes/mynode:resources.xml#MQTopicConnectionFactory_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new MQ queues using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new MQ queue:

Chapter 4. Using the administrative clients 521

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required MQQueue
v Using Jython:
print AdminConfig.required(’MQQueue’)
Example output:
Attribute Type
name String
jndiName String
baseQueueName String
3. Set up required attributes:
v Using Jacl:
set name [list name MQQ]
set jndi [list jndiName jms/MQQ]
set baseQN [list baseQueueName "Put the base queue name here"]
set mqqAttrs [list $name $jndi $baseQN]
Example output:
{name MQQ} {jndiName jms/MQQ} {baseQueueName {Put the base queue name here}}
v Using Jython:
name = [’name’, ’MQQ’]
jndi = [’jndiName’, ’jms/MQQ’]
baseQN = [’baseQueueName’, "Put the base queue name here"]
mqqAttrs = [name, jndi, baseQN]
print mqqAttrs
Example output:
[[name, MQQ], [jndiName, jms/MQQ], [baseQueueName, "Put the base queue name here"]]
4. Set up a template:
v Using Jacl:
set template [lindex [$AdminConfig listTemplates MQQueue] 0]
v Using Jython:
import java
lineseparator = java.lang.System.getProperty(’line.separator’)
template = AdminConfig.listTemplates(’MQQueue’).split(lineseparator)[0]
print template
Example output:
Example.JMS.WMQ.Q1(templates/system:JMS-resource-provider-
templates.xml#MQQueue_1)
5. Create MQ queue factory:
v Using Jacl:
$AdminConfig create MQQueue $newjmsp $mqqAttrs $template
v Using Jython:
print AdminConfig.create(’MQQueue’, newjmsp, mqqAttrs, template)
Example output:

522 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 MQQ(cells/mycell/nodes/mynode|resources.xml#MQQueue_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new MQ topics using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new MQ topic:

1. Identify the parent ID:
v Using Jacl:
set newjmsp [$AdminConfig getid /Cell:mycell/Node:mynode/JMSProvider:JMSP1/]
v Using Jython:
newjmsp = AdminConfig.getid(’/Cell:mycell/Node:myNode/JMSProvider:JMSP1’)
print newjmsp
Example output:
JMSP1(cells/mycell/nodes/mynode|resources.xml#JMSProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required MQTopic
v Using Jython:
print AdminConfig.required(’MQTopic’)
Example output:
Attribute Type
name String
jndiName String
baseTopicName String
3. Set up required attributes:
v Using Jacl:
set name [list name MQT]
set jndi [list jndiName jms/MQT]
set baseTN [list baseTopicName "Put the base topic name here"]
set mqtAttrs [list $name $jndi $baseTN]
Example output:
{name MQT} {jndiName jms/MQT} {baseTopicName {Put the base topic name here}}
v Using Jython:
name = [’name’, ’MQT’]
jndi = [’jndiName’, ’jms/MQT’]
baseTN = [’baseTopicName’, "Put the base topic name here"]
mqtAttrs = [name, jndi, baseTN]
print mqtAttrs
Example output:
[[name, MQT], [jndiName, jms/MQT], [baseTopicName, "Put the base topic name here"]]
4. Create MQ topic factory:
v Using Jacl:
$AdminConfig create MQTopic $newjmsp $mqtAttrs
v Using Jython:
print AdminConfig.create(’MQTopic’, newjmsp, mqtAttrs)

Chapter 4. Using the administrative clients 523

 Example output:
MQT(cells/mycell/nodes/mynode|resources.xml#MQTopic_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring mail, URLs, and resource environment entries with

scripting
This topic contains the following tasks:
v “Configuring new mail providers using scripting”
v “Configuring new mail sessions using scripting” on page 525
v “Configuring new protocols using scripting” on page 526
v “Configuring new custom properties using scripting” on page 527
v “Configuring new resource environment providers using scripting” on page 528
v “Configuring custom properties for resource environment providers using scripting” on page 529
v “Configuring new referenceables using scripting” on page 530
v “Configuring new resource environment entries using scripting” on page 531
v “Configuring custom properties for resource environment entries using scripting” on page 532
v “Configuring new URL providers using scripting” on page 533
v “Configuring custom properties for URL providers using scripting” on page 534
v “Configuring new URLs using scripting” on page 535
v “Configuring custom properties for URLs using scripting” on page 536

Configuring new mail providers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new mail provider:

1. Identify the parent ID:
v Using Jacl:
set node [$AdminConfig getid /Cell:mycell/Node:mynode/]
v Using Jython:
node = AdminConfig.getid(’/Cell:mycell/Node:mynode/’)
print node
Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required MailProvider
v Using Jython:
print AdminConfig.required(’MailProvider’)
Example output:
Attribute Type
name String
3. Set up required attributes:

524 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jacl:
set name [list name MP1]
set mpAttrs [list $name]
v Using Jython:
name = [’name’, ’MP1’]
mpAttrs = [name]
4. Create the mail provider:
v Using Jacl:
set newmp [$AdminConfig create MailProvider $node $mpAttrs]
v Using Jython:
newmp = AdminConfig.create(’MailProvider’, node, mpAttrs)
print newmp
Example output:
MP1(cells/mycell/nodes/mynode|resources.xml#MailProvider_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new mail sessions using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new mail session:

1. Identify the parent ID:
v Using Jacl:
set newmp [$AdminConfig getid /Cell:mycell/Node:mynode/MailProvider:MP1/]
v Using Jython:
newmp = AdminConfig.create(’MailProvider’, node, mpAttrs)
print newmp
Example output:
MP1(cells/mycell/nodes/mynode|resources.xml#MailProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required MailSession
v Using Jython:
print AdminConfig.required(’MailSession’)
Example output:
Attribute Type
name String
jndiName String
3. Set up required attributes:
v Using Jacl:
set name [list name MS1]
set jndi [list jndiName mail/MS1]
set msAttrs [list $name $jndi]
Example output:
{name MS1} {jndiName mail/MS1}
v Using Jython:

Chapter 4. Using the administrative clients 525

 name = [’name’, ’MS1’]
jndi = [’jndiName’, ’mail/MS1’]
msAttrs = [name, jndi]
print msAttrs
Example output:
[[name, MS1], [jndiName, mail/MS1]]
4. Create the mail session:
v Using Jacl:
$AdminConfig create MailSession $newmp $msAttrs
v Using Jython:
print AdminConfig.create(’MailSession’, newmp, msAttrs)
Example output:
MS1(cells/mycell/nodes/mynode|resources.xml#MailSession_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new protocols using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new protocol:

1. Identify the parent ID:
v Using Jacl:
set newmp [$AdminConfig getid /Cell:mycell/Node:mynode/MailProvider:MP1/]
v Using Jython:
newmp = AdminConfig.create(’MailProvider’, node, mpAttrs)
print newmp
Example output:
MP1(cells/mycell/nodes/mynode|resources.xml#MailProvider_1)
2. Get required attributes:
v Using Jacl:
$AdminConfig required ProtocolProvider
v Using Jython:
print AdminConfig.required(’ProtocolProvider’)
Example output:
Attribute Type
protocol String
classname String
3. Set up required attributes:
v Using Jacl:
set protocol [list protocol "Put the protocol here"]
set classname [list classname "Put the class name here"]
set ppAttrs [list $protocol $classname]
Example output:
{protocol protocol1} {classname classname1}
v Using Jython:

526 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 protocol = [’protocol’, "Put the protocol here"]
classname = [’classname’, "Put the class name here"]
ppAttrs = [protocol, classname]
print ppAttrs
Example output:
[[protocol, protocol1], [classname, classname1]]
4. Create the protocol provider:
v Using Jacl:
$AdminConfig create ProtocolProvider $newmp $ppAttrs
v Using Jython:
print AdminConfig.create(’ProtocolProvider’, newmp, ppAttrs)
Example output:
(cells/mycell/nodes/mynode|resources.xml#ProtocolProvider_4)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new custom properties using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new custom property:

1. Identify the parent ID:
v Using Jacl:
set newmp [$AdminConfig getid /Cell:mycell/Node:mynode/MailProvider:MP1/]
v Using Jython:
newmp = AdminConfig.create(’MailProvider’, node, mpAttrs)
print newmp
Example output:
MP1(cells/mycell/nodes/mynode|resources.xml#MailProvider_1)
2. Get the J2EE resource property set:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newmp propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newmp, ’propertySet’)
print propSet
Example output:
(cells/mycell/nodes/mynode|resources.xml#PropertySet_2)
3. Get required attributes:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
4. Set up the required attributes:
v Using Jacl:

Chapter 4. Using the administrative clients 527

 set name [list name CP1]
set cpAttrs [list $name]
Example output:
{name CP1}
v Using Jython:
name = [’name’, ’CP1’]
cpAttrs = [name]
print cpAttrs
Example output:
[[name, CP1]]
5. Create a J2EE resource property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $cpAttrs
v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, cpAttrs)
Example output:
CP1(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_2)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new resource environment providers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new resource environment provider:

1. Identify the parent ID and assign it to the node variable.
v Using Jacl:
set node [$AdminConfig getid /Cell:mycell/Node:mynode/]
v Using Jython:
node = AdminConfig.getid(’/Cell:mycell/Node:mynode/’)
print node
Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required ResourceEnvironmentProvider
v Using Jython:
print AdminConfig.required(’ResourceEnvironmentProvider’)
Example output:
Attribute Type
name String
3. Set up the required attributes and assign it to the repAttrs variable:
v Using Jacl:
set n1 [list name REP1]
set repAttrs [list $name]
v Using Jython:

528 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 n1 = [’name’, ’REP1’]
repAttrs = [n1]
4. Create a new resource environment provider:
v Using Jacl:
set newrep [$AdminConfig create ResourceEnvironmentProvider $node $repAttrs]
v Using Jython:
newrep = AdminConfig.create(’ResourceEnvironmentProvider’, node, repAttrs)
print newrep
Example output:
REP1(cells/mycell/nodes/mynode|resources.xml#ResourceEnvironmentProvider_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring custom properties for resource environment providers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new custom property for a resource environment provider:
1. Identify the parent ID and assign it to the newrep variable.
v Using Jacl:
set newrep [$AdminConfig getid /Cell:mycell/Node:mynode/ResourceEnvironmentProvider:REP1/]
v Using Jython:
newrep = AdminConfig.getid(’/Cell:mycell/Node:mynode/ResourceEnvironmentProvider:REP1/’)
print newrep
Example output:
REP1(cells/mycell/nodes/mynode|resources.xml#ResourceEnvironmentProvider_1)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
3. Set up the required attributes and assign it to the repAttrs variable:
v Using Jacl:
set name [list name RP]
set rpAttrs [list $name]
v Using Jython:
name = [’name’, ’RP’]
rpAttrs = [name]
4. Get the J2EE resource property set:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newrep propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newrep, ’propertySet’)
print propSet

Chapter 4. Using the administrative clients 529

 Example output:
(cells/mycell/nodes/mynode|resources.xml#PropertySet_1)
5. Create a J2EE resource property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $rpAttrs
v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, rpAttrs)
Example output:
RP(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new referenceables using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new referenceable:

1. Identify the parent ID and assign it to the newrep variable.
v Using Jacl:
set newrep [$AdminConfig getid /Cell:mycell/Node:mynode/ResourceEnvironmentProvider:REP1/]
v Using Jython:
newrep = AdminConfig.getid(’/Cell:mycell/Node:mynode/ResourceEnvironmentProvider:REP1/’)
print newrep
Example output:
REP1(cells/mycell/nodes/mynode|resources.xml#ResourceEnvironmentProvider_1)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required Referenceable
v Using Jython:
print AdminConfig.required(’Referenceable’)
Example output:
Attribute Type
factoryClassname String
classname String
3. Set up the required attributes:
v Using Jacl:
set fcn [list factoryClassname REP1]
set cn [list classname NM1]
set refAttrs [list $fcn $cn]
v Using Jython:
fcn = [’factoryClassname’, ’REP1’]
cn = [’classname’, ’NM1’]
refAttrs = [fcn, cn]
print refAttrs
Example output:
{factoryClassname {REP1}} {classname {NM1}}
4. Create a new referenceable:

530 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jacl:
set newref [$AdminConfig create Referenceable $newrep $refAttrs]
v Using Jython:
newref = AdminConfig.create(’Referenceable’, newrep, refAttrs)
print newref
Example output:
(cells/mycell/nodes/mynode|resources.xml#Referenceable_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new resource environment entries using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new resource environment entry:

1. Identify the parent ID and assign it to the newrep variable.
v Using Jacl:
set newrep [$AdminConfig getid /Cell:mycell/Node:mynode/ResourceEnvironmentProvider:REP1/]
v Using Jython:
newrep = AdminConfig.getid(’/Cell:mycell/Node:mynode/ResourceEnvironmentProvider:REP1/’)
print newrep
Example output:
REP1(cells/mycell/nodes/mynode|resources.xml#ResourceEnvironmentProvider_1)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required ResourceEnvEntry
v Using Jython:
print AdminConfig.required(’ResourceEnvEntry’)
Example output:
Attribute Type
name String
jndiName String
referenceable Referenceable@
3. Set up the required attributes:
v Using Jacl:
set name [list name REE1]
set jndiName [list jndiName myjndi]
set newref [$AdminConfig getid /Cell:mycell/Node:mynode/Referenceable:/]
set ref [list referenceable $newref]
set reeAttrs [list $name $jndiName $ref]
v Using Jython:
name = [’name’, ’REE1’]
jndiName = [’jndiName’, ’myjndi’]
newref = AdminConfig.getid(’/Cell:mycell/Node:mynode/Referenceable:/’)
ref = [’referenceable’, newref]
reeAttrs = [name, jndiName, ref]
4. Create the resource environment entry:
v Using Jacl:
$AdminConfig create ResourceEnvEntry $newrep $reeAttrs

Chapter 4. Using the administrative clients 531

 v Using Jython:
print AdminConfig.create(’ResourceEnvEntry’, newrep, reeAttrs)
Example output:
REE1(cells/mycell/nodes/mynode|resources.xml#ResourceEnvEntry_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring custom properties for resource environment entries using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new custom property for a resource environment entry:
1. Identify the parent ID and assign it to the newree variable.
v Using Jacl:
set newree [$AdminConfig getid /Cell:mycell/Node:mynode/ResourceEnvEntry:REE1/]
v Using Jython:
newree = AdminConfig.getid(’/Cell:mycell/Node:mynode/ResourceEnvEntry:REE1/’)
print newree
Example output:
REE1(cells/mycell/nodes/mynode|resources.xml#ResourceEnvEntry_1)
2. Create the J2EE custom property set:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newree propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newree, ’propertySet’)
print propSet
Example output:
(cells/mycell/nodes/mynode|resources.xml#J2EEResourcePropertySet_5)
3. Identify the required attributes:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
4. Set up the required attributes:
v Using Jacl:
set name [list name RP1]
set rpAttrs [list $name]
v Using Jython:
name = [’name’, ’RP1’]
rpAttrs = [name]
5. Create the J2EE custom property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $rpAttrs

532 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, rpAttrs)
Example output:
RPI(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new URL providers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new URL provider:

1. Identify the parent ID and assign it to the node variable.
v Using Jacl:
set node [$AdminConfig getid /Cell:mycell/Node:mynode/]
v Using Jython:
node = AdminConfig.getid(’/Cell:mycell/Node:mynode/’)
print node
Example output:
mynode(cells/mycell/nodes/mynode|node.xml#Node_1)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required URLProvider
v Using Jython:
print AdminConfig.required(’URLProvider’)
Example output:
Attribute Type
streamHandlerClassName String
protocol String
name String
3. Set up the required attributes:
v Using Jacl:
set name [list name URLP1]
set shcn [list streamHandlerClassName "Put the stream handler classname here"]
set protocol [list protocol "Put the protocol here"]
set urlpAttrs [list $name $shcn $protocol]
Example output:
{name URLP1} {streamHandlerClassName {Put the stream handler classname here}} {protocol {Put the protocol here}}
v Using Jython:
name = [’name’, ’URLP1’]
shcn = [’streamHandlerClassName’, "Put the stream handler classname here"]
protocol = [’protocol’, "Put the protocol here"]
urlpAttrs = [name, shcn, protocol]
print urlpAttrs
Example output:
[[name, URLP1], [streamHandlerClassName, "Put the stream handler classname here"],
[protocol, "Put the protocol here"]]
4. Create a URL provider:
v Using Jacl:

Chapter 4. Using the administrative clients 533

 $AdminConfig create URLProvider $node $urlpAttrs
v Using Jython:
print AdminConfig.create(’URLProvider’, node, urlpAttrs)
Example output:
URLP1(cells/mycell/nodes/mynode|resources.xml#URLProvider_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring custom properties for URL providers using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure custom properties for URL providers:
1. Identify the parent ID and assign it to the newurlp variable.
v Using Jacl:
set newurlp [$AdminConfig getid /Cell:mycell/Node:mynode/URLProvider:URLP1/]
v Using Jython:
newurlp = AdminConfig.getid(’/Cell:mycell/Node:mynode/URLProvider:URLP1/’)
print newurlp
Example output:
URLP1(cells/mycell/nodes/mynode|resources.xml#URLProvider_1)
2. Get the J2EE resource property set:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newurlp propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newurlp, ’propertySet’)
print propSet
Example output:
(cells/mycell/nodes/mynode|resources.xml#PropertySet_7)
3. Identify the required attributes:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
4. Set up the required attributes:
v Using Jacl:
set name [list name RP2]
set rpAttrs [list $name]
v Using Jython:
name = [’name’, ’RP2’]
rpAttrs = [name]
5. Create a J2EE resource property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $rpAttrs

534 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, rpAttrs)
Example output:
RP2(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_1)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring new URLs using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following example to configure a new URL:

1. Identify the parent ID and assign it to the newurlp variable.
v Using Jacl:
set newurlp [$AdminConfig getid /Cell:mycell/Node:mynode/URLProvider:URLP1/]
v Using Jython:
newurlp = AdminConfig.getid(’/Cell:mycell/Node:mynode/URLProvider:URLP1/’)
print newurlp
Example output:
URLP1(cells/mycell/nodes/mynode|resources.xml#URLProvider_1)
2. Identify the required attributes:
v Using Jacl:
$AdminConfig required URL
v Using Jython:
print AdminConfig.required(’URL’)
Example output:
Attribute Type
name String
spec String
3. Set up the required attributes:
v Using Jacl:
set name [list name URL1]
set spec [list spec "Put the spec here"]
set urlAttrs [list $name $spec]
Example output:
{name URL1} {spec {Put the spec here}}
v Using Jython:
name = [’name’, ’URL1’]
spec = [’spec’, "Put the spec here"]
urlAttrs = [name, spec]
Example output:
[[name, URL1], [spec, "Put the spec here"]]
4. Create a URL:
v Using Jacl:
$AdminConfig create URL $newurlp $urlAttrs
v Using Jython:
print AdminConfig.create(’URL’, newurlp, urlAttrs)

Chapter 4. Using the administrative clients 535

 Example output:
URL1(cells/mycell/nodes/mynode|resources.xml#URL_1)
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Configuring custom properties for URLs using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to configure a new custom property for a URL:
1. Identify the parent ID and assign it to the newurl variable.
v Using Jacl:
set newurl [$AdminConfig getid /Cell:mycell/Node:mynode/URLProvider:URLP1/URL:URL1/]
v Using Jython:
newurl = AdminConfig.getid(’/Cell:mycell/Node:mynode/URLProvider:URLP1/URL:URL1/’)
print newurl
Example output:
URL1(cells/mycell/nodes/mynode|resources.xml#URL_1)
2. Create a J2EE resource property set:
v Using Jacl:
set propSet [$AdminConfig showAttribute $newurl propertySet]
v Using Jython:
propSet = AdminConfig.showAttribute(newurl, ’propertySet’)
print propSet
Example output:
(cells/mycell/nodes/mynode|resources.xml#J2EEResourcePropertySet_7)
3. Identify the required attributes:
v Using Jacl:
$AdminConfig required J2EEResourceProperty
v Using Jython:
print AdminConfig.required(’J2EEResourceProperty’)
Example output:
Attribute Type
name String
4. Set up the required attributes:
v Using Jacl:
set name [list name RP3]
set rpAttrs [list $name]
v Using Jython:
name = [’name’, ’RP3’]
rpAttrs = [name]
5. Create a J2EE resource property:
v Using Jacl:
$AdminConfig create J2EEResourceProperty $propSet $rpAttrs
v Using Jython:
print AdminConfig.create(’J2EEResourceProperty’, propSet, rpAttrs)

536 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Example output:
RP3(cells/mycell/nodes/mynode|resources.xml#J2EEResourceProperty_7)
6. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
7. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

Troubleshooting with scripting

This topic contains the following tasks:
v “Tracing operations with the wsadmin tool”
v “Configuring traces using scripting” on page 538
v “Turning traces on and off in servers processes using scripting” on page 539
v “Dumping threads in server processes using scripting” on page 539
v “Setting up profile scripts to make tracing easier using scripting” on page 539

Tracing operations with the wsadmin tool

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to trace operations:

Enable wsadmin client tracing with the following command:

v Using Jacl:
$AdminControl trace com.ibm.*=all=enabled
v Using Jython:
AdminControl.trace(’com.ibm.*=all=enabled’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
trace is an AdminControl command
com.ibm.*=all=enabled indicates to turn on tracing

The following command disables tracing:

v Using Jacl:
$AdminControl trace com.ibm.*=all=disabled
v Using Jython:
AdminControl.trace(’com.ibm.*=all=disabled’)
where:

$ is a Jacl operator for substituting a variable name with its

value
AdminControl is an object that enables the manipulation of MBeans
running in a WebSphere server process
trace is an AdminControl command
com.ibm.*=all=disabled indicates to turn off tracing

Chapter 4. Using the administrative clients 537

The trace command changes the trace settings for the current session. You can change this setting
persistently by editting the wsadmin.properties file. The property com.ibm.ws.scripting.traceString is
read by the launcher during initialization. If it has a value, the value is used to set the trace.

A related property, com.ibm.ws.scripting.traceFile, designates a file to receive all trace and logging
information. The wsadmin.properties file contains a value for this property. Run the wsadmin tool with a
value set for this property. It is possible to run without this property set, where all logging and tracing goes
to the administrative console.

Configuring traces using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to set the trace for a configured server:
1. Identify the server and assign it to the server variable:
v Using Jacl:
set server [$AdminConfig getid /Cell:mycell/Node:mynode/Server:server1/]
v Using Jython:
server = AdminConfig.getid(’/Cell:mycell/Node:mynode/Server:server1/’)
print server
Example output:
server1(cells/mycell/nodes/mynode/servers/server1|server.xml#Server_1)
2. Identify the trace service belonging to the server and assign it to the tc variable:
v Using Jacl:
set tc [$AdminConfig list TraceService $server]
v Using Jython:
tc = AdminConfig.list(’TraceService’, server)
print tc
Example output:
(cells/mycell/nodes/mynode/servers/server1|server.xml#TraceService_1)
3. Set the trace string. The following example sets the trace string for a single component:
v Using Jacl:
$AdminConfig modify $tc {{startupTraceSpecification com.ibm.websphere.management.*=all=enabled}}
v Using Jython:
AdminConfig.modify(tc, [[’startupTraceSpecification’, ’com.ibm.websphere.management.*=all=enabled’]])
4. The following command sets the trace string for multiple components:
v Using Jacl:
$AdminConfig modify $tc {{startupTraceSpecification com.ibm.websphere.management.*=all=
enabled:com.ibm.ws.management.*=all=enabled:com.ibm.ws.runtime.*=all=enabled}}
v Using Jython:
AdminConfig.modify(tc, [[’startupTraceSpecification’, ’com.ibm.websphere.management.
*=all=enabled:com.ibm.ws.management.*=all=
enabled:com.ibm.ws.runtime.*=all=enabled’]])
5. Save the configuration changes. See the “Saving configuration changes with the wsadmin tool” on
page 411 article for more information.
6. In a network deployment environment only, synchronize the node. See the “Synchronizing nodes with
the wsadmin tool” on page 396 article for more information.

538 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Turning traces on and off in servers processes using scripting
Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Perform the following steps to turning traces on and off in server processes:
1. Identify the object name for the TraceService MBean running in the process:
v Using Jacl:
$AdminControl completeObjectName type=TraceService,node=mynode,process=server1,*
v Using Jython:
AdminControl.completeObjectName(’type=TraceService,node=mynode,process=server1,*’)
2. Obtain the name of the object and set it to a variable:
v Using Jacl:
set ts [$AdminControl completeObjectName type=TraceService,process=server1,*]
v Using Jython:
ts = AdminControl.completeObjectName(’type=TraceService,process=server1,*’)
3. Turn tracing on or off for the server. For example:
v To turn tracing on, perform the following step:
– Using Jacl:
$AdminControl setAttribute $ts traceSpecification com.ibm.*=all=enabled
– Using Jython:
AdminControl.setAttribute(ts, ’traceSpecification’, ’com.ibm.*=all=enabled’)
v To turn tracing off, perform the following step:
– Using Jacl:
$AdminControl setAttribute $ts traceSpecification com.ibm.*=all=disabled
– Using Jython:
AdminControl.setAttribute(ts, ’traceSpecification’, ’com.ibm.*=all=disabled’)

Dumping threads in server processes using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Use the AdminControl object to dump the Java threads of a running server. The following example
produces a Java core file. You can use this file for problem determination.
v Using Jacl:
set jvm [$AdminControl completeObjectName type=JVM,process=server1,*]
$AdminControl invoke $jvm dumpThreads
v Using Jython:
jvm = AdminControl.completeObjectName(’type=JVM,process=server1,*’)
AdminControl.invoke(jvm, ’dumpThreads’)

Setting up profile scripts to make tracing easier using scripting

Before starting this task, the wsadmin tool must be running. See the “Starting the wsadmin scripting client”
on page 429 article for more information.

Set up a profile script to make tracing easier. The following profile script example turns tracing on and off
for server1:
v Using Jacl:

Chapter 4. Using the administrative clients 539

 proc ton {} {
global AdminControl
set ts [$AdminControl queryNames type=TraceService,node=mynode,process=server1,*]
$AdminControl setAttribute $ts traceSpecification com.ibm.=all=enabled
}

proc toff {} {
global AdminControl
set ts [$AdminControl queryNames type=TraceService,node=mynode,process=server1,*]
$AdminControl setAttribute $ts traceSpecification com.ibm.*=all=disabled
}

proc dt {} {
global AdminControl
set jvm [$AdminControl queryNames type=JVM,node=mynode,process=server1,*]
$AdminControl invoke $jvm dumpThreads
}
v Using Jython:
def ton():
global lineSeparator
ts = AdminControl.queryNames(’type=TraceService,node=mynode,process=server1,*’)

AdminControl.setAttribute(ts, ’traceSpecification’, ’com.ibm.=all=enabled’)

def toff():
global lineSeparator
ts = AdminControl.queryNames(’type=TraceService,node=mynode,process=server1,*’)

AdminControl.setAttribute(ts, ’traceSpecification’, ’com.ibm.*=all=disabled’)

def dt():
global lineSeparator
jvm = AdminControl.queryNames(’type=JVM,node=mynode,process=server1,*’)
AdminControl.invoke(jvm, ’dumpThreads’)

If you start the wsadmin tool with this profile script, you can use the ton command to turn on tracing in the
server, the toff command to turn off tracing, and the dt command to dump the Java threads. For more
information about running scripting commands in a profile script, see the “Starting the wsadmin scripting
client” on page 429 article.

Scripting reference material

This topic contains the following tasks:
v “Wsadmin tool”
v “Commands for the AdminConfig object” on page 557
v “Commands for the AdminControl object” on page 579
v “Commands for the AdminApp object” on page 598
v “Commands for the AdminTask object” on page 672
v “Administrative command invocation syntax” on page 806
v “Commands for the Help object” on page 544
v “Properties used by scripted administration” on page 807

Wsadmin tool
The WebSphere Application Server wsadmin tool runs scripts. You can use the wsadmin tool to manage
WebSphere Application Server as well as the configuration, application deployment, and server run-time
operations.

The command-line invocation syntax for the wsadmin scripting client is as follows:

540 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
wsadmin [-h(help)]

[-?]

[-c <commands>]

[-p <properties_file_name>]

[-profile <profile_script_name>]

[-profileName <profile_name>]

[-f <script_file_name>]

[-javaoption java_option]

[-lang language]

[-wsadmin_classpath classpath]

[-conntype SOAP [-host host_name] [-port port_number] [-user userid] [-password password] |

RMI [-host host_name] [-port port_number] [-user userid] [-password password] |

NONE
]

[script parameters]

Where script parameters represent any arguments other than the ones listed previously. The argc variable
contains the argument number, and the argv variable contains the contents.

Options
-c Designates to run a single command.
Multiple -c options can exist on the command line. They run in the order that you designate. You must
save after using this command.
-f Designates a script to run.
Only one -f option can exist on the command line.
-javaoption
Specifies a valid Java standard or a non-standard option.
Multiple -javaoption options can exist on the command line.
-lang
Specifies the language of the script file, the command, or an interactive shell. The possible languages
include: Jacl and Jython. The options for the -lang argument include: jacl and jython.
This option overrides language determinations that are based on a script file name, or the
com.ibm.ws.scripting.defaultLang property. The -lang argument has no default value. If the command
line or the property does not supply the script language, and the wsadmin tool cannot determine it, an
error message generates. This argument is required if not determined from the script file name.
-p
Specifies a properties file.
The file listed after -p, represents a Java properties file that the scripting process reads. Three levels
of default properties files load before the properties file that you specify on the command line. The first
level is the installation default, wsadmin.properties, which is located in the WebSphere Application
Server properties directory. The second level is the user default, wsadmin.properties, which is
located in your home directory. The third level is the properties file that the environment variable
WSADMIN_PROPERTIES points to.
Chapter 4. Using the administrative clients 541
 Multiple -p options can exist on the command line. They invoke in the order that you supply them.
-profile
Specifies a profile script.
The profile script runs before other commands, or scripts. If you specify -c, the profile script runs
before it invokes this command. If you specify -f, the profile script runs before it runs the script. In
interactive mode, you can use the profile script to perform any standard initialization that you want.
You can specify multiple -profile options on the command line, and they invoke in the order that you
supply them.
-profileName
Specifies the profile from which the wsadmin tool will run. Specify this option if one the following
reasons apply:
v You run the wsadmin tool from the WAS_HOME/bin directory and you do not have a default profile or
you want to run in a profile other than the default profile.
v You are currently in a profile bin directory but want to run the wsadmin tool from a different profile.
-?
Provides syntax help.
-help
Provides syntax help.
-conntype
Specifies the type of connection to use.
This argument consists of a string that determines the type, for example, SOAP, and the options that
are specific to that connection type. Possible types include: SOAP, RMI, and NONE.
Use the -conntype NONE option to run in local mode. The result is that the scripting client is not
connected to a running server. You can manage server configuration, the installation and the
uninstallation of applications without the application server running.
-wsadmin_classpath
Use this option to make additional classes available to your scripting process.
Follow this option with a class path string. For example:
c:/MyDir/Myjar.jar;d:/yourdir/yourdir.jar

The class path is then added to the class loader for the scripting process.

You can also specify this option in a properties file that is used by the wsadmin tool. The property is
com.ibm.ws.scripting.classpath. If you specify -wsadmin_classpath on the command line, the value of
this property overrides any value that is specified in a properties file. The class path property and the
command-line options are not concatenated.
-host
Specify a hostname to which wsadmin should attempt to connect. The default wsadmin.properties file
located in the properties directory of each WebSphere profile provides localhost as the value of the
host property if this option is not specified.
-password
Specify a password to be used by the connector to connect to the server if security is enabled in the
server.
Warning: On UNIX system, the use of -password option may result in security exposure as the
password information becomes visible to the system status program such as ps command which can
be invoked by other user to display all the running processes. Do not use this option if security
exposure is a concern. Instead, specify user and password information in the soap.client.props file for
SOAP connector or sas.client.props file for RMI connector. The soap.client.props and sas.client.props
files are located in the properties directory of your WebSphere profile.

542 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-username
Specify a user name to be used by the connector to connect to the server if security is enabled in the
server.
-port
Specify a port to be used by the connector. The default wsadmin.properties file located in the
properties directory of each WebSphere Application Server profile provides a value in the port property
to connect to the local server.

In the following syntax examples, mymachine is the name of the host in the wsadmin.properties file that is
specified by the com.ibm.ws.scripting.port property:
SOAP connection to the local host
Use the options that are defined in the wsadmin.properties file.
SOAP connection to the mymachine host
Using Jacl:
wsadmin -f test1.jacl -profile setup.jacl -conntype SOAP -port mymachinesoapportnumber -host mymachine

Using Jython:
wsadmin -lang jython -f test1.py -profile setup.py -conntype SOAP -port mymachinesoapportnumber -host mymachine
Initial and maximum Java heap size
Using Jacl:
wsadmin -javaoption -Xms128m -javaoption -Xmx256m -f test.jacl

Using Jython:
wsadmin -lang jython -javaoption -Xms128m -javaoption -Xmx256m -f test.py
RMI connection with security
Using Jacl:
wsadmin -conntype RMI -port rmiportnumber -userid userid -password password

Using Jython:
wsadmin -lang jython -conntype RMI -port rmiportnumber -userid userid -password password

Warning: On UNIX system, the use of -password option may result in security exposure as the
password information becomes visible to the system status program such as ps command which
can be invoked by other user to display all the running processes. Do not use this option if
security exposure is a concern. Instead, specify user and password information in the
soap.client.props file for SOAP connector or sas.client.props file for RMI connector. The
soap.client.props and sas.client.props files are located in the properties directory of your
WebSphere profile.
Local mode of operation to perform a single command
Using Jacl:
wsadmin -conntype NONE -c "$AdminApp uninstall app"

or

Using Jython:
wsadmin -lang jython -conntype NONE -c "AdminApp.uninstall(’app’)"

or

wsadmin tool performance tips: The following performance tips are for the wsadmin tool:
v If the deployment manager is running at a higher service maintenance level than that of the node agent,
you must run the wsadmin.sh or the wsadmin.bat from the bin directory of the deployment manager.
v When you launch a script using the wsadmin.bat or the wsadmin.sh files, a new process is created with
a new Java virtual machine (JVM) API. If you use scripting with multiple wsadmin -c commands from a

Chapter 4. Using the administrative clients 543

 batch file or a shell script, these commands run slower than if you use a single wsadmin -f command.
The -f option runs faster because only one process and JVM API are created for installation and the
Java classes for the installation load only once.
The following example, illustrates running multiple application installation commands from a batch file:
Using Jacl:
wsadmin -c "$AdminApp install c:\\myApps\\App1.ear {-appname appl1}"
wsadmin -c "$AdminApp install c:\\myApps\\App2.ear {-appname appl2}"
wsadmin -c "$AdminApp install c:\\myApps\\App3.ear {-appname appl3}"
or
Using Jython:
wsadmin -lang jython -c "AdminApp.install(’c:\myApps\App1.ear’, ’[-appname appl1]’)"
wsadmin -lang jython -c "AdminApp.install(’c:\myApps\App2.ear’, ’[-appname appl2]’)"
wsadmin -lang jython -c "AdminApp.install(’c:\myApps\App3.ear’, ’[-appname appl3]’)"
or
Or, for example, using Jacl, you can create the appinst.jacl file that contains the commands:
$AdminApp install c:\\myApps\\App1.ear {-appname appl1}
$AdminApp install c:\\myApps\\App2.ear {-appname appl2}
$AdminApp install c:\\myApps\\App3.ear {-appname appl3}
Invoke this file using the following command: wsadmin -f appinst.jacl
Or using Jython, you can create the appinst.py file, that contains the commands:
AdminApp.install(’c:\myApps\App1.ear’, ’[-appname appl1]’)
AdminApp.install(’c:\myApps\App2.ear’, ’[-appname appl2]’)
AdminApp.install(’c:\myApps\App3.ear’, ’[-appname appl3]’)
Then invoke this file using the following command: wsadmin -lang jython -f appinst.py.
v Use the AdminControl queryNames and completeObjectName commands carefully with a large
installation. For example, if only a few beans exist on a single machine, the $AdminControl queryNames
* command performs well. If a scripting client connects to the deployment manager in a multiple
machine environment, use a command only if it is necessary for the script to obtain a list of all the
MBeans in the system. If you need the MBeans on a node, it is easier to invoke ″$AdminControl
queryNames node=mynode,*″. The JMX system management infrastructure forwards requests to the
system to fulfill the first query, *. The second query, node=mynode,* is targeted to a specific machine.
v The WebSphere Application Server is a distributed system, and scripts perform better if you minimize
remote requests. If some action or interrogation is required on several items, for example, servers, it is
more efficient to obtain the list of items once and iterate locally. This procedure applies to the actions
that the AdminControl object performs on running MBeans, and actions that the AdminConfig object
performs on configuration objects.

Commands for the Help object

The Help object provides general help and dynamic online information about the currently running
MBeans. You can use the Help object as an aid in writing and running scripts with the AdminControl
object.

The following commands are available for the Help object:

Command Description: Parameters and return Examples:

name: values:

544 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
AdminApp Provides a v Parameters: none Example usage:
summary of all
v Returns: string Using Jacl:
of the available
methods for the $Help AdminApp
AdminApp
object. Using Jython:
print Help.AdminApp()

Example output:
WASX7095I: The AdminApp object
allows application objects to
be manipulated -- this includes
installing, uninstalling, editing,
and listing. Most of the commands
supported by AdminApp operate in two
modes: the default mode is one
in which AdminApp communicates with the
WebSphere Application Server to accomplish
its tasks. A local mode is also
possible, in which no server
communication takes place. The local
mode of operation is invoked
by bringing up the scripting client with
no server connected using the command line
"-conntype NONE" option or setting the
"com.ibm.ws.scripting.connectionType=NONE"
property in the wsadmin.properties.

The following commands are supported

by AdminApp; more detailed information
about each of these commands
is available by using the
"help" command of AdminApp and
supplying the name of the command
as an argument.

deleteUserAndGroupEntries
Deletes all the user/group
information for all the roles and all
the username/password information for RunAs
roles for a given application.

edit Edit the properties of an application

editInteractive Edit the properties

of an application interactively

export Export application to a file

exportDDL Export DDL from

application to a directory

help Show help information

install Installs an application,

given a file name and an option string.

installInteractive Installs an application

in interactive mode, given a file name
and an option string.

list List all installed applications

Chapter 4. Using the administrative clients 545

AdminApp listModules List the modules
continued in a specified application

options Shows the options available, either

for a given file, or in general.

publishWSDL Publish WSDL

files for a given application

taskInfo Shows detailed information pertaining

to a given installation task for a given file

uninstall Uninstalls an application,

given an application name and an option string

updateAccessIDs Updates the user/group

binding information with accessID from user
registry for a given application

view View an application or module,

given an application or module name

546 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
AdminConfig Provides a v Parameters: None Example usage:
summary of all
v Returns: string Using Jacl:
the available
methods for the $Help AdminConfig
AdminConfig
object. Using Jython:
print Help.AdminConfig()

Example output:
WASX7053I: The following functions are supported
by AdminConfig:

create Creates a configuration object, given a

type, a parent, and a list of attributes

create Creates a configuration object, given a

type, a parent, a list of attributes, and an
attribute name for the new object

remove Removes the specified configuration object

list Lists all configuration objects of a given
type

list Lists all configuration objects of a given

type, contained within the scope supplied

show Show all the attributes of a given

configuration object

show Show specified attributes of a given

configuration object

modify Change specified attributes of a given

configuration object

getId Show the configId of an object, given a

string version of its containment

contents Show the objects which a given type

contains

parents Show the objects which contain a given

type

attributes Show the attributes for a given type

types Show the possible types for configuration

help Show help information

Chapter 4. Using the administrative clients 547

AdminControl Provides a v Parameters: None Example usage:
summary of the
v Returns: string Using Jacl:
help commands
and ways to $Help AdminControl
invoke an
administrative Using Jython:
command. print Help.AdminControl()

Example output:
WASX7027I: The following functions are supported
by AdminControl:

getHost returns String representation of

connected host

getPort returns String representation of

port in use

getType returns String representation of

connection type in use

reconnect reconnects with server

queryNames Given ObjectName and QueryExp,

retrieves set of ObjectNames that match.

queryNames Given String version of ObjectName,

retrieves String of ObjectNames that match.

getMBeanCount returns number of

registered beans

getDomainName returns "WebSphere"

getDefaultDomain returns "WebSphere"

getMBeanInfo Given ObjectName, returns

MBeanInfo structure for MBean

isInstanceOf Given ObjectName and class

name, true if MBean is of that class

isRegistered true if supplied ObjectName

is registered

isRegistered true if supplied String

version of ObjectName is registered

getAttribute Given ObjectName and name

of attribute, returns value of attribute

getAttribute Given String version of

ObjectName and name of attribute, returns
value of attribute

getAttributes Given ObjectName and array

of attribute names, returns AttributeList

getAttributes Given String version of

ObjectName and attribute names, returns
String of name value pairs

548 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
setAttribute Given ObjectName and Attribute
object, set attribute for MBean specified

setAttribute Given String version of

ObjectName, attribute name and attribute
value, set attribute for MBean specified

setAttributes Given ObjectName and

AttributeList object, set attributes
for the MBean specified

invoke Given ObjectName, name of method,

array of parameters and signature, invoke
method on MBean specified

invoke Given String version of ObjectName,

name of method, String version of
parameter list, invoke method on MBean
specified.

invoke Given String version of ObjectName,

name of method, String version of parameter
list, and String version of array of
signatures, invoke method on MBean specified.

makeObjectName Return an ObjectName

built with the given string

completeObjectName Return a String

version of an object name given a template
name

trace Set the wsadmin trace specification

help Show help information

Chapter 4. Using the administrative clients 549

AdminTask Provides a v Parameters: None Example usage:
summary of
v Returns: string Using Jacl:
help commands
and ways to $AdminTask help
invoke an
administrative Using Jython:
command. print AdminTask.help()

Example output:
WASX8001I: The AdminTask object enables the
available administrative commands.
AdminTask commands operate in two modes:
the default mode is one which AdminTask
communicates with the WebSphere Application
Server to accomplish its task. A local mode
is also available in which no server
communication takes place. The local mode of
operation is invoked by bringing up the
scripting client busing the command line
"-conntype NONE" option or setting the
"com.ibm.ws.scripting.connectiontype=NONE"
property in wsadmin.properties file.

The number of administrative commands varies

and depends on your WebSphere Application
Server installation. Use the following help
commands to obtain a list of supported
commands and their parameters:

help -commands list all the

administrative commands
help -commandGroups list all the
administrative command groups
help commandName display detailed
information for the specified command
help commandName stepName display detailed
information for the specified step
belonging to the specified command
help commandGroupName display detailed
information for the specified command group

There are various flavors to invoke an

administrative command. They are

commandName invokes an administrative

command that does not require any argument.

commandName targetObject invokes an admin

command with the target object string,
for example the configuration object name
of a resource adapter. The expected target
object varies with the administrative
command invoked. Use help command to get
information on the target object of an
administrative command.

commandName options invokes an administrative

command with the specified option strings.
This invocation syntax is used to invoke
an administrative command that does not
require a target object. It is also used
to enter interactive mode if "-interactive"
mode is included in the options string.

550 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
AdminTask commandName targetObject options invokes an
continued administrative command with the specified
target object and options strings. If
"-interactive" is included in the options
string, then interactive mode is entered.
The target object and options strings vary
depending on the admin command invoked. Use
help command to get information on the
target object and options.

Chapter 4. Using the administrative clients 551

all Provides a v Parameters: name - Example usage:
summary of the string
information that Using Jacl:
v Returns: string
the MBean $Help all [$AdminControl queryNames type
defines by =TraceService,process=server1,node=pongo,*]
name.
Using Jython:
print Help.all(AdminControl.queryNames
(’type=TraceService,process=server1,
node=pongo,*’))

Example output:
Name: WebSphere:cell=pongo,name=
TraceService,mbeanIdentifier=cells/
pongo/nodes/pongo/servers/server1/
server.xml#TraceService_1,
type=TraceService,node=pongo,process=server1
Description: null
Class name:
javax.management.modelmbean.RequiredModelMBean

Attribute Type Access

ringBufferSize int RW
traceSpecification java.lang.String RW

Operation
int getRingBufferSize()
void setRingBufferSize(int)
java.lang.String getTraceSpecification()
void setTraceState(java.lang.String)
void appendTraceString(java.lang.String)
void dumpRingBuffer(java.lang.String)
void clearRingBuffer()
[Ljava.lang.String;
listAllRegisteredComponents()
[Ljava.lang.String;
listAllRegisteredGroups()
[Ljava.lang.String;
listComponentsInGroup(java.lang.String)
[Lcom.ibm.websphere.ras.TraceElementState;
getTracedComponents()
[Lcom.ibm.websphere.ras.TraceElementState;
getTracedGroups()
java.lang.String getTraceSpecification
(java.lang.String)
void processDumpString(java.lang.String)
void checkTraceString(java.lang.String)
void setTraceOutputToFile(java.lang.String,
int, int, java.lang.String)
void setTraceOutputToRingBuffer(int,
java.lang.String)
java.lang.String rolloverLogFileImmediate
(java.lang.String, java.lang.String)

Notifications
jmx.attribute.changed

Constructors

552 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
attributes Provides a v Parameters: name - Example usage:
summary of all string
the attributes Using Jacl:
v Returns: string
that the MBean $Help attributes [$AdminControl queryNames
defines by type=TraceService,process=server1,node=
name. pongo,*]

Using Jython:
print Help.attributes
(AdminControl.queryNames(’type=TraceService,
process=server1,node=pongo,*’))

Example output:
Attribute Type Access

ringBufferSize java.lang.Integer RW

traceSpecification string RW
classname Provides a v Parameters: name - Example usage:
class name that string
the MBean Using Jacl:
v Returns: string
defines by $Help classname [$AdminControl queryNames
name. type=TraceService,process=server1,node=pongo,*]

Using Jython:
print Help.classname(AdminControl.queryNames
(’type=TraceService,process=server1,node=pongo,*’))

Example output:
javax.management.modelmbean.RequiredModelMBean
constructors Provides a v Parameters: name - Example usage:
summary of all string
of the Using Jacl:
v Returns: string
constructors $Help constructors [$AdminControl queryNames
that the MBean type=TraceService,process=server1,node=pongo,*]
defines by
name. Using Jython:
print Help.constructors
(AdminControl.queryNames(’type=TraceService,
process=server1,node=pongo,*’))

Example output:
Constructors
description Provides a v Parameters: name - Example usage:
description that string
the MBean Using Jacl:
v Returns: string
defines by $Help description [$AdminControl queryNames
name. type=TraceService,process=server1,node=pongo,*]

Using Jython:
print Help.description(AdminControl.queryNames
(’type=TraceService,process=server1,node=pongo,*’))

Example output:
Managed object for overall server process.

Chapter 4. Using the administrative clients 553

help Provides a v Parameters: None Example output:
summary of all WASX7028I: The Help object has two purposes:
v Returns: string
the available
methods for the First, provide general help information for
Help object. the bjects supplied by the wsadmin tool for
scripting: Help, AdminApp, AdminConfig,
and AdminControl.

Second, provide a means to obtain interface

information about the MBeans that run in the
system. For this purpose, a variety of
commands are available to get information
about the operations,attributes, and other
interface information about particular
MBeans.

The following commands are supported by

Help; more detailed
information about each of these commands
is available by using the
"help" command of Help and by supplying
the name of the command
as an argument.

attributes given an MBean,

returns help for attributes
operations given an MBean,
returns help for operations
constructors given an MBean,
returns help for constructors
description given an MBean,
returns help for description
notifications given an MBean,
returns help for notifications
classname given an MBean, returns
help for class name
all given an MBean, returns
help for all the previous
help returns this help text
AdminControl returns general help
text for the AdminControl object
AdminConfig returns general help
text for the AdminConfig object
AdminApp returns general help
text for the AdminApp object
AdminTask returns general help
text for the AdminTask object
wsadmin returns general help
text for the wsadmin script launcher
message given a message ID,
returns an explanation and a user action

554 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
message Displays v Parameters: message Example usage:
information for ID
a message ID. Using Jacl:
v Returns: string
$Help message CNTR0005W

Using Jython:
print Help.message(’CNTR0005W’)

Example output:
Explanation: The container was unable to
passivate an enterprise bean due to
exception {2}User action: Take action based
upon message in exception {2}
notifications Provides a v Parameters: name - Example usage:
summary of all string
the notifications Using Jacl:
v Returns: string
that the MBean $Help notifications [$AdminControl
defines by queryNames type=TraceService,process=server1,
name. node=pongo,*]

Using Jython:
print Help.notifications
(AdminControl.queryNames(’type=TraceService,
process=server1,node=pongo,*’))

Example output:
Notification

websphere.messageEvent.audit

websphere.messageEvent.fatal

websphere.messageEvent.error

websphere.seriousEvent.info

websphere.messageEvent.warning

jmx.attribute.changed

Chapter 4. Using the administrative clients 555

operations Provides a v Parameters: name - Example usage:
summary of all string
the operations Using Jacl:
v Returns: string
that the MBean $Help operations [$AdminControl queryNames
defines by type=TraceService,process=server1,node=pongo,*]
name.
Using Jython:
print Help.operations(AdminControl.queryNames
(’type=TraceService,process=server1,node=pongo,*’))

Example output:
Operation
int getRingBufferSize()
void setRingBufferSize(int)
java.lang.String getTraceSpecification()
void setTraceState(java.lang.String)
void appendTraceString(java.lang.String)
void dumpRingBuffer(java.lang.String)
void clearRingBuffer()
[Ljava.lang.String;
listAllRegisteredComponents()
[Ljava.lang.String;
listAllRegisteredGroups()
[Ljava.lang.String;
listComponentsInGroup(java.lang.String)
[Lcom.ibm.websphere.ras.TraceElementState;
getTracedComponents()
[Lcom.ibm.websphere.ras.TraceElementState;
getTracedGroups()
java.lang.String
getTraceSpecification(java.lang.String)
void processDumpString(java.lang.String)
void checkTraceString(java.lang.String)
void setTraceOutputToFile(java.lang.String,
int, int, java.lang.String)
void setTraceOutputToRingBuffer
(int, java.lang.String)
java.lang.String rolloverLogFileImmediate
(java.lang.String, java.lang.String)
operations Provides the v Parameters: name - Example usage:
signature of the string, opname -
opname Using Jacl:
string
operation for $Help operations [$AdminControl queryNames
v Returns: string
the MBean that type=TraceService,process=server1,node=pongo,*]
is defined by processDumpString
name.
Using Jython:
print Help.operations(AdminControl.queryNames
(’type=TraceService,process=server1,node=pongo,*’),
’processDumpString’)

Example output:
void processDumpString(string)

Description: Write the contents of the Ras

services ring buffer to the specified file.

Parameters:

Type string
Name dumpString
Description A String in the specified format
to process or null.

556 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Commands for the AdminConfig object
Use the AdminConfig object to invoke configuration commands and to create or change elements of the
WebSphere Application Server configuration, for example, creating a data source.

You can start the scripting client without a running server, if you only want to use local operations. To run
in local mode, use the -conntype NONE option to start the scripting client. You receive a message that you
are running in the local mode. If a server is currently running, running the AdminConfig tool in local mode
is not recommended. This is because any configuration changes made in local mode will not be reflected
in the running server configuration and vice versa. If you save a conflicting configuration, you could corrupt
the configuration. In a deployment manager environment, configuration updates are available only if a
scripting client is connected to a deployment manager. When connected to a node agent or a managed
application server, you will not be able to update the configuration because the configuration for these
server processes are copies of the master configuration which resides in the deployment manager. The
copies are created on a node machine when a configuration synchronization occurs between the
deployment manager and the node agent. Make configuration changes to the server processes by
connecting a scripting client to a deployment manager. For this reason, to change a configuration, do not
run a scripting client in local mode on a node machine. It is not a supported configuration.

The following commands are available for the AdminConfig object:

Command Description: Parameters and Examples:

name: return values:
attributes Returns a list v Parameters: Example usage:
of the top object type
level Using Jacl:
The name of the
attributes for $AdminConfig attributes ApplicationServer
object type that
a given type.
you input here is Using Jython:
the one based
on the XML print AdminConfig.attributes
(’ApplicationServer’)
configuration
files and does Example output:
not have to be
the same name "properties Property*" "serverSecurity
ServerSecurity"
that the
"server Server@" "id Long" "stateManagement
administrative StateManageable"
console "name String" "moduleVisibility EEnumLiteral
displays. (MODULE,
v Returns: A list of COMPATIBILITY, SERVER, APPLICATION)"
attributes. "services Service*"
"statisticsProvider StatisticsProvider"

Chapter 4. Using the administrative clients 557

checkin Checks a file v Parameters: Example usage:
that the document URI,
document Using Jacl:
filename,
URI opaque object $AdminConfig checkin
describes cells/MyCell/Node/MyNode/serverindex.xml
v Returns: None c:\\mydir\myfile $obj
into the
configuration
repository. Using Jython:
AdminConfig.checkin
This method (’cells/MyCell/Node/
only applies MyNode/serverindex.xml’,
to ’c:\mydir\myfile’, obj)
deployment
manager The document URI is relative to the root of the configuration
configurations. repository, for example, c:\WebSphere\AppServer\config.

The file that is specified by filename is used as the source of

the file to check. The opaque object is an object that the
extract command of the AdminConfig object returns by a
prior call.
convertToCluster Converts a v Parameters: Example usage:
server so that server ID,
it is the first Using Jacl:
cluster name
member of a set serverid [$AdminConfig getid
v Returns: The
new server /Server:myServer/]
configuration ID $AdminConfig convertToCluster
cluster.
of the new $serverid myCluster
cluster.
Using Jython:
serverid = AdminConfig.getid
(’/Server:myServer/’)
AdminConfig.convertToCluster
(serverid, ’myCluster’)

Example output:
myCluster
(cells/mycell/clusters/myCluster|
cluster.xml#ClusterMember_2

558 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Creates v Parameters The name of the object type that you input here is the one
configuration using Jacl: type- that is based on the XML configuration files. This name does
objects. string; parent not have to be the same name that the administrative console
ID- string; displays.
attributes- string
Example usage:
v Parameters
using Jython: Using Jacl:
type- string; set jdbc1 [$AdminConfig getid
parent ID- /JDBCProvider:jdbc1/]
string; attributes- $AdminConfig create DataSource $jdbc1
string or type- {{name ds1}}
string; parent
ID- string; Using Jython with string attributes:
attributes- jdbc1 = AdminConfig.getid
Jython list (’/JDBCProvider:jdbc1/’)
v Returns: A string AdminConfig.create(’DataSource’, jdbc1,
with ’[[name ds1]]’)
configuration
Using Jython with object attributes:
object names.
jdbc1 = AdminConfig.getid
(’/JDBCProvider:jdbc1/’)
AdminConfig.create(’DataSource’, jdbc1,
[[’name’, ’ds1’]])

Example output:
ds1(cells/mycell/nodes/DefaultNode/servers/server1|
resources.xml#DataSource_6)

Chapter 4. Using the administrative clients 559

createCluster Creates a v Parameters The name of the object type that you input here is the one
Member new server using Jacl: that is based on the XML configuration files. This name does
as a member cluster ID- not have to be the same name that the administrative console
of an existing string; node ID- displays.
cluster. string; member
Example usage:
attributes- string
This method
creates a v Parameters Using Jacl:
new server using Jython: set clid [$AdminConfig getid
object on the cluster ID- /ServerCluster:myCluster/]
node that the string; node ID- set nodeid [$AdminConfig getid /Node:mynode/]
node id string; member $AdminConfig createClusterMember $clid
parameter attributes- string $nodeid
specifies. or cluster ID- {{memberName newMem1} {weight 5}}
This server is string; node ID-
string; member Using Jython with string attributes:
created as a
new member attributes- clid = AdminConfig.getid
of the Jython list (’/ServerCluster:myCluster/’)
nodeid = AdminConfig.getid(’/Node:mynode/’)
existing v Returns: The
AdminConfig.createClusterMember
cluster that is configuration ID (clid, nodeid,
specified by of the new ’[[memberName newMem1] [weight 5]]’)
the cluster id cluster member.
parameter, Using Jython with object attributes:
and contains clid = AdminConfig.getid(’/ServerCluster:myCluster/’)
attributes that nodeid = AdminConfig.getid(’/Node:mynode/’)
are specified AdminConfig.createClusterMember(clid, nodeid,
in the [[’memberName’, ’newMem1’], [’weight’, 5]])
member
attributes Example output:
parameter. myCluster
The server is (cells/mycell/clusters/myCluster|cluster.xml#
created using ClusterMember_2)
the server
template that
is specified
by the
template id
attribute, and
that contains
the name
specified by
the
memberName
attribute. The
memberName
attribute is
required.

560 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
createDocument Creates a v Parameters: Example usage:
new documentURI,
document in Using Jacl:
filename
the $AdminConfig createDocument cells/mycell/myfile.xml
v Returns: None
configuration c:\\mydir\\myfile
repository.
Using Jython:
The AdminConfig.createDocument(’cells/mycell/myfile.xml’,
documentURI ’c:\mydir\myfile’)
parameter
names the
document to
create in the
repository.
The filename
parameter
must be a
valid local file
name where
the contents
of the
document
exist.
createUsing Creates a v Parameters Example usage:
Template type of object using Jacl: type-
with the Using Jacl:
string; parent
given parent, id-string; set node [$AdminConfig getid /Node:mynode/]
using a attributes-string; set templ [$AdminConfig listTemplates JDBCProvider
template. template "DB2 JDBC Provider (XA)"]
$AdminConfig createUsingTemplate JDBCProvider $node
ID-string
{{name newdriver}} $templ
v Parameters
using Jython: Using Jython using string attributes:
type-string; node = AdminConfig.getid(’/Node:mynode/’)
parent id- string; templ = AdminConfig.listTemplates(’JDBCProvider’,
attributes-string; "DB2 JDBC Provider (XA)")
template AdminConfig.createUsingTemplate(’JDBCProvider’,
ID-string or node, ’[[name newdriver]]’, templ)
type-string;
parent id-string; Using Jython using object attributes:
attributes- node = AdminConfig.getid(’/Node:mynode/’)
Jython list; templ = AdminConfig.listTemplates(’JDBCProvider’,
template "DB2 JDBC Provider (XA)")
ID-string AdminConfig.createUsingTemplate(’JDBCProvider’,
node, [[’name’, ’newdriver’]], templ)
v Returns: The
configuration ID
of a new object.

Chapter 4. Using the administrative clients 561

defaults Displays the v Parameters: Example usage:
default type
values for Using Jacl:
The name of the
attributes of a $AdminConfig defaults TuningParams
object type that
given type.
you input here is Using Jython:
This method the one based
on the XML print AdminConfig.defaults(’TuningParams’)
displays all of
the possible configuration
Example output:
attributes files. This name
does not have Attribute Type Default
contained by
an object of a to be the same
usingMultiRowSchema Boolean false
specific type. name that the
maxInMemorySessionCount Integer 1000
If the administrative allowOverflow Boolean true
attribute has console scheduleInvalidation Boolean false
a default displays. writeFrequency ENUM
value, this v Returns: A string writeInterval Integer 120
method also that contains a writeContents ENUM
displays the list of attributes invalidationTimeout Integer 30
invalidationSchedule InvalidationSchedule
type and with its type and
default value value.
for each
attribute.
deleteDocument Deletes a v Parameters: Example usage:
document documentURI
from the Using Jacl:
v Returns: None
configuration $AdminConfig deleteDocument cells/mycell/myfile.xml
repository.
Using Jython:
The AdminConfig.deleteDocument(’cells/mycell/myfile.xml’)
documentURI
parameter
names the
document to
delete from
the
repository.
existsDocument Tests for the v Parameters: Example usage:
existence of documentURI
a document Using Jacl:
v Returns: A true
in the $AdminConfig existsDocument cells/mycell/myfile.xml
value, if the
configuration
document Using Jython:
repository.
exists.
AdminConfig.existsDocument(’cells/mycell/myfile.xml’)
The
documentURI Example output:
parameter
1
names the
document to
test in the
repository.

562 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
extract Extracts a v Parameters: Example usage:
configuration document URI,
repository file Using Jacl:
filename
that is set obj [$AdminConfig extract cells/MyCell/nodes/
v Returns: An
described by MyNode/serverindex.xml
opaue c:\\mydir\myfile]
the document
java.lang.Object
URI and
to use when Using Jython:
places it in
checking in the
the file obj = AdminConfig.extract(’cells/MyCell/nodes/
file. MyNode/serverindex.xml’,
named by
filename. ’c:\mydir\myfile’)
This method
only applies The document URI is relative to the root of the configuration
to repository, for example, c:\WebSphere\AppServer\config.
deployment
If the file that is specified by the filename parameter exists,
manager
the extracted file replaces it.
configurations.
getCrossDocument Returns a v Parameters: Example usage:
ValidationEnabled message with None
the current Using Jacl:
v Returns: A string
cross- $AdminConfig getCrossDocumentValidationEnabled
that contains the
document
message with Using Jython:
enablement
the
setting. print AdminConfig.getCrossDocumentValidationEnabled()
cross-document
This method validation
Example output:
returns true if setting.
WASX7188I: Cross-document validation enablement set to
cross- true
document
validation is
enabled.
getid Returns the v Parameters: Example usage:
configuration containment
ID of an Using Jacl:
path
object. $AdminConfig getid /Cell:testcell/Node:testNode/
v Returns: The
JDBCProvider:Db2JdbcDriver/
configuration ID
for an object Using Jython:
that is described
AdminConfig.getid(’/Cell:testcell/Node:testNode/
by the
JDBCProvider:Db2JdbcDriver/’)
containment
path. Example output:
Db2JdbcDriver(cells/testcell/nodes/testnode|
resources.xml#JDBCProvider_1)

Chapter 4. Using the administrative clients 563

getObjectName Returns a v Parameters: Example usage:
string version configuration ID
of the object Using Jacl:
v Returns: A string
name for the set server [$AdminConfig getid /Node:mynode/Server:server1/]
that contains the
corresponding $AdminConfig getObjectName $server
object name.
running
MBean. Using Jython:
server = AdminConfig.getid(’/Node:mynode/Server:server1/’)
This method AdminConfig.getObjectName(server)
returns an
empty string Example output:
if no WebSphere:cell=mycell,name=server1,mbeanIdentifier=cells/
corresponding mycell/nodes/mynode/servers/server1/server.xml#Server_1,
running type=Server,node=mynode,process=server1,processType=
MBean UnManagedProcess
exists.
getSaveMode Returns the v Parameters: Example usage:
mode that is None
used when Using Jacl:
v Returns: A string
you invoke a $AdminConfig getSaveMode
that contains the
save
current save Using Jython:
command.
mode setting.
print AdminConfig.getSaveMode()
Possible
values Example output:
include the
rollbackOnConflict
following:
v
overwriteOnConflict
- Saves
changes
even if they
conflict with
other
configuration
changes
v
rollbackOnConflict
- Causes a
save
operation to
fail if
changes
conflict with
other
configuration
changes.
This value
is the
default.

564 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
getValidationLevel Returns the v Parameters: Example usage:
validation None
used when Using Jacl:
v Returns: A string
files are $AdminConfig getValidationLevel
that contains the
extracted
validation level. Using Jython:
from the
repository. AdminConfig.getValidationLevel()

Example output:
WASX7189I: Validation level set to HIGH
getValidation Returns the v Parameters: Example usage:
SeverityResult number of severity
validation Using Jacl:
v Returns: A string
messages $AdminConfig getValidationSeverityResult 1
that indicates
with the
the number of Using Jython:
given severity
validation
from the AdminConfig.getValidationSeverityResult(1)
messages of the
most recent
given severity.
validation. Example output:
16
hasChanges Returns true v Parameters: Example usage:
if unsaved None
configuration Using Jacl:
v Returns: A string
changes $AdminConfig hasChanges
that indicates
exist.
whether Using Jython:
unsaved
configuration AdminConfig.hasChanges()
changes exist.
Example output:
1

Chapter 4. Using the administrative clients 565

help Displays v Parameters: Example usage:
static help None
information Using Jacl:
v Returns: A list of
for the $AdminConfig help
options.
AdminConfig
object. Using Jython:
print AdminConfig.help()

Example output:
WASX7053I: The AdminConfig object communicates with the
configuration service in a WebSphere Application Server
to manipulate configuration data
for an Application Server installation. The AdminConfig
object has commands to list, create,
remove, display, and modify configuration data, as well
as commands to display information about configuration
data types.

Most of the commands supported by the AdminConfig object

operate in two modes:
the default mode is one in which the AdminConfig object
communicates with the Application Server to accomplish
its tasks. A local mode is also possible, in which no
server communication takes place. The local mode of
operation is invoked by bringing up the scripting client
without a server connected using the command line
"-conntype NONE" option or setting the
"com.ibm.ws.scripting.connectionType=NONE" property in
the wsadmin.properties file.

The following commands are supported by the AdminConfig

object; more detailed information about each of these
commands is available by using the help command of the
AdminConfig object and by supplying the name of the
command as an argument.

attributes Shows the attributes for a given type

checkin Checks a file into the configuration
repository.
convertToCluster
Converts a server to be the first member
of a new server cluster
create Creates a configuration object, given
a type, a parent, and a list of attributes,
and optionally an attribute name for the
new object
createClusterMember
Creates a new server that is a member of an
existing cluster.
createDocument Creates a new document in the configuration
repository.
installResourceAdapter
Installs a J2C resource adapter with the
given RAR file name and an option string
in the node.
createUsingTemplate
Creates an object using a particular
template type.
defaults Displays the default values for the
attributes of a given type.
deleteDocument Deletes a document from the configuration
repository.
existsDocument Tests for the existence of a document in
the configuration repository.

566 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
help continued extract Extracts a file from the configuration
repository.
getCrossDocumentValidationEnabled
Returns true if cross-document validation
is enabled.
getid Show the configuration ID of an object,
given a string version of its containment
getObjectName Given a configuration ID, returns a string
version of the ObjectName
for the corresponding running MBean, if any.
getSaveMode Returns the mode used when "save" is invoked
getValidationLevel
Returns the validation that is used when
files are extracted from the repository.
getValidationSeverityResult
Returns the number of messages of a given
severity from the most recent validation.
hasChanges Returns true if unsaved configuration
changes exist
help Shows help information
list Lists all the configuration objects of
a given type
listTemplates Lists all the available configuration
templates of a given type.
modify Changes the specified attributes of a
given configuration object
parents Shows the objects which contain a given type
queryChanges Returns a list of unsaved files
remove Removes the specified configuration object
required Displays the required attributes of a
given type.
reset Discards the unsaved configuration changes
save Commits the unsaved changes to the
configuration repository
setCrossDocumentValidationEnabled
Sets the cross-document validation enabled mode.
setSaveMode Changes the mode used when "save" is invoked
setValidationLevel
Sets the validation used when files are
extracted from the repository.
show Shows the attributes of a given
configuration object
showall Recursively shows the attributes of a
given configuration object, and all
the objects that are contained within
each attribute.
showAttribute Displays only the value for the single
attribute that is specified.
types Shows the possible types for configuration
validate Invokes validation

Chapter 4. Using the administrative clients 567

installResource Installs a v Parameters: Example usage:
Adapter Java 2 RAR file name,
Connector Using Jacl:
node, options
(J2C) $AdminConfig installResourceAdapter c:/rar/mine.rar mynode
v Returns: The
resource {-rar.name myResourceAdapter -rar.desc "My rar file"}
configuration ID
adapter with
of the new Using Jython:
the given
J2CResourceAdapter
Resource print AdminConfig.installResourceAdapter(’c:/rar/mine.rar’,
object.
Adapter ’mynode’, ’[-rar.name myResourceAdapter -rar.desc
Archive "My rar file"]’)
(RAR) file
name and an Example output:
option string myResourceAdapter(cells/mycell/nodes/mynode|
in the node. resources.xml#J2CResourceAdapter_1)

The RAR file

name is the
fully qualified
file name that
resides in the
node that you
specify. The
valid options
include the
following
options:
v rar.name
v rar.desc
v
rar.archivePath
v
rar.classpath
v
rar.nativePath
v
rar.threadPoolAlias
v
rar.propertiesSet

568 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
installResource The rar.name
Adapter option is the
continued name for the
J2C resource
adapter. If
you do not
specify this
option, the
display name
in the RAR
deployment
descriptor is
used. If that
name is not
specified, the
RAR file
name is
used. The
rar.desc
option is a
description of
the
J2CResourceAdapter.
The
rar.archivePath
is the name
of the path
where you
extract the
file. If you do
not specify
this option,
the archive is
extracted to
the
$\{CONNECTOR_INSTALL_ROOT\}
directory. The
rar.classpath
option is the
additional
class path.

rar.propertiesSet
is
constructed
with the
following:
name String
value String
type String
*desc String
*required true/false
* means the item is optional

Each
attribute of
the property
are specified
in a set of {}.
A property is
specified in a
set of {}. You
can specify
multiple
Chapter 4. Using the administrative clients 569
properties in
{}.
installResource When you
Adapter edit the
continued installed
application
with the
embedded
RAR, only
existing J2C
connection
factory, J2C
activation
specs, and
J2C
administrative
objects will
be edited. No
new J2C
objects will
be created.
list Returns a list v Parameters: Example usage:
of objects of Object type
a given type, Using Jacl:
The name of the
possibly $AdminConfig list JDBCProvider
object type that
scoped by a
you input here is Using Jython:
parent.
the one that is
based on the print AdminConfig.list(’JDBCProvider’)
XML
Example output:
configuration
files and does Db2JdbcDriver(cells/mycell/nodes/DefaultNode|
not have to be resources.xml#JDBCProvider_1)
Db2JdbcDriver(cells/mycell/nodes/DefaultNode/servers/
the same name
deploymentmgr|
that the resources.xml#JDBCProvider_1)
administrative Db2JdbcDriver(cells/mycell/nodes/DefaultNode/servers/
console nodeAgent|resources.xml#JDBCProvider_1)
displays.
v Returns: A list of
objects.
listTemplates Displays a v Parameters: Example usage:
list of object type
template Using Jacl:
The name of the
object IDs. $AdminConfig listTemplates JDBCProvider
object type that
you input here is Using Jython:
the one that is
based on the print AdminConfig.listTemplates(’JDBCProvider’)
XML
This example displays a list of all the JDBCProvider
configuration
templates that are available on the system.
files and does
not have to be
the same name
that the
administrative
console
displays.
v Returns: A list of
template IDs.

570 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
modify Supports the v Parameters Example usage:
modification using Jacl:
of object Using Jacl:
object-string;
attributes. attributes-string $AdminConfig modify ConnFactory1(cells/mycell/nodes/
DefaultNode/servers/
v Parameters deploymentmgr|resources.xml#GenericJMSConnectionFactory_1)
using Jython: {{userID newID} {password newPW}}
object-string;
attributes-string Using Jython with string attributes:
or object-string; AdminConfig.modify(’ConnFactory1(cells/mycell/nodes/
attributes- DefaultNode/servers/
Jython list deploymentmgr|resources.xml#GenericJMSConnectionFactory_1)’,
v Returns: None ’[[userID newID] [password newPW]]’)

Using Jython with object attributes:

AdminConfig.modify(’ConnFactory1(cells/mycell/nodes/
DefaultNode/servers/
deploymentmgr|resources.xml#GenericJMSConnectionFactory_1)’,
[[’userID’, ’newID’], [’password’, ’newPW’]])
parents Obtains v Parameters: Example usage:
information object type
about object Using Jacl:
The name of the
types. $AdminConfig parents JDBCProvider
object type that
you input here is Using Jython:
the one that is
based on the AdminConfig.parents(’JDBCProvider’)
XML
Example output:
configuration
files and does Cell
not have to be Node
Server
the same name
that the
administrative
console
displays.
v Returns: A list of
object types.
queryChanges Returns a list v Parameters: Example usage:
of unsaved None
configuration Using Jacl:
v Returns: A string
files. $AdminConfig queryChanges
that contains a
list of files with Using Jython:
unsaved
changes. AdminConfig.queryChanges()

Example output:
WASX7146I: The following configuration files contain
unsaved changes:
cells/mycell/nodes/mynode/servers/server1|resources.xml
remove Removes a v Parameters: Example usage:
configuration Object
object. Using Jacl:
v Returns: None
$AdminConfig remove ds1(cells/mycell/nodes/DefaultNode/
servers/server1:resources.xml#DataSource_6)

Using Jython:
AdminConfig.remove(’ds1(cells/mycell/nodes/DefaultNode/
servers/server1:resources.xml#DataSource_6)’)

Chapter 4. Using the administrative clients 571

required Displays the v Parameters: Example usage:
required Type
attributes that Using Jacl:
The name of the
are contained $AdminConfig required URLProvider
object type that
by an object
you input here is Using Jython:
of a certain
the one that is
type. print AdminConfig.required(’URLProvider’)
based on the
XML
Example output:
configuration
files. It does not Attribute Type
have to be the streamHandlerClassName String
protocol String
same name that
the
administrative
console
displays.
v Returns: A string
that contains a
list of the
required
attributes with
its type.
reset Resets the v Parameters: Example usage:
temporary None
workspace Using Jacl:
v Returns: None
that holds $AdminConfig reset
updates to
the Using Jython:
configuration. AdminConfig.reset()
save Saves v Parameters: Example usage:
changes in None
the Using Jacl:
v Returns: None
configuration $AdminConfig save
repository.
Using Jython:
AdminConfig.save()
setCrossDocument Sets the v Parameters: Example usage:
ValidationEnabled cross- Flag
document Using Jacl:
v Returns: None
validation $AdminConfig setCrossDocumentValidationEnabled true
enabled
mode. Values Using Jython:
include true AdminConfig.setCrossDocumentValidationEnabled(’true’)
or false.

572 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
setSaveMode Toggles the v Parameters: Example usage:
behavior of Mode
the save Using Jacl:
v Returns: None
command. $AdminConfig setSaveMode overwriteOnConflict
The default
value is Using Jython:
rollbackOnConflict. AdminConfig.setSaveMode(’overwriteOnConflict’)
When a
conflict is
discovered
while saving,
the unsaved
changes are
not
committed.
The
alternative
value is
overwriteOnConflict,
which saves
the changes
to the
configuration
repository
even if
conflicts
exist.

To use
overwriteOnConflict
as the value
of this
command,
the
deployment
manager
must be
enabled for
configuration
overwrite.
setValidationLevel Sets the v Parameters: Example usage:
validation Level
that is used Using Jacl:
v Returns: A string
when files $AdminConfig setValidationLevel high
that contains the
are extracted
validation level Using Jython:
from the
setting.
repository. AdminConfig.setValidationLevel(’high’)
Five Example output:
validation
WASX7189I: Validation level set to HIGH
levels are
available:
none, low,
medium, high,
or highest.

Chapter 4. Using the administrative clients 573

show Returns the v Parameters: Example usage:
top-level Object,
attributes of Using Jacl:
attributes
the given $AdminConfig show Db2JdbcDriver(cells/mycell/
v Returns: A string
object. nodes/DefaultNode|resources.xm#JDBCProvider_1)
that contains the
attribute value. Example output with Jacl:
{name "Sample Datasource"} {description "Data source for
the Sample entity beans"}

Using Jython:
print AdminConfig.show(’Db2JdbcDriver(cells/mycell/nodes/
DefaultNode|resources.xm#JDBCProvider_1)’)

Example output with Jython:

[name "Sample Datasource"] [description "Data source
for the Sample entity beans"]

574 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
showall Recursively v Parameters: Example usage:
shows the Object,
attributes of a Using Jacl:
attributes
given $AdminConfig showall "Default Datasource(cells/mycell/
v Returns: A string
configuration nodes/DefaultNode/servers/server1:resources.xml#
that contains the DataSource_1)
object.
attribute value.
Example output with Jacl:
{authMechanismPreference BASIC_PASSWORD}
{category default}
{connectionPool {{agedTimeout 0}
{connectionTimeout 1000}
{maxConnections 30}
{minConnections 1}
{purgePolicy FailingConnectionOnly}
{reapTime 180}
{unusedTimeout 1800}}}
{datasourceHelperClassname
com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper}
{description "Datasource for the WebSphere Default
Application"}
{jndiName DefaultDatasource}
{name "Default Datasource"}
{propertySet {{resourceProperties {{{description
"Location of Cloudscape default database."}
{name databaseName}
{type string}
{value ${WAS_INSTALL_ROOT}/bin/DefaultDB}}
{{name remoteDataSourceProtocol}
{type string}
{value {}}} {{name shutdownDatabase}
{type string}
{value {}}} {{name dataSourceName}
{type string}
{value {}}} {{name description}
{type string}
{value {}}} {{name connectionAttributes}
{type string}
{value {}}} {{name createDatabase}
{type string}
{value {}}}}}}}
{provider "Cloudscape JDBC Driver(cells/pongo/nodes/pongo/
servers/server1|resources.xml#JDBCProvider_1)"}
{relationalResourceAdapter "WebSphere Relational
Resource Adapter(cells/pongo/
nodes/pongo/servers/server1|resources.xml#builtin_rra)"}
{statementCacheSize 0}

Using Jython:
AdminConfig.showall("Default Datasource(cells/mycell/nodes/
DefaultNode/servers/server1:resources.xml#DataSource_1)")

Example output with Jython:

[authMechanismPreference BASIC_PASSWORD]
[category default]
[connectionPool [[agedTimeout []]
[connectionTimeout 1000]
[maxConnections 30]
[minConnections 1]
[purgePolicy FailingConnectionOnly]
[reapTime 180]
[unusedTimeout 1800]]]
[datasourceHelperClassname
com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper]
[description "Datasource for the WebSphere Default
Application"]
[jndiName DefaultDatasource]
Chapter 4. Using the administrative clients
[name "Default Datasource"] 575
showall [propertySet [[resourceProperties [[[description "Location
continued of Cloudscape default database."]
[name databaseName]
[type string]
[value ${WAS_INSTALL_ROOT}/bin/DefaultDB]]
[[name remoteDataSourceProtocol]
[type string]
[value []]] [[name shutdownDatabase]
[type string]
[value []]] [[name dataSourceName]
[type string]
[value []]] [[name description]
[type string]
[value []]] [[name connectionAttributes]
[type string]
[value []]] [[name createDatabase]
[type string]
[value []]]]]]]
[provider "Cloudscape JDBC Driver(cells/pongo/nodes/pongo/
servers/server1|resources.xml#JDBCProvider_1)"]
[relationalResourceAdapter "WebSphere Relational Resource
Adapter(cells/pongo/nodes/pongo/servers/server1|
resources.xml#builtin_rra)"]
[statementCacheSize 0]
showAttribute Displays only v Parameters: Example usage:
the value for Configuration
the single Using Jacl:
ID, attribute
attribute that set ns [$AdminConfig getid /Node:mynode/]
v Returns: A string
you specify. $AdminConfig showAttribute $ns hostName
that contains the
The output of attribute value. Using Jython:
this ns = AdminConfig.getid(’/Node:mynode/’)
command is print AdminConfig.showAttribute(ns, ’hostName’)
different from
the output of Example output:
the show mynode
command
when a
single
attribute is
specified.
The
showAttribute
command
does not
display a list
that contains
the attribute
name and
value. It only
displays the
attribute
value.

576 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
types Returns a list v Parameters: Example usage:
of the None
configuration Using Jacl:
v Returns: A list of
object types $AdminConfig types
object types.
that you can
manipulate. Using Jython:
print AdminConfig.types()

Example output:
AdminService
Agent
ApplicationConfig
ApplicationDeployment
ApplicationServer
AuthMechanism
AuthenticationTarget
AuthorizationConfig
AuthorizationProvider
AuthorizationTableImpl
BackupCluster
CMPConnectionFactory
CORBAObjectNameSpaceBinding
Cell
CellManager
Classloader
ClusterMember
ClusteredTarget
CommonSecureInteropComponent

Chapter 4. Using the administrative clients 577

uninstallResource Uninstalls a v Parameters: Example usage:
Adapter Java 2 J2C resource
Connector Using Jacl:
adapter
(J2C) configuration ID, set j2cra [$AdminConfig getid /J2CResourceAdapter:MyJ2CRA/]
resource list of options $AdminConfig uninstallResourceAdapter $j2cra {-force}
adapter with $AdminConfig save
v Returns: The
the given
configuration ID Using Jython:
J2C resource
of
adapter j2cra = AdminConfig.getid(’/J2CResourceAdapter:MyJ2CRA/’)
J2CResourceAdapterprint AdminConfig.uninstallResourceAdapter(j2cra, ’[-force]’)
configuration
object that is AdminConfig.save()
ID and an
removed.
option list.
Example output:
One option is WASX7397I: The following J2CResourceAdapter objects are
valid for this removed:
command: * MyJ2CRA(cells/juniarti/nodes/juniarti|
force resources.xml#J2CResourceAdapter_1069433028609)

This option
forces the
uninstallation
of the
resource
adapter
without
checking
whether the
resource
adapter is
being used
by an
application.
The
application
that is using
it will not be
uninstalled. If
you do not
specify the
force option
and the
specified
resource
adapter is
still in use,
the resource
adapter is not
uninstalled.

578 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
uninstallResource When you
Adapter remove a
continued J2CResourceAdapter
object from
the
configuration
repository,
the installed
directory will
be removed
at the time of
synchronization.
A stop
request will
be sent to
the
J2CResourceAdapter
MBean that
was
removed.
validate Invokes v Parameters: Example usage:
validation. config id
Using Jacl:
(optional)
This $AdminConfig validate
command v Returns: A string
requests that contains Using Jython:
configuration results of the
validation. print AdminConfig.validate()
validation
results based Example output:
on the files in
WASX7193I: Validation results are logged in c:\WebSphere5\
your AppServer\logs\wsadmin.valout: Total number of messages: 16
workspace, WASX7194I: Number of messages of severity 1: 16
the value of
the
cross-
document
validation
enabled flag,
and the
validation
level setting.
Optionally,
you can
specify a
configuration
ID to set the
scope. If you
specify a
configuration
ID, the scope
of this
request is the
object named
by the config
id parameter.

Commands for the AdminControl object

Use the AdminControl object to invoke operational commands that deal with running objects in the
WebSphere Application Server. Many of the AdminControl commands have multiple signatures so that they

Chapter 4. Using the administrative clients 579

can either invoke in a raw mode using parameters that are specified by Java Management Extensions
(JMX), or by using strings for parameters. In addition to operational commands, the AdminControl object
supports some utility commands for tracing, reconnecting with a server, and converting data types.

The following commands are available for the AdminControl object:

Command Description: Parameters and return Examples:

name: values:
completeObject Creates a v Parameters: Example usage:
Name string name-java.lang.String
representation Using Jacl:
v Returns: java.lang.String
of a complete set serverON [$AdminControl
ObjectName completeObjectName node=mynode,type=Server,*]
value that is
based on a Using Jython:
fragment. This serverON = AdminControl.completeObjectName
command (’node=mynode,type=Server,*’)
does not
communicate
with the
server to find
a matching
ObjectName
value. If it
finds several
MBeans that
match the
fragment, the
command
returns the
first one.
getAttribute Returns the v Parameters: Example usage:
value of the name-java.lang.String;
attribute for Using Jacl:
attribute-java.lang.String
the name that set objNameString [$AdminControl
v Returns: java.lang.String
you provide. completeObjectName WebSphere:type=Server,*]
$AdminControl getAttribute
$objNameString processType

Using Jython:
objNameString =
AdminControl.completeObjectName
(’WebSphere:type=Server,*’)
AdminControl.getAttribute(objNameString,
’processType’)

580 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
getAttribute_jmx Returns the v Parameters: Example usage:
value of the name-ObjectName;
attribute for Using Jacl:
attribute-java.lang.String
the name that set objNameString [$AdminControl
v Returns: java.lang.String
you provide. completeObjectName WebSphere:type=Server,*]
set objName [java::new
javax.management.ObjectName
$objNameString]
$AdminControl getAttribute_jmx
$objName processType

Using Jython:
objNameString =
AdminControl.completeObjectName
(’WebSphere:type=Server,*’)
import javax.management as mgmt
objName = mgmt.ObjectName(objNameString)
AdminControl.getAttribute_jmx(objName,
’processType’)
getAttributes Returns the v Parameters using Jacl: Example usage:
attribute name-String;
values for the Using Jacl:
attributes-java.lang.String
names that set objNameString [$AdminControl
v Parameters using Jython:
you provide. completeObjectName WebSphere:type=Server,*]
name-String; $AdminControl getAttributes $objNameString
attributes-java.lang.String "cellName nodeName"
or name-String;
attributes- Using Jython with string attributes:
java.lang.Object[] objNameString =
v Returns: java.lang.String AdminControl.completeObjectname
(’WebSphere:type=Server,*)
AdminControl.getAttributes(objNameString,
’[cellName nodeName]’)

Using Jython with object attributes:

objNameString =
AdminControl.completeObjectname
(’WebSphere:type=Server,*)
AdminControl.getAttributes(objNameString,
[’cellName’, ’nodeName’])
getAttributes_jmx Returns the v Parameters: Example usage:
attribute name-ObjectName;
values for the Using Jacl:
attributes-
names that java.lang.String[] set objectNameString [$AdminControl
you provide. completeObjectName WebSphere:type=Server,*]
v Returns: set objName [$AdminControl makeObjectName
javax.management.AttributeList
$objectNameString]
set attrs [java::new {String[]} 2
{cellName nodeName}]
$AdminControl getAttributes_jmx $objName
$attrs

Using Jython:
objectNameString = AdminControl.completeObjectName
(’type=Server,*’)
objName = AdminControl.makeObjectName
(objectNameString)
attrs = [’cellName’, ’nodeName’]
AdminControl.getAttributes_jmx(objName,
attrs)

Chapter 4. Using the administrative clients 581

getCell Returns the v Parameters: None Example usage:
name of the
v Returns: java.lang.String Using Jacl:
connected
cell. $AdminControl getCell

Using Jython:
AdminControl.getCell()

Example output:
Mycell
getConfigId Creates a v Parameters: Example usage:
configuration name-java.lang.String
ID from an Using Jacl:
v Returns: java.lang.String
ObjectName set threadpoolCID [$AdminControl
or an getConfigId node=mynode,type=ThreadPool,*]
ObjectName
fragment. Use Using Jython:
this ID with threadpoolCID = AdminControl.getConfigId
the (’node=mynode,type=ThreadPool,*’)
$AdminConfig
command.
Not all
MBeans that
run have
configuration
objects that
correspond. If
several
MBeans
correspond to
an
ObjectName
fragment, a
warning is
created and a
configuration
ID builds for
the first
MBean it
finds.
getDefaultDomain Returns the v Parameters: None Example usage:
default
v Returns: java.lang.String Using Jacl:
domain name
from the $AdminControl getDefaultDomain
server.
Using Jython:
AdminControl.getDefaultDomain()

Example output:
WebSphere

582 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
getDomainName Returns the v Parameters: None Example usage:
domain name
v Returns: java.lang.String Using Jacl:
from the
server. $AdminControl getDomainName

Using Jython:
AdminControl.getDomainName()

Example output:
WebSphere
getHost Returns the v Parameters: None Example usage:
name of your
v Returns: java.lang.String Using Jacl:
host.
$AdminControl getHost

Using Jython:
AdminControl.getHost()

Example output:
myhost
getMBeanCount Returns the v Parameters: None Example usage:
number of
v Returns: java.lang.Integer Using Jacl:
MBeans that
are registered $AdminControl getMBeanCount
in the server.
Using Jython:
AdminControl.getMBeanCount()

Example output:
114
getMBeanInfo_jmx Returns the v Parameters: Example usage:
Java name-ObjectName
Management Using Jacl:
v Returns:
Extension set objectNameString [$AdminControl
javax.management.MBeanInfo
MBeanInfo completeObjectName type=Server,*]
structure that set objName [$AdminControl makeObjectName
corresponds $objectNameString]
to an $AdminControl getMBeanInfo_jmx $objName
ObjectName
Using Jython:
value. No
string objectNameString =
signature AdminControl.completeObjectName(’type=Server,*’)
exists for this objName = AdminControl.makeObjectName
(objectNameString)
command,
AdminControl.getMBeanInfo_jmx(objName)
because the
Help object Example output:
displays most
javax.management.modelmbean.
of the
ModelMBeanInfoSupport@10dd5f35
information
available from
the
getMBeanInfo
command.

Chapter 4. Using the administrative clients 583

getNode Returns the v Parameters: None Example usage:
name of the
v Returns: java.lang.String Using Jacl:
connected
node. $AdminControl getNode

Using Jython:
AdminControl.getNode()

Example output:
Myhost
getPort Returns the v Parameters: None Example usage:
name of your
v Returns: java.lang.String Using Jacl:
port.
$AdminControl getPort

Using Jython:
AdminControl.getPort()

Example output:
8877
getPropertiesFor Deprecated, v Parameters: Example usage:
DataSource no configId-java.lang.String
replacement. Using Jacl:
v Returns: java.lang.String
set ds [lindex [$AdminConfig list DataSource] 0]
This $AdminControl getPropertiesForDataSource $ds
command
incorrectly Using Jython:
assumes the ds = AdminConfig.list(’DataSource’)
availability of
a # get line separator
configuration import java.lang.System as sys
service when lineSeparator = sys.getProperty(’line.separator’)
running in
connected dsArray = ds.split(lineSeparator)
mode. AdminControl.getPropertiesForDataSource(dsArray[0])

Example output:
WASX7389E: Operation not supported -
getPropertiesForDataSource command
is not supported.
getType Returns the v Parameters: None Example usage:
connection
v Returns: java.lang.String Using Jacl:
type.
$AdminControl getType

Using Jython:
AdminControl.getType()

Example output:
SOAP

584 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
help Returns v Parameters: None Example usage:
general help
v Returns: java.lang.String Using Jacl:
text for the
AdminControl $AdminControl help
object.
Using Jython:
AdminControl.help()

Example output:
WASX7027I: The AdminControl object enables
the manipulation of MBeans that run in a
WebSphere Application Server process.
The number and type of MBeans that are
available to the scripting client depend
on the server to which the client is
connected. If the client is connected to a
deployment manager, then all the MBeans
running in the Deployment
Manager are visible, as are all the MBeans
running in the node agents that are
connected to this deployment manager, and
all the MBeans that run in the application
servers on those nodes.

The following commands are supported by

the AdminControl object; more detailed
information about each of these commands
is available by using the "help" command
of the AdminControl object and supplying
the name of the command as an argument.

Many of these commands support two

different sets of signatures: one that
accepts and returns strings, and one
low-level set that works with JMX objects
like ObjectName and AttributeList. In most
situations, the string signatures are
likely to be more useful,but JMX-object
signature versions are supplied as well.
Each of these JMX-object signature
commands has "_jmx" appended to the
command name,so an "invoke" command, as
well as a "invoke_jmx" command are
supported.

completeObjectName
Return a String version
of an object name given a
template name
getAttribute_jmx
Given ObjectName and name of
attribute, returns value of
attribute
getAttribute
Given String version of ObjectName
and name of attribute,returns value
of attribute
getAttributes_jmx
Given ObjectName and array of
attribute names, returns
AttributeList
getAttributes
Given String version of ObjectName
and attribute names,returns String
of name value pairs

Chapter 4. Using the administrative clients 585

help continued getCell
returns the cell name of the
connected server
getConfigId
Given String version of ObjectName,
return a config id for the
corresponding configuration
object, if any.
getDefaultDomain
returns "WebSphere"
getDomainName
returns "WebSphere"

getHost
returns String representation
of connected host
getMBeanCount
returns number of registered beans
getMBeanInfo_jmx
Given ObjectName, returns
MBeanInfo structure for MBean

getNode
returns the node name of the connected server
getPort
returns String representation of port in use
getType
returns String representation of connection
type in use
help
Show help information
invoke_jmx
Given ObjectName, name of command,
array of parameters and signature,
invoke command on MBean specified
invoke
Invoke a command on the specified MBean
isRegistered_jmx
true if supplied ObjectName is registered
isRegistered
true if supplied String version of
ObjectName is registered
makeObjectName
Return an ObjectName built with the
given string
queryNames_jmx
Given ObjectName and QueryExp, retrieves
set of ObjectNames that match.
queryNames
Given String version of ObjectName,
retrieves String of ObjectNames that match.
reconnect
reconnects with server
setAttribute_jmx
Given ObjectName and Attribute object,
set attribute for MBean specified
setAttribute
Given String version of ObjectName,
attribute name and attribute value,
set attribute for MBean specified
setAttributes_jmx
Given ObjectName and AttributeList object,
set attributes for the MBean specified
startServer
Given the name of a server, start that server.
stopServer
Given the name of a server, stop that server.
testConnection
586 IBM WebSphere Application Server Network Deployment, Version 6: Test the connection
Administering toand
applications a DataSource object
their environment
trace
Set the wsadmin trace specification
help Returns help v Parameters: Example usage:
text for the command-java.lang.String
specific Using Jacl:
v Returns: java.lang.String
command of $AdminControl help getAttribute
the
AdminControl Using Jython:
object. The AdminControl.help(’getAttribute’)
command
name is not Example output:
case WASX7043I: command: getAttribute
sensitive. Arguments: object name, attribute
Description: Returns value of "attribute"
for the MBean described by "object name."
invoke Invokes the v Parameters: name- Example usage:
object java.lang.String;
operation Using Jacl:
operationName-
without any java.lang.String set objNameString [$AdminControl
parameter. completeObjectName WebSphere:type=Server,*]
v Returns: java.lang.String $AdminControl invoke $objNameString stop
Returns the
result of the
invocation. Using Jython:
objNameString =
AdminControl.completeObjectName
(’WebSphere:type=Server,*’)
AdminControl.invoke(objNameString, ’stop’)

Chapter 4. Using the administrative clients 587

invoke Invokes the v Parameters: Example usage:
object name-java.lang.String;
operation Using Jacl:
operationName-
using the java.lang.String; set objNameString [$AdminControl
parameter list params-java.lang.String completeObjectName WebSphere:type=Server,*]
that you $AdminControl invoke $objNameString
v Returns: java.lang.String appendTraceString com.ibm.*=all=enabled
supply. The
signature
generates Using Jython:
automatically. objNameString =
The types of AdminControl.completeObjectName
parameters (’WebSphere:type=Server,*’)
are supplied AdminControl.invoke(objNameString,
’appendTraceString’, ’com.ibm.*=all=enabled’)
by examining
the
MBeanInfo
that the
MBean
supplies.
Returns the
string result of
the
invocation.
The string
that is
returned is
controlled by
the Mbean
method that
you invoked.
If the Mbean
method is
synchronous,
then control is
returned back
to the
wsadmin tool
only when the
operation is
complete. If
the Mbean
method is
asynchronous,
control is
returned back
to the
wsadmin tool
immediately
even though
the invoked
task might not
be complete.

588 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
invoke Invokes the v Parameters: Example usage:
object name-java.lang.String;
operation by Using Jacl:
operationName-
conforming java.lang.String; set objNameString [$AdminControl
the parameter params-java.lang.String; completeObjectName WebSphere:type=Server,*]
list to the sigs-java.lang.String $AdminControl invoke $objNameString
signature. appendTraceString com.ibm.*=all=enabled
v Returns: java.lang.String java.lang.String
Returns the
result of the
Using Jython:
invocation.
objNameString = AdminControl.completeObjectName
(’WebSphere:type=Server,*’)
AdminControl.invoke(objNameString,
’appendTraceString’, ’com.ibm.*=all=enabled’,
’java.lang.String’)
invoke_jmx Invokes the v Parameters: Example usage:
object name-ObjectName; set objNameString [$AdminControl
operation by operationName- completeObjectName WebSphere:type=TraceService,*]
conforming java.lang.String; params- set objName [java::new javax.management.ObjectName
the parameter java.lang.Object[]; $objNameString]
list to the signature- set parms [java::new {java.lang.Object[]}
signature. 1 com.ibm.ejs.sm.*=all=disabled]
java.lang.String[]
Returns the set signature [java::new
v Returns: java.lang.Object {java.lang.String[]} 1 java.lang.String]
result of the
$AdminControl invoke_jmx $objName
invocation.
appendTraceString $parms $signature

Using Jython:
objNameString = AdminControl.completeObjectName
(’WebSphere:type=TraceService,*’)
import javax.management as mgmt
objName = mgmt.ObjectName(objNameString)
parms = [’com.ibm.ejs.sm.*=all=disabled’]
signature = [’java.lang.String’]
AdminControl.invoke_jmx(objName,
’appendTraceString’, parms, signature)
isRegistered If the v Parameters: Example usage:
ObjectName name-java.lang.String
value is Using Jacl:
v Returns: Boolean
registered in set objNameString [$AdminControl
the server, completeObjectName WebSphere:type=Server,*]
then the value $AdminControl isRegistered $objNameString
is true.
Using Jython:
objNameString =
AdminControl.completeObjectName
(’WebSphere:type=Server,*’)
AdminControl.isRegistered(objNameString)

Chapter 4. Using the administrative clients 589

isRegistered_jmx If the v Parameters: Example usage:
ObjectName name-ObjectName
value is Using Jacl:
v Returns: Boolean
registered in set objectNameString [$AdminControl
the server, completeObjectName type=Server,*]
then the value set objName [$AdminControl makeObjectName
is true. $objNameString]
$AdminControl isRegistered_jmx $objName

Using Jython:
objectNameString =
AdminControl.completeObjectName
(’type=Server,*’)
objName =
AdminControl.makeObjectName
(objectNameString)
AdminControl.isRegistered_jmx(objName)
makeObjectName A v Parameters: Example usage:
convenience name-java.lang.String
command that Using Jacl:
v Returns:
creates an set objectNameString [$AdminControl
javax.management.ObjectName
ObjectName completeObjectName type=Server,node=mynode,*]
value that is set objName [$AdminControl makeObjectName $
based on the objNameString]
strings input.
This Using Jython:
command objectNameString =
does not AdminControl.completeObjectName
communicate (’type=Server,node=mynode,*’)
with the objName = AdminControl.makeObjectName
(objectNameString)
server, so the
ObjectName
value that
results might
not exist. If
the string you
supply
contains an
extra set of
double
quotes, they
are removed.
If the string
does not
begin with a
Java
Management
Extensions
(JMX)
domain, or a
string followed
by a colon,
then the
WebSphere
Application
Server string
appends to
the name.

590 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
queryNames Returns a v Parameters: Example usage:
string that name-java.lang.String
lists all the Using Jacl:
v Returns: java.lang.String
ObjectName $AdminControl queryNames WebSphere:type=Server,*
objects based
on the name Using Jython:
template. AdminControl.queryNames(’WebSphere:type=Server,*’)

Example output:
WebSphere:cell=BaseApplicationServerCell,
name=server1,mbeanIdentifier=server1,type=Server,
node=mynode,process=server1
queryNames_jmx Returns a set v Parameters: Example usage:
of name-
ObjectName Using Jacl:
javax.management.Object
objects that Name;query- set objectNameString [$AdminControl
are based on javax.management.QueryExpcompleteObjectName type=Server,*]
the set objName [$AdminControl
v Returns: java.util.Set makeObjectName $objNameString]
ObjectName
object and the set null [java::null]
QueryExp $AdminControl queryNames_jmx $objName $null
query that you
Using Jython:
provide.
objectNameString =
AdminControl.completeObjectName
(’type=Server,*’)
objName = AdminControl.makeObjectName
(objectNameString)
AdminControl.queryNames_jmx(objName,
None)

Example output:
[WebSphere:cell=BaseApplicationServerCell,
name=server1,mbeanIdentifier=server1,type=
Server,node=mynode,process=server1]
reconnect Reconnects to v Parameters: None Example usage:
the server,
v Returns: None Using Jacl:
and clears
information $AdminControl reconnect
out of the
local cache. Using Jython:
AdminControl.reconnect()

Example output:
WASX7074I: Reconnect of SOAP connector to
host myhost completed.

Chapter 4. Using the administrative clients 591

setAttribute Sets the v Parameters: Example usage:
attribute value name-java.lang.String;
for the name Using Jacl:
attributeName-
that you java.lang.String; set objNameString [$AdminControl
provide. attributeValue- completeObjectName WebSphere:type=
java.lang.String TraceService,*]
$AdminControl setAttribute $objNameString
v Returns: None traceSpecification com.ibm.*=all=disabled

Using Jython:
objNameString =
AdminControl.completeObjectName
(’WebSphere:type=TraceService,*’)
AdminControl.setAttribute(objNameString,
’traceSpecification’, ’com.ibm.*=all=disabled’)
setAttribute_jmx Sets the v Parameters: Example usage:
attribute value name-ObjectName;
for the name Using Jacl:
attribute-
that you javax.management.Attributeset objectNameString [$AdminControl
provide. completeObjectName WebSphere:type=
v Returns: None TraceService,*]
set objName [$AdminControl makeObjectName
$objectNameString]
set attr [java::new javax.management.Attribute
traceSpecification com.ibm.*=all=disabled]
$AdminControl setAttribute_jmx
$objName $attr

Using Jython:
objectNameString =
AdminControl.completeObjectName
(’WebSphere:type=TraceService,*’)
import javax.management as mgmt
objName = AdminControl.makeObjectName
(objectNameString)
attr = mgmt.Attribute(’traceSpecification’,
’com.ibm.*=all=disabled’)
AdminControl.setAttribute_jmx(objName, attr)
setAttributes Sets the v Parameters using Jacl: Example usage:
attribute name-String;
values for the Using Jacl:
attributes-java.lang.String
names that set objNameString [$AdminControl
v Parameters using Jython:
you provide completeObjectName WebSphere:type=
name-String; TracesService,*]
and returns a
attributes-java.lang.String $AdminControl setAttributes $objNameString
list of
or name-String; {{traceSpecification com.ibm.ws.*=all=enabled}}
successfully
attributes-
set names.
java.lang.Object[] Using Jython with string attributes:
v Returns: java.lang.String objNameString = AdminControl.completeObjectName
(’WebSphere:type=TracesService,*’)
AdminControl.setAttributes(objNameString,
’[[traceSpecification "com.ibm.ws.*=all=enabled"]]’)

Using Jython with object attributes:

objNameString = AdminControl.completeObjectName
(’WebSphere:type=TracesService,*’)
473 AdminControl.setAttributes(objNameString,
[[’traceSpecification’, ’com.ibm.ws.*=all=enabled’]])

592 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
setAttributes_jmx Sets the v Parameters: Example usage:
attribute name-ObjectName;
values for the Using Jacl:
attributes-
names that set objectNameString [$AdminControl
javax.management.AttributeList
you provide completeObjectName WebSphere:type=TraceService,*]
v Returns: set objName [$AdminControl makeObjectName
and returns a
javax.management.AttributeList
$objectNameString]
list of
successfully set attr [java::new javax.management.Attribute
set names. traceSpecification com.ibm.ws.*=all=enabled]
set alist
[java::new javax.management.AttributeList]
$alist add $attr
$AdminControl setAttributes_jmx $objName $alist

Using Jython:
objectNameString =
AdminControl.completeObjectName
(’WebSphere:type=TraceService,*’)
import javax.management as mgmt
objName = AdminControl.makeObjectName
(objectNameString)
attr = mgmt.Attribute(’traceSpecification’,
’com.ibm.ws.*=all=enabled’)
alist = mgmt.AttributeList()
alist.add(attr)
AdminControl.setAttributes_jmx(objName,
alist)
startServer Starts the v Parameters: server Example usage:
specified name-java.lang.String
application Using Jacl:
v Returns: java.lang.String
server by $AdminControl startServer server1
locating it in
the Using Jython:
configuration. AdminControl.startServer(’server1’)
This
command
uses the
default wait
time. You can
only use this
command if
the scripting
client is
connected to
a node agent.
This
command
returns a
message to
indicate if the
server starts
successfully.

Chapter 4. Using the administrative clients 593

startServer Starts the v Parameters: server Example usage:
specified name-java.lang.String,
application Using Jacl:
wait time-java.lang.String
server by $AdminControl startServer server1 100
v Returns: java.lang.String
locating it in
the Using Jython:
configuration. AdminControl.startServer(’server1’, 100)
The start
process waits
the number of
seconds
specified by
the wait time
for the server
to start. You
can only use
this command
if the scripting
client is
connected to
a node agent.
This
command
returns a
message to
indicate if the
server starts
successfully.
startServer Starts the v Parameters: server Example usage:
specified name-java.lang.String,
application Using Jacl:
node
server by name-java.lang.String $AdminControl startServer server1 myNode
locating it in
v Returns: java.lang.String Using Jython:
the
configuration. AdminControl.startServer(’server1’, ’myNode’)
This
command
uses the
default wait
time. You can
use this
command
when the
scripting client
is either
connected to
a node agent
or to a
deployment
manager
process. It
returns a
message to
indicate if the
server starts
successfully.

594 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
startServer Starts the v Parameters: server Example usage:
specified name-java.lang.String,
application Using Jacl:
node
server by name-java.lang.String, $AdminControl startServer server1 myNode 100
locating it in wait time-java.lang.String
the Using Jython:
v Returns: java.lang.String
configuration. AdminControl.startServer(’server1’, ’myNode’, 100)
The start
process waits
the number of
seconds
specified by
the wait time
for the server
to start. You
can use this
command
when the
scripting client
is either
connected to
a node agent
or to a
deployment
manager
process. This
command
returns a
message to
indicate if the
server starts
successfully.
stopServer Stops the v Parameters: server Example usage:
specified name-java.lang.String
application Using Jacl:
v Returns: java.lang.String
server. The $AdminControl stopServer server1
command
returns a Using Jython:
message to AdminControl.stopServer(’server1’)
indicate if the
server stops
successfully.

Chapter 4. Using the administrative clients 595

stopServer Stops the v Parameters: server Example usage:
specified name-java.lang.String,
application Using Jacl:
immediate
server. If you flag-java.lang.String $AdminControl stopServer server1 immediate
set the flag to
v Returns: java.lang.String Using Jython:
immediate,
the server AdminControl.stopServer(’server1’,
stops ’immediate’)
immediately.
Otherwise, a
normal stop
occurs. This
command
returns a
message to
indicate if the
server stops
successfully.
stopServer Stops the v Parameters: server Example usage:
specified name-java.lang.String,
application Using Jacl:
node
server. This name-java.lang.String $AdminControl stopServer server1 myNode
command
v Returns: java.lang.String Using Jython:
returns a
message to AdminControl.stopServer(’server1’, ’my Node’)
indicate if the
server stops
successfully.
stopServer Stops the v Parameters: server Example usage:
specified name-java.lang.String,
application Using Jacl:
node
server. If you name-java.lang.String, $AdminControl stopServer server1 myNode immediate
set the flag to immediate
immediate, flag-java.lang.String Using Jython:
the server AdminControl.stopServer(’server1’, ’my Node’,
v Returns: java.lang.String
stops ’immediate’)
immediately.
Otherwise, a
normal stop
occurs. This
command
returns a
message to
indicate if the
server stops
successfully.

596 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
testConnection A v Parameters: Example usage:
convenience configId-java.lang.String
command Using Jacl:
v Returns: java.lang.String
communicates set ds [lindex [$AdminConfig list DataSource] 0]
with the $AdminControl testConnection $ds
DataSourceCfgHelper
MBean to test Using Jython:
a DataSource # get line separator
connection. import java.lang.System as sys
This lineSeparator = sys.getProperty(’line.separator’)
command ds = AdminConfig.list(’DataSource’).split
works with the (lineSeparator)[0]
DataSource AdminControl.testConnection(ds)
that resides in
Example output:
the
configuration WASX7217I: Connection to provided
repository. If datasource was successful.
the
DataSource to
be tested is in
the temporary
workspace
that holds the
update to the
repository,
you have to
save the
update to the
configuration
repository
before
running this
command.
Use this
command
with the
configuration
ID that
corresponds
to the
DataSource
and the
WAS40DataSource
object types.
The return
value is a
message that
contains the
message
indicating a
successful
connection or
a connection
with warning.
If the
connection
fails, an
exception is
created from
the server
indicating the
error.
Chapter 4. Using the administrative clients 597
testConnection Deprecated. v Parameters: Example usage:
configId-java.lang.String;
This Using Jacl:
props-java.lang.String
command can set ds [lindex [$AdminConfig list DataSource] 0]
give false v Returns: java.lang.String
$AdminControl testConnection $ds {{prop1 val1}}
results and
does not work Using Jython:
when # get line separator
connected to import java.lang.System as sys
a node agent. lineSeparator = sys.getProperty(’line.separator’)
As of V5.0.2, ds = AdminConfig.list(’DataSource’).split
the preferred (lineSeparator)[0]
way to test a AdminControl.testConnection(ds, ’[[prop1 val1]]’)
data source
connection is Example output:
with the WASX7390E: Operation not supported -
testConnection testConnection command with config id
command that and properties arguments is not supported.
passes in the Use testConnection command with
config id argument only.
DataSource
configId
parameter as
the only
parameter.
trace Sets the trace v Parameters: Example usage:
specification traceSpec-java.lang.String
for the Using Jacl:
v Returns: None
scripting $AdminControl trace com.ibm.ws.scripting.*=
process to the all=enabled
value that you
specify. Using Jython:
AdminControl.trace(’com.ibm.ws.scripting.*=
all=enabled’)

Commands for the AdminApp object

Use the AdminApp object to install, modify, and administer applications. The AdminApp object interacts
with the WebSphere Application Server management and configuration services to make application
inquiries and changes. This interaction includes installing and uninstalling applications, listing modules,
exporting, and so on.

You can start the scripting client when no server is running, if you want to use only local operations. To run
in local mode, use the -conntype NONE option to start the scripting client. You receive a message that you
are running in the local mode. Running the AdminApp object in local mode when a server is currently
running is not recommended. This is because any configuration changes made in local mode will not be
reflected in the running server configuration and vice versa. If you save a conflicting configuration, you
could corrupt the configuration. In a deployment manager environment, configuration updates are available
only if a scripting client is connected to a deployment manager. When connected to a node agent or a
managed application server, you will not be able to update the configuration because the configuration for
these server processes are copies of the master configuration which resides in the deployment manager.
The copies are created on a node machine when a configuration synchronization occurs between the
deployment manager and the node agent. Make configuration changes to the server processes by
connecting a scripting client to a deployment manager. For this reason, to change a configuration, do not
run a scripting client in local mode on a node machine. It is not a supported configuration.

The following commands are available for the AdminApp object:

598 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Command Description: Parameters and return Examples:
name: values:
deleteUserAnd Deletes users v Parameters: appname Example usage:
GroupEntries or groups for all
v Returns: None Using Jacl:
roles, and
deletes user $AdminApp deleteUserAndGroupEntries myapp
IDs and
passwords for Using Jython:
all of the RunAs AdminApp.deleteUserAndGroupEntries(’myapp’)
roles that are
defined in the
application.
edit Edits an v Parameters using Jacl: Example usage:
application or appname - string; options -
module in Using Jacl:
string
non-interactive $AdminApp edit "JavaMail Sample"
v Parameters using Jython:
mode. {-MapWebModToVH {{"JavaMail
appname - string; options - Sample WebApp" mtcomps.war,WEB-INF/web.xml
The edit string or appname - string; newVH}}}
command options - Jython list
changes the v Returns: string Using Jython with string options:
application AdminApp.edit("JavaMail Sample",
deployment. ’[-MapWebModToVH [["JavaMail
Specify these 32 Sample WebApp" mtcomps.war,WEB-INF/web.xml
changes in the newVH]]]’)
options
parameter. No Using Jython with list options:
options are option = [["JavaMail 32 Sample WebApp",
required for the "mtcomps.war,WEB-INF/web.xml",
edit command. "newVH"]]
mapVHOption = ["-MapWebModToVH", option]
AdminApp.edit("JavaMail Sample", mapVHOption)
editInteractive Edits an v Parameters using Jacl: Example usage:
application or appname - string; options -
module in Using Jacl:
string
interactive $AdminApp editInteractive ivtApp
v Parameters using Jython:
mode.
appname - string; options - Using Jython:
The string or appname - string;
options - Jython list AdminApp.editInteractive(’ivtApp’)
editInteractive
command v Returns: string
changes the
application
deployment.
Specify these
changes in the
options
parameter. No
options are
required for the
editInteractive
command.
export Exports the v Parameters: appname, Example usage:
application filename
appname Using Jacl:
v Returns: None
parameter to a $AdminApp export "My App" /usr/me/myapp.ear
file that you
specify by file Using Jython:
name. AdminApp.export("My App", ’/usr/me/myapp.ear’)

Chapter 4. Using the administrative clients 599

exportDDL Extracts the v Parameters: appname, Example usage:
data definition directoryname, options
language (DDL) Using Jacl:
v Returns: None
from the $AdminApp exportDDL "My App" /usr/me/DDL
application {-ddlprefix myApp}
appname
parameter to Using Jython:
the AdminApp.exportDDL("My App", ’/usr/me/DDL’,
directoryname ’[-ddlprefix myApp]’)
parameter that
a directory
specifies. The
options
parameter is
optional.

600 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
help Displays v Parameters: None Example usage:
general help for
v Returns: None Using Jacl:
the AdminApp
object. $AdminApp help

Using Jython:
print AdminApp.help()

Example output:
WASX7095I: The AdminApp object allows
application objects to be manipulated
including installing, uninstalling,
editing,and listing. Most of the commands
supported by AdminApp operate in two modes:
the default mode is one in which AdminApp
communicates with the WebSphere Application
Server to accomplish its tasks. A local
mode is also possible, in which no server
communication takes place. The local mode
of operation is invoked by including the
"-conntype NONE" flag in the option string
supplied to the command.

The following commands are supported by

AdminApp; more detailed information about
each of these commands is available by
using the "help" command of AdminApp
and supplying the name of the command
as an argument.

edit Edit the properties of an

application
editInteractive Edit the properties of an
application interactively
export Export application to a file
exportDDL Extract DDL from application
to a directory
help Show help information
install Installs an application,
given a file name and an
option string.
installInteractive
Installs an application
in interactive mode, given
a file name and an option
string.
list List all installed
applications
listModules List the modules in a
specified application
options Shows the options available,
either for a given file,
or in general.
taskInfo Shows detailed information
pertaining to a given
installation task for a
given file
uninstall Uninstalls an application,
given an application name
and an option string

Chapter 4. Using the administrative clients 601

help Displays help v Parameters: operation name Example usage:
for an
v Returns: none Using Jacl:
AdminApp
command or $AdminApp help uninstall
installation
option. Using Jython:
print AdminApp.help(’uninstall’)

Example output:
WASX7102I: Method: uninstall
Arguments: application name, options
Description: Uninstalls application named
by "application name" using the options
supplied by String 2.
Method: uninstall
Arguments: application name
Description: Uninstalls the application
specified by
"application name" using default options.
install Installs an v Parameters using Jacl: Example usage:
application in earfile- string; options- string
non-interactive Using Jacl:
v Parameters using Jython:
mode, given a $AdminApp install c:/apps/myapp.ear
earfile- string; options- string
fully qualified
or earfile- string; options- Using Jython:
file name and a
Jython list
string of AdminApp.install(’c:/apps/myapp.ear’)
installation v Returns: None
options. The Many options are available for this command.
options You can obtain a list of valid options for an
parameter is Enterprise Archive (EAR) file with the following
optional. command:

Using Jacl:
$AdminApp options myApp.ear

Using Jython:
AdminApp.options(’myApp.ear’)

You can also obtain help for each object with

the following command:

Using Jacl:
$AdminApp help MapModulesToServers

Using Jython:
AdminApp.help(’MapModulesToServers’)
installInteractive Installs an v Parameters using Jacl: Example usage:
application in earfile- string; options- string
interactive Using Jacl:
v Parameters using Jython:
mode, given a $AdminApp installInteractive c:/websphere/
earfile- string; options- string
fully qualified appserver/installableApps/jmsample.ear
or earfile- string; options-
file name and a
Jython list Using Jython:
string of
installation v Returns: None AdminApp.installInteractive(’c:/websphere/
options. The appserver/installableApps/jmsample.ear’)
options
parameter is
optional.

602 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list Lists the v Parameters: None Example usage:
applications that
v Returns: application names Using Jacl:
are installed in
the $AdminApp list
configuration.
Using Jython:
print AdminApp.list()

Example output:
adminconsole
DefaultApplication
ivtApp
listModules Lists the v Parameters: appname, Example usage:
modules in an options
application. Using Jacl:
v Returns: modules in the
$AdminApp listModules ivtApp
The options application
parameter is Using Jython:
optional. The print AdminApp.listModules(’ivtApp’)
valid option is
-server. This Example output:
option lists the
ivtApp#ivtEJB.jar+META-INF/ejb-jar.xml
application ivtApp#ivt_app.war+WEB-INF/web.xml
servers on
which the This example is formed by the concatenation of
modules are appname, #, module URI, +, and DD URI. You
installed. can pass this string to the edit and
editInteractive AdminApp commands.

Chapter 4. Using the administrative clients 603

options Displays a list v Parameters: earfile Example usage:
of options for
v Returns: Information about Using Jacl:
installing an
the valid installation options
Enterprise $AdminApp options
for an Enterprise Archive
Archive (EAR) c:/websphere/appserver/installableApps/
(EAR) file. ivtApp.ear
file.

Using Jython:
AdminApp.options
(’c:/websphere/appserver/installableApps/
ivtApp.ear’)

Example usage:
WASX7112I: The following options are valid
for "c:/websphere/appserver/installableapps/
ivtApp.ear"
MapRolesToUsers
BindJndiForEJBNonMessageBinding
MapEJBRefToEJB
MapWebModToVH
MapModulesToServers
EnsureMethodProtectionFor10EJB
GetServerName
preCompileJSPs
nopreCompileJSPs
distributeApp
nodistributeApp
useMetaDataFromBinary
nouseMetaDataFromBinary
deployejb
nodeployejb
createMBeansForResources
nocreateMBeansForResources
reloadEnabled
noreloadEnabled
deployws
nodeployws
usedefaultbindings
defaultbinding.force
allowPermInFilterPolicy
noallowPermInFilterPolicy
verbose
update
update.ignore.old
update.ignore.new
installed.ear.destination
appname
reloadInterval
validateinstall
deployejb.rmic
deployejb.dbtype
deployejb.dbschema
deployejb.classpath
deployws.classpath
deployws.jardirs
defaultbinding.datasource.jndi
defaultbinding.datasource.username
defaultbinding.datasource.password
defaultbinding.cf.jndi
defaultbinding.cf.resauth
defaultbinding.ejbjndi.prefix
defaultbinding.virtual.host
defaultbinding.strategy.file
server
node
cell
cluster
604 IBM WebSphere Application Server Network Deployment, Version 6: Administering
contextrootapplications and their environment
custom
options Displays a list v Parameters: Application Example usage:
of options for name
editing an Using Jacl:
v Returns: Information about
existing $AdminApp options ivtApp
the valid edit options for an
application.
application. Using Jython:
AdminApp.options(’ivtApp’)

Example output:
WASX7112I: The following options are valid
for "ivtApp"
MapRolesToUsers
BindJndiForEJBNonMessageBinding
MapEJBRefToEJB
MapWebModToVH
MapModulesToServers
distributeApp
nodistributeApp
useMetaDataFromBinary
nouseMetaDataFromBinary
createMBeansForResources
nocreateMBeansForResources
reloadEnabled
noreloadEnabled
verbose
installed.ear.destination
reloadInterval
options Displays a list v Parameters: application Example usage:
of options for module name. This
editing a Using Jacl:
parameter requires the same
module in an module name format as the $AdminApp options ivtApp#ivtEJB.jar+
existing output that is returned by the META-INF/ejb-jar.xml
application. listModules command.
Using Jython:
v Returns: Information about
AdminApp.options(’ivtApp#ivtEJB.jar+
the valid edit options for a
META-INF/ejb-jar.xml’)
module.
Example output:
WASX7112I: The following options are valid
for "ivtApp#ivtEJB.jar+META-INF/ejb-jar.xml"
MapRolesToUsers
BindJndiForEJBNonMessageBinding
MapModulesToServers
verbose

Chapter 4. Using the administrative clients 605

options Displays a list v Parameters: Example using the updateapp operation:
of options for
file, operation - The following Using Jacl:
installing or
list includes the valid values:
updating an $AdminApp options
application or – installapp - Installing the c:/websphere/appserver/installableApps/
application file that is specified ivtApp.ear updateapp
module file. – updateapp - Updating an
existing application with Using Jython:
the file that is specified AdminApp.options
(’c:/websphere/appserver/installableApps/
– addmodule - Adding the
ivtApp.ear’, ’updateapp’)
module file that is
specified to an existing Example using the addmodule operation:
application
– updatemodule - Updating Using Jacl:
an existing module in an $AdminApp options myModule.jar addmodule
application with the
module file that is Using Jython:
specified AdminApp.options
v Returns: Information about (’DefaultWebApplication.war’, ’addmodule’)
the valid options that are
available for the operation Example output using the updateapp operation:
that is requested with the WASX7112I: The following options are valid
input file. for "c:/websphere/appserver/installableApps/
ivtApp.ear"
MapRolesToUsers
BindJndiForEJBNonMessageBinding
MapEJBRefToEJB
MapWebModToVH
MapModulesToServers
EnsureMethodProtectionFor10EJB
GetServerName
preCompileJSPs
nopreCompileJSPs
distributeApp
nodistributeApp
useMetaDataFromBinary
nouseMetaDataFromBinary
deployejb
nodeployejb
createMBeansForResources
nocreateMBeansForResources
reloadEnabled
noreloadEnabled
deployws
nodeployws
usedefaultbindings
defaultbinding.force
allowPermInFilterPolicy
noallowPermInFilterPolicy
verbose
update
update.ignore.old
update.ignore.new
installed.ear.destination
reloadInterval
deployejb.rmic
deployejb.dbtype
deployejb.dbschema
deployejb.classpath
deployws.classpath
deployws.jardirs

606 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
options defaultbinding.datasource.jndi
continued defaultbinding.datasource.username
defaultbinding.datasource.password
defaultbinding.cf.jndi
defaultbinding.cf.resauth
defaultbinding.ejbjndi.prefix
defaultbinding.virtual.host
defaultbinding.strategy.file
appname
contextroot
custom
contenturi
contents
operation

Example output using the addmodule operation:

WASX7112I: The following options are valid
for "DefaultWebApplication.war"
MapRolesToUsers
MapEJBRefToEJB
MapWebModToVH
MapModulesToServers
GetServerName
preCompileJSPs
nopreCompileJSPs
deployejb
nodeployejb
deployws
nodeployws
usedefaultbindings
defaultbinding.force
verbose
defaultbinding.datasource.jndi
defaultbinding.datasource.username
defaultbinding.datasource.password
defaultbinding.cf.jndi
defaultbinding.cf.resauth
defaultbinding.ejbjndi.prefix
defaultbinding.virtual.host
defaultbinding.strategy.file
server
node
cell
cluster
contextroot
custom
contenturi
contents
operation
publishWSDL Publishes Web v Parameters: appname, Example usage:
Services filename
Description Using Jacl:
v Returns: None
Language $AdminApp publishWSDL JAXRPCHandlerServer
(WSDL) files for c:/temp/a.zip
the application
that is specified Using Jython:
in the appname AdminApp.publishWSDL
parameter to (’JAXRPCHandlerServer’, ’c:/temp/a.zip’)
the file that is
specified in the
filename
parameter.

Chapter 4. Using the administrative clients 607

publishWSDL Publishes Web v Parameters: appname, Example usage:
Services filename,
Description Using Jacl:
soapAddressPrefixes
Language $AdminApp publishWSDL JAXRPCHandlersServer
v Returns: None
(WSDL) files for c:/temp/a.zip
the application {{JAXRPCHandlersServerApp.war
that is specified {{http http://localhost:9080}}}}
in the appname
parameter to Using Jython:
the file that is AdminApp.publishWSDL(’JAXRPCHandlersServer’,
specified in the ’c:/temp/a.zip’,
filename ’[[JAXRPCHandlersServerApp.war
parameter using [[http http://localhost:9080]]]]’)
the SOAP
address
prefixes that are
specified in the
soapAddressPrefixes
parameter.
searchJNDI Lists v Parameters: Node Example usage:
References applications that configuration ID, options
refer to the The following example assumes that an
v Returns: string installed application named MyApp has a JNDI
Java Naming
and Directory name of eis/J2CCF1.
Interface (JNDI)
name on a Using Jacl:
specific node. $AdminApp searchJNDIReferences $node
{-JNDIName eis/J2CCF1 -verbose}

Using Jython:
print AdminApp.searchJNDIReferences(node,
’[-JNDIName eis/J2CCF1 -verbose]’)

Example output:
WASX7410W: This operation may take a while
depending on the number of applications
installed in your system.
MyApp
MapResRefToEJB :ejb-jar-ic.jar : [eis/J2CCF1]

608 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
taskInfo Provides v Parameters: earfile, task Example usage:
information name
about a Using Jacl:
v Returns: None
particular task $AdminApp taskInfo
option for an c:/websphere/appserver/installableApps/
application file. jmsample.ear MapWebModToVH

Using Jython:
print AdminApp.taskInfo
(’c:/websphere/appserver/installableApps/
jmsample.ear’, ’MapWebModToVH’)

Example output:
MapWebModToVH: Selecting virtual hosts for
Web modules Specify the virtual host where
you want to install the Web modules that are
contained in your application. Web modules
can be installed on the same virtual host
or dispersed among several hosts. Each
element of the MapWebModToVH task consists
of the following three fields: "webModule,"
"uri," "virtualHost." Of these fields,
the following fields might be assigned
new values: "virtualHost"and the following
are required: "virtualHost"

The current contents of the task after

running default bindings are:
webModule: JavaMail Sample WebApp
uri: mtcomps.war,WEB-INF/web.xml
virtualHost: default_host
uninstall Uninstalls an v Parameters: appname- string Example usage:
existing
v Returns: None Using Jacl:
application.
$AdminApp uninstall myApp

Using Jython:
AdminApp.uninstall(’myApp’)

Example output:
ADMA5017I: Uninstallation of myapp started.
ADMA5104I: Server index entry for
myCellManager was updated successfully.
ADMA5102I: Deletion of config data for myapp
from config repository completed successfully.
ADMA5011I: Cleanup of temp dir for app myapp
done.
ADMA5106I: Application myapp uninstalled
successfully.

Chapter 4. Using the administrative clients 609

updateAccessIDs Updates the v Parameters: appname, bALL Example usage:
access ID
v Returns: None Using Jacl:
information for
users and $AdminApp updateAccessIDs myapp true
groups that are
assigned to Using Jython:
various roles AdminApp.updateAccessIDs(’myapp’, ’true’)
that are defined
in the
application. The
access IDs are
read from the
user registry
and saved in
the application
bindings. This
operation
improves
run-time
performance of
the application.
Call this
command after
installing an
application or
after editing
security
role-specific
information for
an installed
application. This
method cannot
be invoked
when the
-conntype
option is set to
NONE. You must
be connected to
a server to
invoke this
command.

The bALL
Boolean
parameter
retrieves and
saves all
access IDs for
users and
groups in the
application
bindings.
Specify false if
you want to
retrieve access
IDs for users or
groups that do
not have an
access ID in the
application
bindings.

610 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
view View the task v Parameters: name, taskname Example usage:
that is specified option
by the Using Jacl:
v Returns: string
taskname $AdminApp view adminconsole {-tasknames}
option
parameter for Using Jython:
the application AdminApp.view(’adminconsole’, [’-tasknames’])
or by the
module that is Example output:
specified by the MapModulesToServers
name MapWebModToVH
parameter. Use MapRolesToUsers
-tasknames as
the option to Using Jacl:
get a list of $AdminApp view adminconsole
valid task {-MapModulesToServers}
names for the
application. Using Jython:
Otherwise, AdminApp.view(’adminconsole’,
specify one or [’-MapModulesToServers’])
more task
names as the Example output:
option. MapModulesToServers: Selecting Application
Servers

Specify the application server where you

want to install the modules that are
contained in your application. Modules can
be installed on the same server or dispersed
among several servers:

Module: adminconsole
URI: adminconsole.war,WEB-INF/web.xml
Server: WebSphere:cell=juniartiNetwork,
node=juniartiManager,server=dmgr

Example usage:

Using Jacl:
$AdminApp view adminconsole#adminconsole.war+
WEB-INF/web.xml {-MapRolesToUsers}

Using Jython:
AdminApp.view
(’adminconsole#adminconsole.war+WEB-INF/
web.xml’, [’-MapRolesToUsers’])

Example output:
MapRolesToUsers: Mapping Users to Roles

Each role that is defined in the application

or the module must be mapped to a user or a
group from the user registry of the domain:

Role: administrator
Everyone?: No
All Authenticated?: No
Mapped Users:
Mapped Groups:

Chapter 4. Using the administrative clients 611

view continued Role: operator
Everyone?: No
All Authenticated?: No
Mapped Users:
Mapped Groups:
Role: configurator
Everyone?: No
All Authenticated?: No
Mapped Users:
Mapped Groups:
Role: monitor
Everyone?: No
All Authenticated?: No
Mapped Users:
Mapped Groups:

612 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
update Updates an v Parameters using Jacl: Example usage:
application in appname, content type,
non-interactive Using Jacl:
options – string format
mode. Provide $AdminApp update myApp file {-operation
v Parameters using Jython:
the application add -contents
appname, content type, c:/apps/myApp/web.xml
name, content
option- string or list format -contenturi META-INF/web.xml}
type, and
update options. v Returns: String
Using Jython with string options:
This command supports the
addition, removal, and update AdminApp.update(’myApp‘, ’file‘,
of application subcomponents ’[-operation add -contents
or the entire application. c:/apps/myApp/web.xml
-contenturi META-INF/web.xml]‘)
Use the content type
parameter to indicate if you Using Jython with list options:
want to update part of the AdminApp.update(’myApp‘, ’file‘,
application or the entire [’-operation‘, ’add‘,
application. The following list ’-contents‘, ’c:/apps/myApp/web.xml‘,
includes the valid content ’-contenturi‘,
type values for the update ’META-INF/web.xml‘])
command:
Example output:
– app - Indicates that you
want to update the entire Update of singleFile has started.
application. This option is ADMA5009I: Application archive extracted at
the same as indicating the C:\DOCUME~1\lavena\LOCALS~1\Temp\
app_fb5a1960f0\ext
update option with the
Added files from partial ear: []
install command. With the performFileOperation:
app value as the content source=C:\DOCUME~1\lavena\LOCALS~1\Temp\
type, you must specify the app_fb5a1960f0\ext, dest=C:\DOCUME~1\lavena\
operation option with LOCALS~1\Temp\
update as the value. app_fb5a1960f0\mrg, uri= META-INF/web.xml,
Provide the new op= add
enterprise archive file Copying file from C:\DOCUME~1\lavena\
(EAR) file using the LOCALS~1\Temp\app_fb5a1960f0\ext/
contents option. You can META-INF/web.xml to
C:\DOCUME~1\lavena\LOCALS~1\Temp
also specify binding
\app_fb5a1960f0\mrg\META-INF\web.xml
information and Collapse list is: []
application options. By FileMergeTask completed successfully
default, binding ADMA5005I: Application singleFile
information for installed configured in WebSphere repository
modules is merged with delFiles: []
the binding information for delM: null
updated modules. To addM: null
change this default
behavior, specify the
update.ignore.old or the
update.ignore.new
options.

Chapter 4. Using the administrative clients 613

update v file - Indicates that you Pattern for remove loose and mod:
continued want to update a single file. Loose add pattern: META-INF/[^/]*|
WEB-INF/[^/]*|.*wsdl
You can add, remove, or
root file to be copied: META-INF/web.xml to
update individual files at any C:\asv\b0403.04\WebSphere\AppServer\
scope within the deployed wstemp\Scriptfb5a191b4e\workspace\cells\
application. With the file BAMBIE\applications\
value as the content type, singleFile.ear\deployments\singleFile/
you must perform operations META-INF/web.xml
on the file using the ADMA5005I: Application singleFile
operation option. Depending configured in WebSphere repository
on the type of operation, xmlDoc: [#document: null]
additional options are root element: [app-delta: null]
****** delta file name: C:\asv\b0403.04\
required. For file additions
WebSphere\AppServer\wstemp\Scriptfb5a191
and updates, you must b4e\workspace\cells\BAMBIE\applications\
provide file content and the singleFile.ear/deltas/delta-1079548405564
file URI relative to the root of ADMA5005I: Application singleFile
the EAR file using the configured in WebSphere repository
contents and contenturi ADMA6011I: Deleting directory tree
options. For file deletion, you C:\DOCUME~1\lavena\LOCALS~1\Temp\app_fb5a1960f0
must provide the file URI ADMA5011I: Cleanup of temp dir for app
relative to the root of the singleFile done.
EAR file using the contenturi Update of singleFile has ended.
option which is the only
required input. Any other
options that you provide are
ignored.

614 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
update v modulefile - Indicates that
continued you want to update a
module. You can add,
remove, or update an
individual application module.
If you specify the modulefile
value as the content type,
you must indicate the
operation that you want to
perform on the module using
the operation option.
Depending on the type of
operation, further options are
required. For installing new
modules or updating existing
modules in an application,
you must indicate the file
content and the file URI
relative to the root of the
EAR file using the contents
and contenturi options. You
can also specify binding
information and application
options that pertain to the
new or updated modules. For
module updates, the binding
information for the installed
module is merged with the
binding information for the
input module by default. To
change the default behavior,
specify the update.ignore.old
or the update.ignore.new
options. To delete a module,
indicate the file URI relative
to the root of the EAR file.

Chapter 4. Using the administrative clients 615

update v partialapp - Indicates that
continued you want to update a partial
application. Using a subset of
application components
provided in a zip file format
you can update, add, and
delete files and modules. The
zip file is not a valid Java 2
platform, Enterprise Edition
(J2EE) archive. Instead, it
contains application artifacts
in the same hierarchical
structure as they display in
an EAR file. For more
information on how to
construct the partial
application zip file, see the
Java API section. If you
indicate the partialapp value
as the content type, use the
contents option to specify the
location of the zip file. When
a partial application is
provided as an update input,
binding information and
application options cannot be
specified and are ignored, if
provided.

For a list of the valid options for

the update command, see
“Options for the AdminApp
object install, installInteractive,
edit, editInteractive, update, and
updateInteractive commands”
on page 620.

616 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
updateInteractive Updates an v Parameters using Jacl: Example usage:
application in appname, content type,
interactive Using Jacl:
options - string format
mode. Provide $AdminApp updateInteractive myApp modulefile
v Parameters using Jython:
the application {-operation
appname, content type, add -contents c:/apps/myApp/Increment.jar
name, content
option - string or list format -contenturi
type, and
update options. v Returns: String Increment.jar -nodeployejb
-BindJndiForEJBNonMessageBinding
Use the updateInteractive
{{"Increment Enterprise JavaBeans"
command to add, remove, Increment Increment.
and update application jar,META-INF/ejb-jar.xml Inc}}}
subcomponents or an entire
application. When you update Using Jython string:
an application module or an AdminApp.updateInteractive(’myApp‘,
entire application using ’modulefile‘, ’[-operation add -contents
interactive mode, the steps c:/apps/myApp/Increment.jar -contenturi
that you use to configure Increment.jar -nodeployejb
binding information are -BindJndiForEJBNonMessageBinding
similar to those that apply to [["Increment Enterprise JavaBeans"
the installInteractive Increment Increment.jar,META-INF/
command. If you update a ejb-jar.xml Inc]]]‘)
file or a partial application,
Using Jython list:
the steps that you use to
configure the binding bindJndiForEJBValue = [["Increment Enterprise
information are not available. JavaBeans", "Increment", "Increment.jar,
In this case, the steps are META-INF/ejb-jar.xml", "Inc"]]
the same as the ones you
AdminApp.updateInteractive(’myApp‘,
use with the update ’modulefile‘, [’-operation‘, ’add‘,
command. ’-contents‘, ’c:/apps/myApp/Increment.jar‘,
Use the content type ’-contenturi‘, ’Increment.jar‘,
parameter to indicate if you ’-nodeployejb‘,
want to update part of the ’-BindJndiForEJBNonMessageBinding‘,
application or the entire bindJndiForEJBValue])
application. The following list
Example output:
contains the valid content
type values for the Getting tasks for: myApp
updateInteractive command: WASX7266I: A was.policy file exists for this
application; would you like to display it? [No]
– app - Indicates that you
want to update the entire Task[4]: Binding enterprise beans to JNDI
application. This option is names Each non message driven enterprise
the same as indicating the bean in your application or module must be
update option with install bound to a JNDI name.
command. With the app
value as the content type, EJB Module: Increment Enterprise Java Bean
EJB: Increment
you must specify the
URI: Increment.jar,META-INF/ejb-jar.xml
operation option with JNDI Name: [Inc]:
update as the value.
Provide the new Task[10]: Specifying the default data source
enterprise archive file for EJB 2.x modules
(EAR) file using the Specify the default data source for
contents option. You can the EJB 2.x Module containing 2.x CMP beans.
also specify binding
information and
application options. By
default, binding
information for installed
modules is merged with
the binding information for
updated modules. To
change this default
behavior, specify the
update.ignore.old or the Chapter 4. Using the administrative clients 617
update.ignore.new
options.
updateInteractive v file - Indicates that you WASX7349I: Possible value for resource
continued want to update a single file. authorization is container or per connection
factory
You can add, remove, or
EJB Module: Increment Enterprise Java Bean
update individual files at any URI: Increment.jar,META-INF/ejb-jar.xml
scope within the deployed JNDI Name: [DefaultDatasource]:
application. With the file Resource Authorization: [Per connection
value as the content type, factory]:
you must perform operations
on the file using the Task[12]: Specifying data sources for
operation option. Depending individual 2.x CMP beans
on the type of operation, Specify an optional data source for each
additional options are 2.x CMP bean. Mapping a specific data source
to a CMP bean
required. For file additions
overrides the default data source for
and updates, you must the module containing the enterprise bean.
provide file content and the
file URI relative to the root of WASX7349I: Possible value for resource
the EAR file using the authorization is container or per connection
contents and contenturi factory
options. For file deletion, you EJB Module: Increment Enterprise Java Bean
must provide the file URI EJB: Increment
relative to the root of the URI: Increment.jar,META-INF/ejb-jar.xml
EAR file using the JNDI Name: [DefaultDatasource]:
Resource Authorization: [Per connection
contenturi option which is
factory]: container
the only required input. Any Setting "Resource Authorization" to
other options that you "cmpBinding.container"
provide are ignored. Task[14]: Selecting Application Servers
v modulefile - Indicates that Specify the application server where you want
you want to update a to install modules that are contained in your
module. You can add, application.
Modules can be installed on the same server or
remove, or update an
dispersed among several servers.
individual application module.
If you specify the modulefile Module: Increment Enterprise Java Bean
value as the content type, URI: Increment.jar,META-INF/ejb-jar.xml
you must indicate the Server: [WebSphere:cell=myCell,node=myNode,
operation that you want to server=server1]:
perform on the module using
the operation option. Task[16]: Selecting method protections for
Depending on the type of unprotected methods for 2.x EJB
operation, additional options Specify whether you want to assign security
role to the unprotected method, add the
are required. For installing
method to the exclude list, or mark the
new modules or updating method as unchecked.
existing modules in an
application, you must indicate EJB Module: Increment Enterprise Java Bean
the file content and the file URI: Increment.jar,META-INF/ejb-jar.xml
URI relative to the root of the Protection Type: [methodProtection.uncheck]:
EAR file using the contents
and the contenturi options. Task[18]: Selecting backend ID
You can also specify binding Specify the selection for the BackendID
information and application
EJB Module: Increment Enterprise Java Bean
options that pertain to the
URI: Increment.jar,META-INF/ejb-jar.xml
new or updated modules. For BackendId list: CLOUDSCAPE_V50_1
module updates, the binding CurrentBackendId: [CLOUDSCAPE_V50_1]:
information for the installed
module is merged with the Task[21]: Specifying application options
binding information for the Specify the various options available
input module by default. To to prepare and install your application.
change the default behavior,
specify the update.ignore.old Pre-compile JSP: [No]:
or the update.ignore.new Deploy EJBs: [No]:
Deploy WebServices: [No]:
options. To delete a module,
indicate the file URI relative
618 to the root of the EAR file.
IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
updateInteractive v partialapp - Indicates that Task[22]: Specifying EJB deploy options
continued you want to update a partial Specify the options to deploy EJB.
application. Using subset of
....EJB Deploy option is not enabled.
application components
provided in a zip file format Task[24]: Copy WSDL files
you can update, add, and Copy WSDL files
delete files and modules. The
zip file is not a valid Java 2 ....This task does not require any user
platform, Enterprise Edition input
(J2EE) archive. Instead, this
file contains application Task[25]: Specify options to deploy Web
artifacts in the same services Specify options to deploy Web
services
hierarchical structure as they
are displayed in an EAR file. ....Web Services deploy option is not
For more information on how enabled.
to construct the partial Update of myApp has started.
application zip file, see the ADMA5009I: Application archive extracted at
Java API section. If you C:\DOCUME~1\lavena\LOCALS~1\Temp\
indicate the partialapp value app_fb5a48e969\ext/Increment.jar
as the content type, use the FileMergeTask completed successfully
contents option to specify the ADMA5005I: Application myApp configured
location of the zip file. When in WebSphere repository
delFiles: []
a partial application is
delM: null
provided as an update input, addM: [Increment.jar, ]
the binding information and Pattern for remove loose and mod:
application options cannot be Loose add pattern: META-INF/[^/]*|WEB-INF/[^/]*|.*wsdl
specified and are ignored, if root file to be copied:
provided. META-INF/application.xml to
C:\asv\b0403.04\WebSphere\AppServer\
For a list of the valid options for wstemp\Scriptfb5a487089\
the updateInteractive workspace\cells\BAMBIE\applications\testSM.ear\deployments
command, see “Options for the testSM/META-INF/application.xml
AdminApp object install, del files for full module add/update: []
installInteractive, edit, ADMA6017I: Saved document
C:\asv\b0403.04\WebSphere\AppServer\
editInteractive, update, and
wstemp\Scriptfb5a487089\workspace\cells\
updateInteractive commands” BAMBIE\applications\
on page 620. testSM.ear\deployments\testSM/Increment.jar\
META-INF/ejb-jar.xml
ADMA6016I: Add to workspace
Increment.jar/META-INF/ejb-jar.xml
ADMA6017I: Saved document
C:\asv\b0403.04\WebSphere\AppServer\
wstemp\Scriptfb5a487089\workspace\cells\
BAMBIE\applications\
testSM.ear\deployments\testSM/Increment.jar\
META-INF/MANIFEST.MF
ADMA6016I: Add to workspace Increment.jar/
META-INF/MANIFEST.MF
ADMA6017I: Saved document C:\asv\b0403.04\
WebSphere\AppServer\
wstemp\Scriptfb5a487089\workspace\cells\
BAMBIE\applications\
testSM.ear\deployments\testSM/Increment.jar\
META-INF/ibm-ejb-jar-bnd.xmi
ADMA6016I: Add to workspace Increment.jar/
META-INF/ibm-ejb-jar-bnd.xmi
ADMA6017I: Saved document C:\asv\b0403.04\
WebSphere\AppServer\
wstemp\Scriptfb5a487089\workspace\cells\
BAMBIE\applications\
testSM.ear\deployments\testSM/Increment.jar\
META-INF/Table.ddl
ADMA6016I: Add to workspace Increment.jar/
META-INF/Table.ddl
Chapter 4. Using the administrative clients 619
updateInteractive ADMA6017I: Saved document C:\asv\b0403.04\
continued WebSphere\
AppServer\wstemp\Scriptfb5a487089\workspace\
cells\BAMBIE\
applications\testSM.ear\deployments\testSM/
Increment.jar\META-INF/ibm-ejb-jar-ext.xmi
ADMA6016I: Add to workspace Increment.jar/
META-INF/ibm-ejb-jar-ext.xmi
add files for full module add/update:
[Increment.jar/
META-INF/ejb-jar.xml, Increment.jar/
META-INF/MANIFEST.MF,
Increment.jar/META-INF/ibm-ejb-jar-bnd.xmi,
Increment.jar/META-INF/
Table.ddl, Increment.jar/META-INF/ibm-ejb-jar-ext.xmi]
ADMA5005I: Application myApp configured in
WebSphere repository
xmlDoc: [#document: null]
root element: [app-delta: null]
****** delta file name: C:\asv\b0403.04\
WebSphere\
AppServer\wstemp\Scriptfb5a487089\workspace
\cells\BAMBIE\applications\testSM.ear/
deltas/delta-1079551520393
ADMA5005I: Application myApp configured
in WebSphere repository
ADMA6011I: Deleting directory tree
C:\DOCUME~1\lavena\LOCALS~1\Temp\
app_fb5a48e969
ADMA5011I: Cleanup of temp dir for app
myApp done.
Update of myApp has ended.

Options for the AdminApp object install, installInteractive, edit, editInteractive, update, and
updateInteractive commands: This article lists the available options for the install, installInteractive,
edit, editInteractive, update, and updateInteractive commands of the AdminApp object. The options
listed in this article apply to all of these commands except where noted.

See Commands for the AdminApp object for more detailed information on how to use the commands. See
Usage table for the options of the AdminApp object install, installInteractive, update, updateInteractive,
edit, and editInteractive commands for a list of applicable commands for each option.

The following options are available for the install, installInteractive, edit, editInteractive, update, and
updateInteractive commands:

Option name: Description: Examples:

620 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
ActSpecJNDI Binds J2C Using Jacl:
activation specs $AdminApp install $embeddedEar {-ActSpecJNDI {{"FVT Resource Adapter"
to destination jca15cmd.rar,META-INF/ra.xml javax.jms.MessageListener jndi5}
JNDI names. You {"FVT Resource Adapter" jca15cmd.rar,META-INF/ra.xml
can bind J2C javax.jms.MessageListener2 jndi6}}}
activation specs
in your Using Jython:
application or AdminApp.install(embeddedEar, [’-ActSpecJNDI’, [["FVT Resource Adapter",
module to a ’jca15cmd.rar,META-INF/ra.xml’, ’javax.jms.MessageListener’, ’jndi5’],
destination JNDI ["FVT Resource Adapter", ’jca15cmd.rar,META-INF/ra.xml’,
name. This ’javax.jms.MessageListener2’, ’jndi6’]]])
option is optional.
Each element of
the ActSpecJNDI
option consists of
the following
fields:
RARModule, uri,
j2cid,
j2c.jndiName.
j2c.jndiName
field, can be
assigned a value.
The current
contents of the
option after
running default
bindings include:
v RARModule:
<rar module
name>
v uri: <rar
name>,META-
INF/ra.xml
v j2cid:
<messageListenerType>
v j2c.jndiName:
null
v Object
identifier:
javax.jms.MessageListener

You can only use

this option if the
activation spec
has the
Destination
property defined
in the ra.xml file
and the
introspected type
of the
Destination
property is the
following:
javax.jms.Destination

Chapter 4. Using the administrative clients 621

ActSpecJNDI Use the taskInfo
continued command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.
allowPermInFilter Specifies to
Policy continue with the
application
deployment
process even
when the
application
contains policy
permissions that
are in the filter
policy. This
option does not
require a value.
appname Specifies the
name of the
application. The
default is the
display name of
the application.
BackendIdSelection Specifies the Using Jacl:
backend ID for $AdminApp install c:/myapp.ear {-BackendIdSelection
the enterprise {{Annuity20EJB Annuity20EJB.jar,META-INF/ejb-jar.xml DB2UDBNT_V72_1}}}
bean Java
archive (JAR) Using Jython:
modules that AdminApp.install(’c:/myapp.ear’, ’[-BackendIdSelection
have [[Annuity20EJB Annuity20EJB.jar,META-INF/ejb-jar.xml DB2UDBNT_V72_1]]]’)
container-
managed
persistence
(CMP) beans. An
enterprise bean
JAR module can
support multiple
backend
configurations as
specified using
an application
assembly tool.

Use this option to

change the
backend ID
during
installation.

622 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
BindJndiForEJB Binds enterprise Using Jacl:
MessageBinding beans to listener $AdminApp install $ear {-BindJndiForEJBMessageBinding
port names or {{Ejb1 MessageBean
Java Naming and ejb-jar-ic.jar,META-INF/ejb-jar.xml myListenerPort
Directory jndi1 jndiDest1 actSpecAuth1}}}
Interface (JNDI)
names. Use this Using Jython:
option to provide AdminApp.install(ear, [’-BindJndiForEJBMessageBinding’,
missing data or [[’Ejb1’, ’MessageBean’,
update a task. ’ejb-jar-ic.jar,META-INF/ejb-jar.xml’, ’myListenerPort’,
Ensure each ’jndi1’, ’jndiDest1’, ’actSpecAuth1’]]])
message-driven
enterprise bean
in your
application or
module is bound
to a listener port
name.

Each element of
the
BindJndiForEJBMessageBinding
option consists of
the following
fields:
EJBModule, EJB,
uri, listenerPort,
JNDI, jndi.dest,
and
actspec.auth.
Some of these
fields, can be
assigned values:
listenerPort,
JNDI, jndi.dest,
and
actspec.auth.

The current
contents of the
option after
running default
bindings include:
v EJBModule:
Ejb1
v EJB:
MessageBean
v uri:
ejb-jar-
ic.jar,META-
INF/ejb-jar.xml
v listenerPort:
MessageBeanPort
v JNDI: null
v jndi.dest: null
v actspec.auth:
null

Chapter 4. Using the administrative clients 623

BindJndiForEJB Use the taskInfo
MessageBinding command of the
continued AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.
BindJndiForEJB Binds enterprise Using Jacl:
NonMessageBinding beans to Java $AdminApp install c:/myapp.ear {-BindJndiForEJBNonMessageBinding
Naming and {{"Increment Bean Jar" Inc Increment.jar,META-INF/ejb-jar.xml IncBean}}}
Directory
Interface (JNDI) Using Jython:
names. AdminApp.install(’c:/myapp.ear’, ’[-BindJndiForEJBNonMessageBinding
[["Increment Bean Jar" Inc Increment.jar,META-INF/ejb-jar.xml IncBean]]]’)
Ensure each non
message-driven
enterprise bean
in your
application or
module is bound
to a JNDI name.
Use this option to
provide missing
data or update a
task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

624 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
cell Specifies the cell
name to install or
update an entire
application or to
update an
application in
order to add a
new module. If
you want to
update an entire
application, this
option only
applies if the
application
contains a new
module that does
not exist in the
installed
application.
cluster Specifies the
cluster name to
install or update
an entire
application or to
update an
application in
order to add a
new module.
This option only
applies in a
Network
Deployment
environment. If
you want to
update an entire
application, this
option only
applies if the
application
contains a new
module that does
not exist in the
installed
application.

Chapter 4. Using the administrative clients 625

contents Specifies the file
that contains the
content that you
want to update.
For example,
depending on the
content type, the
file could be an
EAR file, a
module, a partial
zip, or a single
file. The path to
the file must be
local to the
scripting client.
The contents
option is required
unless you have
specified the
delete option.
contenturi Specifies the URI
of the file that
you are adding,
updating, or
removing from an
application. This
option only
applies to the
update
command. The
contenturi
option is required
if the content
type is file or
modulefile. This
option is ignored
for other content
types.
contextroot Specifies the
context root that
you use when
installing a
stand-alone Web
archive (WAR)
file.

626 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CorrectOracleIsolation Specifies the Using Jacl:
Level isolation level for $AdminApp install c:/myapp.ear {-CorrectOracleIsolationLevel
the Oracle type {{AsyncSender jms/MyQueueConnectionFactory jms/Resource1 2}}
provider. Use this
option to provide Using Jython:
missing data or AdminApp.install(’c:/myapp.ear’, ’[-CorrectOracleIsolationLevel
to update a task. [[AsyncSender jms/MyQueueConnectionFactory jms/Resource1 2]]]’)
The last field of
each entry
specifies the
isolation level.
Valid isolation
level values are 2
or 4.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
only need to
provide data for
rows or entries
that are either
missing
information, or
require an
update.

Chapter 4. Using the administrative clients 627

CorrectUseSystem Replaces RunAs Using Jacl:
Identity System to RunAs $AdminApp install c:/myapp.ear {-CorrectUseSystemIdentity
Roles. {{Inc "Increment Bean Jar"
Increment.jar,META-INF/ejb-jar.xml getValue() RunAsUser2
The enterprise user2 password2} {Inc "Increment
beans that you Bean Jar" Increment.jar,META-INF/ejb-jar.xml Increment()
install contain a RunAsUser2 user2 password2}}}
RunAs system
identity. You can Using Jython:
optionally change AdminApp.install(’c:/myapp.ear’, ’[-CorrectUseSystemIdentity
this identity to a [[Inc "Increment Bean Jar"
RunAs role. Use Increment.jar,META-INF/ejb-jar.xml getValue() RunAsUser2
this option to user2 password2] [Inc "Increment
provide missing Bean Jar" Increment.jar,META-INF/ejb-jar.xml Increment()
data or update a RunAsUser2 user2 password2]]]’)
task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.
createMBeansFor Specifies that
Resources MBeans are
created for all
resources such
as, servlets,
JavaServer
Pages (JSP)
files, and
enterprise beans,
that are defined
in an application
when the
application starts
on a deployment
target. This
option does not
require a value.
The default
setting is the
nocreateMBeansForResources
option.

628 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
custom Specifies a
name-value pair
using the format
name=value. Use
the custom option
to pass options
to application
deployment
extensions. See
the application
deployment
extension
documentation
for available
custom options.
DataSourceFor10 Specifies optional Using Jacl:
CMPBeans data sources for $AdminApp install c:/app1.ear {-DataSourceFor10CMPBeans
individual 1.x {{"Increment CMP 1.1 EJB"
container- IncCMP11 IncCMP11.jar,META-INF/ejb-jar.xml myJNDI user1 password1
managed loginName1 authProps1}}}
persistence
(CMP) beans. Using Jython:
Use this option to AdminApp.install(’c:/app1.ear’, [’-DataSourceFor10CMPBeans’,
provide missing [["Increment CMP 1.1 EJB", ’IncCMP11’,
data or to update ’IncCMP11.jar,META-INF/ejb-jar.xml’, ’myJNDI’, ’user1’,
a task. ’password1’, ’loginName1’, ’authProps1’]]])

Mapping a
specific data
source to a CMP
bean overrides
the default data
source for the
module that
contains the
enterprise bean.
Each element of
the
DataSourceFor10CMPBeans
option consists of
the following
fields:
EJBModule, EJB,
uri, JNDI,
userName,
password,
login.config.name,
and auth.props.
Of these fields,
the following can
be assigned
values: JNDI,
userName,
password,
login.config.name,
and auth.props.

Chapter 4. Using the administrative clients 629

DataSourceFor10 The current
CMPBeans continued contents of the
option after
running default
bindings include:
v EJBModule:
Increment
CMP 1.1 EJB
v EJB:
IncCMP11
v uri:
IncCMP11.jar,META-INF/ejb-jar.xml
v JNDI:
DefaultDatasource
v userName:
null
v password: null
v
login.config.name:
DefaultPrincipalMapping
v auth.props:
v
LoginConfiguration:
Name
v Properties

If the
login.config.name
is set to
DefaultPrincipalMapping,
a property is
created with the
name
com.ibm.mapping.authDataAlias
. The value of
the property is
set by the
auth.props. If the
login.config name
is not set to
DefaultPrincipalMapping,
the auth.props
can specify
multiple
properties. The
string format is
websphere:name=
<name1>,value=<value1>,description=<desc1>.
Specify multiple
properties using
the plus sign (+)
.

630 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
DataSourceFor10 Use the taskInfo
CMPBeans continued command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
missing
information, or
require an
update.
DataSourceFor20 Specifies optional Using Jacl:
CMPBeans data sources for $AdminApp install c:/app1.ear {-DataSourceFor20CMPBeans
individual 2.x {{"Increment Enterprise Java Bean" Increment Increment.jar,
container- META-INF/ejb-jar.xml jndi1 container}}}
managed
persistence Using Jython:
(CMP) beans. AdminApp.install(’c:/app1.ear’, [’-DataSourceFor20CMPBeans’,
Use this option to [["Increment Enterprise Java Bean", ’Increment’, ’Increment.jar,
provide missing META-INF/ejb-jar.xml’, ’jndi1’, ’container’]]])
data or to update
a task.

Mapping a
specific data
source to a CMP
bean overrides
the default data
source for the
module that
contains the
enterprise bean.
Each element of
the
DataSourceFor20CMPBeans
option consists of
the following
fields:
EJBModule, EJB,
uri, JNDI,
resAuth,
login.config.name,
and auth.props.
Of these fields,
the following can
be assigned
values: JNDI,
resAuth,
login.config.name,
and auth.props.

Chapter 4. Using the administrative clients 631

DataSourceFor20 The current
CMPBeans continued contents of the
option after
running default
bindings includes
the following:
v EJBModule:
Increment
enterprise
bean
v EJB:
Increment
v uri:
Increment.jar,META-INF/ejb-jar.xml
v JNDI:
DefaultDatasource
v resAuth:
cmpBinding.perConnectionFactory
v
login.config.name:
DefaultPrincipalMapping
v auth.props:
v
LoginConfiguration:
Name
v Properties

632 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
DataSourceFor20 The last field in
CMPBeans continued each entry of this
task specifies the
value for
resource
authorization.
Valid values for
resource
authorization are
per connection
factory or
container.

If the
login.config.name
is set to
DefaultPrincipalMapping,
a property is
created with the
name
com.ibm.mapping.authDataAlias
. The value of
the property is
set by the
auth.props. If the
login.config name
is not set to
DefaultPrincipalMapping,
the auth.props
can specify
multiple
properties. The
string format is
websphere:name=
<name1>,value=<value1>,description=<desc1>.
Specify multiple
properties using
the plus sign (+)
.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data needed
for your
application. You
only need to
provide data for
rows or entries
that are missing
information, or
require an
update.

Chapter 4. Using the administrative clients 633

DataSourceFor10 Specifies the Using Jacl:
EJBModules default data $AdminApp install c:/app1.ear {-DataSourceFor10EJBModules
source for the {{"Increment CMP 1.1 EJB" IncCMP11.jar,META-INF/ejb-jar.xml
enterprise bean yourJNDI user2 password2 loginName authProps}}}
module that
contains 1.x Using Jython:
container- AdminApp.install(’c:/app1.ear’, [’-DataSourceFor10EJBModules’,
managed [["Increment CMP 1.1 EJB", ’IncCMP11.jar,META-INF/ejb-jar.xml’,
persistence ’yourJNDI’, ’user2’, ’password2’, ’loginName’, ’authProps’]]])
(CMP) beans.
Use this option to
provide missing
data or update a
task.

Each element of
the
DataSourceFor10EJBModules
option consists of
the following
fields:
EJBModule, uri,
JNDI, userName,
password,
login.config.name,
and auth.props.
Of these fields,
the following can
be assigned
values: JNDI,
userName,
password,
login.config.name,
and auth.props.

634 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
DataSourceFor10 The current
EJBModules continued contents of the
option after
running default
bindings include:
v EJBModule:
Increment
CMP 1.1
enterprise
bean
v uri:
IncCMP11.jar,META-INF/ejb-jar.xml
v JNDI:
DefaultDatasource
v userName:
null
v password: null
v
login.config.name:
DefaultPrincipalMapping
v auth.props:
v
LoginConfiguration:
Name
v Properties

If the
login.config.name
is set to
DefaultPrincipalMapping,
a property is
created with the
name
com.ibm.mapping.authDataAlias
. The value of
the property is
set by the
auth.props. If the
login.config name
is not set to
DefaultPrincipalMapping,
the auth.props
can specify
multiple
properties. The
string format is
websphere:name=
<name1>,value=<value1>,description=<desc1>.
Specify multiple
properties using
the plus sign (+)
.

Chapter 4. Using the administrative clients 635

DataSourceFor10 Use the taskInfo
EJBModules continued command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

636 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
DataSourceFor20 Specifies the Using Jacl:
EJBModules default data $AdminApp install c:/app1.ear {-DataSourceFor20EJBModules
source for the {{"Increment Enterprise Java Bean" Increment.jar,META-INF/ejb-jar.xml
enterprise bean jndi2 container}}}
2.x module that
contains 2.x Using Jython:
container AdminApp.install(’c:/app1.ear’, [’-DataSourceFor20EJBModules’,
managed [["Increment Enterprise Java Bean", ’Increment.jar,META-INF/ejb-jar.xml’,
persistence ’jndi2’, ’container’]]])
(CMP) beans.
Use this option to
provide missing
data or update a
task.

Each element of
the
DataSourceFor20EJBModules
option consists of
the following
fields:
EJBModule, uri,
JNDI, resAuth,
login.config.name,
and auth.props.
Of these fields,
the following can
be assigned
values: JNDI,
resAuth,
login.config.name,
and auth.props.

The current
contents of the
option after
running default
bindings include:
v EJBModule:
Increment
enterprise
bean
v uri:
Increment.jar,META-INF/ejb-jar.xml
v JNDI:
DefaultDatasource
v resAuth:
cmpBinding.perConnectionFactory
v
login.config.name:
DefaultPrincipalMapping
v auth.props:
v
LoginConfiguration:
Name
v Properties

Chapter 4. Using the administrative clients 637

DataSourceFor20 The last field in
EJBModules each entry of this
task specifies the
value for
resource
authorization.
Valid values for
resource
authorization are
per connection
factory or
container.

If the
login.config.name
is set to
DefaultPrincipalMapping,
a property is
created with the
name
com.ibm.mapping.authDataAlias
. The value of
the property is
set by the
auth.props. If the
login.config name
is not set to
DefaultPrincipalMapping,
the auth.props
can specify
multiple
properties. The
string format is
websphere:name=
<name1>,value=<value1>,description=<desc1>.
Specify multiple
properties using
the plus sign (+)
.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require update.

638 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
defaultbinding.cf.jndi Specifies the
Java Naming and
Directory
Interface (JNDI)
name for the
default
connection
factory.
defaultbinding.cf. Specifies the
resauth RESAUTH for
the connection
factory.
defaultbinding. Specifies the
datasource.jndi Java Naming and
Directory
Interface (JNDI)
name for the
default data
source.
defaultbinding. Specifies the
datasource.password password for the
default data
source.
defaultbinding. Specifies the
datasource.username user name for
the default data
source.
defaultbinding. Specifies the
ejbjndi.prefix prefix for the
enterprise bean
Java Naming and
Directory
Interface (JNDI)
name.
defaultbinding.force Specifies that the
default bindings
override the
current bindings.
defaultbinding.strategy.file
Specifies a
custom default
bindings strategy
file.
defaultbinding.virtual. Specifies the
host default name for
a virtual host.
depl.extension.reg Deprecated. No
replication option
is available.

Chapter 4. Using the administrative clients 639

deployejb Specifies to run
the EJBDeploy
tool during
installation. This
option does not
require a value.

If you pre-deploy
the application
Enterprise
Archive (EAR)
file using the
EJBDeploy tool
then the default
value is
nodeployejb. If
not, the default
value is
deployejb.
deployejb.classpath Specifies an
extra class path
for the
EJBDeploy tool.
deployejb.dbschema Specifies the
database
schema for the
EJBDeploy tool.
deployejb.dbtype Specifies the
database type for
the EJBDeploy
tool.

Possible values
include:
CLOUDSCAPE_V5
DB2UDB_V72
DB2UDBOS390_V6
DB2UDBISERIES
INFORMIX_V73
INFORMIX_V93
MSSQLSERVER_V7
MSSQLSERVER_2000
ORACLE_V8
ORACLE_V9I
SYBASE_V1200

For a list of
current supported
database vendor
types, run
ejbdeploy -?.
deployejb.rmic Specifies extra
RMIC options to
use for the
EJBDeploy tool.

640 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
deployws Specifies to
deploy Web
services during
installation. This
option does not
require a value.

The default value

is: nodeployws.
deployws.classpath Specifies the
extra class path
to use when you
deploy Web
services.
deployws.jardirs Specifies the
extra extension
directories to use
when you deploy
Web services.
distributeApp Specifies that the
application
management
component
distributes
application
binaries. This
option does not
require a value.

This setting is
the default.

Chapter 4. Using the administrative clients 641

EmbeddedRar Binds Java 2 Using Jacl:
Connector $AdminApp install $embeddedEar {-EmbeddedRar {{"FVT Resource Adapter"
objects to JNDI jca15cmd.rar,META-INF/ra.xml javax.sql.DataSource javax.sql.DataSource1
names. You must eis/javax.sql.javax.sql.DataSSource1} {"FVT Resource Adapter"
bind each Java 2 jca15cmd.rar,META-INF/ra.xml javax.sql.DataSource2 javax.sql.DataSource2
Connector object eis/javax.sql.DataSource2} {"FVT Resource Adapter"
in your jca15cmd.rar,META-INF/ra.xml javax.jms.MessageListener
application or javax.jms.MessageListener1 eis/javax.jms.MessageListener1}
module, such as, {"FVT Resource Adapter"
jca15cmd.rar,META-INF/ra.xml javax.jms.MessageLListener2
J2C connection
javax.jms.MessageListener2 eis/javax.jms.MessageListener2}
factories, J2C {"FVT Resource Adapter" jca15cmd.rar,META-INF/ra.xml
activation specs fvt.adapter.message.FVTMessageProvider fvt.adapter.message.
and J2C FVTMessageProvider1
administrative eis/fvt.adapter.message.FVTMessageProvider1} {"FVT Resource Adapter"
objects, to a jca15cmd.rar,META-INF/ra.xml fvt.adapter.message.FVTMessageProvider2
JNDI name. fvt.
Each element of adapter.message.FVTMessageProvider2 eis/fvt.adapter.
the message.FVTMessageProvider2}}}
EmbeddedRar
Using Jython:
option contains
the following AdminApp.install(embeddedEar, [’-EmbeddedRar’, [["FVT Resource Adapter",
fields: RARModule, ’jca15cmd.rar,META-INF/ra.xml’, ’javax.sql.DataSource’,
uri, j2cid, ’javax.sql.DataSource1’,
’eis/javax.sql.javax.sql.DataSSource1’], ["FVT Resource Adapter",
j2c.name,
’jca15cmd.rar,META-INF/ra.xml javax.sql.DataSource2’, ’javax.sql.DataSource2’,
j2c.jndiName. ’eis/javax.sql.DataSource2’], ["FVT Resource Adapter",
You can assign ’jca15cmd.rar,META-INF/ra.xml’, ’javax.jms.MessageListener’,
the following ’javax.jms.MessageListener1’, ’eis/javax.jms.MessageListener1’],
values to the ["FVT Resource Adapter", ’jca15cmd.rar,META-INF/ra.xml’,
fields: j2c.name, ’javax.jms.MessageLListener2’, ’javax.jms.MessageListener2’,
j2c.jndiName. ’eis/javax.jms.MessageListener2’], ["FVT Resource Adapter",
’jca15cmd.rar,META-INF/ra.xml fvt.adapter.message.FVTMessageProvider’,
The current ’fvt.adapter.message.FVTMessageProvider1’, ’eis/fvt.adapter.message.
contents of the FVTMessageProvider1’], ["FVT Resource Adapter", ’jca15cmd.rar,META-INF/
option after ra.xml’, ’fvt.adapter.message.FVTMessageProvider2’, ’fvt.adapter.message.
running default FVTMessageProvider2’, ’eis/fvt.adapter.message.FVTMessageProvider2’]]])
bindings include:
RARModule: <rar module name>
uri: <rar name>,META-INF/ra.xml
j2cid: <identifier of the J2C object>
j2c.name: j2cid
j2c.jndiName: eis/j2cid

Where j2cid is:

J2C connection factory :connectionFactoryInterface
J2C admin object :adminObjectInterface
J2C activation spec : message listener type

If the ID is not
unique in the
ra.xml file,
-<number> will
be added. For
example,
javax.sql.DataSource-2.

642 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
EmbeddedRar Use the taskInfo
continued command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.
EnsureMethod Selects method Using Jacl:
ProtectionFor10EJB protections for $AdminApp install c:/myapp.ear {-EnsureMethodProtectionFor10EJB
unprotected {{"Increment EJB Module"
methods of 1.x IncrementEJBBean.jar,META-INF/ejb-jar.xml ""} {"Timeout EJB Module"
enterprise beans. TimeoutEJBBean.jar,META-INF/ejb-jar.xml
Specify to leave methodProtection.denyAllPermission}}}
the method as
unprotected, or Using Jython:
assign protection AdminApp.install(’c:/myapp.ear’, ’[-EnsureMethodProtectionFor10EJB
which denies all [["Increment EJB Module"
access. Use this IncrementEJBBean.jar,META-INF/ejb-jar.xml ""] ["Timeout EJB Module"
option to provide TimeoutEJBBean.jar,META-INF/ejb-jar.xml
missing data or methodProtection.denyAllPermission]]]’)
to update a task.
The last field in each entry of this task specifies the value of the
Use the taskInfo protection. Valid protection values include:
command of the methodProtection.denyAllPermission. You can also leave the value
AdminApp object blank if you want the method to remain unprotected.
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

Chapter 4. Using the administrative clients 643

EnsureMethodProtectionSelects method Using Jacl:
For20EJB protections for $AdminApp install c:/myapp.ear {-EnsureMethodProtectionFor20EJB
unprotected {{CustomerEjbJar
methods of 2.x customerEjb.jar,META-INF/ejb-jar.xml methodProtection.uncheck}
enterprise beans. {SupplierEjbJar
Specify to assign supplierEjb.jar,META-INF/ejb-jar.xml methodProtection.exclude}}}
a security role to
the unprotected Using Jython:
method, add the AdminApp.install(’c:/myapp.ear’, ’[-EnsureMethodProtectionFor20EJB
method to the [[CustmerEjbJar
exclude list, or customerEjb.jar,META-INF/ejb-jar.xml methodProtection.uncheck]
mark the method [SupplierEjbJar
as cleared. You supplierEjb.jar,META-INF/ejb-jar.xml methodProtection.exclude]]]’)
can assign
The last field in each entry of this task specifies the value of the
multiple roles for
protection. Valid protection values include: methodProtection.uncheck,
a method by
methodProtection.exclude, or a list of security roles that are separated
separating roles
by commas.
names with
commas. Use
this option to
provide missing
data or to update
a task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update the
existing data.
installdir Deprecated. This
option is
replaced by the
installed.ear.destination
option.
installed.ear.destination Specifies the
directory to place
application
binaries.

644 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MapModulesToServers Specifies the Using Jacl:
application server $AdminApp install c:/myapp.ear {-MapModulesToServers
where you want {{"Increment Bean Jar"
to install modules Increment.jar,META-INF/ejb-jar.xml WebSphere:cell=mycell,
that are node=mynode,server=server1}
contained in your {"Default Application" default_app.war,WEB-INF/web.xml WebSphere:
application. You cell=mycell,node=mynode,server=server1}
can install {"Examples Application" examples.war,WEB-INF/web.xml WebSphere:
modules on the cell=mycell,node=mynode,server=server1}}}
same server, or
Using Jython:
disperse them
among several AdminApp.install(’c:/myapp.ear’, ’[-MapModulesToServers
servers. Use this [["Increment Bean Jar"
Increment.jar,META-INF/ejb-jar.xml WebSphere:cell=mycell,
option to provide
node=mynode,server=server1]
missing data or ["Default Application" default_app.war,WEB-INF/web.xml
to update to a WebSphere:cell=mycell,node=mynode,server=server1]
task. ["Examples Application" examples.war,WEB-INF/web.xml WebSphere:
cell=mycell,node=mynode,server=server1]]]’)
Use the taskInfo
command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

Chapter 4. Using the administrative clients 645

MapEJBRefToEJB Maps enterprise Using Jacl:
Java references $AdminApp install c:/myapp.ear {-MapEJBRefToEJB
to enterprise {{"Examples Application" ""
beans. You must examples.war,WEB-INF/web.xml BeenThereBean com.ibm.websphere.
map each beenthere.BeenThere IncBean}}}
enterprise bean
reference defined Using Jython:
in your AdminApp.install(’c:/myapp.ear’, ’[-MapEJBRefToEJB
application to an [["Examples Application" ""
enterprise bean. examples.war,WEB-INF/web.xml BeenThereBean com.ibm.websphere.
Use this option to beenthere.BeenThere IncBean]]]’)
provide missing
data or update to
a task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data needed
for your
application. You
only need to
provide data for
rows or entries
that are missing
information, or
those where you
want to update
the existing data.

646 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MapMessage Maps message Using Jacl:
DestinationRefToEJB destination $AdminApp install $earfile {-MapMessageDestinationRefToEJB
references to {{ejb-jar-ic.jar Publisher ejb-jar-ic.jar,META-INF/ejb-jar.xml
Java Naming and MyConnection jndi2}
Directory {ejb-jar-ic.jar Publisher ejb-jar-ic.jar,META-INF/ejb-jar.xml
Interface (JNDI) PhysicalTopic jndi3}
names of {ejb-jar-ic.jar Publisher ejb-jar-ic.jar,META-INF/ejb-jar.xml
administrative jms/ABC jndi4}}}
objects from the
Using Jython:
installed resource
adapters. You AdminApp.install(ear1, [’-MapMessageDestinationRefToEJB’,
must map each [[’ejb-jar-ic.jar’, ’Publisher’, ’ejb-jar-ic.jar,META-INF/
message ejb-jar.xml’, ’MyConnection’, ’jndi2’],
[’ejb-jar-ic.jar’, ’Publisher’, ’ejb-jar-ic.jar,META-INF/
destination
ejb-jar.xml’, ’PhysicalTopic’, ’jndi3’],
reference that is [’ejb-jar-ic.jar’, ’Publisher’, ’ejb-jar-ic.jar,META-INF/
defined in your ejb-jar.xml’, ’jms/ABC’, ’jndi4’]]])
application to an
administrative
object. Use this
option to provide
missing data or
to update a task.

The current
contents of the
option after
running default
bindings include:
v EJB Module:
ejb-jar-ic.jar
v EJB:
MessageBean
v URI:
ejb-jar-
ic.jar,META-
INF/ejb-jar.xml
v JNDI Name:
[eis/J2CACT1]:
v Destination
JNDI Name:
[jms/TopicName]:
v The default
JNDI name
will be picked
up from the
corresponding
message
destination
reference.

Chapter 4. Using the administrative clients 647

MapMessage Use the taskInfo
DestinationRefToEJB command of the
continued AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.
MapResEnvRefToRes Maps resource Using Jacl:
environment $AdminApp install c:/myapp.ear {-MapResEnvRefToRes
references to {{AsyncSender AsyncSender
resources. You asyncSenderEjb.jar,META-INF/ejb-jar.xml jms/ASYNC_SENDER_QUEUE
must map each javax.jms.Queue jms/Resource2}}}
resource
environment Using Jython:
reference that is AdminApp.install(’c:/myapp.ear’, ’[-MapResEnvRefToRes
defined in your [[AsyncSender AsyncSender
application to a asyncSenderEjb.jar,META-INF/ejb-jar.xml jms/ASYNC_SENDER_QUEUE
resource. Use javax.jms.Queue jms/Resource2]]]’)
this option to
provide missing
data or to update
a task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

648 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MapResRefToEJB Maps resource Using Jacl:
references to $AdminApp install c:/app1.ear {-MapResRefToEJB {{deplmtest.jar
resources. You MailEJBObject deplmtest.jar,META-INF/ejb-jar.xml mail/MailSession9
must map each javax.mail.Session jndi1 login1 authProps1} {"JavaMail Sample WebApp" ""
resource mtcomps.war,WEB-INF/web.xml mail/MailSession9 javax.mail.
reference that is Session jndi2 login2 authProps2}}}
defined in your
application to a Using Jython:
resource. Use AdminApp.install(’c:/app1.ear’, [’-MapResRefToEJB’, [[’deplmtest.jar’,
this option to ’MailEJBObject’, ’deplmtest.jar,META-INF/ejb-jar.xml mail/MailSession9’,
provide missing ’javax.mail.Session’, ’jndi1’, ’login1’, ’authProps1’],
data or to update ["JavaMail Sample WebApp", "",
a task. ’mtcomps.war,WEB-INF/web.xml’, ’mail/MailSession9’, ’javax.mail.
Session’, ’jndi2’, ’login2’, ’authProps2’]]])
Each element of
the
MapResRefToEJB
option consists of
the following
fields: module,
EJB, uri,
referenceBinding,
resRef.type,
JNDI,
login.config.name,
and auth.props.
Of these fields,
the following can
be assigned
values: JNDI,
login.config.name,
auth.props. The
JNDI field is
required.

The current
contents of the
option after
running default
bindings include:
v Module:
deplmtest.jar
v EJB:
MailEJBObject
v uri:
deplmtest.jar,META-INF/ejb-jar.xml
v
referenceBinding:
mail/MailSession9
v resRef.type:
javax.mail.Session
v JNDI:
mail/DefaultMailSession
v
login.config.name:
DefaultPrincipalMapping
v auth.props:

Chapter 4. Using the administrative clients 649

MapResRefToEJB If the
continued login.config.name
is set to
DefaultPrincipalMapping,
a property is
created with the
name
com.ibm.mapping.authDataAlias
. The value of
the property is
set by the
auth.props. If the
login.config name
is not set to
DefaultPrincipalMapping,
the auth.props
can specify
multiple
properties. The
string format is
websphere:name=
<name1>,value=<value1>,description=<desc1>.
Specify multiple
properties using
the plus sign (+)
.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

650 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MapRolesToUsers Maps users to Using Jacl:
roles. You must $AdminApp install c:/myapp.ear {-MapRolesToUsers {{"All Role" No Yes "" ""}
map each role {"Every Role" Yes No "" ""} {DenyAllRole No No user1 group1}}}
that is defined in
the application or Using Jython:
module to a user AdminApp.install(’c:/myapp.ear’, ’[-MapRolesToUsers [["All Role" No Yes "" ""]
or group from the ["Every Role" Yes No "" ""] [DenyAllRole No No user1 group1]]]’)
domain user
registry. You can where {{″All Role″ No Yes ″″ ″″} corresponds to the following:
specify multiple ″All Role″
users or groups Represents the role name
for a single role No Indicates to allow access to everyone (yes/no)
by separating Yes Indicates to allow access to all authenticated users (yes/no)
them with a pipe ″″ Indicates the mapped users
(|). Use this ″″ Indicates the mapped groups
option to provide
missing data or
to update a task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

Chapter 4. Using the administrative clients 651

MapRunAsRolesToUsersMaps RunAs Using Jacl:
Roles to users. $AdminApp install c:/myapp.ear {-MapRunAsRolesToUsers
The enterprise {{UserRole user1 password1}
beans you that {AdminRole administrator administrator}}}
install contain
predefined Using Jython:
RunAs roles. AdminApp.install(’c:/myapp.ear’, ’[-MapRunAsRolesToUsers
Enterprise beans [[UserRole user1 password1]
that need to run [AdminRole administrator administrator]]]’)
as a particular
role for
recognition while
interacting with
another
enterprise bean
use RunAs roles.
Use this option to
provide missing
data or to update
a task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.

652 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MapWebModToVH Selects virtual Using Jacl:
hosts for Web $AdminApp install c:/myapp.ear {-MapWebModToVH {{"Default Application"
modules. Specify default_app.war,WEB-INF/web.xml default_host} {"Examples Application"
the virtual host examples.war,WEB-INF/web.xml default_host}}}
where you want
to install the Web Using Jython:
modules that are AdminApp.install(’c:/myapp.ear’, ’[-MapWebModToVH [["Default Application"
contained in your default_app.war,WEB-INF/web.xml default_host] ["Examples Application"
application. You examples.war,WEB-INF/web.xml default_host]]]’)
can install Web
modules on the
same virtual
host, or disperse
them among
several hosts.
Use this option to
provide missing
data or to update
a task.

Use the taskInfo

command of the
AdminApp object
to obtain
information about
the data that is
needed for your
application. You
need to provide
data for rows or
entries that are
either missing
information, or
require an
update.
noallowPermInFilterPolicy
Specifies not to
continue with the
application
deployment
process when
the application
contains policy
permissions that
are in the filter
policy. This
option is the
default setting
and it does not
require a value.

Chapter 4. Using the administrative clients 653

node Specifies the
node name to
install or update
an entire
application or to
update an
application in
order to add a
new module. If
you want to
update an entire
application, this
option only
applies if the
application
contains a new
module that does
not exist in the
installed
application.
nocreateMBeansFor Specifies that
Resources MBeans are not
created for all
resources such
as, servlets,
JSPs, and
enterprise beans,
that are defined
in an application
when the
application starts
on a deployment
target. This
option is the
default setting
and it does not
require a value.
nodeployejb Specifies not to
run the
EJBDeploy tool
during
installation. This
option is the
default setting
and it does not
require a value.
nodeployws Specifies not to
deploy Web
services during
installation. This
option is the
default setting
and it does not
require a value.

654 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
nodistributeApp Specifies that the
application
management
component does
not distribute
application
binaries. This
option does not
require a value.
The default
setting is the
distributeApp
option.
noreloadEnabled Disables class
reloading. This
option does not
require a value.
The default
setting is the
reloadEnabled
option.
nopreCompileJSPs Specifies not to
precompile
JavaServer
Pages files. This
option is the
default setting
and it does not
require a value.
noprocessEmbeddedConfig
Use this option to
ignore the
embedded
configuration
data that is
include in the
application. This
option does not
required a value.

If the application
Enterprise
Archive (EAR)
file does not
contain
embedded
configuration
data, the
noprocessEmbeddedConfig
option is the
default setting.
Otherwise, the
default setting is
the
processEmbeddedConfig
option.

Chapter 4. Using the administrative clients 655

nouseMetaDataFrom Specifies that the
Binary metadata that is
used at run time,
for example,
deployment
descriptors,
bindings,
extensions, and
so on, come from
the configuration
repository. This
option is the
default setting
and it does not
require a value.
Use this option to
indicate that the
metadata that is
used at run time
comes from the
enterprise
archive file (EAR)
file.
nousedefaultbindings Specifies not to
use default
bindings for
installation. This
option is the
default setting
and it does not
require a value.

656 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
operation Specifies the The following examples show how to use the options for the update
operation that command to update a single file in a deployed application:
you want to
perform. This Using Jacl:
option only $AdminApp update app1 file {-operation update -contents
applies to the c:/apps/app1/my.xml -contenturi app1.jar/my.xml}
update
command. The Using Jython string:
valid values AdminApp.update(’app1’, ’file’, ’[-operation update -contents
include: c:/apps/app1/my.xml -contenturi app1.jar/my.xml]’)
v add - Adds
Using Jython list:
new content.
AdminApp.update(’app1’, ’file’, [’-operation’, ’update’,
v addupdate -
’-contents’, ’c:/apps/app1/my.xml’, ’-contenturi’, app1.jar/my.xml’])
Adds or
updates where AdminApp is the scripting object, update is the command, app1 is
content based the name of the application you want to update, file is the content type,
on the operation is an option of the update command, update is the value of
existence of the operationoption, contents is an option of the update command,
content in the /apps/app1/my.xml is the value of the contents option, contenturi is an
application. option of the update command, app1.jar/my.xml is the value of the
v delete - contenturi option.
Deletes
content.
v update -
Updates
existing
content.

The operation
option is required
if the content
type is file or
modulefile. If the
value of the
content type is
app, the value of
the operation
option must be
update.

Chapter 4. Using the administrative clients 657

processEmbedded Use this option to
Config process the
embedded
configuration
data that is
included in the
application. This
option does not
required a value.

If the application
Enterprise
Archive (EAR)
file contains
embedded
configuration
data, this option
is the default
setting. If not, the
default setting is
the
nonprocessEmbeddedConfig
option.
preCompileJSPs Specifies to
precompile the
JavaServer
Pages files. This
option does not
require a value.
The default is
nopreCompileJSPs.
reloadEnabled Specifies that the
file system of the
application will
be scanned for
updated files so
that changes
reload
dynamically. This
option is the
default setting
and it does not
require a value.
reloadInterval Specifies the
time period in
seconds that the
file system of the
application will
be scanned for
updated files.
Valid range is
greater than
zero. The default
is three seconds.

658 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
server Specifies the
server name to
install or update
an entire
application or to
update an
application in
order to add a
new module. If
you want to
update an
application, this
option only
applies if the
application
contains a new
module that does
not exist in the
installed
application.

Chapter 4. Using the administrative clients 659

update Updates the
installed
application with a
new version of
the enterprise
archive file (EAR)
file. This option
does not require
a value.

The application
that is being
updated, which is
specified by the
appname option,
must already be
installed in the
WebSphere
Application
Server
configuration.
The update
action merges
bindings from the
new version with
the bindings from
the old version,
uninstalls the old
version, and
installs the new
version. The
binding
information from
new version of
the EAR file is
preferred over
the
corresponding
one from the old
version. If any
element of
binding is
missing in the
new version, the
corresponding
element from the
old version is
used.

660 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
update.ignore.new Specifies that
during the update
action, bindings
from the new
version of the
application are
ignored. This
option does not
require a value.

This option
applies only if
you specify one
of the following
items:
v The update
option for the
install
command.
v The modulefile
or app as the
content type
for the update
command.
update.ignore.old Specifies that
during the update
action, the
bindings from the
installed version
of the application
are ignored. This
option does not
require a value.

This option
applies only if
you specify one
of the following
items:
v The update
option for the
install
command.
v The modulefile
or app as the
content type
for the update
command.

Chapter 4. Using the administrative clients 661

useMetaDataFromBinarySpecifies that the
metadata that is
used at run time,
for example,
deployment
descriptors,
bindings,
extensions, and
so on, come from
the EAR file. This
option does not
require a value.

The default value

is
nouseMetaDataFromBinary,
which means that
the metadata that
is used at run
time comes from
the configuration
repository.
usedefaultbindings Specifies to use
default bindings
for installation.
This option does
not require a
value.

The default
setting is
nousedefaultbindings.

662 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
validateinstall Specifies the
level of
application
installation
validation.

Valid option
values include:
v off - Specifies
no application
deployment
validation. This
value is the
default.
v warn -
Performs
application
deployment
validation and
continues with
the application
deployment
process even
when reported
warnings or
error
messages
exist.
v fail - Performs
application
deployment
validation and
does not to
continue with
the application
deployment
process when
reported
warnings or
error
messages
exist.
verbose Causes
additional
messages to
display during
installation. This
option does not
require a value.

Chapter 4. Using the administrative clients 663

WebServicesClientBind The immutable Using Jacl:
DeployedWSDL values for this $AdminApp install WebServicesSamples.ear
option identify {-WebServicesClientBindDeployedWSDL
the client Web {{AddressBookW2JE.jar AddressBookW2JE service/WSLoggerService2
service that you META-INF/wsdl/DeployedWsdl1.wsdl}}}
are modifying.
The scoping Using Jython:
fields include: AdminApp.install(’WebServicesSamples.ear’,
Module, EJB, ’[-WebServicesClientBindDeployedWSDL
and Web service. [[AddressBookW2JE.jar AddressBookW2JE service/WSLoggerService2
The single META-INF/wsdl/DeployedWsdl1.wsdl]]]’)
mutable value for
this task is the
deployed WSDL
file name. It
indicates the
Web Services
Description
Language
(WSDL) the
client uses.

The Module field

identifies the
enterprise or
Web application
within the
application. If the
module is an
enterprise bean ,
the EJB field
identifies a
particular
enterprise bean
within the
module. The
Web service field
identifies the
Web service
within the
enterprise bean
or the Web
application
module. This
identifier
corresponds to
the wsdl:service
attribute in the
WSDL file,
prepended with
service/, for
example,
service/WSLoggerService2.

664 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebServicesClientBind The deployed
DeployedWSDL WSDL attribute
continued names a WSDL
file relative to the
client module. An
example of a
deployed WSDL
for a Web
application is the
following:
WEB-
INF/wsdl/WSLoggerService.
WebServicesClientBind The immutable Using Jacl:
PortInfo values identify $AdminApp install WebServicesSamples.ear
the port of a {-WebServicesClientBindPortInfo
client Web {{AddressBookW2JE.jar AddressBookW2JE
service that you service/WSLoggerService2 WSLoggerJMS 3000 newHTTP_ID newHTTP_pwd
are modifying. sslAliasConfig http://yunus:9090/WSLoggerEJB/services/WSLoggerJMS}}}
The scoping
fields include: Using Jython:
Module, EJB, AdminApp.install(’WebServicesSamples.ear’,
Web service and ’[-WebServicesClientBindPortInfo
Port. The [[AddressBookW2JE.jar AddressBookW2JE
mutable values service/WSLoggerService2 WSLoggerJMS 3000 newHTTP_ID newHTTP_pwd
for this task sslAliasConfig http://yunus:9090/WSLoggerEJB/services/WSLoggerJMS]]]’)
include: Sync
Timeout,
BasicAuth ID,
BasicAuth
Password, SSL
Config, and
Overridden
Endpoint URI.
The basic
authentication
and Secure
Sockets Layer
(SSL) fields
affect transport
level security, not
Web services
security.

Chapter 4. Using the administrative clients 665

WebServicesClientBind Associates a Using Jacl:
PreferredPort preferred port $AdminApp install WebServicesSamples.ear
(implementation) {-WebServicesClientBindPreferredPort
with a port type {{AddressBookW2JE.jar AddressBookW2JE service/WSLoggerService2
(interface) for a WSLoggerJMS WSLoggerJMSPort}}}
client Web
service. The Using Jython:
immutable values AdminApp.install(’WebServicesSamples.ear’,
identify a port ’[-WebServicesClientBindPreferredPort
type of the client [[AddressBookW2JE.jar AddressBookW2JE service/WSLoggerService2
Web service that WSLoggerJMS WSLoggerJMSPort]]]’)
you are
modifying. The
scoping fields
include: Module,
EJB, Web
service and Port
Type. The
mutable value for
this task is Port.
v Port Type -
QName
(″{namespace}
localname″) of
a port type
that is defined
by a
wsdl:portType
attribute in the
WSDL file that
identifies an
interface.
v Port - QName
of a port
defined by a
wsdl:port
attribute within
a wsdl:service
attribute in a
WSDL file that
identifies an
implementation
that has
preference.

666 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebServicesServerBind Sets two Using Jacl:
Port attributes of a $AdminApp install WebServicesSamples.ear {-WebServicesServerBindPort
Web service port. {{AddressBookW2JE.jar service/WSLoggerService2 WSLoggerJMS {} Session}}}
The immutable
values identify Using Jython:
the port of a Web AdminApp.install(’WebServicesSamples.ear’, ’[-WebServicesServerBindPort
service that you [[AddressBookW2JE.jar service/WSLoggerService2 WSLoggerJMS "" Session]]]’)
are modifying.
The scope fields
include: Module,
Web service and
Port. The
mutable values
include: WSDL
Service Name,
and Scope.

The scope
determines the
life cycle of
implementing the
Java bean. The
valid values
include: Request
(new instance for
each request),
Application (one
instance for each
web-app), and
Session (new
instance for each
HTTP session).

The scope
attribute does not
apply to Web
services that a
Java Message
Service (JMS)
transport. The
scope attribute
does not apply to
enterprise beans.

The WSDL
service name
identifies a
service when
more than one
service has the
same port name.
The WSDL
service name is
represented as a
QName string,
for example,
{namespace}localname
.

Chapter 4. Using the administrative clients 667

WebServicesClient Supports the Using Jacl:
CustomProperty configuration of $AdminApp edit WebServicesSamples {-WebServicesServerCustomProperty
the name value {{AddressBookW2JE.jar AddressBookService AddressBook http.proxyHost
parameter for the +http.proxyPort myhost+80}}}
description of the
client bind file of Using Jython:
a Web service. AdminApp.edit ( ’WebServicesSamples’, ’[ -WebServicesServerCustomProperty
The immutable [[AddressBookW2JE.jar AddressBookService AddressBook
values identify http.proxyHost+http.proxyPort myhost+80]]]’)
the port of the
Web service that
you are
modifying. The
scope fields
include: Module,
Web service, and
Port. The
mutable values
include: name and
value.

The format of the

name and value
values include a
string that
represents
multiple name
and value pairs
by using the +
character as a
separator. For
example, name
string =
″n1+n2+n3″
value string =
″v1+v2+v3″
yields
name/value
pairs: {{″n1″
″v1″}, {″n2″
″v2″}, {″n3″ ″
v3″}}

668 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebServicesServer Supports the Using Jacl:
CustomProperty configuration of $AdminApp edit WebServicesSamples {-WebServicesServerCustomProperty
the name value {{AddressBookW2JE.jar AddressBookService AddressBook
parameter for the com.ibm.websphere.webservices.http.responseContentEncoding deflate}}}
description of the
server bind file of Using Jython:
a Web service. AdminApp.edit ( ’WebServicesSamples’, ’[ -WebServicesServerCustomProperty
The scoping [[AddressBookW2JE.jar AddressBookService AddressBook
fields include the com.ibm.websphere.webservices.http.responseContentEncoding deflate]]]’)
following:
Module, EJB,
and Web service.
The mutable
values for this
task include:
name and value.

The format of the

these values
include a string
that represents
multiple name
and value pairs
by using the plus
(+) character as
a separator. For
example, name
string =
″n1+n2+n3″
value string =
″v1+v2+v3″
yields
name/value
pairs: {{″n1″
″v1″}, {″n2″
″v2″}, {″n3″ ″
v3″}}

Usage table for the options of the AdminApp object install, installInteractive, update, updateInteractive,
edit, and editInteractive commands:

The following table lists all of the options available for the install, installInteractive, update,
updateInteractive, edit, and editInteractive commands of the AdminApp object. The table indicates the
applicable commands for each option.

Option name install and update and update and update edit and edit and
install update update and edit edit
update
Interactive Interactive Interactive Interactive Interactive
commands commands commands - Interactive commands commands
- install an - Update an Add a commands - Edit an - Edit a
application application module - Update a application module
module
ActSpecJNDI Yes Yes Yes Yes Yes Yes
allowPermInFilterPolicy Yes Yes
appname Yes Yes
BackendIdSelection Yes Yes Yes Yes

Chapter 4. Using the administrative clients 669

BindJndiForEJBMessagingBinding Yes Yes Yes Yes Yes Yes
BindJndiForEJBNonMessageBinding Yes Yes Yes Yes Yes Yes
cell Yes Yes Yes
cluster Yes Yes Yes
contents Yes Yes Yes
contenturi Yes Yes Yes
contextroot Yes Yes Yes
CorrectOracleIsolationLevel Yes Yes Yes Yes Yes Yes
CorrectUseSystemIdentity Yes Yes Yes Yes Yes Yes
createMBeansForResources Yes Yes Yes
custom Yes Yes Yes Yes Yes Yes
DataSourceFor10CMPBeans Yes Yes Yes Yes Yes Yes
DataSourceFor20CMPBeans Yes Yes Yes Yes Yes Yes
DataSourceFor10EJBModules Yes Yes Yes Yes Yes Yes
DataSourceFor20EJBModules Yes Yes Yes Yes Yes Yes
defaultbinding.datasource.jndi Yes Yes Yes Yes
defaultbinding.cf.jndi Yes Yes Yes Yes
defaultbinding.cf.resauth Yes Yes Yes Yes
defaultbinding.datasource.password Yes Yes Yes Yes
defaultbinding.datasource.username Yes Yes Yes Yes
defaultbinding.ejbjndi.prefix Yes Yes Yes Yes
defaultbinding.force Yes Yes Yes Yes
defaultbinding.strategy.file Yes Yes Yes Yes
defaultbinding.virtual.host Yes Yes Yes Yes
depl.extension.reg (deprecated)
deployejb Yes Yes Yes Yes
deployejb.classpath Yes Yes Yes Yes
deployejb.dbschema Yes Yes Yes Yes
deployejb.dbtype Yes Yes Yes Yes
deployejb.rmic Yes Yes Yes Yes
deployws Yes Yes Yes Yes
deployws.classpath Yes Yes Yes Yes
deployws.jardirs Yes Yes Yes Yes
distributeApp Yes Yes Yes
EmbeddedRar Yes Yes Yes Yes Yes Yes
EnsureMethodProtectionFor10EJB Yes Yes Yes Yes
EnsureMethodProtentionFor20EJB Yes Yes Yes Yes
installdir (deprecated)
installed.ear.destination Yes Yes Yes
MapMessageDestinationRefToEJB Yes Yes Yes Yes Yes Yes
MapModulesToServers Yes Yes Yes Yes Yes Yes
MapEJBRefToEJB Yes Yes Yes Yes Yes Yes

670 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MapResEnvRefToRes Yes Yes Yes Yes Yes Yes
MapResRefToEJB Yes Yes Yes Yes Yes Yes
MapRolesToUsers Yes Yes Yes Yes
MapRunAsRolesToUsers Yes Yes Yes Yes Yes Yes
MapWebModToVH Yes Yes Yes Yes Yes Yes
noallowPermInFilterPolicy Yes Yes
nocreateMBeansForResources Yes Yes Yes
node Yes Yes Yes
nodeployejb Yes Yes Yes Yes
nodeployws Yes Yes Yes Yes
nodistributeApp Yes Yes Yes
nopreCompileJSPs Yes Yes Yes Yes
noprocessEmbeddedConfig Yes Yes
noreloadEnabled Yes Yes Yes
nousedefaultbindings Yes Yes Yes Yes
nouseMetaDataFromBinary Yes Yes Yes
operation Yes Yes Yes
preCompileJSPs Yes Yes Yes Yes
processEmbeddedConfig Yes Yes
reloadEnabled Yes Yes Yes
reloadInterval Yes Yes Yes
server Yes Yes Yes
update Yes Yes
update.ignore.old Yes Yes Yes
update.ignore.new Yes Yes Yes
useMetaDataFromBinary Yes Yes Yes
usedefaultbindings Yes Yes Yes Yes
validateinstall Yes Yes
verbose Yes Yes Yes Yes Yes Yes
WebServicesClientBindingDeployedWSDL
Yes Yes Yes Yes Yes Yes
WebServicesClientBindPortInfo Yes Yes Yes Yes Yes Yes
WebServicesClientBindPreferredPort Yes Yes Yes Yes Yes Yes
WebServicesClientCustomProperty Yes Yes Yes Yes Yes Yes
WebServicesServerBindPort Yes Yes Yes Yes Yes Yes
WebServicesServerCustomProperty Yes Yes Yes Yes Yes Yes

Example: Obtaining option information for AdminApp object commands: Use the taskInfo
command of the AdminApp object to obtain information about the data that is needed for your application.
You need to provide data for rows or entries that are either missing information, or require an update.
v You can use the options command to see the requirements for an enterprise archive file (EAR) file if
you construct installation command lines. The taskInfo command provides detailed information for each
task option with a default binding applied to the result.
v The options for the AdminApp install command can be complex if you specify various types of binding
information, for example, Java Naming and Directory Interface (JNDI) name, data sources for enterprise
Chapter 4. Using the administrative clients 671
 bean modules, or virtual hosts for Web modules. An easy way to specify command-line installation
options is to use a feature of the installInteractive command that generates the options for you. After
you install the application interactively once and specify all the updates that you need, look for message
WASX7278I in the wsadmin output log. The default output log for wsadmin is wsadmin.traceout. You
can cut and paste the data in this message into a script, and modify it. For example:
WASX7278I: Generated command line: install c:/websphere/appserver/installableapps/jmsample.ear
{-BindJndiForEJBNonMessageBinding {{deplmtest.jar MailEJBObject deplmtest.jar,META-INF/ejb-jar.xml ejb/JMSampEJB1 }}
-MapResRefToEJB {{deplmtest.jar MailEJBObject deplmtest.jar,META-INF/ejb-jar.xml mail/MailSession9
javax.mail.Session mail/DefaultMailSessionX } {"JavaMail Sample WebApp" mtcomps.war,WEB-INF/web.xml
mail/MailSession9 javax.mail.Session mail/DefaultMailSessionY }} -MapWebModToVH {{"JavaMail Sample WebApp"
mtcomps.war,WEB-INF/web.xml newhost }} -nopreCompileJSPs -novalidateApp -installed.ear.destination
c:/mylocation -distributeApp -nouseMetaDataFromBinary}

Commands for the AdminTask object

Use AdminTask object to run an administrative command. Administrative commands are discovered
dynamically when you start the wsadmin tool. The administrative commands that are available for your
use, and what you can do with them, depends on the edition of the WebSphere Application Server that
you have.

You can start the scripting client without a server running by using the -conntype NONE option with the
wsadmin tool. The AdminTask administrative commands are available in both connected and local modes.
If a server is currently running, it is not recommended to run the AdminTask commands in local mode. This
is because any configuration changes made in local mode will not be reflected in the running server
configuration and vice versa. If you save a conflicting configuration, you could corrupt the configuration. In
a deployment manager environment, configuration updates are available only if a scripting client is
connected to a deployment manager. When connected to a node agent or a managed application server,
you will not be able to update the configuration because the configuration for these server processes are
copies of the master configuration which resides in the deployment manager. The copies are created on a
node machine when a configuration synchronization occurs between the deployment manager and the
node agent. Make configuration changes to the server processes by connecting a scripting client to a
deployment manager. For this reason, to change a configuration, do not run a scripting client in local mode
on a node machine. It is not a supported configuration.

The following commands are available for the AdminTask object:

Command Group Description: Target Parameters and return Examples:

name: name: object: values:

672 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
addNode Node The The target v Parameters: Batch mode example usage:
Group Group addNode object is the v Using Jacl:
Member Commands Group node group - nodeName
The name of the $AdminTask addNodeGroupMember
group Member where the
node to be WBINodeGroup {
command member will -nodeName WBINode}
adds a be created. added to a node
member to This target group. This v Using Jython:
a node object is parameter is AdminTask.addNodeGroupMember(
group. required. required. ’WBINodeGroup’,
Nodes may v Returns: Node group ’[-nodeName WBINode]’)
be members member object ID
Interactive mode example usage:
of more
than one v Using Jacl:
node group. $AdminTask addNodeGroupMember {
The -interactive}
command v Using Jython:
will do
AdminTask.addNodeGroupMember (
validity
’[-interactive]’)
checking to
ensure the
following:
v
Distributed
and z/OS
nodes are
not
combined
in the
same node
group.

Chapter 4. Using the administrative clients 673

add SIBWS SIB The add The object v Parameters: Batch mode example usage:
Inbound WebServicesSIBWS name of the v Using Jacl:
Port group Inbound inbound name
The name of the set inPort [
Port service to
port. (required) $AdminTask addSIBWSInboundPort
command which the $inService {
adds the port will be endpointListener -name "MyServiceSoap"
configuration added. The name of the -endpointListener "SOAPHTTP1"
for an associated end -node "MyNode"
inbound port point listener. -server "server1"}]
to an (required) v Using Jython:
inbound
node inPort =
service. This
AdminTask.addSIBWSInboundPort(
command The node where
inService, ’[
will fail if: the endpoint -name MyServiceSoap
v the port listener is -endpointListener SOAPHTTP1
name is located. You -node MyNode
already in must specify the -server server1]’)
use by node parameter,
the server Interactive mode example usage:
another
inbound parameter, or the v Using Jacl:
port for cluster
$AdminTask addSIBWSInboundPort {
the parameter. -interactive}
inbound (conditional)
v Using Jython:
service or server AdminTask.addSIBWSInboundPort (
the end The server ’[-interactive]’)
point where the
listener endpoint listener
that you is located. You
specified. must specify the
v the node parameter,
template the server
port that parameter, or the
you cluster
specified parameter.
does not (conditional)
exist in
cluster
the
The cluster
template
where the
WSDL of
endpoint listener
the
is located. You
inbound
must specify the
service.
node parameter,
the server
parameter, or the
cluster
parameter.
(conditional)
templatePort
The name of the
port in the
template WSDL
to use as a basis
for the binding of
the port.
(optional)
v Returns: The object
name of the inbound
port object that was
created.

674 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
add SIBWS SIB The add The object v Parameters: Batch mode example usage:
Outbound WebServicesSIBWS name of the v Using Jacl:
Port group Outbound outbound name
The name of the set outPort [
Port service for
port in the WSDL $AdminTask
command which the addSIBWSOutboundPort
adds the port will be of the service
$outService {
configuration associated. provider. -name "MyServiceSoap"
for an (required) -node "MyNode"
outbound node -server "server"}]
port to an Node where the v Using Jython:
outbound port destination outPort =
service. will be localized. AdminTask
You must specify .addSIBWSOutboundPort(
the node outService, ’[
parameter, the -name MyServiceSoap
server -node MyNode
parameter, or the -server server]’)
cluster
Interactive mode example usage:
parameter.
(conditional) v Using Jacl:
$AdminTask
server addSIBWSOutboundPort {
The server -interactive}
where the port
v Using Jython:
destination will
be localized. You AdminTask
must specify the .addSIBWSOutboundPort (
node parameter, ’[-interactive]’)
the server
parameter, or the
cluster
parameter.
(conditional)
cluster
The cluster
where the port
destination will
be localized. You
must specify the
node parameter,
the server
parameter, or the
cluster
parameter.
(conditional)
destination
The name of the
port destination.
(optional)
userId
The user ID to
use to retrieve
the WSDL.
(optional)
password
The password to
use to retrieve
the WSDL.
(optional)
v Returns: The object
name of the Chapter 4. Using the administrative clients 675
outbound port object
that you created.
add SIBus SIB Admin Use this None v Parameters: Batch mode example usage:
Member Commands command to v Using Jacl:
group add a server bus
name of bus to $AdminTask addSIBusMember {
or a cluster
add member to -bus busname
to a SIB -node nodename
bus. (String, required)
-server servername
node -description text}
to specify a v Using Jython:
server bus AdminTask.addSIBusMember(’[
member, supply -bus busname
node and server -node nodename
name, but not -server servername
cluster name -description "text"]’)
(String, optional)
Interactive mode example usage:
server
v Using Jacl:
to specify a
server bus $AdminTask addSIBusMember {
member, supply -interactive}
node and server v Using Jython:
name, but not AdminTask.addSIBusMember (’[
cluster name -interactive]’)
(String, optional)
cluster
to specify a
cluster bus
member, supply
cluster name but
not node and
server name
(String, optional)
createDefault
Datasource
set this to true if
a default data
source should be
created when the
messaging
engine is
created.
(Boolean,
optional)
datasource
JndiName
the JNDI name
of the data
source to be
referenced from
the datastore
created when the
member is added
to the bus
(String, optional)
v Returns:

676 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
addWSGWTargetService
WSGatewayThe add Object v Parameters: Batch mode example usage:
group WSGW name of the v Using Jacl:
Target Gateway name
The set gwTarget [
Service Service
administrative $AdminTask
command object addWSGWTargetService
adds a name of the
$gwService {
target to a target service. -name "AnotherTarget"
gateway (Required) -targetService
service. You target Destination "AnotherService"}]
must specify The name of the v Using Jython:
the target target gwTarget=
Service destination. This AdminTask.
parameter can be within the addWSGWTargetService(
or the target same bus as the gwService, ’[
Destination gateway -name AnotherTarget
parameter. destination or in -targetService
a different bus. If AnotherService]’)
the target
Interactive mode example usage:
destination is not
within the same v Using Jacl:
bus as the $AdminTask
gateway addWSGWTargetService {
destination, you -interactive}
must also specify v Using Jython:
the targetBus AdminTask
parameter. You .addWSGWTargetService
must either (’[ -interactive]’)
specify the target
Destination
parameter or the
target Service
parameter.
(Conditional)
target Service
The name of the
target outbound
service. You
must either
specify the target
Destination
parameter or the
target Service
parameter.
(Conditional)
targetBus
The name of the
WPM bus that
contains the
target. (Optional)
v Returns: The object
name of the target
service object that
you created.

Chapter 4. Using the administrative clients 677

compareNodeManagedObject
The None v Parameters: Batch mode example usage:
Version Metadata compare v Using Jacl:
group Node - nodeName
The name of the $AdminTask
Version
node associated compareNodeVersion {
command -nodeName node1
compares with the
-version 5}
the metadata you
want this v Using Jython:
WebSphere
Application command to AdminTask
Server return. .compareNodeVersion(’[
version -nodeName node1
- version -version 5]’)
given a A version
node that number that you Interactive mode example usage:
you specify want to compare
and an input v Using Jacl:
to the
version. $AdminTask
WebSphere
compareNodeVersion {
Application -interactive}
Server version
number. v Using Jython:

v Returns: AdminTask
.compareNodeVersion (’[
– 0 if node version -interactive]’)
matches the input
version
– -1 if node version
is smaller than the
input version
– 1 is node version
is higher than the
input version
configure Interactive mode example usage:
TAM v Using Jacl:
$AdminTask configureTAM {
-interactive}
v Using Jython:
AdminTask.configureTAM (’[
-interactive]’)

678 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
connect SIB Web The Object v Parameters: Batch mode example usage:
SIBWS Services connect name of the v Using Jacl:
Endpoint group SIBWS end point bus
The name of the set busConn [
Listener Endpoint listener that
bus to which the $AdminTask
Listener you want to connectSIBWSEndpointListener
command create. end point listener
$epl {-bus "MyBus"}]
connects an will be
connected. v Using Jython:
end point
listener to a (required) busConn =
bus. AdminTask
replyDestination .connectSIBWSEndpointListener
The name of the (epl, ’[-bus MyBus]’)
reply destination
for the Interactive mode example usage:
connection. v Using Jacl:
(optional)
$AdminTask
v Returns: The SIBWS connectSIBWSEndpointListener
bus connection { -interactive}
property object. v Using Jython:
AdminTask
.connectSIBWSEndpointListener
(’[-interactive]’)

Chapter 4. Using the administrative clients 679

copy JCA Use the J2CResource v Parameters: Batch mode example usage:
Resource managementcopy Adapter v Using Jacl:
Adapter group Resource _object _ID - name
Indicates the $AdminTask
Adapter
name of the new copyResourceAdapter
command to $ra [subst {
create a J2C resource
-name newRA -scope
Java 2 adapter. This $scope}]
Connector parameter is
required. v Using Jython:
(J2C)
resource AdminTask
- scope .copyResourceAdapter(
adapter Indicates the ra, ’[-name newRA
under the scope object ID. -scope scope]’)
scope that This parameter is
you specify. required. Interactive mode example usage:

- use Deep Copy v Using Jacl:

If you set this $AdminTask
parameter to copyResourceAdapter {
true, all of the -interactive}
J2C connection v Using Jython:
factory, J2C AdminTask
activation .copyResourceAdapter
specification, and (’[-interactive]’)
J2C
administrative
objects will be
copied to the
new J2C
resource adapter
(deep copy). If
you set this
parameter to
false, the
objects are not
created (shallow
copy). The
default is false.
v Returns: J2C
resource adapter
object ID
create Interactive mode example usage:
Application v Using Jacl:
Server
$AdminTask
createApplicationServer
{-interactive}
v Using Jython:
AdminTask
.createApplicationServer
(’[-interactive]’)

680 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Interactive mode example usage:
Application v Using Jacl:
Server
$AdminTask
Template
createApplicationServerTemplate
{-interactive}
v Using Jython:
AdminTask
.createApplicationServerTemplate
(’[-interactive]’)

Chapter 4. Using the administrative clients 681

createChain Channel The The v Parameters: Batch mode example usage:
Framework createChain instance of v Using Jacl:
Managementcommand the transport - template
The chain $AdminTask
group creates a channel
template on createChain (
new chain service cells/rohitbuildCell01
of transport under which which to base
/nodes
channels the new the new chain. /rohitbuildCellManager01
based on a chain is (ObjectName, /servers
chain created. required) /dmgr|server.xml#
template. (ObjectName, - name TransportChannelService_1) {
required) -template WebContainer
The name of the (templates
new chain. /chains|webcontainer
(String, required) -chains.xml#Chain_1)
-name trialChain1 }
- endPoint
The name of the $AdminTask createChain (
end point to be cells/rohitbuildCell01
used by the /nodes/
rohitbuildCellManager01
instance of the
/servers
TCP inbound /dmgr|server.xml#
channel in the TransportChannelService_1)
new chain if the {-template
chain is an WebContainer
inbound chain. (templates/chains
(ObjectName, |webcontainer
optional) -chains.xml#Chain_1)
-name trialChain1
v Returns: The object -endPoint (
name of the channel cells/rohitbuildCell01/
chain that was nodes
created. /rohitbuildCellManager01
|serverindex.xml
#EndPoint_3) }
v Using Jython:
AdminTask.createChain
(’cells/rohitbuildCell01
/nodes/
rohitbuildCellManager01
/servers
/dmgr|server.xml#
TransportChannelService_1’,
’[-template "WebContainer
(templates
/chains|webcontainer
-chains.xml#Chain_1)"
-name trialChain]’)
AdminTask.createChain
(’cells
/rohitbuildCell01/nodes
/rohitbuildCellManager01/
servers/dmgr|server.xml
#TransportChannelService_1’,
’[-template
"WebContainer(templates
/chains|webcontainer-chains.
xml#Chain_1)" -name
trialChain
-endPoint "(cells/
rohitbuildCell01/nodes
/rohitbuildCellManager01
|serverindex
.xml#EndPoint_3)"]’)

682 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
createChain Interactive mode example usage:
continued v Using Jacl:
$AdminTask createChain
{-interactive}
v Using Jython:
AdminTask.createChain (
’[-interactive]’)

create Cluster The create None v Parameters for step Batch mode example usage:
Cluster Config Cluster one: v Using Jacl:
Commands command
-clusterConfig $AdminTask createCluster {
creates a
Specifies the -clusterConfig {{cluster1
new server true}}}
cluster. A configuration of
server the new server $AdminTask createCluster {
cluster. This -clusterConfig {{cluster1
cluster
command step is true}}
consists of a -replicationDomain {{true}}}
group of required. The
application following $AdminTask createCluster {
parameters can -clusterConfig {{
servers
be specified for cluster1 true}}
which are -convertServer {{
referred to this step.
server1 node1 "" "" ""}}}
as cluster clusterName v Using Jython:
members. The name of the
Optionally, a AdminTask.createCluster(’[
new server -clusterConfig
replication cluster. This
domain can [[cluster1 true]]]’)
parameter is
be created AdminTask.createCluster(’[
required.
for the new -clusterConfig
cluster, and preferLocal [[cluster1 true]]
an existing Enables or -replicationDomain
disables node [[true]]]’)
server can
be included scoped routing AdminTask.createCluster(’[
as the first optimization -clusterConfig
cluster within this [[cluster1 true]]
cluster. This -convertServer [[
member.
server1 node1 "" "" ""]]]’)
parameter is
optional. The Interactive mode example usage:
value is true or
false. It not v Using Jacl:
specified, the $AdminTask createCluster
default value is {-interactive}
true. v Using Jython:
AdminTask.createCluster (’[
-interactive]’)

Chapter 4. Using the administrative clients 683

create Parameters for step
Cluster two:
continued
-replication Domain
Specifies the
configuration of a
replication domain
for this cluster. A
replication domain
is used to support
HTTP session data
replication. This
command step is
optional. The
following
parameters can be
specified for this
step:
createDomain
Creates a
replication domain
with a name set to
the name of the
new cluster. This
parameter is
optional. The value
is true or false. It
not specified, the
default value is
false.

684 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Parameters for step
Cluster three:
continued
-convertServer
Specifies
information about
an existing
application server
to convert to be the
first member of the
cluster. This
command step is
optional. The
following
parameters can be
specified for this
step:
serverNode
The name of the
node with the
server to be
converted to the
first cluster
member. This
parameter is
required for the
command step. You
must also specify
the serverName
parameter.
serverName
The name of the
application server
to be converted to
the first cluster
member. This
parameter is
required for the
command step. You
must also specify
the serverNode
parameter.
memberWeight
The weight of the
cluster member.
The weight controls
the amount of work
directed to the
application server. If
the weight is
greater than the
weight assigned to
other cluster
members, the
server will receive a
larger share of the
workload. The
value is a number
between 0 and 100.
If none is specified,
the default is 2.
Chapter 4. Using the administrative clients 685
create
nodeGroup
Cluster
The name of the
continued
node group which
this cluster
member‘s node,
and all future
cluster members‘
nodes, must belong
to. All cluster
members must
reside on nodes in
the same node
group. This
parameter is
optional. If
specified, it must be
one of the node
groups which this
member‘s node
belongs to. If not
specified, the
default value will be
the first node group
listed for this
member‘s node.
replicatorEntry
Specifies a
replicator entry for
the converted
member will be
created in the
cluster‘s replication
domain. A replicator
entry is used to
provide HTTP
session data
replication. This
command
parameter is
optional. The value
is true or false
which indicates
whether the
replicator entry will
be created. The
default value is
false. You can
specify this
parameter only if
the createDomain
parameter was set
to true in the
replication Domain
command step.

Returns: ObjectName
of cluster created.

686 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Cluster The create cluster v Parameters: Batch mode example usage:
Cluster Config Cluster Object ID - v Using Jacl:
Member Commands Member The -clusterName
The name of the First member creation using
command configuration
cluster which the template name:
creates a object ID of
member of the cluster new member will $AdminTask createClusterMember
a server which the belong to. If this {
cluster. A new parameter is not -clusterName cluster1
specified, then -memberConfig
cluster member will
the cluster object {{node1 member1 "" ""
member is belong to. If true false}}
an this is not ID must be
-firstmember {{
application specified, specified in the serverTemplateName
server that then the command target. "" "" "" ""}}}
belongs to a cluster v Parameters for step First member creation using
cluster. If Name one: server and node for template:
this is the parameter
first member must be -memberConfig $AdminTask createClusterMember
Specifies the {
of the specified.
attributes of the -clusterName cluster1
cluster, you The object -memberConfig
must specify name can new cluster
member to be {{node1 member1 "" ""
a template be obtained true false}}
to use as program- created in the
-firstmember {{
the model matically via cluster. This "" node1 server1 "" ""}}}
for the Java using command step is
required. The Second member creation:
cluster the
following $AdminTask
member. WebSphere
parameters can createClusterMember {
The Config -clusterName cluster1
template Service API, be specified for
this step: -memberConfig
can be or via {{node1 member2 "" ""
either a wsadmin memberName true false}}}
default scripting The name of the v Using Jython:
server using the server to be
template, or Admin First member creation using
created for the
an existing Config template name:
new cluster
application command. member. This AdminTask.createClusterMember
server parameter is (’[
-clusterName cluster1
required.
-memberConfig
memberNode [[node1 member1 "" ""
The name of the true false]]
node where the -firstMember [[
serverTemplateName
new cluster
"" "" "" ""]]]’)
member will be
created. This First member creation using
parameter is server and node for template:
required. AdminTask.createClusterMember
(’[
-clusterName cluster1
-memberConfig
[[node1 member1 "" ""
true false]]
-firstMember [[
"" node1 server1
"" ""]]]’)
Second member creation:
AdminTask.createClusterMember
(’[
-clusterName cluster1
-memberConfig
[[node1 member2 "" ""
true false]]]’)

Chapter 4. Using the administrative clients 687

create v Parameters for step Interactive mode example usage:
Cluster one continued: v Using Jacl:
Member
memberWeight $AdminTask
continued
The weight of the createClusterMember {
-interactive}
new cluster
member. This v Using Jython:
controls the AdminTask.createClusterMember
amount of work (’[
directed to the -interactive]’)
application
server. If the
weight is greater
than the weight
assigned to other
cluster members,
the server will
receive a larger
share of the
workload.
genUniquePorts
Generates
unique port
numbers for
each HTTP
transport defined
in the server.
The new server
will not have
HTTP transports
which conflict
with any other
servers defined
on the same
node. The value
is true or false.
The default value
is true .
replicatorEntry
Specifies a
replicator entry
for the new
cluster member
will be created in
the cluster‘s
replication
domain. A
replicator entry is
used to provide
HTTP session
data replication.
This command
parameter is
optional. The
value is true or
false which
indicates whether
the entry is
created. Default
value is false.
Specify this
688 parameter
IBM WebSphere Application Server Network Deployment, Version only if applications and their environment
6: Administering
a replication
domain has been
created for the
create v Parameters for step
Cluster two:
Member
continued -firstMember
Specifies
additional
information
necessary to
create the first
cluster member.
This command
step is required
when creating
the first member
of the cluster,
and is
executable only
when creating
the first member
of the cluster.
The target of this
command step is
a Boolean value
indicating
whether or not to
perform this step.
The default value
is true if any of
the step
parameters are
specified;
otherwise the
default value is
false. The
following
parameters can
be specified for
this step:
templateName
The name of an
application
server template
to use when
creating the new
cluster member.
If you specify a
template, you
cannot specify
the template
ServerNode and
template
ServerName
parameters to
use an existing
application
server as a
template. You
are required to
specify either the
templateName,or
the template
ServerNode and
template Chapter 4. Using the administrative clients 689
ServerName
parameters in
create v Parameters for step
Cluster two continued:
Member
continued template erverNode
The name of the
node with an
existing
application
server to use as
the template
when creating
the new cluster
member. If you
specify the
template
ServerNode
parameter, you
must also specify
the template
ServerName
parameter, and
you cannot
specify the
templateName
parameter. You
are required to
specify either the
templateName
parameter, or the
template
ServerNode and
template
ServerName
parameters, in
this step.
template
ServerName
The name of the
existing
application
server used as
the model when
creating a new
cluster member.
If you specify the
template
ServerName
parameter, you
must also specify
the template
ServerNode
parameter, and
cannot specify
the
templateName
parameter. You
must specify
either the
templateName
parameter, or the
template
ServerNode and
690 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
template
ServerName
parameters, in
create v Parameters for step
Cluster two continued:
Member
continued nodeGroup
The name of the
node group
which this cluster
member‘s node,
and all future
cluster members‘
nodes, must
belong to. All
cluster members
must reside on
nodes in the
same node
group. This
parameter is
optional. If
specified, it must
be one of the
node groups
which this
member‘s node
belongs to. If not
specified, the
default value will
be the first node
group listed for
this member‘s
node.
coreGroup
The name of the
core group this
cluster member,
and all future
cluster members,
must belong to.
All cluster
members must
belong to the
same core
group. This
parameter is
optional. If not
specified, the
default value is
the default core
group defined in
the cell.
v Returns:
ObjectName of
cluster member
created.

Chapter 4. Using the administrative clients 691

create Core Core The create None v Parameters: Batch mode example usage:
Group Group Core Group v Using Jacl:
Managementcommand - coreGroupName
The name of the $AdminTask createCoreGroup {
group creates a
core group that -coreGroupName MyCoreGroup}
new core
group. The you are creating. v Using Jython:
core group (String required) AdminTask.createCoreGroup(’[
that you v Returns: None -coreGroupName MyCoreGroup]’)
create will
contain no Interactive mode example usage:
members. v Using Jacl:
$AdminTask createCoreGroup {
-interactive}
v Using Jython:
AdminTask.createCoreGroup (’[
-interactive]’)

create Core Core The create Core group v Parameters: Batch mode example usage:
Group Group Core Group bridge v Using Jacl:
Access Bridge Access settings - coreGroupName
The name of the $AdminTask
Point ManagementPoint object for
core group for createCoreGroupAccessPoint
group command the cell. (cells/
creates a (ObjectName, which the core
rohitbuildCell01
default core required). group access |coregroupbridge.xml#
group point will be CoreGroupBridgeSettings_1)
access point created. (String "-coreGroupName
for the core required) DefaultCoreGroup"
group that v Returns: None v Using Jython:
you specify
AdminTask
and adds it .createCoreGroupAccessPoint(
to the ’cells/
default rohitbuildCell01|coregroupbridge
access point .xml#CoreGroupBridgeSettings_1’,
group. If the ’[-coreGroupName
default DefaultCoreGroup]’)
access point
group does Interactive mode example usage:
not exist, v Using Jacl:
the $AdminTask
command createCoreGroupAccessPoint
creates a {interactive}
default v Using Jython:
access point
group. AdminTask
.createCoreGroupAccessPoint
(’[-interactive]’)

create Interactive mode example usage:

Default v Using Jacl:
CGAP
$AdminTask createDefaultCGAP
{-interactive}
v Using Jython:
AdminTask.createDefaultCGAP
(’[-interactive]’)

692 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Serve r Use the None v Parameters: Batch mode example usage:
Generic Managementcreate v Using Jacl:
Server group Generic - name
The name of the $AdminTask createGenericServer
Server
Step: server that you jim667BaseNode
command to {-name jgeneric
Config create a want to create.
-ConfigProcDef {{
ProcDef new generic "/usr/bin/myStartCommand"
- templateName
server in the Picks up a server "arg1 arg2" "" ""
configuration. template. This "/tmp/workingDirectory"
A generic "/tmp/stopCommand"
step provides a
server is a "argy argz"}}}
list of application
server that server templates v Using Jython:
the for the node and AdminTask
WebSphere server type. The .createGenericServer(
Application default value is jim667BaseNode,
Server the default ’[-name jgeneric
manages templates for the -ConfigProcDef [[
but did not /usr/bin/myStartCommand
server type.
supply. The "arg1 arg2"
(String, optional) "" "" /tmp/workingDirectory
create
Generic - genUniquePorts /tmp/StopCommand
The port for the "argy argz"]]]’)
Server
command server.
Interactive mode example usage:
provides an
- templateLocation v Using Jacl:
additional
The location of
step, Config $AdminTask
the server createGenericServer {
ProcDef,
template. -interactive}
that you can
use to - startCommand v Using Jython:
configure Indicates the AdminTask.createGenericServer
the path to the (’[-interactive]’)
parameters command that
that are will run when this
specific to generic server is
generic started. (String,
servers. optional)
- startCommand
Args
Indicates the
arguments to
pass to the
startCommand
when the generic
server is started.
(String, optional)
- executable
TargetKind
Specifies
whether a Java
class name (use
JAVA_CLASS) or
the name of an
executable JAR
file (use
EXECUTABLE_JAR)
will be used as
the executable
target for this
process. This
field should be
left blank for
binary Chapter 4. Using the administrative clients 693
executables. This
parameter is only
applicable for
create v Parameters:
Generic
Server - executable Target
continued Specifies the
name of the
executable target
(a Java class
containing a
main() method or
the name of an
executable JAR),
depending on the
executable target
type. This field
should be left
blank for binary
executables. This
parameter is only
applicable for
Java processes.
(String, optional)
- working Directory
Specifies the
working directory
for the generic
server.
- stopCommand
Indicates the
path to the
command that
will run when this
generic server is
stopped. (String,
optional)
- stopCommand
Args
Indicates the
arguments to
pass to the
stopCommand
parameter when
the generic
server is
stopped. (String,
optional)
v Returns: null
create Interactive mode example usage:
Generic v Using Jacl:
Server
$AdminTask
Template
createGenericServerTemplate
{-interactive}
v Using Jython:
AdminTask
.createGenericServerTemplate
(’[-interactive]’)

694 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create J2C JCA Use the J2C v Parameters: Batch mode example usage:
Activation managementcreate J2C Resource v Using Jacl:
Spec group Activation Adapter - message
ListenerType $AdminTask
Spec _object _ID
Identifies the createJ2CActivationSpec
command to $ra {-name J2CActSpec
create a activation
-jndiName
Java 2 specification for eis/ActSpec1
Connector the J2C -messageListenerType
(J2C) activation javax.jms.MessageListener }
activation specification to
v Using Jython:
specification be created. Use
this parameter to AdminTask
under a J2C
identify the .createJ2CActivationSpec(
resource ra, ’[-name J2CActSpec
adapter and activation
-jndiName
attributes specification eis/ActSpec1
that you template for the -messageListenerType
specify. Use J2C resource javax.jms.MessageListener]’)
the adapter that you
message specify. Interactive mode example usage:
ListenerType - name v Using Jacl:
parameter Indicates the $AdminTask
to indicate name of the J2C createJ2CActivationSpec
the activation {-interactive}
activation specification that v Using Jython:
specification you are creating.
that is AdminTask
defined for - jndiName .createJ2CActivationSpec
Indicates the (’[-interactive]’)
the J2C
resource name of the Java
adapter. Naming and
Directory
Interface (JNDI).
- destination
JndiName
Indicates the
name of the Java
Naming and
Directory
Interface (JNDI)
of corresponding
destination.
- authentication
Alias
Indicates the
authentication
alias of the J2C
activation
specification that
you are creating.
- description
Description of
the created J2C
activation spec.
v Returns:
J2CActivationSpec
object ID

Chapter 4. Using the administrative clients 695

create J2C JCA Use the J2CResource v Parameters: Batch mode example usage:
Admin managementcreate J2C Adapter_object v Using Jacl:
Object group Admin _ID -admin
ObjectInterface $AdminTask
Object
Specifies the createJ2CAdminObject
command to $ra {-adminObjectInterface
create a administrative
fvt.adapter
administrative object interface .message.FVTMessage
object under to identify the Provider -name J2CA01
a resource administrative -jndiName eis/J2CA01}
adapter with object for the
v Using Jython:
attributes resource adapter
that you specify. AdminTask
that you
This parameter is .createJ2CAdminObject(
specify. Use ra, ’[-adminObjectInterface
the required.
fvt.adapter.message
administrative -name .FVTMessageProvider
object Indicates the -name J2CA01 -jndiName
interface to name of the eis/J2CA01]’)
indicate the administrative
administrative Interactive mode example usage:
object.
object v Using Jacl:
defined in -jndiName
$AdminTask
the resource Specifies the createJ2CAdminObject
adapter. name of the Java {-interactive}
Naming and
v Using Jython:
Directory
Interface (JNDI). AdminTask
.createJ2CAdminObject
-description (’[-interactive]’)
Description of
the created J2C
admin object.

v Returns:
J2CAdminObject
object ID

696 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create J2C JCA Use the J2C v Parameters: Batch mode example usage:
Connection managementcreate J2C Connection v Using Jacl:
Factory group Connection Factory -connection Factory
Interface $AdminTask
Factory _object _ID
Identifies the createJ2CConnectionFactory
command to $ra
create a connection
{-connectionFactoryInterfaces
Java 2 definition for the javax.sql.DataSource
connection Java 2 resource -name
factory adapter that you J2CCF1 -jndiName
under a specify. This eis/J2CCF1}
Java 2 parameter is v Using Jython:
resource required.
AdminTask.
adapter and -name createJ2CConnectionFactory
attributes Indicates the (ra,
that you name of the ’[-connectionFactoryInterfaces
specify. Use connection javax.sql.DataSource
the factory. -name
connection J2CCF1 -jndiName
factory -jndiName eis/J2CCF1]’)
interfaces to Indicates the
indicate the name of the Java Interactive mode example usage:
connection Naming and v Using Jacl:
definitions Directory $AdminTask
defined for Interface (JNDI). createJ2CConnectionFactory
the Java 2 {-interactive}
-description
resource v Using Jython:
Description of
adapter.
the created J2C AdminTask
connection .createJ2CConnectionFactory
factory. (’[-interactive]’)
v Returns: J2C
connectionfactory
object ID.
create Node The create The node v Parameters: Batch mode example usage:
Node Group Node group name v Using Jacl:
Group Commands Group to be - shortName
The short name $AdminTask createNodeGroup
group command created.
of the node WBINodeGroup
creates a This target
new node object is group. This v Using Jython:
group. A required. parameter is AdminTask
node group optional. .createNodeGroup(
consists of a ’WBINodeGroup’)
- description
group of The description
nodes which Interactive mode example usage:
of the node
are referred v Using Jacl:
group. This
to as node parameter is $AdminTask createNodeGroup
group optional. {-interactive}
members. v Using Jython:
Optionally, v Returns: Node group
you can object ID AdminTask.createNodeGroup
(’[-interactive]’)
create a
short name
and
description
for the new
node group.

Chapter 4. Using the administrative clients 697

create Node The create The name v Parameters: Batch mode example usage:
Node Group Node of the node v Using Jacl:
Group Commands Group group. This - name
The name of the $AdminTask
Property group Property target object
custom property createNodeGroupProperty
command is required. WBINodeGroup {
creates to create. This
-name Channel -value
custom parameter is "channel1"}
properties required.
v Using Jython:
for a node - value
group. AdminTask
The value of the .createNodeGroupProperty(
custom property. ’WBINodeGroup’,
This parameter is ’[-name Channel
optional. -value channel1]’)
- description Interactive mode example usage:
The description
v Using Jacl:
of the custom
property. This $AdminTask
parameter is createNodeGroupProperty
optional. {-interactive}

v Returns: Properties v Using Jython:

object ID AdminTask
.createNodeGroupProperty
(’[-interactive]’)

698 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB SIB Admin Use this None v Parameters: Batch mode example usage:
Destination Commands command to v Using Jacl:
create a SIB bus
name of the bus $AdminTask
destination.
where this createSIBDestination
{-bus busname -name
destination is to
destname
be configured -type TopicSpace}
(String, required)
v Using Jython:
name AdminTask
destination name .createSIBDestination
(String, required) (’[-bus busname
-name destname
type
-type TopicSpace]’)
The destination
type. Valid value Interactive mode example usage:
include: Queue,
v Using Jacl:
TopicSpace,
WebService or $AdminTask
Port. If the type createSIBDestination
is not {-interactive}
TopicSpace, you v Using Jython:
must use the AdminTask
node/server or .createSIBDestination
cluster option to (’[-interactive]’)
specify a bus
member. (String,
required)
cluster
to assign the
destination to a
cluster, supply
cluster name, but
not node and
server name.
(optional)
node
to assign the
destination to a
server, supply
node name
server name, but
not cluster name.
(optional)
server
to assign the
destination to a
server, supply
node name
server name, but
not cluster name.
(optional)
aliasBus
if this is an alias
destination, the
source bus name
of alias mapping.
(optional)

Chapter 4. Using the administrative clients 699

create SIB v Parameters
Destination continued:
continued
targetBus
if this is an alias
destination, the
name of the bus
that the
destination it
maps to is
configured on.
(optional)
targetName
if this is an alias
destination, the
name of the
destination it
maps to.
(optional)
foreignBus
if this is a foreign
destination, the
name of the
foreign bus.
(optional)
description
description.
(optional)
reliability
the reliability
quality of service
for message
flows through
this destination,
from
BEST_EFFORT
_NON-
PERSISTENT to
ASSURED
_PERSISTENT,
in order of
increasing
reliability. Higher
levels of
reliability have
higher impacts
on the
performance.
(optional)
maxReliability
the maximum
reliability quality
of service that is
accepted for
values specified
by producers.
(optional)

700 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB Parameters continued:
Destination
override OfQOS
continued
ByProducer Allowed
controls the quality
of service for
message flows
between producers
and the destination.
Select this option to
use the quality of
service specified by
producers instead
of the quality
defined for the
destination.
(optional)
defaultPriority
the default priority
for message flows
through this
destination, in the
range 0 (lowest)
through 9 (highest).
This default priority
is used for
messages that do
not contain a
priority value
(Integer, optional).
(optional)
maxFailed Deliveries
the maximum
number of times
that service tries to
deliver a message
to the destination
before forwarding it
to the exception
destination (Integer,
optional). (optional)
exception Destination
the name of
another destination
to which the system
sends a message
that cannot be
delivered to this
destination within
the specified
maximum number
of failed deliveries.
(optional)
sendAllowed
clear this option
(setting it to false)
to stop producers
from being able to
send messages to
this destination.
(optional) Chapter 4. Using the administrative clients 701
create SIB Parameters for step
Destination one continued:
continued
receiveAllowed
clear this option
(setting it to false)
to prevent
consumers from
being able to
receive messages
from this
destination.
(optional)
quiesceMode
select this option
(setting it to true) to
indicate that the
destination is
quiescing. In
quiesce mode, new
messages for the
destination cannot
be added to the
bus, but any
messages already
in the bus can still
be sent to, and
processed by, the
destination
(Boolean, optional,
default=False).
(optional)
receiveExclusive
select this option
(setting it to true) to
allow only one
consumer to attach
to a destination
(Boolean, optional,
default=False).
(optional)
topicAccess Check
Required
topic access check
required (Boolean,
optional)
replyDestination
clear this option
(setting it to false)
to stop producers
from being able to
send messages to
this destination.
(optional)
replyDestination Bus
clear this option
(setting to false) to
prevent consumers
from being able to
receive messages
702 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
from destination.
(optional).
create SIB Parameters for step
Destination one:
continued
delegate Authorization
CheckToTarget
indicates whether
the authorization
check should be
delegated to the
alias or target
destination
(Boolean, optional)
defaultForward
RoutingPath
the default forward
routing path.
bus
bus name
destination
destination name

Returns: A new SIB

destination.

Chapter 4. Using the administrative clients 703

create SIB SIB Admin Use the None v Parameters: Batch mode example usage:
Engine Commands create SIB v Using Jacl:
Engine bus
name of the bus $AdminTask
command to
to which the createSIBEngine
create a {-bus busname
new messaging
-node
messaging engine is to nodeName
engine for a belong (String, -server severname}
bus optional)
v Using Jython:
member. node AdminTask.createSIBEngine
to create a (’[-bus busname
messaging -node nodeName
engine on a -server severname]’)
server, supply
node and server Interactive mode example usage:
name, but not v Using Jacl:
cluster name $AdminTask createSIBEngine
(String, optional) {-interactive}
server v Using Jython:
to create a AdminTask.createSIBEngine
messaging (’[-interactive]’)
engine on a
server, supply
node and server
name, but not
cluster name
(String, optional)
cluster
to create a
messaging
engine on a
cluster, supply
cluster name, but
not node and
server name
(String, optional)
description
description of the
messaging
engine (String,
optional)
initialState
Indicates if the
messaging
engine is started
or stopped when
the associated
application
server starts.
Until started, the
messaging
engine is
unavailable. Valid
values are
Stopped and
Started. (String,
optional)

704 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB v Parameters
Engine continued:
continued
destinationHigh
Msgs
the maximum
total number of
messages that
the messaging
engine can place
on its message
points (Long,
optional)
createDefault
Datasource
Set to true if a
default data
source should be
created when the
messaging
engine is created
(Boolean,
optional)
datasourceJndi
Name
JNDI name of
the data source
to be referenced
from the
datastore created
when the
messaging
engine is created
(String, optional)
v Returns: A new SIB
messaging engine.

Chapter 4. Using the administrative clients 705

create SIB SIB JMS Use the Scope of v Parameters: Batch mode example usage:
JMS Admin create SIB the SIB JMS v Using Jacl:
Activation Commands JMS resource name
name of new $AdminTask
Spec Activation adapter to
activation createSIBJMSActivationSpec
Spec which the $ra {-name specname
command to activation specification
-jndiName specname}
create a SIB specification (String, required)
v Using Jython:
JMS will be jndiName
activation added. AdminTask
JNDI name of .createSIBJMSActivationSpec
specification. the activation (ra,
specification ’[-name specname
(String, required) -jndiName specname]’)
destinationJndi Interactive mode example usage:
Name
JNDI name of a v Using Jacl:
destination $AdminTask
(String, required) createSIBJMSActivationSpec
{-interactive}
description
v Using Jython:
a JMS activation
specification is AdminTask
used by the .createSIBJMSActivationSpec
(’[-interactive]’)
default
messaging
provider to
validate the
activation-
configuration
properties for a
JMS
message-driven
bean (MDB)
(String, optional)
acknowledge Mode
how the session
acknowledges
any messages it
receives (String,
optional)
authentication Alias
authentication
alias (String,
optional)
busName
name of the SIB
bus to connect to
(String, required)
clientId
client identifier.
Required for
durable topic
subscriptions
(String, optional)

706 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB v Parameters:
JMS
Activation destinationType
Spec Indicates if the
continued message-driven
bean uses a
queue or topic
destination.
(String, optional)
durable
Subscription Home
The name of the
durable
subscription
home. This
identifies the
messaging
engine where all
durable
subscriptions
accessed
through this
activation
specification are
managed (String,
optional)
maxBatchSize
the maximum
number of
messages
received from the
messaging
engine in a
single batch
(Integer, optional)
maxConcurrency
the maximum
number of
endpoints to
which messages
are delivered
concurrently
(Integer, optional)
messageSelector
the JMS
message
selector used to
determine which
messages the
message-driven
bean (MDB)
receives (String,
optional)
password
password (String,
optional)

Chapter 4. Using the administrative clients 707

create SIB v Parameters:
JMS
Activation subscription
Spec Durability
continued whether a JMS
topic subscription
is durable or
nondurable
(String, optional)
subscriptionName
the subscription
name needed for
durable topic
subscriptions
(String, optional)
shareDurable
Subscriptions
used to control
how durable
subscriptions are
shared (String,
optional, default
= AsCluster)
userName
user name
(String, optional)
v Returns: A new SIB
JMS activation
specification.

708 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB SIB JMS Use the Scope of v Parameters: Batch mode example usage:
JMS Admin create SIB the SIB JMS v Using Jacl:
Connection Commands JMS resource name
The name of the $AdminTask
Factory Connection adapter to
SIB JMS createSIBJMSConnectionFactory
Factory which the $ra {
command to SIB JMS connection
-name
create a connection factory (String, connectionfactory_name
generic, factory will required) -jndiName jndi_name}
queue or be added. jndiName v Using Jython:
topic SIB the JNDI name
JMS AdminTask
of the SIB JMS .createSIBJMSConnectionFactory
connection connection (ra, ’[
factory. factory (String, -name
required) connectionfactory_name
-jndiName
type jndi_name]’)
The type of
connection Interactive mode example usage:
factory to create. v Using Jacl:
To create a
$AdminTask
queue
createSIBJMSConnectionFactory
connection {-interactive}
factory, set the
value to Queue. v Using Jython:
To create a topic AdminTask
connection .createSIBJMSConnectionFactory
factory, set to (’[-interactive]’)
Topic. To create
a generic
connection
factory, do not
set a value.
(String, optional)
authDataAlias
Specifies a user
ID and password
to be used to
authenticate
connections to
the JMS provider
for
application-
managed
authentication
(String, optional)
category
classifies or
groups the
connection
factory (String,
optional)
description
description of the
connection
factory (String,
optional)

Chapter 4. Using the administrative clients 709

create SIB v Parameters:
JMS
Connection logMissing
Factory Transaction
continued Context
whether or not
the container
logs that there is
a missing
transaction
context when a
connection is
obtained
(Boolean,
optional, default
= False)
manageCached
Handles
Indicates if
cached handles
(handles held in
instance
variables in a
bean) should be
tracked by the
container
(Boolean,
optional, default
= False)
xaRecoveryAuth
Alias
the
authentication
alias used during
XA recovery
processing
(String, optional)
busName
the SIB bus
name (String,
optional)
clientID
user-defined
string, only
required for
durable
subscriptions
(String, optional)
userName
The user name
that is used to
create
connections from
the connection
factory (String,
optional)

710 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB v Parameters:
JMS
Connection password
Factory the password
continued that is used to
create
connections from
the connection
factory (String,
optional)
nonPersistent
Mapping
non-persistent
mapping value.
Valid values
include: Best
EffortNon
Persistent,
ExpressNon
Persistent,
ReliableNon
Persistent,
Reliable
Persistent,
Assured
Persistent,
AsSIB
Destination and
None (String,
optional)
persistent Mapping
persistent
mapping value.
Valid values
include:
BestEffortNon
Persistent,
ExpressNon
Persistent,
ReliableNon
Persistent,
Reliable
Persistent,
Assured
Persistent,
AsSIBDestination
and None (String,
optional)
durable
Subscription Home
durable
subscription
home value
(String, optional)
readAhead
read-ahead
value. Valid
values include:
Default,
AlwaysOn and
AlwaysOff Chapter 4. Using the administrative clients 711
(String, optional)
create SIB v Parameters:
JMS
Connection target
Factory the name of a
continud target that
resolves to a
group of
messaging
engines (String,
optional)
targetType
specifies the type
of the name in
the target
parameter. Valid
values are
BusMember,
Custom and ME
(String, optional)
targetSignificance
this property
specifies the
significance of
the target group
(String, optional)
remoteProtocol
the name of the
protocol that
should be used
to connect to a
remote
messaging
engine (String,
optional)
providerEnd Points
A list of endpoint
triplets seperated
by commas, for
example:
host:port:chain
(String, optional)
connection
Proximity
the proximity of
acceptable
messaging
engines. Valid
values include:
Bus, Host,
Cluster and
Server (String,
optional)

712 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB v Parameters:
JMS
Connection tempQueueName
Factory Prefix
continud temporary queue
name prefix
(String, optional)
tempTopicName
Prefix
temporary topic
name prefix
(String, optional)
share DataSource
WithCMP
used to control
how data
sources are
shared (Boolean,
optional)
shareDurable
Subscriptions
used to control
how durable
subscriptions are
shared. Legal
values are
″AsCluster″,
″AlwaysShared″
and
″NeverShared″
(String, optional,
default =
AsCluster)
v Returns: A new SIB
JMS connection
factory.

Chapter 4. Using the administrative clients 713

create SIB SIB JMS Use the Scope of v Parameters: Batch mode example usage:
JMS Queue Admin create SIB the SIB JMS v Using Jacl:
Commands JMS Queue resource name
The name of the $AdminTask
command to adapter to
SIB JMS queue. createSIBJMSQueue $ra
create a SIB which the {-name queue_name
JMS queue. SIB JMS (String, required)
-jndiName jndi_name
queue will jndiName -queueName queue_name}
be added. The JNDI name v Using Jython:
of the SIB JMS AdminTask
queue. (String, .createSIBJMSQueue(ra,
required) ’[-name queue_name
-jndiName jndi_name
description
-queueName
A description of queue_name]’)
the SIB JMS
queue (String, Interactive mode example usage:
optional)
v Using Jacl:
queueName $AdminTask
The name of the createSIBJMSQueue
underlying SIB {-interactive}
queue to which v Using Jython:
the queue points
AdminTask
(String, required)
.createSIBJMSQueue
deliveryMode (’[-interactive]’)
The delivery
mode for
messages. Legal
values are
″Application″,
″NonPersistent″
and ″Persistent″
(String, optional)
timeToLive
the time in
milliseconds to
be used for
message
expiration (Long,
optional)
priority
the priority for
messages.
Whole number in
the range 0 to 9
(Integer, optional)
readAhead
read-ahead
value. Legal
values are
″AsConnection″,
″AlwaysOn″ and
″AlwaysOff″
(String, optional)
busName
the name of the
bus on which the
queue resides
(String, optional)
v Returns: A new SIB
714 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
JMS queue.
create SIB SIB JMS Use this Scope of v Parameters: Batch mode example usage:
JMS Topic Admin command to the SIB JMS v Using Jacl:
Commands create a SIB resource name
The name of the $AdminTask
JMS topic. adapter to
SIB JMS topic createSIBJMSTopic $ra
which the {-name topic_name
SIB JMS (String, required)
-jndiName jndi_name
topic will be jndiName -topicName topic_name
added. the SIB JMS -topicSpace
topic’s JNDI topicspace_name}
name (String, v Using Jython:
required) AdminTask
.createSIBJMSTopic(ra,
description
’[-name topic_name
a description of -jndiName jndi_name
the SIB JMS -topicName topic_name
queue (String, -topicSpace
optional) topicspace_name]’)
topicSpace Interactive mode example usage:
the name of the
underlying SIB v Using Jacl:
topic space to $AdminTask
which the topic createSIBJMSTopic
points (String, {-interactive}
required) v Using Jython:
*topicName AdminTask
the topic to be .createSIBJMSTopic
(’[-interactive]’)
used inside the
topic space (for
example,
stock/IBM)
(String, required)
deliveryMode
the delivery
mode for
messages. Legal
values are
″Application″,
″NonPersistent″
and ″Persistent″
(String, optional)
timeToLive
the time in
milliseconds to
be used for
message
expiration (Long,
optional)
priority
the priority for
messages.
Whole number in
the range 0 to 9
(Integer, optional)

Chapter 4. Using the administrative clients 715

create SIB v Parameters
JMS Topic continued:
continued
readAhead
read-ahead
value. Legal
values are
″AsConnection″,
″AlwaysOn″ and
″AlwaysOff″
(String, optional)
busName
the name of the
bus on which the
topic resides
(String, optional)
v Returns: A new SIB
JMS topic.

716 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB SIB Admin Use this None v Parameters: Batch mode example usage:
Mediation Commands command to v Using Jacl:
create a SIB bus
name of the bus $AdminTask
mediation.
where the createSIBMediation
{-bus bus_name
mediation is to
-mediationName
be created mediation_name
(String, required) -handlerListName
mediationName handlerList_name}
name to be given v Using Jython:
to the mediation AdminTask
(String, required) .createSIBMediation(
’[-bus bus_name
description -mediationName
description of the mediation_name
mediation -handlerListName
(String, optional) handlerList_name]’)
handler ListName Interactive mode example usage:
name of the
handler list that v Using Jacl:
was defined $AdminTask
when the createSIBMediation
mediation was {-interactive}
deployed (String, v Using Jython:
required) AdminTask
globalTransaction .createSIBMediation
(’[-interactive]’)
whether or not a
global
transaction is
started for each
message
processed
(Boolean,
optional, default
= False)
allow Concurrent
Mediation
whether or not to
apply the
mediation to
multiple
messages
concurrently, and
preserve
message
ordering
(Boolean,
optional, default
= False)

Chapter 4. Using the administrative clients 717

create SIB v Parameters:
Mediation
continued discriminator
the text string
that must not be
present in a
message for the
mediation to
process the
message (String,
optional)
v Returns: A new SIB
mediation.
create SIB Web The create Object v Parameters: Batch mode example usage:
SIBWS Services SIBWS name of the v Using Jacl:
Endpoint group Endpoint server name
The name of the set epl [$AdminTask
Listener Listener where the
end point listener createSIBWSEndpointListener
command end point $server
creates an listener will within the server.
{-name "soaphttp1"
end point be created. (required) -urlRoot
listener urlRoot "http://myserver.com
object with The root of the /wsgwsoaphttp1"
no SIBWS -wsdlUrlRoot
end point
bus "http://myserver.com
address URL for /wsgwsoaphttp1"}]
connection Web services
property that you access v Using Jython:
objects. through the end epl =
point listener. AdminTask
(required) .createSIBWSEndpointListener
(server, ’[-name
wsdlUrlRoot soaphttp1
The root of the -urlRoot
HTTP URL http://myserver.com
where you can /wsgwsoaphttp1
retrieve the -wsdlUrlRoot
http://myserver.com
WSDL
/wsgwsoaphttp1]’)
associated with
this end point Interactive mode example usage:
listener.
v Using Jacl:
(required)
$AdminTask
v Returns: The SIBWS
createSIBWSEndpointListener
end point object. {-interactive}
v Using Jython:
AdminTask
.createSIBWSEndpointListener
(’[-interactive]’)

718 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create SIB Web The create The object v Parameters: Batch mode example usage:
SIBWS Services SIBWS name of the v Using Jacl:
Inbound group Inbound messaging name
The set inService
Service Service bus within
administrative [$AdminTask
command which the createSIBWSInboundService
creates a service will name of the
$bus {-name
new be created. inbound service. "MyService"
inbound (required) -destination $destName
service destination -wsdlLocation
object that "http://myserver.com
The name of the
represents a /MyService.wsdl"}]
underlying WPM
protocol destination. v Using Jython:
attachment (required) inService =
that service AdminTask
requesters wsdlLocation .createSIBWSInboundService
will use. If The location of (bus, ’[-name MyService
you specify the template -destination destName
the UDDI WSDL. The -wsdlLocation
Reference value of this http://myserver.com
option, the parameter can /MyService.wsdl]’)
wsdlLocation be a URL or a
option is UDDI service key Interactive mode example usage:
assumed to (UUID). v Using Jacl:
be a UDDI (required) $AdminTask
service key createSIBWSInboundService
wsdl ServiceName
in the {-interactive}
The name of the
following v Using Jython:
service in the
format
WSDL. You must AdminTask
where each .createSIBWSInboundService
specify this
n is a hex (’[-interactive]’)
parameter or the
digit:
wsdlServiceNamespace
nnnnnnnn
parameter.
nnnn-nnnn
(conditional)
-nnnn-nnnn
-nnnnnnnn. wsdlService
Namespace
The namespace
of the service in
the WSDL. You
must specify this
parameter or the
wsdlServiceName
parameter.
(conditional)
uddiReference
The reference of
the UDDI registry
for the WSDL.
(optional)
userId
The user ID to
use to retrieve
the WSDL.
(optional)
password
The password to
use to retrieve
the WSDL.
(optional)
v Returns: The object
name of the created
Chapter 4. Using the administrative clients 719
inbound service
object.
create SIB Web The create The object v Parameters: Batch mode example usage:
SIBWS Services SIBWS name of the v Using Jacl:
Outbound group Outbound messaging name
The set outService [$AdminTask
Service Service bus within
administrative createSIBWSOutboundService
command which the $bus {-name
creates a service is name of the
"MyService"
new created. outbound -wsdlLocation
outbound service. "http://myserver.com
service (required) /MyService.wsdl"}]
object that wsdlLocation v Using Jython:
represents a The location of outService =
protocol the WSDL of the AdminTask
attachment service provider. .createSIBWSOutboundService
to a service It can be a URL (bus, ’[-name MyService
provider. or a UDDI -wsdlLocation
This service key http://myserver.com
command (UUID). /MyService.wsdl]’)
requires the (required)
identification Interactive mode example usage:
of a single wsdlServiceName v Using Jacl:
service The name of the
$AdminTask
element service in the createSIBWSOutboundService
within a WSDL. You must {-interactive}
WSDL specify the wsdl
v Using Jython:
document. ServiceName
parameter or the AdminTask
wsdlService .createSIBWSOutboundService
Namespsace (’[-interactive]’)
parameter.
(conditional)
wsdlServiceNamespace
Namespace of
the service in the
WSDL. You must
specify the
wsdlServiceName
parameter or the
wsdlService
Namespsace
parameter.
(conditional)
uddiReference
The reference of
the UDDI registry
for the WSDL.
(optional)
destination
The name of the
service
destination.
(optional)
userId
The user ID to
use to retrieve
the WSDL.
(optional)
password
The password to
use to retrieve
720 the WSDL.
IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
(optional)
v Returns: The object
name of the
create SI SIB Admin Use this None v Parameters: Batch mode example usage:
Bus Commands command to v Using Jacl:
create a bus
name of bus to $AdminTask createSIBus
new bus on
create, which {-bus
the current busname -description
node. must be unique
text
in the cell -secure True
(String, required) -mediationsAuthAlias
description name -protocol
protocol
descriptive
-discardOnDelete False}
information about
the bus (String, v Using Jython:
required) AdminTask.createSIBus
(’[-bus
secure busname
enable or disable -description
bus security "text"
(Boolean, -secure True
optional, default -mediationsAuthAlias
= False) name
-protocol protocol
interEngine -discardOnDelete
AuthAlias False]’)
name of the
authentication Interactive mode example usage:
alias used to v Using Jacl:
authorize $AdminTask createSIBus
communication {-interactive}
between
v Using Jython:
messaging
engines on the AdminTask.createSIBus
bus (String, (’[-interactive]’)
optional)
mediationsAuth
Alias
name of the
authentication
alias used to
authorize
mediations to
access the bus
(String, optional)
protocol
the protocol used
to send and
receive
messages
between
messaging
engines, and
between API
clients and
messaging
engines (String,
optional)

Chapter 4. Using the administrative clients 721

create SI v Parameters:
Bus
continued discardOnDelete
indicate whether
or not any
messages left in
the data store of
a queue should
be discarded
when the queue
is deleted
(Boolean,
optional, default
= False)
destinationHigh
Msgs
the maximum
number of
messages that
any queue on
the bus can hold
(Long, optional)
configuration
Reload Enabled
indicate whether
configuration files
should be
dynamically
reloaded for this
bus (Boolean,
optional, default
= True)
v Returns: A new SIB
bus.

722 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create None Use the None v Parameters: Batch mode example usage:
Server create v Using Jacl:
Type Server Type -version
(String, required) $AdminTask createServerType
command to
{-version version
define a -serverType -serverType
server type. (String, required) serverType
-createTemplateCommand
-createTemplate name
Command -createCommand name}
(String, required) v Using Jython:
-createCommand AdminTask.createServerType
(String, required) (’[-version version
-serverType serverType
-defaultTemplate -createTemplateCommand
Name name
The default value -createCommand
is: default. name]’)
(String, optional)
Interactive mode example usage:
-configValidator
v Using Jacl:
(String, optional)
$AdminTask
v Returns: The
createServerType
identification of the {-interactive}
server type that you
created, javax v Using Jython:
.management AdminTask.createServerType
.ObjectName. (’[-interactive]’)

Chapter 4. Using the administrative clients 723

create TCP None The create Parent v Parameters: Batch mode example usage:
End Point TCP End instance of v Using Jacl:
Point the -name
Name for the $AdminTask
command Transport
new Named createTCPEndPoint
creates a Channel (cells/rohitbuildCell01
new named Service that EndPoint.
/nodes/
end point contains the (String, required) rohitbuildCellManager01
you can TCP - host /servers/dmgr
associate Inbound Host for the new |server.xml
with a TCP Channel. #TransportChannelService_1)
Named
inbound (Object EndPoint.
channel. Name, {-name
(String, required) Sample_End_Pt_Name
required)
- port -host
rohitbuild.raleigh.ibm.com
Port for the new
-port 8978}
NamedEndPoint.
(String, required) v Using Jython:
v Returns: Object name AdminTask.createTCPEndPoint
of the created (’cells/rohitbuildCell01
/nodes
NamedEndPoint.
/rohitbuildCellManager01
/servers
/dmgr|server.xml
#TransportChannelService_1’,
’[-name
Sample_End_Pt_Name
-host
rohitbuild.raleigh.ibm.com
-port 8978]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask createTCPEndPoint
{-interactive}
v Using Jython:
AdminTask.createTCPEndPoint
(’[-interactive]’)

724 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Unmanaged Use the None v Parameters: Batch mode example usage:
Unmanaged Node create v Using Jacl:
Node Commands Unmanaged - nodeName
The name that $AdminTask
group Node
will represent the createUnmanagedNode
command to {-nodeName myNode
create a node in the
-hostName myHost
new configuration -nodeOperatingSystem
unmanaged repository. linux}
node in the (String, required)
v Using Jython:
configuration. - hostName
An AdminTask
The host name .createUnmanagedNode
unmanaged of the system (’[-nodeName jjNode
node is a associated with -hostName
node that this node. jjHost
does not (String, required) -nodeOperatingSystem
have a node linux]’)
agent nor a - nodeOperating
deployment System Interactive mode example usage:
manager. The operating v Using Jacl:
Unmanaged system in use on
$AdminTask
nodes may the system
createUnmanagedNode
contain Web associated with {-interactive}
servers, this node. Valid
entries include v Using Jython:
such as IBM
IHS server. the following: AdminTask
os400, aix, hpux, .createUnmanagedNode
linux, solaris, (’[-interactive]’)
windows, and
os390.(String
required)
v Returns: null

Chapter 4. Using the administrative clients 725

create WS The create Object v Parameters: Batch mode example usage:
WSGW Gateway WSGW Name of the v Using Jacl:
Gateway group Gateway gateway -name
Administrative set gwService
Service Service instance
name of the [$AdminTask
command which the createWSGWGatewayService
creates a gateway Gateway
$wsgw
new service is Service. {-name
Gateway created (required) MyGatewayService
Service with -wsdlLocation -targetService
associated MyService}]
Location of the
Inbound template WSDL. v Using Jython:
Service and May be a URL or gwService =
Target a UDDI business AdminTask
Service key (UUID). .createWSGWGatewayService
object. (conditional) (wsgw, ’[-name
Configuration MyGatewayService
of the -wsdl ServiceName -targetService
Inbound The name of the MyService]’)
Port and service in the
Outbound WSDL. Interactive mode example usage:
Service/Port (conditional) v Using Jacl:
associated $AdminTask
-wsdlService
with these is createWSGWGatewayService
Namespace
done using {-interactive}
The namespace
separate v Using Jython:
of the service in
commands.
the WSDL. $AdminTask
(conditional) createWSGWGatewayService
(’[-interactive]’)
-targetDestination
The name of the
target
destination.
(conditional)
-targetService
The name of the
target outbound
service.
(conditional)
-request
Destination
The name of the
gateway
destination.
(optional)
-replyDestination
The name of the
gateway reply
destination.
(optional)
-targetBus
The name of the
WPM bus
containing the
target. (optional)

726 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create v Parameters:
WSGW
Gateway -uddiReference
Service The reference of
continued the UDDI registry
for the WSDL.
(optional)
-userId
The user id to
use to retrieve
the WSDL.
(optional)
-password
The password to
use to retrieve
the WSDL.
(optional)
v Returns: ObjectName
of the created
GatewayService
object

Chapter 4. Using the administrative clients 727

create WS The create The object v Parameters: Batch mode example usage:
WSGW Gateway WSGW name of the v Using Jacl:
Proxy group Proxy gateway name
The set proxyService
Service Service instance
administrative [$AdminTask
command within which createWSGWProxyService
creates a the proxy name of the
$wsgw
new proxy service is proxy service. {-name
service with created. (required) MyProxyService
an node -node MyNode
associated -server server1}]
The node where
inbound the destinations v Using Jython:
service, and will be localized. proxyService =
a target (conditional) AdminTask
service .createWSGWProxyService
object with server (wsgw, ’[-name
an The server MyProxyService
associated where the -node MyNode
outbound destinations will -server server1]’)
service. be localized.
Configuration (conditional) Interactive mode example usage:
of the v Using Jacl:
cluster
inbound port $AdminTask
Cluster where
objects createWSGWProxyService
the destinations
associated {-interactive}
will be localized.
with the v Using Jython:
(conditional)
inbound
service is -request AdminTask
.createWSGWProxyService
done using Destination
(’[-interactive]’)
separate The name of the
commands. proxy request
destination.
(optional)
-replyDestination
The name of the
proxy reply
destination.
(optional)
-wsdlLocation
The location of
the proxy WSDL
(URL). (optional)
v Returns: The object
name of the proxy
service object that
you created.

728 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Web Server Use the None v Parameters for step Batch mode example usage:
Server Managementcreate Web one: v Using Jacl:
group Server
nodeName $AdminTask
command to
The name of the createWebServer
create a {-name web1
Web server node. (String,
-serverConfig
definition. required) {{webPort
This name WebserverInstallRoot
command is The name of the PluginInstallRoot
a two step Configuration
server. (String,
process. _file_name
required) Windows_Server_Name
The first
step creates templateName errorLogPath
The name of the accessLogPath
a Web
WebProtocol}}
server template that you
-remoteServerConfig
definition want to use. {{AdminPort
using a Templates UserID
template. include the Password
The following: IHS, AdminProtocol}}
parameters iPlanet, IIS, v Using Jython:
of the DOMINO, APACHE.
The default AdminTask.createWebServer
second step
(’[-name web1
configure template is IHS.
-serverConfig
the Web (String, required) [[webPort
server WebserverInstallRoot
genUniquePorts
definition PluginInstallRoot
Indicates that
properties. Configuration
you want to
Web server _file_name
generate unique Windows_Server
definitions
ports. (optional) _Name errorLogPath
generate
and v Parameters for step accessLogPath
two: WebProtocol]]
propagate
-remoteServerConfig
the plugin serverConfig [[AdminPort
-config.xml Create the Web UserID Password
file for each server. (String, AdminProtocol]]]’)
Web server. required) where -serverConfig is second
For IHS
webPort step of the command.
only, the
Web server The port for the – WebPort - is the port for the
definitions Web server. Webserver (required for all
allow you to (String, required) webservers)
administer configurationFile – Webserver InstallRoot - is the
and The configuration install path (directory) for
configure file. The default webserver. necessary for IHS
IHS Web is the path Admin Function.
servers relative to the – Plugin Install Root - is install
using the installation root, root where the plugin for the
administrative for example, webserver is installed.
console. conf/httpd.conf. Necessary for all webservers.
These (String, optional) – Configuration file name - is the
functions
webInstallRoot file path for the IBM HTTP
include the
The installation Server. This is necessary for
following:
path for the Web View and edit of the IHS
Start, Stop,
server. (String, Configuration file only.
View logs,
View and required)
Edit
configuration
file.

Chapter 4. Using the administrative clients 729

create Web v Parameters for step v Windows Service Name - The
Server two continued: windows service name on which
continued IHS is to be started. This is
pluginInstallRoot
necessary for Start and stop of
The plug-in
the IHS webserver only.
installation path.
(String, required) v ErrorLogPath - This is the path for
the IHS error log (error.log)
serviceName
v AccessLogPath - This is the path
The service
for the IHS access log
name. (String,
(access.log)
optional)
v WebServerProtocol - HTTP or
errorLogfile HTTPS
The error log for
viewing. The where -remoteServerConfig is 3rd
default is the step of the command
path relative to
the installation These parameters are only
root, for necessary if the IHS webserver is
example, installed on a machine remote from
logs/error_log. WebSphere.
(String, optional) v Admin Server Port - This is the
port for the ADministration server.
accessLogfile
The administration server is
The access log
installed on the same machine as
for viewing. The
the IBM HTTP Server. The admin
default is the
server handles admin request to
path relative to
the IHS webserver.
the installation
root, for v UserID - This is the userID for
example, logs authentication, if authentication is
/access_log. activated on the Administration
(String, optional) server in the admin configuration
file (admin.conf).
webProtocol
v Passwd - This is the password for
Parameters for
the specified authentication
the IHS
UserID. The password is
administration
generated by htpasswd utility in
server running
the admin.passwd file.
with an
unmanaged or v Admin ServerProtocol - HTTP or
remote Web HTTPS
server. Options
include HTTP or Interactive mode example usage:
HTTPS. The v Using Jacl:
default is HTTP. $AdminTask
(String, required) createWebServer
-interactive
adminPort
The port of the v Using Jython:
IHS AdminTask.createWebServer
administrative (’[-interactive]’)
server. (String,
required)
adminUserID
The user ID. This
value should
match the one
for authentication
in the
admin.conf.
(String, required)

730 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
create Web v Parameters for step
Server two continued:
continued
adminPasswrd
The
administrative
password.
(String, required)
adminProtocol
The
administrative
protocol title.
Options include
HTTP or HTTPS.
The default is
HTTP. (String,
required)
v Parameters for step
three:
Parameters for IHS
administration server
running with an
unmanaged or
remote Web server
(installed on machine
different from
WebSphere
Application Server)
adminPortTitle
(adminPort)
Port of IHS
administration
admin UserIDTitle
(adminUserID)
The user ID. This
value should
match the
authentication in
the admin.conf
file.
adminPasswd Title
(adminPasswd)
password
Admin Protocol
Title
(adminProtocol)
This parameter is
required. The
value is either
HTTP or HTTPS.
The default value
is HTTP.
v Returns: None

Chapter 4. Using the administrative clients 731

delete Channel The delete The chain to v Parameters: Batch mode example usage:
Chain Framework Chain be deleted. v Using Jacl:
Managementcommand (Object - delete Channels
If the value of $AdminTask deleteChain
group deletes an Name
this attribute is trialChain1
existing ,required) (cells/rohitbuildCell01
chain and, true, non-shared
/nodes
optionally, transport /rohitbuildCellManager01
the transport channels used /servers
channels in by the specified /dmgr|server.xml#Chain
the chain. chain will be _1093554462922)
deleted. $AdminTask deleteChain
(Boolean, trialChain
optional) (cells/rohitbuildCell01
v Returns: None /nodes
/rohitbuildCellManager01
/servers
/dmgr|server.xml
#Chain_1093554378078)
{-deleteChannels true}
v Using Jython:
AdminTask.deleteChain
(’trialChain1
(cells/rohitbuildCell01
/nodes
/rohitbuildCellManager01
/servers/dmgr
|server.xml
#TransportChannelService_1)’)
AdminTask.deleteChain
(’trialChain1
(cells/rohitbuildCell01
/nodes
/rohitbuildCellManager01
/servers
/dmgr
|server.xml
#TransportChannelService_1)
’, ’[-deleteChannels true]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask deleteChain
{-interactive}
v Using Jython:
AdminTask.deleteChain
(’[-interactive]’)

732 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
delete Cluster The delete cluster v Parameters: Batch mode example usage:
Cluster Config Cluster Object ID - v Using Jacl:
Commands command The -clusterName
The name of the $AdminTask deleteCluster
deletes the configuration
cluster to be { -clusterName cluster1 }
configuration object ID of
of a server the cluster deleted. If this $AdminTask deleteCluster
cluster. A to be parameter is not { -clusterName cluster1
specified, then -replicationDomain
server deleted. If
the cluster object {{true}}}
cluster the cluster‘s
consists of a object ID is ID must be v Using Jython:
group of not specified in the AdminTask.deleteCluster
application specified, command target. (’[-clusterName
servers then the v Parameters for step cluster1]’)
which are cluster one: AdminTask.deleteCluster
referred to Name (’[-clusterName
as cluster parameter -replication Domain cluster1
members. must be Specifies the -replicationDomain
When a specified. removal of the [[true]]]’)
server The object replication
domain for this Interactive mode example usage:
cluster is name can
deleted, all be obtained cluster. This v Using Jacl:
of its programmatically command step is
$AdminTask
members via Java optional. The deleteCluster -interactive
are deleted. using the following
parameters can v Using Jython:
WebSphere
Use the be specified for AdminTask.deleteCluster
Config
delete this step: (’[-interactive]’)
Service API,
Cluster or via deleteDomain
Member wsadmin Deletes the
command to scripting replication
delete the using the domain for this
configuration AdminConfig cluster. This
of an command. parameter is
individual optional. The
cluster value is true or
member. false which
indicates whether
the domain will
be deleted. The
default value is
false. . Deleting
the replication
domain deletes
all replicator
entries defined in
the domain.
v Returns: None

Chapter 4. Using the administrative clients 733

delete Cluster The delete member v Parameters: Batch mode example usage:
Cluster Config Cluster Object ID - v Using Jacl:
Member Commands Member The -clusterName
The name of the $AdminTask
command configuration
cluster which the deleteClusterMember
deletes the object ID of {-clusterName
configuration the cluster member to be
cluster1 -memberNode
of a cluster member to deleted belongs node1 -memberName
member. A be deleted. to. If this member1}
cluster If this is not parameter is
$AdminTask
member is specified, specified, then
deleteClusterMember
an then the the member {-clusterName cluster1
application cluster Name and -memberNode node1
server that Name, member Node -memberName member2
belongs to a member parameters must -replicationEntry
server Node and also be specified. {{true}}}
cluster. member If this is not v Using Jython:
Name specified, then
AdminTask
Use the parameters the member
.deleteClusterMember
delete must be object ID must (’[-clusterName cluster1
Cluster specified. be specified in -memberNode node1
command to The object the command -memberName member1]’)
delete the name can target.
AdminTask
configuration be obtained .deleteClusterMember
-memberName
of a cluster. programmatically (’[-clusterName cluster1
The server name
via Java of the member to -memberNode node1
using the -memberName member2
be deleted from
WebSphere -replicationEntry
the cluster. If this [[true]]]’)
Config parameter is
Service API, specified, then Interactive mode example usage:
or via the clusterName
wsadmin v Using Jacl:
and
scripting memberNode $AdminTask
using the parameters must deleteClusterMember
Admin -interactive
also be specified.
Config If this is not v Using Jython:
command. specified, then AdminTask
the member .deleteClusterMember
object ID must (’[-interactive]’)
be specified in
the command
target.
-memberNode
The name of the
node having the
cluster member
to be deleted. If
this parameter is
specified, then
the
memberName
and clusterName
parameters must
also be specified.
If this is not
specified, then
the cluster
member object
ID must be
specified in the
command target.

734 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
delete v Parameters for step
Cluster one:
Member
continued -replicatorEntry
Specifies the
removal of a
replicator entry
for this cluster
member. This
command step is
optional. The
following
parameters can
be specified for
this step:
deleteEntry
Delete the
replicator entry
having this
cluster member‘s
name from the
cluster‘s
replication
domain. This
parameter is
optional. The
value is true or
false which
indicates whether
to delete the
replicator entry.
The default value
is false.
v Returns: None
delete Core Core The delete None v Parameters: Batch mode example usage:
Group Group Core Group v Using Jacl:
Managementcommand - core GroupName
The name of the $AdminTask
group deletes an
existing core deleteCoreGroup
existing core {-coreGroupName
group. The group that will be
MyCoreGroup}
core group deleted. (String
required) v Using Jython:
that you
specify must v Returns: None AdminTask
not contain .deleteCoreGroup
any (’[-coreGroupName
MyCoreGroup]’)
members.
You cannot Interactive mode example usage:
delete the
default core v Using Jacl:
group. $AdminTask
deleteCoreGroup
{-interactive}
v Using Jython:
AdminTask
.deleteCoreGroup
(’[-interactive]’)

Chapter 4. Using the administrative clients 735

delete Core Core The delete Core group v Parameters: Batch mode example usage:
Group Group Core Group bridge v Using Jacl:
Access Bridge Access settings - core GroupName
The name of the $AdminTask
Points ManagementPoints object for
core group deleteCoreGroupAccessPoints
group command the cell. (cells/
deletes all (Object whose core
rohitbuildCell01
the core Name, group access |coregroupbridge.xml#
group required) points will be CoreGroupBridgeSettings_1)
access deleted. (String "-coreGroupName
points required) DefaultCoreGroup"
associated v Returns: None v Using Jython:
with a group
AdminTask
that you .deleteCoreGroupAccessPoints
specify. (’(cells/rohitbuildCell01
|coregroupbridge.xml
#CoreGroupBridgeSettings_1)’,
’[-coreGroupName
DefaultCoreGroup]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
deleteCoreGroupAccessPoints
{-interactive}
v Using Jython:
AdminTask
.deleteCoreGroupAccessPoints
(’[-interactive]’)

delete SIB SIB Admin Use the None v Parameters: Batch mode example usage:
Destination Commands delete SIB v Using Jacl:
Destination bus
name of the bus $AdminTask
command to
on which the deleteSIBDestination
delete a bus {-bus busname
destination. destination to be
-name destname}
This deleted exists
command (String, required) v Using Jython:
deletes the AdminTask
name .deleteSIBDestination
named name of the
destination (’[-bus busname
destination to be -name destname]’)
of the deleted (String,
named bus required) Interactive mode example usage:
and deletes
all related v Returns: None v Using Jacl:
message $AdminTask
points. deleteSIBDestination
{-interactive}
v Using Jython:
AdminTask
.deleteSIBDestination
(’[-interactive]’)

736 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
delete SIB SIB Admin Use the None v Parameters: Batch mode example usage:
Engine Commands delete SIB v Using Jacl:
Engine *bus
name of the bus $AdminTask
command to
to which the deleteSIBEngine
delete the {-bus busname
default or messaging
-node nodeName
named bus engine to be -server severname}
messaging deleted belongs
(String, required) v Using Jython:
engine from
the named AdminTask.deleteSIBEngine
node (’[-bus busname -node
SIB bus. A to delete a nodeName -server
server can messaging severname]’)
only have engine on a
one server, supply Interactive mode example usage:
messaging node and server v Using Jacl:
engine, so name, but not
when using $AdminTask
cluster name deleteSIBEngine
this (String, optional)
command to {-interactive}
delete a server v Using Jython:
messaging to delete a AdminTask
engine from messaging .deleteSIBEngine
a server engine on a (’[-interactive]’)
there is no server, supply
need to node and server
supply the name, but not
engine cluster name
name. A (String, optional)
cluster can
cluster
have more
to delete a
than one
messaging
messaging
engine on a
engine so
cluster, supply
the name of
cluster name, but
the engine
not node and
must be
server name
supplied.
(String, optional)
engine
name of the
messaging
engine to delete.
This is optional,
and is only
required when
deleting a
messaging
engine from a
cluster (String,
optional)
v Returns: None

Chapter 4. Using the administrative clients 737

delete SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Admin delete SIB v Using Jacl:
Activation Commands JMS name
The name of the $AdminTask
Spec Activation
activation deleteSIBJMSActivationSpec
Spec {-name specname}
command to specification that
delete an you want to v Using Jython:
activation delete. (String, AdminTask
specification. (required) .deleteSIBJMSActivationSpec
v Returns: None (’[-name specname]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
deleteSIBJMSActivationSpec
{-interactive}
v Using Jython:
AdminTask
.deleteSIBJMSActivationSpec
(’[-interactive]’)

delete SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Admin delete SIB v Using Jacl:
Connection Commands JMS name
The name of the $AdminTask
Factory Connection
SIB JMS deleteSIBJMSConnectionFactory
Factory {-name factory_name}
command to connection
factory (String, v Using Jython:
required) AdminTask
v Returns: None .deleteSIBJMSConnectionFactory
(’[-name factory_name]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
deleteSIBJMSConnectionFactory
{-interactive}
v Using Jython:
AdminTask
.deleteSIBJMSConnectionFactory
(’[-interactive]’)

738 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
delete SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Queue Admin delete SIB v Using Jacl:
Commands JMS Queue name
The name of the $AdminTask
command to
SIB JMS queue. deleteSIBJMSQueue
delete a {-name queue_name}
JMS queue. (String, required)
v Using Jython:
v Returns: None
AdminTask
.deleteSIBJMSQueue
(’[-name queue_name]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
deleteSIBJMSQueue
{-interactive}
v Using Jython:
AdminTask
.deleteSIBJMSQueue
(’[-interactive]’)

delete SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Topic Admin delete SIB v Using Jacl:
Commands JMS Topic name
The name of the $AdminTask
command to
SIB JMS topic deleteSIBJMSTopic
delete a {-name topic_name}
JMS topic. (String, required)
v Using Jython:
v Returns: None
AdminTask
.deleteSIBJMSTopic
(’[-name topic_name]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
deleteSIBJMSTopic
{-interactive}
v Using Jython:
AdminTask
.deleteSIBJMSTopic
(’[-interactive]’)

Chapter 4. Using the administrative clients 739

delete SIB SIB Admin Use this None v Parameters: Batch mode example usage:
Mediation Commands command to v Using Jacl:
delete the bus
named name of the bus v Using Jython:
mediation that owns the
Interactive mode example usage:
from the mediation
named bus. (String, required) v Using Jacl:
$AdminTask
mediation Name
deleteSIBMediation
name of the {-interactive}
mediation to be
deleted (String, v Using Jython:
required) AdminTask
.deleteSIBMediation
v Returns: None
(’[-interactive]’)

delete SIB Web The delete Object v Parameters: None Batch mode example usage:
SIBWS Services SIBWS name of the v Using Jacl:
v Returns: None
EndpointListener
group Endpoint end point
$AdminTask
Listener listener that
deleteSIBWSEndpointListener
command you want to $epl
deletes the delete.
configuration v Using Jython:
oa an end AdminTask
point .deleteSIBWSEndpointListener
listener. This (epl)
command
Interactive mode example usage:
fails if there
are inbound v Using Jacl:
port objects $AdminTask
associated deleteSIBWSEndpointListener
with the end {-interactive}
point v Using Jython:
listener.
AdminTask
.deleteSIBWSEndpointListener
(’[-interactive]’)

740 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
delete SIB Web The delete The object v Parameters: Batch mode example usage:
SIBWS Services SIBWS name of the v Using Jacl:
Inbound group Inbound inbound userId
The user ID to $AdminTask
Service Service service
use to interact deleteSIBWSInboundService
command object that $inService
deletes an you want to with UDDI
inbound delete. registries. v Using Jython:
service (optional) AdminTask
object and .deleteSIBWSInboundService
password (inService)
any inbound The password to
port objects use to interact Interactive mode example usage:
that are with UDDI
associated. v Using Jacl:
registries.
(optional) $AdminTask
deleteSIBWSInboundService
v Returns: None {-interactive}
v Using Jython:
AdminTask
.deleteSIBWSInboundService
(’[-interactive]’)

delete SIB Web The delete Object v Parameters: None Batch mode example usage:
SIBWS Services SIBWS name of the v Using Jacl:
v Returns: None
Outbound group Outbound outbound
$AdminTask
Service Service service
deleteSIBWSOutboundService
command object that $outService
deletes an you want to
outbound delete. v Using Jython:
service AdminTask
object and .deleteSIBWSOutboundService
any (outService)
outbound
Interactive mode example usage:
port objects
that are v Using Jacl:
associated. $AdminTask
Resources deleteSIBWSOutboundService
that are {-interactive}
associated v Using Jython:
with the
AdminTask
outbound .deleteSIBWSOutboundService
service or (’[-interactive]’)
outbound
ports, for
example,
WS-Security
configuration,
are
disassociated
from the
outbound
service and
the
outbound
ports but
are not
deleted.

Chapter 4. Using the administrative clients 741

delete SIB Admin Use this None v Parameters: Batch mode example usage:
SIBus Commands command to v Using Jacl:
delete the bus
name of bus to $AdminTask deleteSIBus
named SIB
be deleted from {-bus bus_name}
bus. Also
deletes all the current cell v Using Jython:
SIB (String, required) AdminTask.deleteSIBus
mediations v Returns: None (’[-bus bus_name]’)
and SIB
destinations Interactive mode example usage:
owned by v Using Jacl:
the bus. $AdminTask deleteSIBus
{-interactive}
v Using Jython:
AdminTask.deleteSIBus
(’[-interactive]’)

delete None Use the None v Parameters: Batch mode example usage:
Server delete v Using Jacl:
Server -nodeName
(String, required) $AdminTask deleteServer
command to
{-nodeName node_name
delete the -serverName -serverName
server (String, required) server_name}
scope
v Returns: None v Using Jython:
configuration
and the AdminTask.deleteServer
server entry (’[-nodeName node_name
that -serverName
server_name]’)
corresponds
to it in the Interactive mode example usage:
server
index.xml v Using Jacl:
file. You can $AdminTask deleteServer
also use this {-interactive}
command to v Using Jython:
delete a AdminTask.deleteServer
Web server. (’[-interactive]’)

742 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
delete None Use the A server v Returns: Void Interactive mode example usage:
Server delete template v Using Jacl:
Template Server identification,
$AdminTask
Template javax
deleteServerTemplate
command to .management {-interactive}
delete .ObjectName.
server This target v Using Jython:
templates. object is AdminTask
You cannot required. .deleteServerTemplate
delete (’[-interactive]’)
templates
defined by
the system.
You can
only delete
server
templates
that you
created.
This
command
deletes the
directory
that hosts
the server
template.

Chapter 4. Using the administrative clients 743

delete WS The delete Object v Parameters: None Batch mode example usage:
WSGW Gateway WSGW name of the v Using Jacl:
v Returns: None
Gateway group Gateway gateway
$AdminTask
Service Service service
deleteWSGWGatewayService
command object $gwService
deletes a
gateway v Using Jython:
service. It AdminTask
deletes the .deleteWSGWGatewayService
gateway (gwService)
destination
Interactive mode example usage:
the
corresponding v Using Jacl:
reply $AdminTask
destination, deleteWSGWGatewayService
inbound {-interactive}
service, and v Using Jython:
inbound port
AdminTask
enablement .deleteWSGWGatewayService
objects, and (’[-interactive]’)
all of the
target
service
objects that
are
associated.
This
command
does not
delete the
destinations
that are
associated
with the
target
services.
delete WS The delete Object v Parameters: None Batch mode example usage:
WSGW Gateway WSGW name of the v Using Jacl:
v Returns: None
Proxy group Proxy Proxy
$AdminTask
Service Service Service
deleteWSGWProxyService
command object $proxyService
deletes a
proxy v Using Jython:
service AdminTask
including the .deleteWSGWProxyService
proxy (proxyService)
destinations,
Interactive mode example usage:
outbound
service, v Using Jacl:
outbound $AdminTask
ports, deleteWSGWProxyService
inbound {-interactive}
service, and v Using Jython:
inbound port
AdminTask
enablement .deleteWSGWProxyService
objects. (’[-interactive]’)

744 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
disconnect SIB Web The Object v Parameters: Batch mode example usage:
SIBWS Services disconnect name of the v Using Jacl:
Endpoint group SIBWS end point bus
The name of the $AdminTask
Listener Endpoint listener to
bus from which disconnectSIBWS
Listener be EndpointListener
command disconnected. to be
$epl {-bus "MyBus"}
disconnects disconnected.
(required) v Using Jython:
an end point
listener from v Returns: None AdminTask
a bus. .disconnectSIBWS
EndpointListener
(epl,’[-bus MyBus]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
disconnectSIBWS
EndpointListener
{-interactive}
v Using Jython:
AdminTask
.disconnectSIBWS
EndpointListener
(’[-interactive]’)

does Core Core The does None v Parameters: Batch mode example usage:
Group Exist Group Core Group v Using Jacl:
ManagementExist coreGroupName
The name of the $AdminTask
group command
core group. doesCoreGroupExist
returns a {-coreGroupName
boolean (String, required)
MyCoreGroup}
value that v Returns: A boolean
v Using Jython:
indicates if value.
the core AdminTask
group that .doesCoreGroupExist
you specify (’[-coreGroupName
MyCoreGroup]’)
exists.
Interactive mode example usage:
v Using Jacl:
$AdminTask
doesCoreGroupExist
{-interactive}
v Using Jython:
AdminTask
.doesCoreGroupExist
(’[-interactive]’)

Chapter 4. Using the administrative clients 745

export ConfigurationUse the None v Parameters: Batch mode example usage:
Server archive export v Using Jacl:
Operations Server -archive
The fully $AdminTask exportServer
group command to
qualified path of {-archive
export the c:\myServer.ear
server the exported
-nodeName
configuration configuration node1 -serverName
to a node archive. (String, server1}
defined in required)
v Using Jython:
the -nodeName
configuration AdminTask.exportServer
The node name (’[-archive
archive. of the server. c:\myServer.ear
This parameter is -nodeName
The export
only required node1 -serverName
Server server1]’)
when the server
command
name is not
virtualizes Interactive mode example usage:
unique across
the server
the cell. (String, v Using Jacl:
configuration
optional) $AdminTask exportServer
and exports
a server to {-interactive}
-serverName
a The server v Using Jython:
configuration name. (String, AdminTask.exportServer
archive. This required) (’[-interactive]’)
process v Returns: None
breaks any
existing
associations
between the
server
configurations
in the
configuration
archive and
the
configurations
in the
system. This
process also
removes
applications
from the
server that
you specify,
breaks the
relationship
between the
server that
you specify
and the core
group of the
server,
cluster, or
SIBus
membership.
The
exportServer
command
exports the
metadata
file of the
node where
746 the server
IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
resides. You
can use this
information
export Was configurationUse the None v Parameters: Batch mode example usage:
profile archive export Was v Using Jacl:
Operations profile archive
The fully $AdminTask
group command to
qualified file path exportWasprofile
export the {-archive
entire cell of the exported
c:\myCell.ear}
configuration configuration
archive. (String, v Using Jython:
to a
configuration required) AdminTask
archive. v Returns: None .exportWasprofile
(’[-archive
c:\myCell.ear]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
exportWasprofile
{-interactive}
v Using Jython:
AdminTask
.exportWasprofile
(’[-interactive]’)

get All Core Core The get All None v Parameters: None Batch mode example usage:
Group Group Core Group v Using Jacl:
v Returns: String array
ames ManagementNames
(String[ ]) $AdminTask
group command
getAllCoreGroupNames
returns a
string that v Using Jython:
contains the AdminTask
names of all .getAllCoreGroupNames()
of the
existing core Interactive mode example usage:
groups v Using Jacl:
$AdminTask
getAllCoreGroupNames
{-interactive}
v Using Jython:
AdminTask
.getAllCoreGroupNames
(’[-interactive]’)

Chapter 4. Using the administrative clients 747

get Core Core The get None v Parameters: Batch mode example usage:
Group Group Core Group v Using Jacl:
Name For ManagementName For - nodeName
The name of the $AdminTask
Server group Server
node that getCoreGroupNameForServer
command {-nodeName myNode
returns the contains the
-serverName
name of the server. (String, myServer}
core group required)
v Using Jython:
for which - serverName
the server AdminTask
The name of the .getCoreGroupNameForServer
you specify server. (String, (’[-nodeName myNode
is currently required) -serverName
a member. myServer]’)
v Returns: The name of
the core group that
Interactive mode example usage:
currently contains the
server that you v Using Jacl:
specified. (String) $AdminTask
getCoreGroupNameForServer
{-interactive}
v Using Jython:
AdminTask
.getCoreGroupNameForServer
(’[-interactive]’)

get Default Core The get None v Parameters: None Batch mode example usage:
Core Group Group Default v Using Jacl:
v Returns: String
Name ManagementCore Group
$AdminTask
group Name
getDefaultCoreGroupName
command
returns the v Using Jython:
name of the AdminTask
default core .getDefaultCoreGroupName()
group.
Interactive mode example usage:
v Using Jacl:
$AdminTask
getDefaultCoreGroupName
{-interactive}
v Using Jython:
AdminTask
.getDefaultCoreGroupName
(’[-interactive]’)

748 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
get Managed The get None v Parameters: Batch mode example usage:
Metadata Object Metadata v Using Jacl:
Properties Metadata Properties - nodeName
The name of the $AdminTask
group command
node associated getMetadataProperties
obtains all {-nodeName node1}
metadata for with the
the node metadata you v Using Jython:
that you want this AdminTask
specify. command to .getMetadataProperties
return. (’[-nodeName node1]’)
v Returns: The list of
Interactive mode example usage:
metadata properties.
v Using Jacl:
$AdminTask
getMetadataProperties
{-interactive}
v Using Jython:
AdminTask
.getMetadataProperties
(’[-interactive]’)

get Managed The get None v Parameters: Batch mode example usage:
Metadata Object Metadata v Using Jacl:
Property Metadata Property - nodeName
The name of the $AdminTask
group command
node associated getMetadataProperty
obtains {-nodeName node1
metadata with the
-propertyName
with the metadata you com.ibm.websphere
specified want this .baseProductVersion}
key for the command to
v Using Jython:
node that return.
you specify. AdminTask
- propertyName .getMetadataProperty
Metadata (’[-nodeName node1
property key. -propertyName
v Returns: The com.ibm.websphere
.baseProductVersion]’)
requested property
for the node that you Interactive mode example usage:
specified.
v Using Jacl:
$AdminTask
getMetadataProperty
{-interactive}
v Using Jython:
AdminTask
.getMetadataProperty
(’[-interactive]’)

Chapter 4. Using the administrative clients 749

get Named Core The get The bridge v Parameters: None Batch mode example usage:
TCP End Group Named TCP interface v Using Jacl:
v Returns: The port
Point Bridge End Point object for
(named end point) $AdminTask
Managementcommand which the
object name of the getNamedTCPEndPoint
group returns the port will be (cells/rohitbuildCell01|
TCP inbound channel
port listed. coregroupbridge.xml
instance which
associated (Object #BridgeInterface_2)
resides on the DCS
with the Name,
transport channel v Using Jython:
bridge required)
chain of the bridge AdminTask
interface
interface. .getNamedTCPEndPoint
that you
(’(cells/rohitbuildCell01
specify. The
|coregroupbridge.xml
port that is #BridgeInterface_2)’)
returned is
the one that Interactive mode example usage:
is specified
v Using Jacl:
on the TCP
inbound $AdminTask
channel of getNamedTCPEndPoint
{-interactive}
the transport
channel v Using Jython:
chain for AdminTask
bridge .getNamedTCPEndPoint
interface (’[-interactive]’)
that you
specify.
get Node Managed The get None v Parameters: Batch mode example usage:
Base Object Node Base v Using Jacl:
Product Metadata Product - nodeName
The name of the $AdminTask
Version group Version
node associated getNodeBaseProductVersion
command {-nodeName node1}
returns the with the
version of metadata you v Using Jython:
the want this AdminTask
WebSphere command to .getNodeBaseProductVersion
Application return. (’[-nodeName node1]’)
Server for a v Returns: WebSphere
Interactive mode example usage:
node that Application Server
you specify. version for the node v Using Jacl:
This that you specify. $AdminTask
command getNodeBaseProductVersion
only returns {-interactive}
the version v Using Jython:
for a
AdminTask
distributed .getNodeBaseProductVersion
installation (’[-interactive]’)
of the
product.

750 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
get Node Managed The get None v Parameters: Batch mode example usage:
Major Object Node Major v Using Jacl:
Version Metadata Version nodeName
The name of the $AdminTask
group command
node associated getNodeMajorVersion
returns the {-nodeName node1}
major with the
version of metadata you v Using Jython:
the want this AdminTask
WebSphere command to .getNodeMajorVersion
Application return. (’[-nodeName node1]’)
Server for a v Returns: WebSphere
Interactive mode example usage:
node that Application Server
you specify. major version for the v Using Jacl:
It only node that you $AdminTask
returns the specified. getNodeMajorVersion
version for a {-interactive}
distributed v Using Jython:
installation
AdminTask
of the .getNodeMajorVersion
product. (’[-interactive]’)

get Node Managed None v Parameters: Batch mode example usage:

Minor Object v Using Jacl:
Version Metadata - nodeName
The name of the $AdminTask
group
node associated getNodeMinorVersion
{-nodeName node1}
with the
metadata you v Using Jython:
want this AdminTask
command to .getNodeMinorVersion
return. (’[-nodeName node1]’)
v Returns: WebSphere
Interactive mode example usage:
Application Server
minor version for the v Using Jacl:
node that you $AdminTask
specified. getNodeMinorVersion
{-interactive}
v Using Jython:
AdminTask
.getNodeMinorVersion
(’[-interactive]’)

Chapter 4. Using the administrative clients 751

get Node Managed The get None v Parameters: Batch mode example usage:
Platform Object Node v Using Jacl:
OS Metadata Platform - nodeName
The name of the $AdminTask
group OS
node associated getNodePlatformOS
command {-nodeName node1}
returns the with the
operating metadata you v Using Jython:
system want this AdminTask
name for a command to .getNodePlatformOS
node that return. (’[-nodeName node1]’)
you specify. v Returns: The
Interactive mode example usage:
operating system
name of the node v Using Jacl:
that you specified. $AdminTask
getNodePlatformOS
{-interactive}
v Using Jython:
AdminTask
.getNodePlatformOS
(’[-interactive]’)

get Node Managed The get None v Parameters: Batch mode example usage:
Sysplex Object Node v Using Jacl:
Name Metadata Sysplex - nodeName
The name of the $AdminTask
group Name
node associated getNodeSysplexName
command {-nodeName node1}
returns the with the
sysplex metadata you v Using Jython:
name for a want this AdminTask
node that command to .getNodeSysplexName
you specify. return. (’[-nodeName node1]’)
v Returns: The sysplex
Interactive mode example usage:
name of the given
node. v Using Jacl:
$AdminTask
getNodeSysplexName
{-interactive}
v Using Jython:
AdminTask
.getNodeSysplexName
(’[-interactive]’)

get Server Interactive mode example usage:

Type v Using Jacl:
$AdminTask getServerType
{-interactive}
v Using Jython:
AdminTask.getServerType
(’[-interactive]’)

752 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
get TCP None The get TCP v Parameters: None Batch mode example usage:
End Point TCP End Inbound
v Returns: Object name v Using Jacl:
Point Channel, or
of an existing named $AdminTask getTCPEndPoint
command containing
end point that is TCP_1(cells
obtains the chain, /rohitbuildCell01/
associated with the
named end instance nodes/rohitbuildCellManager01
TCP inbound channel
point that is /servers/dmgr|server.xml
instance or a channel
associated associated #TCPInboundChannel_1)
chain.
with either a with a $AdminTask getTCPEndPoint
TCP Named DCS
inbound EndPoint. (cells/rohitbuildCell01
channel or a (Object /nodes/
chain that Name, rohitbuildCellManager01
contains a required) /servers
TCP /dmgr|server.xml#Chain_3)
inbound v Using Jython:
channel. AdminTask.getTCPEndPoint
(’TCP_1(cells/rohitbuildCell01/
nodes/rohitbuildCellManager01
/servers/dmgr
|server.xml
#TCPInboundChannel_1)’)
AdminTask.getTCPEndPoint
(’DCS(cells/rohitbuildCell01
/nodes/
rohitbuildCellManager01
/servers
/dmgr|server.xml#Chain_3)’)

Interactive mode example usage:

v Using Jacl:
$AdminTask getTCPEndPoint
{-interactive}
v Using Jython:
AdminTask.getTCPEndPoint
(’[-interactive]’)

Chapter 4. Using the administrative clients 753

import ConfigurationUse the None v Parameters: Batch mode example usage:
Server archive import v Using Jacl:
Operations Server -archive
The fully $AdminTask importServer
group command to
qualified path of {-archive
import a c:\myServer.ear
server that the configuration
-nodeInArchive node1
resides in a archive. (String, -serverInArchive
configuration required) server1}
archive to -node InArchive v Using Jython:
the system. The node name
This AdminTask.importServer
of the server (’[-archive
command defined in the c:\myServer.ear
imports all configuration -nodeInArchive node1
the server archive. (String, -serverInArchive
scope optional if there server1]’)
configurations is only one node
defined in defined in the Interactive mode example usage:
the configuration v Using Jacl:
configuration archive, required $AdminTask importServer
archive to if there are {-interactive}
system multiple nodes
configuration. v Using Jython:
defined in the
configuration AdminTask.importServer
(’[-interactive]’)
archive)
-server InArchive
The name of the
server defined in
the configuration
archive. (String,
optional if there
is only one
server defined on
the specified
nodeIn
Configuration
archive, required
if there are
multiple servers
defined under
the specified
nodeIn
Configuration
archive)
-nodeName
The node name
where the server
is imported.
(String, optional
if there is only
one node)
-serverName
The server name
where the server
is imported. If the
server name that
you specify
matches an
existing server
name under the
node, an
754 exception
IBM WebSphere Application Server Network Deployment, Version is
6: Administering applications and their environment
thrown. (String,
optional,
default:serve
import v Parameters
Server continued:
continued
-serverName
The server name
where the server
is imported. If the
server name that
you specify
matches an
existing server
name under the
node, an
exception is
thrown. (String,
optional,
default:serve
rInArchive)
-coreGroup
The core group
name to which
the server should
belong. (String,
optional)
v Returns: None
help None The help None v Parameters: None v Using Jacl:
command
v Returns: A general $AdminTask help
provides a
help description v Using Jython:
summary of
the help print AdminTask.help()
commands
and ways to
invoke an
administrative
command.
help None The help None v Parameters: v Using Jacl:
command
- options $AdminTask help -commands
provides a
list of v Returns: A summary v Using Jython:
available of all available AdminTask.help(’-commands’)
administrative administrative
commands commands.
if the option
string is
-commands
or
administrative
command
groups if the
option string
is -command
Groups.
Valid options
include
-commands
and
-command
Groups.

Chapter 4. Using the administrative clients 755

help None If you None v Parameters: v Using Jacl:
provide the
– - commandName $AdminTask help
step name,
– - stepName createJ2CConnectionFactory
this
command v Returns: A summary v Using Jython:
provides of the specified AdminTask.help
help command group, (’createJ2CConnectionFactory’)
information administrative
for a given command, or step.
step of an
administrative
command.
Otherwise, it
provides
help
information
for a given
admin
command or
administrative
command
group. The
stepName
parameter is
optional.
import Was configurationUse the None v Parameters: Batch mode example usage:
profile archive import Was v Using Jacl:
Operations profile archive
The fully $AdminTask importWasprofile
group command to
qualified file path {-archive c:\myCell.ear}
import a cell
configuration of the v Using Jython:
in the configuration AdminTask.importWasprofile
configuration archive. (String, (’[-archive
archive to required) c:\myCell.ear]’)
the system. v Returns: Void
Only a base Interactive mode example usage:
single v Using Jacl:
server $AdminTask importWasprofile
configuration {-interactive}
is supported v Using Jython:
for this
command. AdminTask.importWasprofile
(’[-interactive]’)

756 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
is Node Managed The is None v Parameters: Batch mode example usage:
ZOS Object Node ZOS v Using Jacl:
Metadata command - nodeName
The name of the $AdminTask isNodeZOS
group tests if a
node associated {-nodeName node1}
node that
you specify with the v Using Jython:
is running metadata you AdminTask.isNodeZOS
on the z/OS want this (’[-nodeName node1]’)
platform. command to
This return. Interactive mode example usage:
command v Returns: A true value v Using Jacl:
does not if the node operating $AdminTask isNodeZOS
apply to system is z/OS. A {-interactive}
distributed false value if the v Using Jython:
platforms or node operating
WebSphere system is not z/OS. AdminTask.isNodeZOS
Application (’[-interactive]’)
Server-
Express.
list Admin JCA Use the list J2C v Parameters: None Batch mode example usage:
Object managementAdmin Resouce v Using Jacl:
v Returns: A list of
Interfaces group Object adapter
administrative object $AdminTask
Interfaces object ID
interfaces. listAdminObjectInterfaces
command to $ra
list the
administrative v Using Jython:
object AdminTask
interfaces .listAdminObjectInterfaces
defined (ra)
under the
resource
adapter that
you specify.

Chapter 4. Using the administrative clients 757

list Chain Channel The list None v Parameters: Batch mode example usage:
Templates Framework Chain v Using Jacl:
ManagementTemplates - acceptorFilter
The templates $AdminTask
group command
returned by this listChainTemplates {}
displays a
list of method all have $AdminTask
templates a transport listChainTemplates
channel instance "-acceptorFilter
that you can
of the specified WebContainerInboundChannel"
use to
create type as the last v Using Jython:
chains in transport channel AdminTask
this in the chain. .listChainTemplates()
configuration. (String, optional) AdminTask
All v Returns: A list of all .listChainTemplates
templates the chain template (’[-acceptorFilter
have a object names. If you WebContainerInboundChannel]’)
certain type specify the
of transport acceptorFilter Interactive mode example usage:
channel as parameter, the list v Using Jacl:
the last that returns is filtered $AdminTask
transport to match the filter that listChainTemplates
channel in you specified. {-interactive}
the chain. v Using Jython:
AdminTask
.listChainTemplates
(’[-interactive]’)

758 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list Chains Channel The list The v Parameters: Batch mode example usage:
Framework Chains instance of v Using Jacl:
Managementcommand the transport - acceptorFilter
The chains that $AdminTask listChains
group lists all the channel
are returned by (cells/rohitbuildCell01
chains service /nodes/
configured under which this parameter
rohitbuildNode01/servers
under a the chains will have a /server2
particular are transport channel |server.xml#
instance of configured. instance of the TransportChannelService
the transport (Object type that you _1093445762328)
channel Name, specify as the $AdminTask listChains
service. required) last transport (cells/rohitbuildCell01
channel in the /nodes/
chain. (String, rohitbuildNode01/servers
optional) /server2
|server.xml#
- endPoint Filter: TransportChannelService
The chains _1093445762328)
returned by this {-acceptorFilter
parameter will WebContainerInboundChannel}
have a TCP $AdminTask listChains
inbound channel (cells/rohitbuildCell01
using an end /nodes/
point with the rohitbuildNode01/servers
name that you /server2
specify.(String, |server.xml#
optional) TransportChannelService
_1093445762328)
v Returns: A list of all {-endPointFilter
the channel chain WC_adminhost}
object names that
v Using Jython:
match the specified
filters. If no you do AdminTask.listChains(’
not specify any (cells/rohitbuildCell01
/nodes
parameters, all of the
/rohitbuildNode01/servers
channel chains that /server2|server.xml
are configured under #TransportChannelService
the particular _1093445762328)’)
instance of transport
AdminTask.listChains(’(
channel service are cells/rohitbuildCell01
returned. /nodes
/rohitbuildNode01/servers
/server2|server.xml
#TransportChannelService
_1093445762328)’,
’[-acceptorFilter
WebContainerInboundChannel]’)
AdminTask.listChains
(’(cells
/rohitbuildCell01/nodes
/rohitbuildNode01/servers
/server2
|server.xml
#TransportChannelService
_1093445762328)’,
’[-endPointFilter
WC_adminhost]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask listChains
{-interactive}
v Using Jython:
Chapter 4. AdminTask.listChains
Using the administrative clients 759
(’[-interactive]’)
list JCA Use the list J2C v Parameters: None Batch mode example usage:
Connection managementConnection Resource v Using Jacl:
v Returns: A list of
Factory group Factory Adapter
connection factory $AdminTask
Interfaces Interfaces object ID
interfaces. listConnectionFactory
command to Interfaces
list all of the $ra
connection
v Using Jython:
factory
interfaces AdminTask
defined .listConnectionFactory
under the Interfaces
(ra)
Java 2
resource
adapter that
you specify.
list Core Core The list The name v Parameters: Batch mode example usage:
Groups Group Core of the core v Using Jacl:
Bridge Groups group for - cgBridge Settings
The group bridge $AdminTask listCoreGroups
Managementcommand which the
settings object DefaultCoreGroup
group returns a related core "-cgBridgeSettings
collection of groups will for the cell.
(cells/rohitbuildCell01
core groups be listed. (Object Name, |coregroupbridge.xml#
that are (String, required) CoreGroupBridgeSettings_1)"
related to required) v Returns: A set of core v Using Jython:
the core group names.
group that AdminTask.listCoreGroups
(’DefaultCoreGroup’,
you specify.
’[-cgBridgeSetting
(cells/rohitbuildCell01
|coregroupbridge.xml
#CoreGroupBridgeSettings_1)]’)

Interactive mode example usage:

v Using Jacl:
$AdminTask listCoreGroups
{-interactive}
v Using Jython:
AdminTask.listCoreGroups
(’[-interactive]’)

760 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list Eligible Core The list The core v Parameters: None Batch mode example usage:
Bridge Group Eligible group v Using Jacl:
v Returns: A set of
Interfaces Bridge Bridge access point
bridge interfaces. $AdminTask
ManagementInterfaces object for
(Set of String) Each listEligibleBridgeInterfaces
group command which bridge CGAP_DCG_2
bridge interface is
returns a interfaces (cells/rohitbuildCell01
represented by a
collection of will be |coregroupbridge.xml#
combination of a
node, server listed. CoreGroupAccessPoint
node, a server and a
and (Object _1089636614062)
DCS channel chain:
transport Name, v Using Jython:
<node name>,
channel required)
<server name>, AdminTask
chain
<DCS Channel Chain .listEligibleBridgeInterfaces
combinations (’CGAP_DCG_2
objectName. For
that are (cells/rohitbuildCell01
example, an element
eligible to |coregroupbridge.xml#
of the set returned by
become CoreGroupAccessPoint
this command may
bridge _1089636614062)’)
look like the
interfaces
following: rohitbuild Interactive mode example usage:
for the
dmgr DCS-Secure
specified v Using Jacl:
(cells
core group $AdminTask
/rohitbuildCell
access listEligibleBridgeInterfaces
/nodes/rohitbuild
point. {-interactive}
/servers
/dmgr|server.xml v Using Jython:
#Chain_4) AdminTask
.listEligibleBridgeInterfaces
(’[-interactive]’)

list J2C JCA Use the list J2C v Parameters: Batch mode example usage:
Activation managementJ2c Resource v Using Jacl:
Specs group Activation Adapter -message
ListenerType $AdminTask
Specs object ID
Specifies the listJ2CActivationSpecs
command to $ra {-messageListenerType
list the message listener
javax.jms
activation type for the .MessageListener}
specs resource adapter
contained for which you are v Using Jython:
under the making a list. AdminTask
resource This parameter is .listJ2CActivationSpecs
required. (ra, ’[-messageListenerType
adapter and
javax.jms
message v Returns: A list of .MessageListener]’)
listener type activation specs that
that you has specified
specify. message Listener
type.

Chapter 4. Using the administrative clients 761

list J2C JCA Use the list J2C v Parameters: Batch mode example usage:
Admin ManagementJ2C Admin Resource v Using Jacl:
Objects group Objects Adapter -adminObject
Interface $AdminTask
command to object ID
Specifies the listJ2CAdminObjects
list $ra {-adminObjectInterface
administrative administrative
fvt.adaptor.message
objects that object interface .FVTMessageProvider}
contains the for which you
want to list. This v Using Jython:
administrative
object parameter is AdminTask
interface required. .listJ2CAdminObjects
(ra,
that you v Returns: A list of ’[-adminObjectInterface
specify. administrative objects fvt.adaptor.message
that has specified .FVTMessageProvider]’)
adminObject
Interface.

list J2C JCA Use the list J2C v Parameters: Batch mode example usage:
Connection managementJ2C Resource v Using Jacl:
Factories group Connection Adapter -connection Factory
Interface $AdminTask
Factories object ID
Indicates the listJ2CConnectionFactories
command to $ra
list the Java name of the
{-connectionFactoryInterface
2 connection javax.sql.DataSource}
connection factory that you
factories want to list. This v Using Jython:
under the parameter is AdminTask
resource required. .listJ2CConnectionFactories
(ra,
adapter and v Returns: A list of J2C ’[-connectionFactoryInterface
connection connection Factory javax.sql.DataSource]’)
factory that has the specified
interface connection Factory
that you Interface.
specify
list Unmanaged Use the list None v Parameters: None Batch mode example usage:
Managed Node Managed v Using Jacl:
v Returns: List
Nodes Commands Nodes
$AdminTask listManagedNodes
group command to
list the v Using Jython:
managed AdminTask.listManagedNodes()
nodes
(nodes that
have a node
agent
defined) in a
configuration.
list JCA Use the list J2C v Parameters: None Batch mode example usage:
Message ManagementMessage Resource v Using Jacl:
v Returns: A list of
Listener group Listener Adapter
message listener $AdminTask
Types Types object ID
types. listMessageListenerTypes
command to $ra
list the
message v Using Jython:
listener AdminTask
types .listMessageListenerTypes
defined (ra)
under the
resource
adapter that
you specify.

762 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list Node Node The list The target v Parameters: None Batch mode example usage:
Group Group Node object is v Using Jacl:
v Returns: A list of all
Properties Commands Group name of the
of the custom $AdminTask
group Properties node group.
properties of a node listNodeGroupProperties
command This target WBINodeGroup
group.
displays all object is
of the required. v Using Jython:
custom AdminTask
properties of .listNodeGroupProperties
a node (’WBINodeGroup’)
group.
Interactive mode example usage:
v Using Jacl:
$AdminTask
listNodeGroupProperties
{-interactive}
v Using Jython:
AdminTask
.listNodeGroupProperties
(’[-interactive]’)

list Node Node The list The target v Parameters: None Batch mode example usage:
Groups Group Node object is v Using Jacl:
v Returns: A list of the
Commands Groups name of the
node groups in the $AdminTask listNodeGroups
group command node. This
cell.
returns the target object $AdminTask listNodeGroups
list of node is optional. nodeName
groups from
v Using Jython:
the
configuration AdminTask.listNodeGroups
repository.
You can AdminTask.listNodeGroups
(’nodeName’)
pass an
optional Interactive mode example usage:
node name
to the v Using Jacl:
command $AdminTask listNodeGroups
that returns {-interactive}
the list of v Using Jython:
node groups AdminTask.listNodeGroups
where the (’[-interactive]’)
node
resides.

Chapter 4. Using the administrative clients 763

list Nodes Node The list The target v Parameters: None Batch mode example usage:
Group Nodes object is v Using Jacl:
v Returns: A list of all
Commands command name of the
the nodes in the cell $AdminTask listNodes
group displays all node group.
of the nodes This target v Using Jython:
in the cell. object is AdminTask.listNodes()
optional.
Interactive mode example usage:
v Using Jacl:
$AdminTask listNodes
{-interactive}
v Using Jython:
AdminTask.listNodes
(’[-interactive]’)

list SIB SIB Admin Use this None v Parameters: Batch mode example usage:
Destinations Commands command to v Using Jacl:
get a list of bus
Bus name $AdminTask
SIB
(String, required) listSIBDestinations
destinations {-bus busname -name
of the name destname -type Queue}
named type Destination name v Using Jython:
owned by a (String, required)
named SIB AdminTask
bus. If no type .listSIBDestinations
type is type of (’[-bus busname -name
destination to list destname -type Queue]’)
named, all
destinations - Queue,
Interactive mode example usage:
owned by TopicSpace,
the named WebService or v Using Jacl:
bus are Port (String, $AdminTask
listed. optional) listSIBDestinations
{-interactive}
v Returns: List of SIB
destinations. v Using Jython:
AdminTask
.listSIBDestinations
(’[-interactive]’)

764 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list SIB SIB Admin Use the list None v Parameters: Batch mode example usage:
Engines Commands SIB v Using Jacl:
Engines bus
name of the bus $AdminTask
command to
whose engines listSIBEngines {-bus
get a list of busname -node
bus are to be listed
nodeName
messaging (String, optional) -server severname}
engines. node v Using Jython:
Supplying node name. To
only the bus AdminTask.listSIBEngines
list messaging (’[-bus
parameter engines on a busname -node
will result in server, supply nodeName
a list of all node and server -server severname]’)
engines name, but not
associated cluster name Interactive mode example usage:
with the (String, optional) v Using Jacl:
named bus.
Supplying server $AdminTask listSIBEngines
only the server name. To {-interactive}
node and list messaging v Using Jython:
server engines on a AdminTask.listSIBEngines
parameters server, supply (’[-interactive]’)
will result in node and server
a list of all name, but not
engines cluster name
owned by (String, optional)
the named
cluster
node/server.
cluster name. To
Supplying
list messaging
only the
engines on a
cluster
cluster, supply
parameter
cluster name, but
will result in
not node and
a list of all
server name
engines
(String, optional)
owned by
the named v Returns: A list of SIB
cluster. All messaging engines.
other
parameter
combinations
are illegal.
list SIB SIB JMS Interactive mode example usage:
JMS Admin v Using Jacl:
Activation Commands
$AdminTask
Specs
listSIBJMSActivationSpecs
{-interactive}
v Using Jython:
AdminTask
.listSIBJMSActivationSpecs
(’[-interactive]’)

Chapter 4. Using the administrative clients 765

list SIB SIB JMS Use the list None v Parameters: Batch mode example usage:
JMS Admin SIB JMS v Using Jacl:
Connection Commands Connection type
Filters the list of $AdminTask
Factories Factories
connection listSIBJMSConnectionFactories
command to {-type queue}
list all of the factories. Valid
JMS values include: v Using Jython:
connection – all - Lists all AdminTask
factories for the JMS .listSIBJMSConnectionFactories
the default connection (’[-type queue]’)
messaging factories
Interactive mode example usage:
provider at (unified,
the scope queue, and v Using Jacl:
that you topic) at the $AdminTask
specify. scope that listSIBJMSConnectionFactories
you specify. {-interactive}
– queue - Lists v Using Jython:
all of the JMS AdminTask
queue .listSIBJMSConnectionFactories
connection (’[-interactive]’)
factories at
the scope that
you specify.
– topic - Lists
all of the JMS
topic
connection
factories at
the scope that
you specify.
If you do no
specify the type
option, this
command will
return only the
unified JMS
connection
factories at the
scope that you
specified.
v Returns: A list of
connection factories
at the scope that you
specified.
list SIB SIB JMS Use the list None v Parameters: None Batch mode example usage:
JMS Admin SIB JMS v Using Jacl:
v Returns: None
Queues Commands Queues
$AdminTask listSIBJMSQueues
command to
list all the v Using Jython:
JMS queues AdminTask.listSIBJMSQueues()
for the
default
messaging
provider at
the specified
scope.

766 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list SIB SIB JMS Lists all None v Parameters: None Batch mode example usage:
JMS Topics Admin JMS topics
v Returns: A list of JMS v Using Jacl:
Commands for the
topics. $AdminTask listSIBJMSTopics
default
messaging v Using Jython:
provider at AdminTask.listSIBJMSTopics()
the specified
scope.

list SIB SIB Admin Use this None v Parameters: Batch mode example usage:
Mediations Commands command to v Using Jacl:
list the bus
name of the SIB $AdminTask listSIBMediations
mediations
bus where the {-bus bus_name}
on a named
SIB bus. mediations to be v Using Jython:
listed are to be AdminTask.listSIBMediations
found (String, (’[-bus bus_name]’)
required)
v Returns: A list of SIB Interactive mode example usage:
mediations. v Using Jacl:
$AdminTask
listSIBMediations
{-interactive}
v Using Jython:
AdminTask
.listSIBMediations
(’[-interactive]’)

list SI Bus SIB Admin Use this None v Parameters: Batch mode example usage:
Members Commands command to v Using Jacl:
list all bus
name of the SIB $AdminTask
servers and
bus whose listSIBusMembers
clusters {-bus bus_name}
which are members are to
members of be listed (String, v Using Jython:
the named required) AdminTask
SIB bus. v Returns: List .listSIBusMembers
containing the IDs of (’[-bus bus_name]’)
bus members –
Interactive mode example usage:
servers and clusters.
v Using Jacl:
$AdminTask
listSIBusMembers
{-interactive}
v Using Jython:
AdminTask
.listSIBusMembers
(’[-interactive]’)

list SI SIB Admin Use this None v Parameters: None Batch mode example usage:
Buses Commands command to v Using Jacl:
v Returns: None
list all SIB
$AdminTask listSIBuses
buses in the
cell. v Using Jython:
AdminTask.listSIBuses()

Chapter 4. Using the administrative clients 767

list SSL None The list SSL v Parameters: None Batch mode example usage:
Repertoires SSL Inbound v Using Jacl:
v Returns: A list of
Repertoires Channel
eligible SSL $AdminTask
command instance for
configuration object listSSLRepertoires
lists all of which the SSL_3
names.
the Secure SSL Config (cells/rohitbuildCell01/
Sockets candidates nodes/rohitbuildNode01
Layer (SSL) are listed. /servers
configuration /server2|server.xml
instances #SSLInbound
you can Channel_1093445762330)
associate v Using Jython:
with an SSL AdminTask
inbound .listSSLRepertoires
channel. (’SSL_3(cells
/rohitbuildCell01
/nodes/rohitbuildNode01
/servers
/server2|server.xml
#SSLInboundChannel
_1093445762330)’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
listSSLRepertoires
{-interactive}
v Using Jython:
AdminTask
.listSSLRepertoires
(’[-interactive]’)

list Server None Use the list None v Parameters: Batch mode example usage:
Templates Server v Using Jacl:
Templates -serverType
(String, optional) $AdminTask
command to
listServerTemplates
query -platform {-serverType server_Type}
available (String, optional)
server v Using Jython:
templates -release Version AdminTask
based on (String, optional) .listServerTemplates
server type, (’[-serverType server_Type]’)
v Returns: A list of
platform, or server template Interactive mode example usage:
release identifications that
level. match with the v Using Jacl:
criteria that you $AdminTask
specify with the listServerTemplates
command {-interactive}
parameters. If you do v Using Jython:
no specify any AdminTask
parameters, all server .listServerTemplates
templates are (’[-interactive]’)
returned.

768 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list Server None Use the list The v Returns: A list of Interactive mode example usage:
Types Server identification server types that you v Using Jacl:
Types of a node in can define on a node. $AdminTask listServerTypes
command to the cell, If you do not specify {-interactive}
query javax the target object, this
defined .management.ObjectName. v Using Jython:
command returns all
server types This target of the server types AdminTask.listServerTypes
on a node. object is defined in the entire (’[-interactive]’)
optional. cell.

list Servers Interactive mode example usage:

v Using Jacl:
$AdminTask listServers
{-interactive}
v Using Jython:
AdminTask.listServers
(’[-interactive]’)

list TAM Interactive mode example usage:

Settings v Using Jacl:
$AdminTask listTAMSettings
{-interactive}
v Using Jython:
AdminTask.listTAMSettings
(’[-interactive]’)

Chapter 4. Using the administrative clients 769

list TCP None The list TCP v Parameters: Batch mode example usage:
End Points TCP End Inbound v Using Jacl:
Points Channel - exclude
Distinguished $AdminTask
command instance for
Shows only listTCPEndPoints
lists all which TCP_1(cells
named end named end non-distinguished
/rohitbuildCell01/
points that points named end nodes
can be candidates points. This /rohitbuildCellManager01
associated are listed. parameter does /servers
with a TCP (ObjectName, not require a /dmgr|server.xml#
inbound required) value. (Boolean, TCPInboundChannel_1)
channel. optional) $AdminTask
- unusedOnly listTCPEndPoints
TCP_1(cells
Shows the
/rohitbuildCell01/
named end nodes
points not in use /rohitbuildCellManager01
by other TCP /servers
inbound channel /dmgr|server.xml#
instances. This TCPInboundChannel_1)
parameter does {-excludeDistinguished}
not require a $AdminTask
value. (Boolean, listTCPEndPoints
optional) TCP_1(cells
v Returns: A list of /rohitbuildCell01/
nodes
object names for the
/rohitbuildCellManager01
eligible named end /servers
points. /dmgr|server.xml
#TCPInboundChannel_1)
{-excludeDistinguished
-unusedOnly}
v Using Jython:
AdminTask
.listTCPEndPoints
(’TCP_1
(cells/rohitbuildCell01
/nodes
/rohitbuildCellManager01
/servers
/dmgr|server.xml
#TCPInboundChannel_1)’,
’[-excludeDistinguished]’)
AdminTask
.listTCPEndPoints
(’TCP_1(cells
/rohitbuildCell01/
nodes
/rohitbuildCellManager01
/servers
/dmgr|server.xml#
TCPInboundChannel_1)’,
’[-excludeDistinguished]’)
AdminTask.listTCPEndPoints
(’TCP_1
(cells/rohitbuildCell01
/nodes
/rohitbuildCellManager01
/servers/dmgr|server.xml
#TCPInboundChannel_1)’,
’[-excludeDistinguished
-unusedOnly]’)

770 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
list TCP Interactive mode example usage:
End Points v Using Jacl:
continued
$AdminTask
listTCPEndPoints
{-interactive}
v Using Jython:
AdminTask
.listTCPEndPoints
(’[-interactive]’)

list TCP None The list TCP v Parameters: None Batch mode example usage:
Thread TCP Thread Inbound v Using Jacl:
v Returns: A list of
Pools Pools Channel or
eligible thread pool $AdminTask
command TCP
object names. listTCPThreadPools
lists all of Outbound TCP_1(cells
the thread Channel /rohitbuildCell01/
pools that instance for nodes
can be which /rohitbuildCellManager01
associated Thread Pool /servers/dmgr|server.xml#
with a TCP candidates TCPInboundChannel_1)
inbound are listed. v Using Jython:
channel or (Object
AdminTask
TCP Name, .listTCPThreadPools
outbound required) (’TCP_1(cells
channel. /rohitbuildCell01/
nodes
/rohitbuildCellManager01
/servers
/dmgr|server.xml#
TCPInboundChannel_1)’)

Interactive mode example usage:

v Using Jacl:
$AdminTask
listTCPThreadPools
{-interactive}
v Using Jython:
AdminTask
.listTCPThreadPools
(’[-interactive]’)

Chapter 4. Using the administrative clients 771

list Unmanaged Use the list None v Parameters: None Batch mode example usage:
Unmanaged Node Unmanaged v Using Jacl:
v Returns: List
Nodes Commands Nodes
$AdminTask
group command to
listUnmanagedNodes
list the
unmanaged v Using Jython:
nodes in a AdminTask
configuration. .listUnmanagedNodes()

Interactive mode example usage:

v Using Jacl:
$AdminTask
listUnmanagedNodes
{-interactive}
v Using Jython:
AdminTask
.listUnmanagedNodes
(’[-interactive]’)

772 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
mediate SIB Admin Use the None v Parameters: Batch mode example usage:
SIB Commands mediate v Using Jacl:
Destination SIB bus
the name of the $AdminTask mediateSIBDestination
Destination
bus where the {-bus busname -name
command to destname -mediationName
mediate a destination is to
mediationName}
bus be mediated
destination. (String, required) v Using Jython:
The bus, AdminTask.mediateSIBDestination
destinationName (’[-bus busname -name
destination, the name of the
and destname -mediationName
destination to be mediationName]’)
mediation mediated (String,
definitions required) Interactive mode example usage:
must exist
prior to mediationName v Using Jacl:
using this the name to be $AdminTask mediateSIBDestination
command. given to the {-interactive}
The mediation v Using Jython:
destination (String, required)
AdminTask.mediateSIBDestination
must not be (’[-interactive]’)
node
mediated
if mediating a
already.
destination to a
server, specify
the node and
server name, but
not the cluster
name (String,
optional)
server
if mediating a
destination to a
server, specify
the node and
server name, but
not the cluster
name (String,
optional)
cluster
if mediating a
destination to a
cluster, specify
the cluster name,
but not the node
or server name
(String, optional)
v Returns: None

Chapter 4. Using the administrative clients 773

modify Node The modify The target v Parameters: Batch mode example usage:
Node Group Node object is the v Using Jacl:
Group Commands Group node group - shortName
The short name $AdminTask modifyNodeGroup
group command name. This
of the node WBINodeGroup {-shortName WBIGroup
modifies the target object -description "Default node group"}
configuration is required. group. This
of a node parameter is v Using Jython:
group. The optional. AdminTask.modifyNodeGroup
node group WBINodeGroup(’[-shortName WBIGroup
- description -description "WBI" node
name can The description
not be group]’)
of the node
changed. group. This Interactive mode example usage:
However, its parameter is
short name v Using Jacl:
optional.
and $AdminTask modifyNodeGroup
description v Returns: Node group {-interactive}
are allowed. object ID.
v Using Jython:
Also, its
AdminTask.modifyNodeGroup
node (’[-interactive]’)
membership
can be
modified.
modify Node The modify The name v Parameters: Batch mode example usage:
Node Group Node of the node v Using Jacl:
Group Commands Group group. This - name
The name of the $AdminTask modifyNodeGroupProperty
Property group Property target object
custom property WBINodeGroup {-name Channel -value
command is required. "channel1"}
modifies to modify. This
custom parameter is v Using Jython:
properties required. AdminTask.modifyNodeGroupProperty
for a node (’WBINodeGroup’, ’[-name Channel
- value -value channel1]’)
group The value of the
custom property. Interactive mode example usage:
This parameter is
v Using Jacl:
optional.
$AdminTask modifyNodeGroupProperty
- description {-interactive}
The description v Using Jython:
of the custom
property. This AdminTask.modifyNodeGroupProperty
(’[-interactive]’)
parameter is
optional.
v Returns: Properties
object ID

774 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
modify SIB SIB Admin Use the None v Parameters: Batch mode example usage:
Destination Commands modify SIB v Using Jacl:
Destination bus
bus name $AdminTask modifySIBDestination
command to
(String, required) {-bus busname -name
modify the destname}
attributes of name
a SIB v Using Jython:
destination name
destination. AdminTask.modifySIBDestination
(String, required)
The bus and (’[-bus busname -name
name description destname]’)
parameters description
are used to (String, optional) Interactive mode example usage:
identify the v Using Jacl:
reliability
SIB $AdminTask modifySIBDestination
the reliability
destination {-interactive}
quality of service
and cannot v Using Jython:
for message
be modified.
flows through AdminTask.modifySIBDestination
this destination, (’[-interactive]’)
from
BEST_EFFORT
_NON-
PERSISTENT to
ASSURED
_PERSISTENT,
in order of
increasing
reliability. Higher
levels of
reliability have
higher impacts
on the
performance
(String, optional)
maxReliability
the maximum
reliability quality
of service that is
accepted for
values specified
by producers
(String, optional)
overrideOf QOSBy
ProducerAllowed
controls the
quality of service
for message
flows between
producers and
the destination.
Select this option
to use the quality
of service
specified by
producers
instead of the
quality defined
for the
destination
(String, optional)

Chapter 4. Using the administrative clients 775

modify SIB v Parameters:
Destination
continued defaultPriority
the default
priority for
message flows
through this
destination, in
the range 0
(lowest) through
9 (highest). This
default priority is
used for
messages that
do not contain a
priority value
(Integer, optional)
maxFailed
Deliveries
the maximum
number of times
that service tries
to deliver a
message to the
destination
before forwarding
it to the
exception
destination
(Integer, optional)
exception
Destination
the name of
another
destination to
which the system
sends a
message that
cannot be
delivered to this
destination within
the specified
maximum
number of failed
deliveries (String,
optional)
sendAllowed
clear this option
(setting it to
false) to stop
producers from
being able to
send messages
to this
destination
(String, optional)
receiveAllowed
clear this option
(setting it to
false) to prevent
776 consumers
IBM WebSphere Application Server Network Deployment, Version from
6: Administering applications and their environment
being able to
receive
messages from
modify SIB SIB Admin Use the None v Parameters: Batch mode example usage:
Engine Commands modify SIB v Using Jacl:
Engine bus
the name of the $AdminTask modifySIBEngine
command to
bus to which the {-bus busname -node
modify the nodeName -server
attributes of messaging
severname}
a bus engine is to
belong (String, v Using Jython:
messaging
engine. The required) AdminTask.modifySIBEngine
bus, node, (’[-bus busname -node
node nodeName -server
server, to modify a severname]’)
cluster and messaging
engine engine on a Interactive mode example usage:
parameters server, supply
are used to v Using Jacl:
node and server
identify the $AdminTask modifySIBEngine
name, but not
engine and {-interactive}
cluster name
cannot be (String, optional) v Using Jython:
modified. A AdminTask.modifySIBEngine
server can server (’[-interactive]’)
only have to modify a
one messaging
messaging engine on a
engine, so server, supply
when using node and server
this name, but not
command to cluster name
modify a (String, optional)
messaging
cluster
engine from
to modify a
a server
messaging
there‘s no
engine on a
need to
cluster, supply
supply the
cluster name, but
engine
not node and
name.
server name
However,
(String, optional)
since a
cluster can engine
have more the name of the
than one engine to be
messaging modified. This is
engine, the only required if
engine‘s the engine
name must belongs to a
be supplied. cluster (String,
optional)
description
description of the
messaging
engine (String,
optional)

Chapter 4. Using the administrative clients 777

modify SIB v Parameters:
Engine
continued initialState
whether the
messaging
engine is started
or stopped when
the associated
application
server is first
started. Until
started, the
messaging
engine is
unavailable.
(Stopped |
Started) (String,
optional)
destination
HighMsgs
the maximum
total number of
messages that
the messaging
engine can place
on its message
points (Long,
optional)
v Returns: None
modify SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Admin modify SIB v Using Jacl:
Activation Commands JMS name
The name of the $AdminTask
Spec Activation
activation modifySIBJMSActivationSpec
Spec {-name specname
command to specification that
-propertyList propertyList}
modify the you want to
modify. (String, v Using Jython:
properties of
an activation (required) AdminTask.modifySIBJMSActivationSpec
specification. (’[-name specname
propertyList -propertyList propertyList]’)
A list of
name-value Interactive mode example usage:
pairs. (required) v Using Jacl:
v Returns: None $AdminTask
modifySIBJMSActivationSpec
{-interactive}
v Using Jython:
AdminTask.modifySIBJMSActivationSpec
(’[-interactive]’)

778 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
modify SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Admin modify SIB v Using Jacl:
Connection Commands JMS name
The name of the $AdminTask
Factory Connection
SIB JMS modifySIBJMSConnectionFactory
Factory {-name factory_name
command to connection
-jndiName jndi_name}
modify a factory. (String,
required) v Using Jython:
unified JMS
connection AdminTask
jndiName .modifySIBJMSConnectionFactory
factory at The JNDI name
the current (’[-name factory_name
of the SIB JMS -jndiName jndi_name]’)
scope. connection
factory. (String, Interactive mode example usage:
required) v Using Jacl:
type $AdminTask
The type of modifySIBJMSConnectionFactory
connection {-interactive}
factory to modify. v Using Jython:
To modify a AdminTask
queue .modifySIBJMSConnectionFactory
connection (’[-interactive]’)
factory, set the
value to Queue.
To modify a topic
connection
factory, set the
value to Topic. If
you want to
create a generic
connection
factory, do not
specify this
option. (String,
optional)
busName
the SIB bus
name (String,
optional)
category
Classifies or
groups the
connection
factory. (String,
optional)
clientID
A user-defined
string. Only
required for
durable
subscriptions.
(String, optional)
connection
Proximity
The proximity of
acceptable
messaging
engines. Valid
values include:
Bus, Host,
Cluster and Chapter 4. Using the administrative clients 779
Server. (String,
optional)
modify SIB v Parameters:
JMS
Connection durable
Factory Subscription Home
continued The durable
subscription
home value.
(String, optional)
nonPersistent
Mapping
The
non-persistent
mapping value.
Valid values are
BestEffort
NonPersistent,
Express
NonPersistent,
Reliable
NonPersistent,
ReliablePersistent,
AssuredPersistent,
AsSIBDestination
and None.
(String, optional)
password
The password
that is used to
modify
connections from
the connection
factory. (String,
optional)
provider EndPoints
A list of endpoint
triplets separated
by commas. For
example:
host:port:
chain (String,
optional)
readAhead
The read ahead
value. Valid
values include:
Default,
AlwaysOn, and
AlwaysOff.
(String, optional)
remoteProtocol
The name of the
protocol used to
connect to a
remote
messaging
engine. (String,
optional)
remoteTarget
Group
780 IBM WebSphere Application Server Network Deployment, Version 6: Administering
(String, optional) applications and their environment

remoteTargetType
(String, optional)
modify SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Queue Admin modify SIB v Using Jacl:
Commands JMS Queue name
The name of the $AdminTask modifySIBJMSQueue
command to
SIB JMS queue. {-name queue_name
modify a -jndiName jndi_name
unified JMS (String, required)
-queueName queue_name}
queue at the jndiName v Using Jython:
current The JNDI name
scope. AdminTask.modifySIBJMSQueue
of the SIB JMS (’[-name queue_name
queue. (String, -jndiName jndi_name
required) -queueName queue_name]’)
description
Interactive mode example usage:
A description of
the SIB JMS v Using Jacl:
queue (String, $AdminTask modifySIBJMSQueue
optional) {-interactive}

queueName v Using Jython:

The name of the AdminTask.modifySIBJMSQueue
underlying SIB (’[-interactive]’)
queue to which
the queue points
(String, required)
deliveryMode
The delivery
mode for
messages. Legal
values are
″Application″,
″NonPersistent″
and ″Persistent″
(String, optional)
timeToLive
the time in
milliseconds to
be used for
message
expiration (Long,
optional)
priority
the priority for
messages.
Whole number in
the range 0 to 9
(Integer, optional)
readAhead
read-ahead
value. Legal
values are
″AsConnection″,
″AlwaysOn″ and
″AlwaysOff″
(String, optional)
timeToLive
(optional)
v Returns: None

Chapter 4. Using the administrative clients 781

modify SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Topic Admin modify SIB v Using Jacl:
Commands JMS Topic name
The name of the $AdminTask modifySIBJMSTopic
command to
SIB JMS topic {-name topic_name -jndiName
modify the jndi_name -topicName
JMS topic at (String, required)
topic_name -topicSpace
the current jndiName topicspace_name}
scope. the SIB JMS v Using Jython:
topic’s JNDI AdminTask.modifySIBJMSTopic
name (String, (’[-name topic_name
required) -jndiName jndi_name
-topicName topic_name
description
-topicSpace topicspace_name]’)
a description of
the SIB JMS Interactive mode example usage:
queue (String,
v Using Jacl:
optional)
$AdminTask modifySIBJMSTopic
topicSpace {-interactive}
the name of the
v Using Jython:
underlying SIB
topic space to AdminTask.modifySIBJMSTopic
which the topic (’[-interactive]’)
points (String,
required)
*topicName
the topic to be
used inside the
topic space (for
example,
stock/IBM)
(String, required)
deliveryMode
the delivery
mode for
messages. Legal
values are
″Application″,
″NonPersistent″
and ″Persistent″
(String, optional)
timeToLive
the time in
milliseconds to
be used for
message
expiration (Long,
optional)
priority
the priority for
messages.
Whole number in
the range 0 to 9
(Integer, optional)

782 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
modify SIB v Parameters:
JMS Topic
continued readAhead
read-ahead
value. Legal
values are
″AsConnection″,
″AlwaysOn″ and
″AlwaysOff″
(String, optional)
busName
the name of the
bus on which the
topic resides
(String, optional)
v Returns: None

Chapter 4. Using the administrative clients 783

modify SIB SIB Admin Use this None v Parameters: Batch mode example usage:
Mediation Commands command to v Using Jacl:
modify the bus
the name of the $AdminTask modifySIBMediation
attributes of
bus that owns {-bus bus_name -jndiName
a SIB jndi_name}
mediation. the mediation
The bus and (String, required) v Using Jython:
mediation AdminTask.modifySIBMediation
mediationName
Name (’[-bus bus_name
name of the -mediationName
parameters mediation to be
identify the mediation_name]’)
modified (String,
mediation required) Interactive mode example usage:
and cannot
be modified. description v Using Jacl:
description of the $AdminTask modifySIBMediation
mediation {-interactive}
(String, optional) v Using Jython:
handlerList Name AdminTask.modifySIBMediation
the name of the (’[-interactive]’)
handler list that
was defined
when the
mediation was
deployed (String,
optional)
globalTransaction
whether or not a
global
transaction is
started for each
message
processed
(Boolean,
optional)
allowConcurrent
Mediation
whether or not to
apply the
mediation to
multiple
messages
concurrently, and
preserve
message
ordering
(Boolean,
optional)
selector
the text string
that must be
present in a
message for the
mediation to
process the
message (String,
optional)
discriminator
the text string
that must not be
784 present
IBM WebSphere Application Server Network Deployment, Version in a
6: Administering applications and their environment
message for the
mediation to
process the
modify SIB Admin Use this None v Parameters: Batch mode example usage:
SIBus Commands command to v Using Jacl:
modify the bus
name of bus to $AdminTask modifySIBus {-bus
attributes of
modify (String, busname -description text -secure True
the named -mediationsAuthAlias name
bus. He required)
-protocol protocol
“bus” description -discardOnDelete False}
parameter description of v Using Jython:
identifies the bus modify
bus to be AdminTask.modifySIBus
(String, optional) (’[-busbusname -description
modified,
secure "text" -secure True
and is not
-mediationsAuthAlias name
used to enable or disable
-protocol protocol
change the bus security -discardOnDelete False]’)
name of the (Boolean,
bus. optional) Interactive mode example usage:
interEngineAuthAlias v Using Jacl:
name of the $AdminTask modifySIBus
authentication {-interactive}
alias used to v Using Jython:
authorize
communication AdminTask.modifySIBus
(’[-interactive]’)
between
messaging
engines on the
bus.
mediations
AuthAlias
name of the
authentication
alias used to
authorize
mediations to
access the bus
(String, optional)
protocol
the protocol used
to send and
receive
messages
between
messaging
engines, and
between API
clients and
messaging
engines (String,
optional)

Chapter 4. Using the administrative clients 785

modify v Parameters:
SIBus
continued discardOnDelete
indicate whether
or not any
messages left in
a queue’s data
store should be
discarded when
the queue is
deleted
(Boolean,
optional)
destination
HighMsgs
the maximum
number of
messages that
any queue on
the bus can hold
(Long, optional)
configuration
ReloadEnabled
indicate whether
configuration files
should be
dynamically
reloaded for this
bus (Boolean,
optional)
v Returns: None

786 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
modify SIB Admin Use this None v Parameters: Batch mode example usage:
SIBus Commands command to v Using Jacl:
Member modify the bus
name of bus to $AdminTask modifySIBusMember
attributes of
which the {-bus busname -node
the bus nodename -server
member member
servername -description
identified by belongs(String, text}
the bus, required)
v Using Jython:
node, server node
and cluster AdminTask.modifySIBusMember
to specify a (’[-bus busname -node
parameters. server bus nodename -server
member, supply servername -description
node and server "text"]’)
name, but not
cluster name Interactive mode example usage:
(String, optional) v Using Jacl:
server $AdminTask modifySIBusMember
to specify a {-interactive}
server bus v Using Jython:
member, supply AdminTask.modifySIBusMember
node and server (’[-interactive]’)
name, but not
cluster name
(String, optional)
cluster
to specify a
cluster bus
member, supply
cluster name but
not node and
server name
(String, optional)
v Returns: None

Chapter 4. Using the administrative clients 787

move Core The move None v Parameters: Batch mode example usage:
Cluster To Group Cluster To v Using Jacl:
Core Group ManagementCore Group - source
The name of the $AdminTask moveClusterToCoreGroup
group command
core group that {-source OldCoreGroup
moves all of -target NewCoreGroup
servers in a contains the
-clusterName ClusterOne}
cluster that cluster that you
want to move. v Using Jython:
you specify
from a core The core group AdminTask.moveClusterToCoreGroup
group to must exist prior (’[-source OldCoreGroup
another core to running this -target NewCoreGroup
command. The -clusterName ClusterOne]’)
group. All of
the servers cluster that you
Interactive mode example usage:
in cluster specify must be
must be a member of this v Using Jacl:
members of core group. $AdminTask moveClusterToCoreGroup
the same (String, required) {-interactive}
core group. - target v Using Jython:
The name of the AdminTask.moveClusterToCoreGroup
core group (’[-interactive]’)
where you want
to move the
cluster. (String,
required)
- clusterName
The name of the
cluster that you
want to move.
(String, required)
v Returns: None

788 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
move Core The move None v Parameters: Batch mode example usage:
Server To Group Server To v Using Jacl:
Core Group ManagementCore Group - source
The name of the $AdminTask moveServerToCoreGroup
group command
core group that {-source OldCoreGroup
moves a -target NewCoreGroup
server to a contains the
-nodeName myNode -serverName
core group server that you myServer}
that you want to move.
The core group v Using Jython:
specify.
When the must already AdminTask.moveServerToCoreGroup
server is exist with the (’[-source OldCoreGroup
server that you -target NewCoreGroup
added to the
specify being a -nodeName myNode -serverName
core group myServer]’)
that you member of the
specify, it core group. Interactive mode example usage:
will be (String, required)
v Using Jacl:
removed - target
from the $AdminTask moveServerToCoreGroup
The name of the {-interactive}
core group core group
where it v Using Jython:
where you want
originally to move the AdminTask.moveServerToCoreGroup
resided. server. The core (’[-interactive]’)
group that you
specify must
exist prior to
running the
command.
(String, required)
- nodeName
The name of the
node that
contains the
server that you
want to move.
(String, required)
- serverName
The name of the
server that you
want to move.
(String, required)
v Returns: None

Chapter 4. Using the administrative clients 789

publish SIB SIB Web The publish The object v Parameters: Batch mode example usage:
WS Services SIB WS name of the v Using Jacl:
Inbound group Inbound inbound uddiPublication
The name of the $AdminTask
Service Service service
UDDI publication publishSIBWSInboundService
command object. $inService {-uddiPublication
publishes for the service.
"MyUddi"}
the WSDL (required)
v Using Jython:
document userId
for the AdminTask.publishSIBWSInboundService
The user ID to (inService, ’[-uddiPublication
inbound use to retrieve
service and MyUddi]’)
the WSDL.
the (optional) Interactive mode example usage:
associated
ports to the password v Using Jacl:
registry and The password to $AdminTask
business use to retrieve publishSIBWSInboundService
defined by the WSDL. {-interactive}
the UDDI (optional) v Using Jython:
Publication v Returns: None AdminTask.publishSIBWSInboundService
object. (’[-interactive]’)

reconfigure Interactive mode example usage:

TAM v Using Jacl:
$AdminTask reconfigureTAM
{-interactive}
v Using Jython:
AdminTask.reconfigureTAM
(’[-interactive]’)

790 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
refresh SIB SIB Web The refresh The object v Parameters: Batch mode example usage:
WS Services SIB WS name of the v Using Jacl:
Inbound group Inbound inbound userId
The user ID to $AdminTask
Service Service service
use to retrieve refreshSIBWSInboundServiceWSDL
WSDL WSDL object. $inService
command the WSDL.
loads the (optional) v Using Jython:
WSDL AdminTask
password
document .refreshSIBWSInboundServiceWSDL
The password to (inService)
from the use to retrieve
WSDL the WSDL. Interactive mode example usage:
Location (optional)
parameters v Using Jacl:
of the v Returns: None
$AdminTask
inbound refreshSIBWSInboundServiceWSDL
service and {-interactive}
locates the v Using Jython:
WSDL
AdminTask
Location .refreshSIBWSInboundServiceWSDL
-specified (’[-interactive]’)
service
element. If
the service
element is
not present,
this
command
fails. If the
outbound
ports are
not a subset
of the ports
in the
loaded
WSDL
document,
this
command
fails.

If the WSDL
will be
retrieved
through a
proxy, the
server on
which the
command is
running
must have
the system
properties
that identify
the proxy
server set
correctly.

Chapter 4. Using the administrative clients 791

refresh SIB SIB Web The refresh The object v Parameters: Batch mode example usage:
WS Services SIB WS name of the v Using Jacl:
Outbound group Outbound outbound userId
The user ID to $AdminTask
Service Service service
use to retrieve refreshSIBWSOutboundServiceWSDL
WSDL WSDL object. $outService
command the WSDL.
loads the (optional) v Using Jython:
WSDL AdminTask
password
document .refreshSIBWSOutboundServiceWSDL
The password to (outService)
from the use to retrieve
WSDL the WSDL. Interactive mode example usage:
Location (optional)
parameters v Using Jacl:
of the v Returns: None
$AdminTask
outbound refreshSIBWSOutboundServiceWSDL
service and {-interactive}
locates the v Using Jython:
WSDL
AdminTask
Location .refreshSIBWSOutboundServiceWSDL
specified (’[-interactive]’)
service
element. If
the service
element is
not present,
this
command
fails. If the
outbound
ports are
not a subset
of the ports
in the
loaded
WSDL
document,
this
command
fails.

If the WSDL
will be
retrieved
through a
proxy, the
server on
which the
command is
running
must have
the system
properties
that identify
the proxy
server set
correctly.

792 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
remove Node The remove The name v Parameters: None Batch mode example usage:
Node Group Node of the node v Using Jacl:
v Returns: Node group
Group Commands Group group to be
object ID. $AdminTask removeNodeGroup
group command removed.
WBINodeGroup
removes the This target
configuration object is v Using Jython:
of a node required. AdminTask.removeNodeGroup
group. You (’WBINodeGroup’)
can remove
a node Interactive mode example usage:
group if it v Using Jacl:
does not $AdminTask removeNodeGroup
contain any {-interactive}
members.
v Using Jython:
Also, the
default node AdminTask.removeNodeGroup
group can (’[-interactive]’)
not be
removed.
remove Node The remove The target v Parameters: Batch mode example usage:
Node Group Node object is the v Using Jacl:
Group Commands Group node group - nodeName
The name of the $AdminTask removeNodeGroupMember
Member group Member containing
node to be WBINodeGroup {-nodeName WBINode}
command the member
removes the to be removed from a v Using Jython:
configuration removed. node group. This AdminTask.removeNodeGroupMember
of a node This target parameter is (’WBINodeGroup’,
group object is required. ’[-nodeName WBINode]’)
member. required. v Returns: Node group
Interactive mode example usage:
v A node member object ID.
must v Using Jacl:
always be $AdminTask removeNodeGroupMember
a {-interactive}
member v Using Jython:
of at least AdminTask.removeNodeGroupMember
one node (’[-interactive]’)
group.
v You
cannot
remove a
node
from a
node
group
that is
part of a
cluster in
that node
group.

Chapter 4. Using the administrative clients 793

remove Node The remove The name v Parameters: Batch mode example usage:
Node Group Node of the node v Using Jacl:
Group Commands Group group. This - name
The name of the $AdminTask removeNodeGroupProperty
Property group Property target object
custom property WBINodeGroup {-name Channel}
command is required.
removes to remove. This v Using Jython:
custom parameter is AdminTask.removeNodeGroupProperty
properties of required. (’WBINodeGroup’,
a node v Returns: Properties ’[-name Channel]’)
group. object ID
Interactive mode example usage:
v Using Jacl:
$AdminTask removeNodeGroupProperty
{-interactive}
v Using Jython:
AdminTask.removeNodeGroupProperty
(’[-interactive]’)

remove SIB SIB Web The remove The object v Parameters: None Batch mode example usage:
WS Services SIB WS name of the v Using Jacl:
v Returns: None
Inbound group Inbound inbound port
$AdminTask removeSIBWSInboundPort
Port Port object that
$inPort
command you want to
removes the remove. v Using Jython:
configuration AdminTask
of an .removeSIBWSInboundPort(inPort)
inbound
port. Interactive mode example usage:
v Using Jacl:
$AdminTask removeSIBWSInboundPort
{-interactive}
v Using Jython:
AdminTask.removeSIBWSInboundPort
(’[-interactive]’)

794 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
remove SIB SIB Web The remove Object v Parameters: None Batch mode example usage:
WS Services SIB WS name of the v Using Jacl:
v Returns: None
Outbound group Outbound outbound
$AdminTask removeSIBWSOutboundPort
Port Port port object
$outPort
command that you
removes the want to v Using Jython:
configuration remove. AdminTask.removeSIBWSOutboundPort
of an (outPort)
outbound
port. If the Interactive mode example usage:
port that you v Using Jacl:
delete is the $AdminTask removeSIBWSOutboundPort
default port {-interactive}
for the
v Using Jython:
outbound
service, one AdminTask.removeSIBWSOutboundPort
of the (’[-interactive]’)
remaining
ports, if any,
will be
chosen as
the new
default.
Resources
that are
associated
with the
outbound
port, for
example,
WS-Security
configuration,
are
disassociated
from the
outbound
port but not
deleted.

Chapter 4. Using the administrative clients 795

remove SI SIB Admin Use this None v Parameters: Batch mode example usage:
Bus Commands command to v Using Jacl:
Member remove a bus
name of SIB bus $AdminTask removeSIBusMember
server or a
to remove {-bus busname -node
cluster from nodename -server
a SIB bus. member from
servername}
As well as (String, required)
v Using Jython:
removing node
the server AdminTask.removeSIBusMember
to specify a (’[-bus busname -node
or cluster server bus
from the SIB nodename -server
member, supply servername]’)
bus, this node and server
command name, but not Interactive mode example usage:
also deletes cluster name
all SIB v Using Jacl:
(String, optional)
messaging $AdminTask removeSIBusMember
engines server {-interactive}
associated to specify a v Using Jython:
with the server bus
AdminTask.removeSIBusMember
bus, all member, supply (’[-interactive]’)
queue node and server
points and name, but not
publication cluster name
points (String, optional)
owned by
cluster
those
to specify a
engines,
cluster bus
and all
member, supply
queue point
cluster name but
references
not node and
and
server name
publication
(String, optional)
point
references v Returns:
which refer
to the
deleted
queue
points and
publication
points.
remove Unmanaged Use the None v Parameters: Batch mode example usage:
Unmanaged Node remove v Using Jacl:
Node Commands Unmanaged - nodeName
The name of the $AdminTask removeUnmanagedNode
group Node
unmanaged {-nodeName myNode }
command to
remove an node. (String, v Using Jython:
unmanaged required) AdminTask.removeUnmanagedNode
node from v Returns: null (’[-nodeName myNode]’)
the
configuation. Interactive mode example usage:
v Using Jacl:
$AdminTask removeUnmanagedNode
{-interactive}
v Using Jython:
AdminTask.createUnmanagedNode
(’[-interactive]’)

796 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
remove WS WS The remove object name v Parameters: None Batch mode example usage:
GW Target Gateway WS GW of the Target v Using Jacl:
v Returns: None
Service group Target Service
$AdminTask removeWSGWTargetService
Service object
$gwTarget
command
removes a v Using Jython:
target AdminTask.removeWSGWTargetService
service from (gwTarget)
the gateway
service. The Interactive mode example usage:
destinations v Using Jacl:
that are $AdminTask removeWSGWTargetService
associated {-interactive}
with the
v Using Jython:
target
service are AdminTask.removeWSGWTargetService
not deleted. (’[-interactive]’)
If the target
service that
you remove
is the
default
target
service, the
default is
set to the
first target
service in
the set or
cleared if
there are
none left.
set Default SIB Web The set The object v Parameters: Batch mode example usage:
SIB WS Services Default SIB name of the v Using Jacl:
Outbound group WS outbound name
The name of the $AdminTask
Port Outbound service
port that you setDefaultSIBWSOutboundPort
Port whose $outService {-name "MyServiceSoap"}
command default port want to set as
updates the you want to the default. v Using Jython:
default update. (required) AdminTask
outbound v Returns: None .setDefaultSIBWSOutboundPort
port for an (outService, ’[-name MyServiceSoap]’)
outbound
Interactive mode example usage:
service.
v Using Jacl:
$AdminTask
setDefaultSIBWSOutboundPort
{-interactive}
v Using Jython:
AdminTask
.setDefaultSIBWSOutboundPort
(’[-interactive]’)

Chapter 4. Using the administrative clients 797

show SIB SIB Admin Use the None v Parameters: Batch mode example usage:
Destination Commands show SIB v Using Jacl:
Destination bus
bus name $AdminTask showSIBDestination
command to
(String, required) {-bus busname -name
get the destname}
attribute name
names/values v Using Jython:
destination name
of a SIB AdminTask.showSIBDestination
(String, required)
destination. (’[-bus busname -name
The bus and v Returns: The attribute destname]’)
name names and values of
the named SIB Interactive mode example usage:
parameter
identify the destination on the v Using Jacl:
SIB named bus.
$AdminTask showSIBDestination
destination {-interactive}
whose v Using Jython:
attributes
AdminTask.showSIBDestination
are
(’[-interactive]’)
required.

798 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
show SIB SIB Admin Use the None v Parameters: Batch mode example usage:
Engine Commands show SIB v Using Jacl:
Engine bus
the name of the $AdminTask showSIBEngine {-bus
command to
bus to which the busname -node nodeName
get the -server severname}
attribute messaging
names/values engine to be v Using Jython:
of a SIB shown belongs AdminTask.showSIBEngine(’[-bus
messaging (String, required) busname -node nodeName
engine -server severname]’)
node
belonging to to show a Interactive mode example usage:
a given bus messaging
member. If v Using Jacl:
engine that
the bus belongs to a $AdminTask showSIBEngine
member is a server, supply {-interactive}
server, only node and server v Using Jython:
the bus, name, but not AdminTask.showSIBEngine
node and cluster name (’[-interactive]’)
server (String, optional)
parameters
need be server
supplied. A to show a
server only messaging
has 1 engine that
engine, so belongs to a
the engine server, supply
parameter is node and server
not name, but not
necessary. If cluster name
the bus (String, optional)
member is a
cluster
cluster, the
to show a
bus, cluster
messaging
and engine
engine that
parameters
belongs to a
must be
cluster, supply
supplied,
cluster name, but
since a
not node and
cluster can
server name
have more
(String, optional)
than one
engine. engine
The name of the
engine to show.
If the bus
member has only
one messaging
engine, you do
not need to
specify the
engine option. If
the bus member
has several
messaging
engines, you
must specify the
name of the
engine for which
you want to
display details.
(String, optional)
v Returns: The attribute
names and values Chapter
of 4. Using the administrative clients 799
the identified SIB
messaging engine.
show SIB SIB Admin The show None v Parameters: Batch mode example usage:
JMS Commands SIB JMS v Using Jacl:
Activation Activation bus
The name of the $AdminTask showSIBJMSActivationSpec
Spec Spec
bus that owns {-bus bus_name
command -mediationName mediation_name}
shows the mediation
details (String, required) v Using Jython:
about a AdminTask.showSIBJMSActivationSpec
mediationName
JMS (’[-bus bus_name
The name of the -mediationName
activation mediation to be
specification. mediation_name]’)
shown (String,
required) Interactive mode example usage:
v Returns: A list v Using Jacl:
$AdminTask showSIBJMSActivationSpec
{-interactive}
v Using Jython:
AdminTask.showSIBJMSActivationSpec
(’[-interactive]’)

show SIB SIB JMS The show None v Parameters: Batch mode example usage:
JMS Admin SIB JMS v Using Jacl:
Connection Commands Connection name
The name of the $AdminTask
Factory Factory
SIB JMS showSIBJMSConnectionFactory
command {-name factory_name}
shows connection
details factory (String, v Using Jython:
about a required) AdminTask
JMS v Returns: A set of .showSIBJMSConnectionFactory
connection property value pairs (’[-name factory_name]’)
factory. for the JMS
Interactive mode example usage:
connection factory
that you specified. v Using Jacl:
$AdminTask
showSIBJMSConnectionFactory
{-interactive}
v Using Jython:
AdminTask
.showSIBJMSConnectionFactory
(’[-interactive]’)

800 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
show SIB SIB JMS Use the None v Parameters: Batch mode example usage:
JMS Queue Admin show SIB v Using Jacl:
Commands JMS Queue name
The name of the $AdminTask showSIBJMSQueue
command to
SIB JMS queue. {-name queue_name}
show the
details (String, required) v Using Jython:
about a v Returns: A set of AdminTask.showSIBJMSQueue
JMS queue. property value pairs (’[-name queue_name]’)
for the JMS queue
that you specified. Interactive mode example usage:
v Using Jacl:
$AdminTask showSIBJMSQueue
{-interactive}
v Using Jython:
AdminTask.showSIBJMSQueue
(’[-interactive]’)

show SIB SIB JMS Use this None v Parameters: Batch mode example usage:
JMS Topic Admin command to v Using Jacl:
Commands show the - name
The name of the $AdminTask showSIBJMSTopic
details for a
SIB JMS topic {-name topic_name}
JMS topic.
(String, required) v Using Jython:
v Returns: A set of AdminTask.showSIBJMSTopic
property value pairs (’[-name topic_name]’)
for the JMS topic that
you specified. Interactive mode example usage:
v Using Jacl:
$AdminTask showSIBJMSTopic
{-interactive}
v Using Jython:
AdminTask.showSIBJMSTopic
(’[-interactive]’)

show SIB SIB Admin Use this None v Parameters: Batch mode example usage:
Mediation Commands command to v Using Jacl:
get the bus
the name of the $AdminTask showSIBMediation
attribute
bus that owns {-bus bus_name
names/values -mediationName mediation_name}
of a SIB the mediation
mediation. (String, required) v Using Jython:
AdminTask.showSIBMediation
mediationName
(’[-bus bus_name
the name of the -mediationName
mediation to be mediation_name]’)
shown (String,
required) Interactive mode example usage:
v Returns: The attribute v Using Jacl:
names and values of $AdminTask showSIBMediation
the identified SIB {-interactive}
mediation.
v Using Jython:
AdminTask.showSIBMediation
(’[-interactive]’)

Chapter 4. Using the administrative clients 801

show SIBus SIB Admin Use this None v Parameters: Batch mode example usage:
Commands command to v Using Jacl:
get the bus
bus name $AdminTask showSIBus {-bus
attribute
(String, required) bus_name}
names/values
of a SIB v Returns: The attribute v Using Jython:
bus. names and values of AdminTask.showSIBus(’[-bus
the identified SIB bus_name]’)
bus.
Interactive mode example usage:
v Using Jacl:
$AdminTask showSIBus {-interactive}
v Using Jython:
AdminTask.showSIBus
(’[-interactive]’)

show SIBus SIB Admin Use this None v Parameters: Batch mode example usage:
Member Commands command to v Using Jacl:
get the bus
name of bus to $AdminTask showSIBusMember
attribute
show member {-bus busname -node
names/values nodename -server
of a SIB bus from (String,
servername}
member. required)
v Using Jython:
node
AdminTask.showSIBusMember
to specify a (’[-bus busname -node
server bus nodename -server
member, supply servername]’)
node and server
name, but not Interactive mode example usage:
cluster name v Using Jacl:
(String, optional)
$AdminTask showSIBusMember
server {-interactive}
to specify a v Using Jython:
server bus
AdminTask.showSIBusMember
member, supply (’[-interactive]’)
node and server
name, but not
cluster name
(String, optional)
cluster
to specify a
cluster bus
member, supply
cluster name but
not node and
server name
(String, optional)
v Returns: The attribute
names and values of
the identified SIB bus
member.

802 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
show Interactive mode example usage:
Server Info v Using Jacl:
$AdminTask showServerInfo
{-interactive}
v Using Jython:
AdminTask.showServerInfo
(’[-interactive]’)

show Interactive mode example usage:

Server v Using Jacl:
Type Info
$AdminTask showServerTypeInfo
{-interactive}
v Using Jython:
AdminTask.showServerTypeInfo
(’[-interactive]’)

show None Use the The v Returns: A property Interactive mode example usage:
Template show identification object that holds the v Using Jacl:
Info Template of a server metadata information $AdminTask showTemplateInfo
Info template, regarding a specific {-interactive}
command to javax template.
query .management v Using Jython:
metadata .ObjectName. AdminTask.showTemplateInfo
information This target (’[-interactive]’)
for a object is
specific required.
template.
This
command
will only
work for
server
templates.
unconfig- Interactive mode example usage:
ure TAM v Using Jacl:
$AdminTask unconfigureTAM
{-interactive}
v Using Jython:
AdminTask.unconfigureTAM
(’[-interactive]’)

Chapter 4. Using the administrative clients 803

unmediate SIB Admin Use this None v Parameters: Batch mode example usage:
SIB Commands command to v Using Jacl:
Destination unmediated bus
the name of the $AdminTask unmediateSIBDestination
the named
bus where the {-bus bus_name
destination -destinationName
on the destination is
destination_name}
named bus. currently
Unmediating mediated (String, v Using Jython:
a required) AdminTask.unmediateSIBDestination
destination (’[-bus bus_name
destinationName -destinationName
simply the name of the destination_name]’)
removes the destination to be
association unmediated Interactive mode example usage:
between a (String, required) v Using Jacl:
SIB
destination v Returns: None $AdminTask unmediateSIBDestination
and a SIB {-interactive}
mediation. v Using Jython:
AdminTask.unmediateSIBDestination
(’[-interactive]’)

unpublish SIB Web The The object v Parameters: Batch mode example usage:
SIB WS Services unpublish name of the v Using Jacl:
Inbound group SIB WS inbound uddi Publication
The name of the $AdminTask
Service Inbound service
UDDI publication unpublishSIBWSInboundService
Service object. $inService {-uddiPublication
command for the service.
"MyUddi"}
removes the (required)
v Using Jython:
WSDL userId
document AdminTask
The user ID to .unpublishSIBWSInboundService
for the use to retrieve
inbound (inService, ’[-uddiPublication
the WSDL. MyUddi]’)
service, (optional)
including the Interactive mode example usage:
ports, from password
the registry The password to v Using Jacl:
and use to retrieve $AdminTask
business the WSDL. unpublishSIBWSInboundService
defined by (optional) {-interactive}
the UDDI v Returns: None v Using Jython:
publication AdminTask
object. .unpublishSIBWSInboundService
(’[-interactive]’)

804 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
update App None The update None v Parameters: Batch mode example usage:
On Cluster App On v Using Jacl:
Cluster -Application Names
The names of $AdminTask updateAppOnCluster
command
the applications {-ApplicationNames app1}
can be used
to that are updated. $AdminTask updateAppOnCluster
synchronize { -ApplicationNames app1
-timeout -timeout 600}
nodes and The timeout
restart v Using Jython:
value in seconds
cluster for each node AdminTask.updateAppOnCluster
members for synchronization. (’[-ApplicationNames app1]’)
an The default is AdminTask.updateAppOnCluster
application 300 seconds. (’[-ApplicationNames app1 -timeout 600]’)
update
deployed to v Returns: None Interactive mode example usage:
a cluster. v Using Jacl:
After
$AdminTask updateAppOnCluster
application
-interactive
update, this
command v Using Jython:
can be used AdminTask.updateAppOnCluster
to (’[-interactive]’)
synchronize
the nodes
without
stopping all
the cluster
members on
all the
nodes at
one time.

This
command
synchronizes
one node at
a time. Each
node is
synchronized
by first
stopping the
cluster
members on
which the
application
is targetted
and then
performing
nodesync
operation
and then
restarting
the cluster
members.

Chapter 4. Using the administrative clients 805

update App This
On Cluster command
may take
more than
the default
connector
timeout
period
depending
on the
number of
nodes that
the target
cluster
spans. Be
sure to set
proper
timeout
values in
the
soap.client
.props file,
when a
SOAP
connector is
used, and in
the
sas.client
.props file,
when a RMI
connector is
used.

This
command is
not
supported in
local mode.

Administrative command invocation syntax

You can use an administrative command in batch mode or interactive mode. The following is the syntax for
using an administrative command:

Using Jacl:
$AdminTask cmdName [targetObject] [options]

where options include:

{
[-paramName paramValue] [-paramName] ...
[-stepName {{stepParamValue ...} ...} ...]
[-delete {-stepName {{stepKeyParamValue ...} ...} ...} ...]
[-interactive]
}

Using Jython:
AdminTask.cmdName([’targetObject‘], [options])

where options include:

806 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
’[
[-paramName paramValue] [-paramName ...]
[-stepName [[stepParamValue ...] ...] ...]
[-delete [-collectionStepName [[stepKeyParamValue ...] ...] ...] ...]
[-interactive]
]‘

where:

cmdName represents the name of an administrative command to be run.

targetObject represents the target object on which the command operates. Depending on the
administrative command, this input can be required, optional, or nonexistent.
This input corresponds to the Target object that is displayed in the
command-specific help.
paramName represents the parameter name of the executed command. Depending on the
administrative command, this input can be required, optional, or nonexistent.
Each parameter name corresponds to an argument name that is displayed in the
Arguments area of the command specific help.
paramValue represents the parameter value to set for the preceding parameter name.
Parameters are specified as name-value pairs. The parameter value is not
required if a parameter has Boolean as its value type. If you specify the
parameter name only, without specifying a value for a Boolean type parameter,
the value is set to true.
stepName represents the step name of the command. This input corresponds to a step
name that is displayed in the Steps area of the command-specific help.
stepParamValue ... represents the values of the parameters for a step. Provide all the parameter
values of a step in the correct order as displayed in the step-specific help. For
any optional parameters that you do not want to specify a value, put ″″ instead
of the value. If a command step is a collection type, for example, it contains
multiple objects where each object has the same set of parameters, then you
can specify multiple objects with each object enclosed by a pair of braces. For
collection type steps, each step parameter is a key or non-key. Key parameters
in a step are used to uniquely identify an object in the collection. If data exists in
the step, key parameter values that are provided in the input are compared with
key parameter values in the existing data. If a match is found, the existing data
is updated. Otherwise, if the specified step allows the addition of new objects,
the input values are added.
delete represents the option to delete existing data from specified step that supports
collection.
collectionStepName represents the collection step name .
stepKeyParamValue ... represents the values of key parameters to uniquely identify an object to be
deleted from a collection step. You must provide the key parameter values of an
object in the order that they are displayed in the step specific help.
interactive represents the option to enter interactive mode.
[ ] represents a Jython list bracket.
[ ] indicates that the parameters or options inside the brackets are optional. Do not
type these brackets as part of the syntax.

Properties used by scripted administration

This article explains the Java properties that are used by scripted administration. Three levels of default
property files load before any property file that is specified on the command line. The first level represents
an installation default, located in the properties directory for each WebSphere Application Server profile
called wsadmin.properties. The second level represents a user default, and is located in the Java
user.home property. This properties file is also called wsadmin.properties. The third level is a properties
file that is pointed to by the WSADMIN_PROPERTIES environment variable. This environment variable is

Chapter 4. Using the administrative clients 807

defined in the environment where the wsadmin tool starts. If one or more of these property files is present,
they are interpreted before any properties file that is present on the command line. These three levels of
property files load in the order that they are specified. The properties file that is loaded last overrides the
ones loaded earlier.

The following Java properties are used by scripting:

com.ibm.ws.scripting.classpath:

Searches for classes and resources, and is appended to the list of paths.

com.ibm.ws.scripting.connectionType:

Determines the connector to use. This value can either be SOAP, RMI, or NONE. The wsadmin.properties file
specifies SOAP as the connector.

com.ibm.ws.scripting.host:

Determines the host to use when attempting a connection. If not specified, the default is the local machine.

com.ibm.ws.scripting.port:

Specifies the port to use when attempting a connection. The wsadmin.properties file specifies 8879 as the
SOAP port for a single server installation.

com.ibm.ws.scripting.defaultLang:

Indicates the language to use when running scripts. The wsadmin.properties file specifies Jacl as the
scripting language.

The supported scripting languages are Jacl and Jython.

com.ibm.ws.scripting.traceString:

Turns on tracing for the scripting process. The default has tracing turned off.

com.ibm.ws.scripting.traceFile:

Determines where trace and log output is directed. The wsadmin.properties file specifies the
wsadmin.traceout file that is located in the logs directory of each WebSphere Application Server profile as
the value of this property.

If multiple users work with the wsadmin tool simultaneously, set different traceFile properties in the user
properties files. If the file name contains double-byte character set (DBCS) characters, use a unicode
format, such as \uxxxx, where xxxx is a number.

com.ibm.ws.scripting.validationOutput:

Determines where the validation reports are directed. The default file is wsadmin.valout which is located in
the logs directory of each WebSphere Application Server profile.

If multiple users work with the wsadmin tool simultaneously, set different validationOutput properties in the
user properties files. If the file name contains double-byte character set (DBCS) characters, use unicode
format, such as \uxxxx, where xxxx is a number.

com.ibm.ws.scripting.emitWarningForCustomSecurityPolicy:

808 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Controls whether the WASX7207W message is emitted when custom permissions are found.

The possible values are true and false. The default value is true.

com.ibm.ws.scripting.tempdir:

Determines the directory to use for temporary files when installing applications.

The Java virtual machine API uses java.io.temp as the default value.

com.ibm.ws.scripting.validationLevel:

Determines the level of validation to use when configuration changes are made from the scripting
interface.

Possible values are: NONE, LOW, MEDIUM, HIGH, HIGHEST. The default is HIGHEST.

com.ibm.ws.scripting.crossDocumentValidationEnabled:

Determines whether the validation mechanism examines other documents when changes are made to one
document.

Possible values are true and false. The default value is true.

com.ibm.ws.scripting.profiles:

Specifies a list of profile scripts to run automatically before running user commands, scripts, or an
interactive shell.

The wsadmin.properties file specifies securityProcs.jacl and LTPA_LDAPSecurityProcs.jacl as the

values of this property. If Jython is specified with the wsadmin -lang option, the wsadmin tool performs a
conversion to change the profile script names that are specified in this property to use the file extension
that matches the language specified. Use the provided script procedures with the default settings to make
security configuration easier.

Using Ant to automate tasks

To support using Apache Ant with Java 2 Platform, Enterprise Edition (J2EE) applications running on the
application server, the product provides a copy of the Ant tool and a set of Ant tasks that extend the
capabilities of Ant to include product-specific functions. Ant has become a very popular tool among Java
programmers.

Apache Ant is a Java-based build tool. In theory, it is similar to Make, but Ant is different. Instead of a
model in which it is extended with shell-based commands, Ant is extended using Java classes. Instead of
writing shell commands, XML-based configuration files are used. These files reference a target tree in
which various tasks are run. Each task is run by an object that implements a particular Task interface.

By combining the following tasks with those provided by Ant, you can create build scripts that compile,
package, install, and test your application on the application server:
v Install and uninstall applications
v Start and stop servers in a base configuration
v Run administrative scripts or commands
v Run the Enterprise JavaBeans (EJB) deployment tool
v Run the JavaServer Pages (JSP) file precompilation tool

Chapter 4. Using the administrative clients 809

For more detailed information about Ant, refer to the Apache organization Web site.
v To run Ant and have it automatically see the WebSphere classes, use the “ws_ant command.”
v Use “Ant tasks for deployment and server operation.”
This topic describes where to find the API documentation for the Apache Ant tasks for deploying
applications and operating application servers.
v Use “Ant tasks for building application code.”
This topic describes where to find the API documentation for the Apache Ant tasks for building
applications.

ws_ant command
This topic describes where to find information about the ws_ant command, which is provided for using with
Apache Ant, a Java-based build tool that is popular among Java programmers.

In theory, Ant is similar to Make, but Ant is different. Instead of a model in which it is extended with
shell-based commands, Ant is extended using Java classes. Instead of writing shell commands,
XML-based configuration files are used. These files reference a target tree in which various tasks are run.
Each task is run by an object that implements a particular Task interface.

For the Apache Ant tool that is provided by this product, see the following file:
install_root/bin/ws_ant.bat|sh

Ant tasks for deployment and server operation

This topic describes where to find the API documentation for the Apache Ant tasks for deploying
applications and operating application servers.

The Apache Ant tasks for the product reside in the Java package: com.ibm.websphere.ant.tasks. The API
documentation for this package contains detailed information about all of the Ant tasks that are provided
and how to use them. The API documentation is available in the Reference section of the information
center.

Ant tasks for building application code

This topic describes where to find the documentation for the Ant tasks provided for building application
code using the Application Server Toolkit (which is a CD included with WebSphere Application Server as a
separately installable toolkit).

Note that this toolkit includes an Automated Deployment example ″Example: Automated Deploy″ for JACL
scripted deployment of multiple application updates to multiple servers and clusters in a WebSphere
Network Deployment cell.

Within the Application Server Toolkit product documentation, open the section Working with Ant. You can
locate the topic by searching for Working with Ant, or from the navigation view, select Help > Help
Contents > Developing Java Applications > Developing enterprise applications > J2EE applications
> Working with Ant.

Using administrative programs (JMX)

This topic describes how to use Java application programming interfaces (APIs) to administer WebSphere
Application Server and to manage your applications.

You can administer WebSphere Application Server and your applications through tools that come with the
product or through programming with the Java APIs.

810 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The wsadmin scripting tool, the administrative console, and the administrative command-line tools come
with the product. These administrative tools provide most of the functions that you need to manage the
product and the applications that run in WebSphere Application Server. You can use the command-line
tools from automation scripts to control the servers. Scripts that are written for the wsadmin scripting tool
offer a wide range of possible custom solutions that you can develop quickly.

Investigate these tools with the Java APIs to determine the best ways to administer WebSphere
Application Server and your applications. For information on the Java APIs, view Java Management
Extensions (JMX) API documentation

WebSphere Application Server supports access to the administrative functions through a set of Java
classes and methods. You can write a Java program that performs any of the administrative features of the
WebSphere Application Server administrative tools. You can also extend the basic WebSphere Application
Server administrative system to include your own managed resources.

You can prepare, install, uninstall, edit, and update applications through programming. Preparing an
application for installation involves collecting various types of WebSphere Application Server-specific
binding information to resolve references that are defined in the application deployment descriptors. This
information can also be modified after installation by editing a deployed application. Updating consists of
adding, removing or replacing a single file or a single module in an installed application, or supplying a
partial application that manipulates an arbitrary set of files and modules in the deployed application.
Updating the entire application uninstalls the old application and installs the new one. Uninstalling an
application removes it entirely from the WebSphere Application Server configuration.

Perform any or all of the following tasks to manage WebSphere Application Server and your Java 2
Platform, Enterprise Edition (J2EE) applications through programming.
v Create a custom Java administrative client program using the Java administrative APIs.
This topic describes how to develop a Java program that uses the WebSphere Application Server
administrative APIs to access the administrative system of WebSphere Application Server.
v Extend the WebSphere Application Server administrative system with custom MBeans.
This topic describes how to extend the WebSphere Application Server administration system by
supplying and registering new JMX MBeans in one of the Application Server processes. In this case,
you can use the administrative classes and methods to add newly managed objects to the
administrative system.
v Deploy and manage a custom Java administrative client program for use with multiple Java 2 Platform,
Enterprise Edition application servers.
This topic describes how to connect to a J2EE server, and how to manage multiple vendor servers.
v Manage applications through programming
This topic describes how, through Java MBean programming, to install, update, and delete a J2EE
application on WebSphere Application Server.

Depending on which tasks you complete, you have created your own administrative program, extended the
WebSphere Application Server administrative console, connected and managed vendor servers, or
managed your applications through programming.

You can continue to administer WebSphere Application Server and your applications through programming
or in combination with the tools that come with the WebSphere Application Server.

Creating a custom Java administrative client program using

WebSphere Application Server administrative Java APIs
This section describes how to develop a Java program for accessing the WebSphere Application Server
administrative system by using the WebSphere Application Server administrative application programming
interfaces (APIs).

Chapter 4. Using the administrative clients 811

This task assumes a basic familiarity with Java Management Extensions (JMX) API programming. See the
JMX API documentation for information.

When you develop and run administrative clients that use various JMX connectors and that have security
enabled, use the following guidelines. When you follow these guidelines, you guarantee the behavior
among different implementations of JMX connectors. Any programming model that strays from these
guidelines is unsupported.
1. Create and use a single administrative client before you create and use another administrative client.
2. Create and use an administrative client on the same thread.
3. Use one of the following ways to specify a user ID and password to create a new administrative client:
v Specify a default user ID and password in the property file.
v Specify a user ID and password other than the default. Once you create an administrative client with
a non-default user ID and password, specify the non-default user ID and password when you create
subsequent administrative clients.
1. Develop an administrative client program.
2. Build and run the administrative client program.
The steps required to build and run your program depends on the kind of application environment your
code runs. Refer to “Using application clients” on page 1038 for details on how to build and run your
administrative client program.

Developing an administrative client program

This page contains examples of key features of an administrative client program that utilizes WebSphere
Application Server administrative APIs and Java Management Extensions (JMX). WebSphere Application
Server administrative APIs provide control of the operational aspects of your distributed system as well as
the ability to update your configuration. This page also demonstrates examples of operational control. For
information, view the Administrative API documentation, the JMX API documentation, or the MBean API
documentation.
1. Create an AdminClient instance. An administrative client program needs to invoke methods on the
AdminService object that is running in the deployment manager (or the application server in the base
installation). The AdminClient class provides a proxy to the remote AdminService object through one of
the supported Java Management Extensions (JMX) connectors. The following example shows how to
create an AdminClient instance:
Properties connectProps = new Properties();
connectProps.setProperty(
AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);

connectProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
connectProps.setProperty(AdminClient.CONNECTOR_PORT, "8879");
AdminClient adminClient = null;
try
{
adminClient = AdminClientFactory.createAdminClient(connectProps);
}
catch (ConnectorException e)
{
System.out.println("Exception creating admin client: " + e);
}
2. Find an MBean Once you obtain an AdminClient instance, you can use it to access managed
resources in the administration servers and application servers. Each managed resource registers an
MBean with the AdminService through which you can access the resource. The MBean is represented
by an ObjectName instance that identifies the MBean. An ObjectName consists of a domain name
followed by an unordered set of one or more key properties. For the WebSphere Application Server,
the domain name is WebSphere and the key properties defined for administration are as follows:

812 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
type The type of MBean. For example: Server, TraceService,
Java Virtual Machine (JVM).
name The name identifier for the individual instance of the
MBean.
cell The name of the cell that the MBean is running.
node The name of the node that the MBean is running.
process The name of the process that the MBean is running.

You can locate an MBean by querying for them with ObjectNames that match desired key properties.
The following example shows how to find the MBean for the NodeAgent of node MyNode:
String nodeName = "MyNode";
String query = "WebSphere:type=NodeAgent,node=" + nodeName + ",*";
ObjectName queryName = new ObjectName(query);
ObjectName nodeAgent = null;
Set s = adminClient.queryNames(queryName, null);
if (!s.isEmpty())
nodeAgent = (ObjectName)s.iterator().next();
else
System.out.println("Node agent MBean was not found");
3. Use the MBean. What a particular MBean allows you to do depends on that MBean’s management
interface. It may declare attributes that you can obtain or set. It may declare operations that you can
invoke. It may declare notifications for which you can register listeners. For the MBeans provided by
the WebSphere Application Server, you can find information about the interfaces they support in the
MBean API documentation. The following example invokes one of the operations available on the
NodeAgent MBean that we located above. The following example will start the MyServer application
server:
String opName = "launchProcess";
String signature[] = { "java.lang.String" };
String params[] = { "MyServer" };
try
{
adminClient.invoke(nodeAgent, opName, params, signature);
}
catch (Exception e)
{
System.out.println("Exception invoking launchProcess: " + e);
}
4. Register for events. In addition to managing resources, the Java Management Extensions (JMX) API
also supports application monitoring for specific administrative events. Certain events produce
notifications, for example, when a server starts. Administrative applications can register as listeners for
these notifications. The WebSphere Application Server provides a full implementation of the JMX
notification model, and provides additional function so you can receive notifications in a distributed
environment. For a complete list of the notifications emitted from WebSphere Application Server
MBeans, refer to the com.ibm.websphere.management.NotificationConstants class in the API
documentation. The following is an example of how an object can register itself for event notifications
emitted from an MBean using the node agent ObjectName:
adminClient.addNotificationListener(nodeAgent, this, null, null);

In this example, the null value will result in receiving all of the node agent MBean event notifications.
You can also use the null value with the handback object.
5. Handle the events. Objects receive JMX event notifications via the handleNotification method which is
defined by the NotificationListener interface and which any event receiver must implement. The
following example is an implementation of handleNotification that reports the notifications that it
receives:
public void handleNotification(Notification n, Object handback)
{
System.out.println("***************************************************");

Chapter 4. Using the administrative clients 813

 System.out.println("* Notification received at " + new Date().toString());
System.out.println("* type = " + ntfyObj.getType());
System.out.println("* message = " + ntfyObj.getMessage());
System.out.println("* source = " + ntfyObj.getSource());
System.out.println(
"* seqNum = " + Long.toString(ntfyObj.getSequenceNumber()));
System.out.println("* timeStamp = " + new Date(ntfyObj.getTimeStamp()));
System.out.println("* userData = " + ntfyObj.getUserData());
System.out.println("***************************************************");
}

Administrative client program example: The following example is a complete administrative client
program. Copy the contents to a file named MyAdminClient.java. After changing the node name and
server name to the appropriate values for your configuration, you can compile and run it using the
instructions from ″Creating a custom Java administrative client program using WebSphere Application
Server administrative Java APIs″ in the information center.
import java.util.Date;
import java.util.Properties;
import java.util.Set;

import javax.management.InstanceNotFoundException;
import javax.management.MalformedObjectNameException;
import javax.management.Notification;
import javax.management.NotificationListener;
import javax.management.ObjectName;

import com.ibm.websphere.management.AdminClient;
import com.ibm.websphere.management.AdminClientFactory;
import com.ibm.websphere.management.exception.ConnectorException;

public class AdminClientExample implements NotificationListener

{

private AdminClient adminClient;

private ObjectName nodeAgent;
private long ntfyCount = 0;

public static void main(String[] args)

{
AdminClientExample ace = new AdminClientExample();

// Create an AdminClient
ace.createAdminClient();

// Find a NodeAgent MBean

ace.getNodeAgentMBean("ellington");

// Invoke launchProcess
ace.invokeLaunchProcess("server1");

// Register for NodeAgent events

ace.registerNotificationListener();

// Run until interrupted

ace.countNotifications();
}

private void createAdminClient()

{
// Set up a Properties object for the JMX connector attributes
Properties connectProps = new Properties();
connectProps.setProperty(
AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
connectProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
connectProps.setProperty(AdminClient.CONNECTOR_PORT, "8879");

814 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 // Get an AdminClient based on the connector properties
try
{
adminClient = AdminClientFactory.createAdminClient(connectProps);
}
catch (ConnectorException e)
{
System.out.println("Exception creating admin client: " + e);
System.exit(-1);
}

System.out.println("Connected to DeploymentManager");
}

private void getNodeAgentMBean(String nodeName)

{
// Query for the ObjectName of the NodeAgent MBean on the given node
try
{
String query = "WebSphere:type=NodeAgent,node=" + nodeName + ",*";
ObjectName queryName = new ObjectName(query);
Set s = adminClient.queryNames(queryName, null);
if (!s.isEmpty())
nodeAgent = (ObjectName)s.iterator().next();
else
{
System.out.println("Node agent MBean was not found");
System.exit(-1);
}
}
catch (MalformedObjectNameException e)
{
System.out.println(e);
System.exit(-1);
}
catch (ConnectorException e)
{
System.out.println(e);
System.exit(-1);
}

System.out.println("Found NodeAgent MBean for node " + nodeName);

}

private void invokeLaunchProcess(String serverName)

{
// Use the launchProcess operation on the NodeAgent MBean to start
// the given server
String opName = "launchProcess";
String signature[] = { "java.lang.String" };
String params[] = { serverName };
boolean launched = false;
try
{
Boolean b = (Boolean)adminClient.invoke(

nodeAgent, opName, params, signature);

launched = b.booleanValue();
if (launched)
System.out.println(serverName + " was launched");
else
System.out.println(serverName + " was not launched");

}
catch (Exception e)
{

Chapter 4. Using the administrative clients 815

 System.out.println("Exception invoking launchProcess: " + e);
}
}

private void registerNotificationListener()

{
// Register this object as a listener for notifications from the
// NodeAgent MBean. Don’t use a filter and don’t use a handback
// object.
try
{
adminClient.addNotificationListener(nodeAgent, this, null, null);
System.out.println("Registered for event notifications");
}
catch (InstanceNotFoundException e)
{
System.out.println(e);
}
catch (ConnectorException e)
{
System.out.println(e);
}
}

public void handleNotification(Notification ntfyObj, Object handback)

{
// Each notification that the NodeAgent MBean generates will result in
// this method being called
ntfyCount++;
System.out.println("***************************************************");
System.out.println("* Notification received at " + new Date().toString());
System.out.println("* type = " + ntfyObj.getType());
System.out.println("* message = " + ntfyObj.getMessage());
System.out.println("* source = " + ntfyObj.getSource());
System.out.println(
"* seqNum = " + Long.toString(ntfyObj.getSequenceNumber()));
System.out.println("* timeStamp = " + new Date(ntfyObj.getTimeStamp()));
System.out.println("* userData = " + ntfyObj.getUserData());
System.out.println("***************************************************");

private void countNotifications()

{
// Run until killed
try
{
while (true)
{
Thread.currentThread().sleep(60000);
System.out.println(ntfyCount + " notification have been received");
}
}
catch (InterruptedException e)
{
}
}

Extending the WebSphere Application Server administrative system

with custom MBeans
You can extend the WebSphere Application Server administration system by supplying and registering new
Java Management Extensions (JMX) MBeans (see JMX 1.0 Specification for details) in one of the

816 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebSphere processes. JMX MBeans represent the management interface for a particular piece of logic.
All of the managed resources within the standard WebSphere infrastructure are represented as JMX
MBeans. There are a variety of ways in which you can create your own MBeans and register them with
the JMX MBeanServer running in any WebSphere process. For more information, view the MBean API
documentation.
1. Create custom JMX MBeans.
You have some alternatives to select from, when creating MBeans to extend the WebSphere
administrative system. You can use any existing JMX MBean from another application. You can
register any MBean that you tested in a JMX MBean server outside of the WebSphere Application
Server environment in a WebSphere Application Server process, including standard MBeans, dynamic
MBeans, open MBeans, and model MBeans.
In addition to any existing JMX MBeans, and ones that were written and tested outside of the
WebSphere Application Server environment, you can use the special distributed extensions provided
by WebSphere and create a WebSphere ExtensionMBean provider. This alternative provides better
integration with all of the distributed functions of the WebSphere administrative system. An
ExtensionMBean provider implies that you supply an XML file that contains an MBean Descriptor
based on the DTD shipped with the WebSphere Application Server. This descriptor tells the
WebSphere system all of the attributes, operations, and notifications that your MBean supports. With
this information, the WebSphere system can route remote requests to your MBean and register remote
Listeners to receive your MBean event notifications.
All of the internal WebSphere MBeans follow the Model MBean pattern (see WebSphere Application
Server administrative MBean documentation for details). Pure Java classes supply the real logic for
management functions, and the WebSphere MBeanFactory class reads the description of these
functions from the XML MBean Descriptor and creates an instance of a ModelMBean that matches the
descriptor. This ModelMBean instance is bound to your Java classes and registered with the
MBeanServer running in the same process as your classes. Your Java code now becomes callable
from any WebSphere Application Server administrative client through the ModelMBean created and
registered to represent it.
2. Register the new MBeans. There are various ways to register your MBean.
You can register your MBean with the WebSphere Application Server administrative service.
You can register your MBean with the MBeanServer in a WebSphere Application Server process. The
following list describes the available options in order of preference:
v Go through the MBeanFactory class. If you want the greatest possible integration with the
WebSphere Application Server system, then use the MBeanFactory class to manage the life cycle of
your MBean through the activateMBean and deactivateMBean methods of the MBeanFactory class.
Use these methods, by supplying a subclass of the RuntimeCollaborator abstract superclass and an
XML MBean descriptor file. Using this approach, you supply a pure Java class that implements the
management interface defined in the MBean descriptor. The MBeanFactory class creates the actual
ModelMBean and registers it with the WebSphere Application Server administrative system on your
behalf.
This option is recommended for registering model MBeans.
v Use the JMXManageable and CustomService interface. You can make the process of integrating
with WebSphere administration even easier, by implementing a CustomService interface, that also
implements the JMXManageable interface. Using this approach, you can avoid supplying the
RuntimeCollaborator. When your CustomService interface is initialized, the WebSphere
MBeanFactory class reads your XML MBean descriptor file and creates, binds, and registers an
MBean to your CustomService interface automatically. After the shutdown method of your
CustomService is called, the WebSphere Application Server system automatically deactivates your
MBean.
v Go through the AdminService interface. You can call the registerMBean() method on the
AdminService interface and the invocation is delegated to the underlying MBeanServer for the
process, after appropriate security checks. You can obtain a reference to the AdminService using
the getAdminService() method of the AdminServiceFactory class.

Chapter 4. Using the administrative clients 817

 This option is recommended for registering standard, dynamic, and open MBeans. Implement the
UserCollaborator class to use the MBeans and to provide a consistent level of support for them
across distributed and z/OS platforms.
v Get MBeanServer instances directly. You can get a direct reference to the JMX MBeanServer
instance running in any WebSphere Application Server process, by calling the getMBeanServer()
method of the MBeanFactory class. You get a reference to the MBeanFactory class by calling the
getMBeanFactory() method of the AdminService interface. Registering the MBean directly with the
MBeanServer instance can result in that MBean not participating fully in the distributed features of
the WebSphere Application Server administrative system.

Regardless of the approach used to create and register your MBean, you must set up proper Java 2
security permissions for your new MBean code. The WebSphere AdminService and MBeanServer are
tightly protected using Java 2 security permissions and if you do not explicitly grant your code base
permissions, security exceptions are thrown when you attempt to invoke methods of these classes. If you
are supplying your MBean as part of your application, you can set the permissions in the was.policy file
that you supply as part of your application metadata. If you are using a CustomService interface or other
code that is not delivered as an application, you can edit the library.policy file in the node configuration,
or even the server.policy file in the properties directory for a specific installation.

Best practices for standard, dynamic, and open MBeans

This article discusses recommended guidelines for standard, dynamic, and open MBeans.

The underlying interface for the WebSphere Application Server administrative service is AdminService.
Remote access occurs through the AdminControl scripting object.

For WebSphere Application Server Version 5, the MBean registration and capabilities are as follows:

MBean type Registered with: Capabilities

Model WebSphere Application Server Local access is through the
administrative service WebSphere Application Server
administrative service or the MBean
server. Remote access is through the
WebSphere Application Server
administrative service, and
WebSphere Application Server
security.
Standard, dynamic, or open MBean server Local access is through the
WebSphere Application Server
administrative service or the MBean
server on the distributed platform.

For V6, you can optionally register standard, dynamic, and open custom MBeans with the WebSphere
Application Server administrative service to take advantage of the capabilities that in V5 are available only
to model MBeans.

V6 introduces a special run-time collaborator that you use with standard, dynamic or open custom MBeans
to register the custom MBeans with the WebSphere Application Server administrative service. The
standard, dynamic, and open MBeans display in the administrative service as model MBeans. The
administrative service uses the capabilities available to MBeans that are registered with the administrative
service.

For WebSphere Application Server Version 6, the MBean registration and capabilities are as follows:

MBean type Registered with: Capabilities

818 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Model, and optionally standard, WebSphere Application Server Local access is through the
dynamic, or open administrative service WebSphere Application Server
administrative service or the MBean
server. Remote access is through the
WebSphere Application Server
administrative service, and
WebSphere Application Server
security.
Standard, dynamic, or open MBean server Local access is through the
WebSphere Application Server
administrative service or the MBean
server on the distributed platform.

Creating and registering standard, dynamic, and open custom MBeans

You can create standard, dynamic, and open custom MBeans and register them with the WebSphere
Application Server administrative service.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Perform the following tasks to create and register a standard, dynamic, or open custom MBean.
1. Create your particular MBean class or classes.
2. Write an MBean descriptor in the XML language for your MBean.
3. Register your MBean by inserting code that uses the WebSphere Application Server run-time
com.ibm.websphere.management.UserMBeanCollaborator collaborator class into your application code.
4. Package the class files for your MBean interface and implementation, the descriptor XML file, and your
application Java archive (JAR) file.

After you successfully complete the steps, you have a standard, dynamic, or open custom MBean that is
registered and activated with the WebSphere Application Server administrative service.

The following example shows how to create and register a standard MBean with the WebSphere
Application Server administrative service:
SnoopMBean.java:

/**
* Use the SnoopMBean MBean, which has a standard mbean interface.
*/
public interface SnoopMBean {
public String getIdentification();
public void snoopy(String parm1);
}

SnoopMBeanImpl.java:

/**
* SnoopMBeanImpl - SnoopMBean implementation
*/
public class SnoopMBeanImpl implements SnoopMBean {
public String getIdentification() {
System.out.println(">>> getIdentification() called...");
return "snoopy!";
}

public void snoopy(String parm1) {

System.out.println(">>> snoopy(" + parm1 + ") called...");
}
}

Chapter 4. Using the administrative clients 819

Define the following MBean descriptor for your MBean in an .xml file. The getIdentification method is set to
run with the unicall option and the snoopy method is set to use the multicall option. These options are
used only for z/OS platform applications. The WebSphere Application Server for z/OS options are not
applicable to the distributed platforms, but they do not need to be removed. The options are ignored on
the distributed platforms.
SnoopMBean.xml:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE MBean SYSTEM "MbeanDescriptor.dtd">
<MBean type="SnoopMBean"
version="5.0"
platform="dynamicproxy"
description="Sample SnoopMBean to be initialized inside an EJB.">

<attribute name="identification" getMethod="getIdentification"

type="java.lang.String" proxyInvokeType="unicall"/>

<operation name="snoopy" role="operation" type="void" targetObjectType="objectReference"

impact="ACTION" proxyInvokeType="multicall">
<signature>
<parameter name="parm1" description="test parameter" type="java.lang.String"/>
</signature>
</operation>
</MBean>

Assume that your MBean is used in an enterprise bean. Register your MBean in the enterprise bean
ejbCreate method and unregister it in the ejbRemove method.
//The method MBeanFactory.activateMBean() requires four parameters:
//String type: The type value that you put in this MBean’s descriptor. For this example
//the string type is SnoopMBean.
//RuntimeCollaborator co: The UserMBeanCollaborator user MBean collaborator instance
//that you create
//String id: Unique name that you pick
//String desciptor: The MBean descriptor file name

import com.ibm.websphere.management.UserMBeanCollaborator;
//Import other classes here.
.
.
.
static private ObjectName snoopyON = null;
static private Object lockObj = "this is a lock";
.
.
.
/**
* ejbCreate method: Register your Mbean.
*/
public void ejbCreate() throws javax.ejb.CreateException {
synchronized (lockObj) {
System.out.println(">>> SnoopMBean activating for --|" + this + "|--");
if (snoopyON != null) {
return;
}
try {
System.out.println(">>> SnoopMBean activating...");
MBeanFactory mbfactory = AdminServiceFactory.getMBeanFactory();
RuntimeCollaborator snoop = new UserMBeanCollaborator(new SnoopMBeanImpl());
snoopyON = mbfactory.activateMBean("SnoopMBean", snoop, "snoopMBeanId", "SnoopMBean.xml");
System.out.println(">>> SnoopMBean activation COMPLETED! --|" + snoopyON + "|--");
} catch (Exception e) {

820 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 System.out.println(">>> SnoopMBean activation FAILED:");
e.printStackTrace();
}
}
}
.
.
.
/**
* ejbRemove method: Unregister your MBean.
*/
public void ejbRemove() {
synchronized (lockObj) {
System.out.println(">>> SnoopMBean Deactivating for --|" + this + "|--");
if (snoopyON == null) {
return;
}
try {
System.out.println(">>> SnoopMBean Deactivating ==|" + snoopyON +
"|== for --|" + this + "|--");
MBeanFactory mbfactory = AdminServiceFactory.getMBeanFactory();
mbfactory.deactivateMBean(snoopyON);
System.out.println(">>> SnoopMBean Deactivation COMPLETED!");
} catch (Exception e) {
System.out.println(">>> SnoopMBean Deactivation FAILED:");
e.printStackTrace();
}
}
}

Compile the MBean Java files and package the resulting class files with the descriptor .xml file, into the
enterprise bean JAR file.

Java 2 security permissions

When you enable Java 2 security, you must grant Java 2 security permissions to application-specific code
for Java Management Extensions (JMX) and WebSphere Application Server administrative privileges. With
these permissions, your application code can call WebSphere Application Server administrative methods
and JMX methods.

Use the following permission to invoke all the JMX class methods and interface methods:
permission javax.management.MBeanPermission "*", "*";

Consult the Java Management Extensions (JMX) API documentation for specific actions under the
MBeanPermission class.

Use the following permission for WebSphere Application Server administrative application programming
interfaces (APIs):
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";

Developing administrative programs for multiple Java 2 Platform,

Enterprise Edition application servers
You can develop an administrative client to manage multiple vendor application servers through existing
MBean support in the WebSphere Application Server.

Existence of MBeans for stopped components

The WebSphere Application Server completely implements the Java 2 Platform, Enterprise Edition (J2EE)
Management specification. However, some differences in details between the J2EE specification and the
WebSphere Application Server implementation are important for you to understand when you access

Chapter 4. Using the administrative clients 821

WebSphere Application Server components. These differences are important to you when you access
application MBeans because you can use either the WebSphere Application Server programming model or
the J2EE programming model.

In the WebSphere Application Server programming model, if an MBean exists, you can assume that it is
running. If an MBean does not exist, you can assume that it is stopped. Transient states between the
started state and the stopped state are the same as the stopped state, which means that no MBean
exists.

In the J2EE programming model, the MBean always exists regardless of the state of the component.

You can determine the state of a component by querying the state attribute. However, the state attribute
only exists for MBeans that are state manageable, meaning that they implement the StateManageable
interface. State manageable MBeans have start(), startRecursive(), and stop() operations whether these
MBeans are J2EE MBeans or WebSphere Application Server MBeans. Additionally, the WebSphere
Application Server defines the stateful interface. The stateful interface means that the component has a
state and emits the j2ee.state.notifications method, but that the component cannot directly manage the
state. For example, a Web module cannot stop itself. However, the application that contains the Web
module can stop it.

Not all MBeans that have a state are state-manageable. Servlets, J2EE modules and enterprise beans, for
example, are all stateful, but are not state manageable. The J2EE server is not state-manageable because
no start() operation is available on a server.

The J2EEApplication MBean is an example of a state manageable MBean. When the WebSphere
Application Server starts, each application activates a J2EEApplication MBean for itself. A J2EEApplication
MBean has a J2EE type of J2EEApplication (for example, ObjectName *:*,j2eeType=J2EEApplication). If
the application starts, it also activates an Application MBean with a type of Application (for example,
*:*,type=Application). When the application changes state, the Application MBean is activated or
deactivated. However, the J2EEApplication MBean is always activated. You can retrieve the application
state changes by getting the state attribute.

The modules attribute on the J2EEApplication component returns an array of object names, one for every
module in the application. The Application Server activates an MBean for each of these modules only after
the Application Server starts the application. The managed enterprise bean isRegistered(ObjectName)
method returns false if the application, and therefore the module, is not running.

All of the attributes that are defined in the J2EE management specification return valid values when the
managed object stops. Other attributes and operations, for example those that are specifically defined for
the Application Server, use the com.ibm.websphere.management.exception.ObjectNotRunningException
exception if they are accessed when the object is stopped.

If you install the application while the server runs, the application installs the J2EEApplication MBean when
the installation completes. Conversely, when the application uninstalls the J2EEApplication MBean, the
application deactivates the MBean.

Mapping key properties

The following table lists the mapping from the J2EE management-defined j2eeType key property to the
WebSphere Application Server type key property. You can use either key property to access MBeans.
However, only use the j2eeType key property if you want to connect to application servers other than
WebSphere Application Server.

j2eeType key property type key property

J2EEDomain J2EEDomain [new]

822 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
J2EEServer Server
JVM JVM
J2EEApplication Application [separate MBean from j2eeType
WebModule WebModule
ResourceAdapterModule ResourceAdapterModule
EJBModule EJBModule
EJB and subtypes / Servlet / ResourceAdapter EJB and subtypes / Servlet / ResourceAdapter
JavaMailResource MailProvider
JNDIResource NameServer
JMSResource JMSProvider
JTAResource TransactionService
RMI_IIOPResource ORB
URLResource URLProvider
JDBCResource JDBCProvider
JDBCDataSource DataSource
JDBCDriver JDBCDriver [new]
JCAResource J2CResourceAdapter
JCAConnectionFactory J2CConnectionFactory
JCAManagedConnectionFactory J2CManagedConnectionFactory [new]

Optional WebSphere Application Server interfaces

The following table shows the optional J2EE management interfaces that WebSphere Application Server
provides.

j2eeType key property EventProvider interface StateManageable interface StatisticsProvider

interface
J2EEDomain No No No
J2EEServer Yes Stateful No
JVM No No Yes
J2EEApplication Yes Yes No
WebModule Yes Stateful No
ResourceAdapterModule Yes Stateful No
EJBModule Yes Stateful No
AppClientModule Yes Stateful No
EJB and subtypes / Servlet No No Yes
/ ResourceAdapter
JavaMailResource No No No
JNDIResource No No No
JMSResource No No No
JTAResource Yes No Yes
RMI_IIOPResource No No Yes
URLResource No No No

Chapter 4. Using the administrative clients 823

JDBCResource No No Yes
JDBCDataSource No No No
JDBCDriver No No No
JCAResource Yes No Yes
JCAConnectionFactory No No No
JCAManagedConnectionFactory
No No No

Deploying and managing a custom Java administrative client program

with multiple Java 2 Platform, Enterprise Edition application servers
This section describes how to connect to a Java 2 Platform, Enterprise Edition (J2EE) server, and how to
manage multiple vendor servers.

The WebSphere Application Server completely implements the J2EE Management specification, also
known as JSR-77 (Java Specification Requests 77). However, some differences in details between the
J2EE specification and the WebSphere Application Server implementation are important for you to
understand when you develop a Java administrative client program to manage multiple vendor servers.
For information, see the Java Platform, Enterprise Edition (J2EE) Management Specification and the
MBean application programming interface (API) documentation.

When your administrative client program accesses WebSphere Application Servers exclusively, you can
use the Java APIs and WebSphere Application Server-defined MBeans to manage them. If your program
needs to access both WebSphere Application Servers and other J2EE servers, use the API defined in the
J2EE Management specification.
1. Connect to a J2EE server.
Connect to a server by looking up the Management enterprise bean from the Java Naming and
Directory Interface (JNDI). The Management enterprise bean supplies a remote interface to the MBean
server that runs in the application server. The Management enterprise bean works almost exactly like
the WebSphere Application Server administrative client, except that it does not provide WebSphere
Application Server specific functionality. The following example shows how to look up the Management
enterprise bean.
import javax.management.j2ee.ManagementHome;
import javax.management.j2ee.Management;

Properties props = new Properties();

props.setProperty(Context.PROVIDER_URL, "iiop://myhost:2809");
Context ic = new InitialContext(props);
Object obj = ic.lookup("ejb/mgmt/MEJB");
ManagementHome mejbHome = (ManagementHome)
PortableRemoteObject.narrow(obj, ManagementHome.class);
Management mejb = mejbHome.create();
The example gets an initial context to an application server by passing the host and port of the
Remote Method Invocation (RMI) connector. You must explicitly code the RMI port, in this case 2809.
The lookup method looks up the ejb/mgmt/MEJB path, which is the location of the Management
enterprise bean home. The example then creates the mejb stateless session bean, which you use in
the next step.
2. Manage multiple vendor application servers.
After you create the mejb stateless session bean, you can use it to manage your application servers.
Components from the application servers appear as MBeans, which the specification defines. These
MBeans all have the j2eeType key property. This key property is one of a set of types that the
specification defines. All of these types have a set of exposed attributes.

824 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Use the following example to guide you in managing multiple vendor application servers. The example
uses the Java virtual machine (JVM) MBean to determine what the current heap size is for the
application server.
ObjectName jvmQuery = new ObjectName("*:j2eeType=JVM,*");
Set s = mejb.queryNames(jvmQuery, null);
ObjectName jvmMBean = (ObjectName) s.iterator().next();
boolean hasStats = ((Boolean) mejb.getAttribute(jvmMBean,
"statisticsProvider")).booleanValue();
if (hasStats) {
JVMStats stats = (JVMStats) mejb.getAttribute(jvmMBean,
"stats");
String[] statisticNames = stats.getStatisticNames();
if (Arrays.asList(statisticNames).contains("heapSize")) {
System.out.println("Heap size: " + stats.getHeapSize());
}
}
The queryNames() method first queries the JVM MBean. The getAttribute method gets the
statisticsProvider attribute and determine if this MBean provides statistics. If the MBean does, the
example accesses the stats attribute, and then invokes the getHeapSize() method to get the heap size.

The strength of this example is that the example can run on any vendor application server. It demonstrates
that an MBean can optionally implement defined interfaces, in this case the StatisticsProvider interface. If
an MBean implements the StatisticsProvider interface, you can see if an application server supports a
particular statistic, in this case the heap size. The specification defines the heap size, although this value
is optional. If the application server supports the heap size, you can display the heap size for the JVM.

Migrating Java Management Extensions V1.0 to Java Management

Extensions V1.2
Each Java Virtual Machine (JVM) in WebSphere Application Server includes an embedded implementation
of Java Management Extensions (JMX). In Application Server, Version 5, the JVMs contain an
implementation of the JMX 1.0 specification. In Application Server, Version 6, the JVMs contain an
implementation of the JMX 1.2 specification. The JMX 1.0 implementation used in Version 5 is the TMX4J
package that IBM Tivoli products supply. The JMX 1.2 specification used in Version 6 is the open source
mx4j package. The JMX implementation change across the releases does not affect the behavior of the
JMX MBeans in the Application Server. No Application Server administrative application programming
interfaces (APIs) are altered due to the change from the JMX V1.0 specification to the JMX V1.2
specification.

The JMX V1.2 specification is backward compatible with the JMX 1.0 specification. However, you might
need to migrate custom MBeans that are supplied by products other than the Application Server from
Version 5 to Version 6. The primary concern for these custom MBeans is related to the values that are
used in key properties of the JMX ObjectName class for the MBean. The open source mx4j
implementation more stringently enforces property validation according to the JMX 1.2 specification. Test
the custom MBeans that you deployed in Version 5 in Version 6, to ensure compatibility. Full details of the
JMX V1.2 specification changes from the JMX V1.0 specification are available in the JMX 1.2 specification.

Java Management Extensions interoperability

WebSphere Application Server Version 6 implements Java Management Extensions (JMX) Version 1.2,
while WebSphere Application Server Version 5 implements JMX Version 1.0.

Due to the evolution of the JMX specification, the serialization format for JMX objects, such as the
javax.management.ObjectName object, differs between the V5 implementation and the V6 implementation.
The V6 JMX run time is enhanced to be aware of the version of the client with which it is communicating.
The V6 run time makes appropriate transformations on these incompatible serialized formats to support

Chapter 4. Using the administrative clients 825

communication between the different version run times. A V5 wsadmin script or a V5 administrative client
can call a V6 deployment manager, node, or server. A V6 wsadmin script or a V6 administrative client can
call a V5 node or server.

When a V5 wsadmin script or a V5 administrative client calls a V6 MBean, the instances of classes that
are new in V6 cannot be passed back to V5 because these classes are not present in the V5 environment.
The problem occurs infrequently. However, it usually occurs when an exception embeds a nested
exception that is new in V6. The symptom is usually a serialization exception or a
NoClassDefFoundException exception.

Due to changes in the JMX implementation from V5 to V6, different exceptions are created when a
method on an MBean is invoked for V5 than when a method on an MBean is invoked for V6. For example,
when a method gets or sets an unknown attribute for V5, the MBeanRuntimeException exception is
created. When a method gets or sets an unknown attribute for V6, the MBeanException exception that
wraps a ServiceNotFoundException exception is created.

An instance of a user-defined class that implements the Serializable interface that is passed as a
parameter or return value during MBean invocation, or sent as part of a notification, cannot contain a
non-transient instance variable that is in the javax.management.package package. If the instance does, it
cannot be properly deserialized when passed between V5 and V6 run times.

Due to changes in the supported format for the ObjectName class from V5 to V6, the configuration ID in
V6 contains a vertical bar (|), whereas in V5, the ID contains a colon (:). This change is reflected in the
output for wsadmin clients. For example, for a V5 client, the output is:
wsadmin> $AdminConfig list Cell
DefaultCellNetwork(cells/DefaultCellNetwork:cell.xml#Cell_1)

whereas for a V6 client, the output is:

wsadmin> $AdminConfig list Cell
DefaultCellNetwork(cells/DefaultCellNetwork|cell.xml#Cell_1)

The change to the configuration ID generally is not a problem because configuration IDs are generated
dynamically. When a V5 client passes a configuration ID that contains a colon, the JMX run time, for
upward compatibility, automatically transforms the configuration ID that contains a colon into a
configuration ID that contains a vertical bar. Similarly, a reverse transformation is performed for backward
compatibility.

Do not save the configuration ID and then try to use it later. Only query the ID and use it.

Managed object metadata

Information about a node, such as operating system platform and product features, is maintained in the
configuration repository in the form of properties. As product features are installed on a node, new property
settings are added.

WebSphere Application Server system management uses the managed object metadata properties as
follows:
v To display the node version in the administrative console
v To ensure that new configuration types or attributes are not created or set on older release nodes
v To ensure that new resource types are not created on old release notes
v To ensure that new applications are not installed on old release nodes because the old run time cannot
support the new applications

Base properties

826 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The following base property keys are defined for WebSphere Application Server:

com.ibm.websphere.baseProductVersion: The version of WebSphere Application Server that is installed.

com.ibm.websphere.nodeOperatingSystem: The operating system platform on which the node runs.

com.ibm.websphere.nodeSysplexName: The sysplex name on a z/OS operating system.

com.ibm.websphere.deployed.features: A list of features that extends a profile. An example of a feature

is an administrative console plug-in.

Here are examples of metadata property values. The last item is split on two lines for printing purposes.
com.ibm.websphere.baseProductVersion=6.0.0.0
com.ibm.websphere.nodeOperatingSystem=os390
com.ibm.websphere.nodeSysplexName=PLEX1
com.ibm.websphere.deployed.features=
com.ibm.ws.base_6.0.0.0,com.ibm.ws.j2ee_6.0.0.0,com.ibm.ws.uddi_6.0.0.0,com.ibm.ws.wsgateway_6.0.0.0

For detailed information on metadata properties, view the ManagedObjectMetadataHelper class in the
Application Server API documentation.

Accessing managed object metadata properties

An administrator can query managed object metadata through the wsadmin tool or Application Server
APIs. They can additionally be viewed on the Node Installation properties administrative console panel.
This article provides details on the Application Server API method.

An accessor class is used to obtain the managed object metadata properties. An accessor instance is
created through its factory. A helper class, which uses the accessor instance, makes it easy to query the
base metadata properties. These classes are all part of the com.ibm.websphere.management.metadata
package in the Application Server API documentation. The specific names of these classes are:
v com.ibm.websphere.management.metadata.ManagedObjectMetadataHelper
v com.ibm.websphere.management.metadata.ManagedObjectMetadataAccessor
v com.ibm.websphere.management.metadata.ManagedObjectMetadataAccessorFactory

Managing applications through programming

This topic describes how, through Java MBean programming, to install, update, and delete a Java 2
Platform, Enterprise Edition (J2EE) application on WebSphere Application Server.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can install or change an application on WebSphere Application Server, you must first create or
update your application and assemble it using an assembly tool.

Besides installing, uninstalling, and updating applications through programming, you can additionally
install, uninstall, and update J2EE applications through the administrative console or the wsadmin tool. All
three ways provide identical updating capabilities.
1. Perform any or all of the following tasks to manage your J2EE applications through programming.
a. Install an application.
This article provides an example for initially installing an application on WebSphere Application
Server.
b. Uninstall an application.

Chapter 4. Using the administrative clients 827

 This article provides an example for uninstalling an application that resides on WebSphere
Application Server.
c. Update an application.
This article provides an example for updating the installed application on WebSphere Application
Server with a new application. When you completely update an application, the deployed
application is uninstalled and the new enterprise archive (EAR) file is installed.
d. Add to, update, or delete part of an application.
This article provides an example that you can use to add to, update, or delete part of an
application on WebSphere Application Server.
e. Add a module.
This article provides an example for adding a module to an application that resides on WebSphere
Application Server.
f. Update a module.
This article provides an example for updating a module that resides on WebSphere Application
Server. When you update a module, the deployed module is uninstalled and the updated module is
installed.
g. Delete a module.
This article provides an example for deleting a module that resides on WebSphere Application
Server. When you delete a module, the deployed module is uninstalled.
h. Add a file.
This article provides an example for adding a file to an application that resides on WebSphere
Application Server.
i. Update a file.
This article provides an example for updating a file on WebSphere Application Server. When you
update a file, the deployed file is uninstalled and the updated file is installed.
j. Delete a file.
This article provides an example for deleting a file on WebSphere Application Server. When you
delete a file, the deployed file is uninstalled.
2. Save your changes to the master configuration repository.
3. Synchronize changes to the master configuration across the nodes for the changes to take effect.

If you have further application updates, you can do the updates through programming, the administrative
console, or the wsadmin tool.

Installing an application through programming

You can install an application through the administrative console, the wsadmin tool, or programming. Use
this example to install an application through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can install an application on WebSphere Application Server, you must first create or update
your application and assemble it using an assembly tool.

Perform the following tasks to install an application through programming.

1. Populate the enterprise archive (EAR) file with WebSphere Application Server-specific binding
information.
a. Create the controller and populate the EAR file with appropriate options.
b. Optionally run the default binding generator.
c. Save and close the EAR file.

828 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 d. Retrieve the saved options table that will be passed to the installApplication MBean (API).
2. Connect to WebSphere Application Server.
3. Create the application management proxy.
4. If the preparation phase (population of the EAR file) is not performed, the do the following actions:
a. Create an options table to be passed to the installApplication MBean API.
b. Create a table for module to server relations and add the table to the options table.
Refer to the com.ibm.websphere.management.application.AppManagement class in the
Application Server API documentation to understand various options that can be passed to the
installApplication MBean API.
5. Create the notification filter for listening to installation events.
6. Add the listener.
7. Install the application.
8. Wait for some timeout so that the program does not end.
9. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
10. When the installation is done, remove the listener and quit.

After you successfully run the code, the application is installed.

The following example shows how to install an application based on the previous steps:
import java.lang.*;
import java.io.*;
import java.util.*;
import java.lang.reflect.*;
import com.ibm.websphere.management.application.*;
import com.ibm.websphere.management.application.client.*;
import com.ibm.websphere.management.*;

import javax.management.*;

public class Install {

public static void main (String [] args) {

try {
String earFile = "C:/test/test.ear";
String appName = "MyApp";

// Preparation phase: Begin

// Through the preparation phase you populate the enterprise archive (EAR) file with
// WebSphere Application Server-specific binding information. For example, you can specify
// Java Naming and Directory Interface (JNDI) names for enterprise beans, or virtual hosts
// for Web modules, and so on.

// First, create the controller and populate the EAR file with the appropriate options.
Hashtable prefs = new Hashtable();
prefs.put(AppConstants.APPDEPL_LOCALE, Locale.getDefault());

// You can optionally run the default binding generator by using the following options.
// Refer to Java documentation for the AppDeploymentController class to see all the
// options that you can set.
Properties defaultBnd = new Properties();
prefs.put (AppConstants.APPDEPL_DFLTBNDG, defaultBnd);
defaultBnd.put (AppConstants.APPDEPL_DFLTBNDG_VHOST, "default_host");

// Create the controller.

AppDeploymentController controller = AppDeploymentController
.readArchive(earFile, prefs);
AppDeploymentTask task = controller.getFirstTask();
while (task != null)

Chapter 4. Using the administrative clients 829

 {
// Populate the task data.
String[][] data = task.getTaskData();
// Manipulate task data which is a table of stringtask.
setTaskData (data);
task = controller.getNextTask();
}
controller.saveAndClose();

Hashtable options = controller.getAppDeploymentSavedResults();

// The previous options table contains the module-to-server relationship if it was set by
// using tasks.
//Preparation phase: End

// Get a connection to WebSphere Application Server.

String host = "localhost";
String port = "8880";
String target = "WebSphere:cell=cellName,node=nodeName,server=server1";

Properties config = new Properties();

config.put (AdminClient.CONNECTOR_HOST, host);
config.put (AdminClient.CONNECTOR_PORT, port);
config.put (AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
System.out.println ("Config: " + config);
AdminClient _soapClient = AdminClientFactory.createAdminClient(config);

// Create the application management proxy, AppManagement.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (_soapClient);

// If code for the preparation phase has been run, then you already have the options table.
// If not, create a new table and add the module-to-server relationship to it by uncommenting
// the next statement.
//Hashtable options = new Hashtable();
options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());

// Uncomment the following statements to add the module to the server relationship table if
// the preparation phase does not collect it.
//Hashtable module2server = new Hashtable();
//module2server.put ("*", target);
//options.put (AppConstants.APPDEPL_MODULE_TO_SERVER, module2server);

//Create the notification filter for listening to installation events.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (AppConstants.NotificationType);

//Add the listener.

NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.INSTALL);

// Install the application.

proxy.installApplication (earFile, appName, options, null);
System.out.println ("After install App is called..");

// Wait for some timeout. The installation application programming interface (API) is
// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.

}
catch (Exception e) {
e.printStackTrace();
}

830 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:type=

AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " + handback+ "): " + ev);

//When the installation is done, remove the listener and quit.

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Once you install the application, you must explicitly start the application or restart the server.

Starting an application through programming:

You can start an application through the administrative console, the wsadmin tool, or programming. Use
this example to start an application through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can start an application on WebSphere Application Server, you must first install your
application.

Perform the following tasks to start an application through programming.

Chapter 4. Using the administrative clients 831

1. Connect the administrative client to WebSphere Application Server.
2. Create the application management proxy.
3. Call the startApplication method on the proxy by passing the application name and optionally the list of
targets on which to start the application.

After you successfully run the code, the application is started.

The following example shows how to start an application following the previously listed steps:
//Do a get of the administrative client to connect to
//WebSphere Application Server.

AdminClient client = ...;

String appName = "myApp";
Hashtable prefs = new Hashtable();
// Use the AppManagement MBean to start and stop applications on all or some targets.
// The AppManagement MBean is on the deployment manager in the Network Deployment product
// or on server1 in WebSphere Application Server.
// Query and get the AppManagement MBean.
ObjectName on = new ObjectName ("WebSphere:type=AppManagement,process=dmgr,*");
Iterator iter = client.queryNames (on, null).iterator();
ObjectName appmgmtON = (ObjectName)iter.next();

//Start the application on all targets.

AppManagement proxy = AppManagementProxy.getJMXProxyForClient(client);
String started = proxy.startApplication(appName, prefs, null);
System.out.println("Application started on folloing servers: " + started);

//Start the application on some targets.

//String targets = "WebSphere:cell=cellname,node=nodename,server=
servername+WebSphere:cell=cellname,cluster=clusterName";
//String started1 = proxy.startApplication(appName, targets, prefs, null);
//System.out.println("Application started on following servers: " + started1)

Uninstalling an application through programming

You can uninstall an application through the administrative console, the wsadmin tool, or programming.
Use this example to uninstall an application through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can uninstall an application on WebSphere Application Server, you must first install it.

Perform the following tasks to uninstall an application through programming.

1. Get a connection to WebSphere Application Server.
2. Get the application management proxy.
3. Create the notification filter for listening to uninstallation events.
4. Add the listener.
5. Uninstall the application.
6. Wait for some timeout so that the program does not end.
7. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
8. When the uninstallation is done, remove the listener and quit.

After you successfully run the code, the application is uninstalled.

The following example shows how to uninstall an application based on the previous steps:

832 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
import java.lang.*;
import java.io.*;
import java.util.*;
import java.lang.reflect.*;
import com.ibm.websphere.management.application.*;
import com.ibm.websphere.management.application.client.*;
import com.ibm.websphere.management.*;

import javax.management.*;

public class Uninstall {

public static void main (String [] args) {

try {

// Get a connection to the server.

String host = "localhost";
String port = "8880";
String target = "WebSphere:cell=cellName,node=nodeName,server=server1";

Properties config = new Properties();

config.put (AdminClient.CONNECTOR_HOST, host);
config.put (AdminClient.CONNECTOR_PORT, port);
config.put (AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
System.out.println ("Config: " + config);
AdminClient _soapClient = AdminClientFactory.createAdminClient(config);

// Get the application management proxy.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (_soapClient);

String appName = "MyApp";

Hashtable options = new Hashtable();
options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());

//Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (AppConstants.NotificationType);

//Add the listener.

NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.UNINSTALL);

// Uninstall the application.

proxy.uninstallApplication (appName, options, null);
System.out.println ("After uninstall App is called..");

// Wait for some timeout. The installation application programming interface (API) is
// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.

}
catch (Exception e) {
e.printStackTrace();
}

// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;

Chapter 4. Using the administrative clients 833

 NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:

type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " + handback+
"): " + ev);

//When the unistallation is done, remove the listener and quit

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Updating an application through programming

You can update an existing application through the administrative console, the wsadmin tool, or
programming. Use this example to completely update an application through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can update an application on WebSphere Application Server, you must first install your
application.

Perform the following tasks to completely updaste an application through programming.

1. Connect to WebSphere Application Server.
2. Create the application management proxy.
3. Create the notification filter for listening to events.
4. Add the listener.
5. Prepare the enterprise archive (EAR) file by populating it with binding information.

834 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
6. Update the application.
7. Wait for some timeout so that the program does not end.
8. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
9. When the update is done, remove the listener and quit.

After you successfully run the code, the application is updated.

The following example shows how to update an application based on the previous steps:
import java.lang.*;
import java.io.*;
import java.util.*;
import java.lang.reflect.*;
import com.ibm.websphere.management.application.*;
import com.ibm.websphere.management.application.client.*;
import com.ibm.websphere.management.*;

import javax.management.*;

public class aa {

public static void main (String [] args) {

try {

// Connect to WebSphere Application Server.

String host = "localhost";
String port = "8880";
String target = "WebSphere:cell=cellName,node=nodeName,server=server1";

Properties config = new Properties();

config.put (AdminClient.CONNECTOR_HOST, host);
config.put (AdminClient.CONNECTOR_PORT, port);
config.put (AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
System.out.println ("Config: " + config);
AdminClient _soapClient = AdminClientFactory.createAdminClient(config);

// Create the application management proxy, AppManagement.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (_soapClient);

String appName = "MyApp";

String fileContents = "C:/test/test.ear";

// Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);
//Add the listener.
NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.INSTALL);

// Refer to the installation example to see how you can prepare the enterprise
archive (EAR)
// file by populating it with binding information.
// If code for the preparation phase has started, then you already have the options table.
// If not, create a new table and add the module-to-server relationship to it by uncommenting
// the next statement.
//Hashtable options = new Hashtable();
options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());
options.put ((AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.APPUPDATE_CONTENT_APP);

// Uncomment the following statements to add the module to the server relationship table if
// the preparation phase does not collect it
//Hashtable module2server = new Hashtable();
//module2server.put ("*", target);
//options.put (AppConstants.APPDEPL_MODULE_TO_SERVER, module2server);

Chapter 4. Using the administrative clients 835

// Update the application.
proxy.updateApplication ( appName,
null,
fileContents,
AppConstants.APPUPDATE_UPDATE,
options,
null);

// Wait for some timeout. The installation application programming interface (API) is
// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.

}
catch (Exception e) {
e.printStackTrace();
}

// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName

("WebSphere:type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//When the installation is done, remove the listener and quit

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}

836 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 System.exit (0);
}
}
}

Adding to, updating, or deleting part of an application through programming

You can add to, update, or delete part of an existing application through the administrative console, the
wsadmin tool, or programming. This example changes part of an application through programming. You
can use this example whether you add to, update, or delete part of an existing application. Multiple
changes to an application can be packaged in a single .zip file.

To learn about the structure of the .zip file, see updating applications through the administrative console.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can add to, update, or delete part of an application on WebSphere Application Server, you
must first install your application.

Perform the following tasks to add to, update, or delete part of an application through programming.
1. Connect to WebSphere Application Server.
2. Create the application management proxy.
3. Create the notification filter.
4. Add the listener.
5. Partially change the existing application.
6. Wait for some timeout so that the program does not end.
7. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
8. When the update is done, remove the listener and quit.

After you successfully run the code, you have changed the application.

The following example shows how to add to, update, or delete part of an application based on the
previous steps:
//Inputs:
//partialApp specifies the location of the partial application.
//appName specifies the name of the application.

String partialApp = "C:/apps/partial.zip";

String appName = "MyApp";

//Do a get of the administrative client to connect to

//WebSphere Application Server.

AdminClient client = ...;

//Create the application management proxy.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (client);

// Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);
//Add the listener.
NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.UPDATE);
//Partially change the existing application, MyApp.

Hashtable options = new Hashtable();

options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());
options.put (AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.

Chapter 4. Using the administrative clients 837

 APPUPDATE_CONTENT_PARTIALAPP);

proxy.updateApplication ( appName,
null,
partialApp,
null,
options,
null);

// Wait for some timeout. The installation application programming interface (API) is
// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.
}
catch (Exception e) {
e.printStackTrace();
}

}
// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:

type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//When the installation is done, remove the listener and quit

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}

838 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 System.exit (0);
}
}
}

Preparing a module and adding it to an existing application through programming

You can add a module to an existing application through the administrative console, the wsadmin tool, or
programming. Use this example to add a module through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can add a module to an application on WebSphere Application Server, you must install the
application.

Perform the following tasks to add a module to an application through programming.

1. Create an application deployment controller instance to populate the module file with binding
information.
2. Save the binding information in the module.
3. Get the installation options.
4. If the preparation phase (population of the EAR file) is not performed, the do the following actions:
a. Create an options table to be passed to the updateApplication MBean API.
b. Create a table for module to server relations and add the table to the options table.
5. Connect to WebSphere Application Server.
6. Create the application management proxy.
7. Create the notification filter.
8. Add the listener.
9. Add the module to the application.
10. Specify the target for the new module.
11. Wait for some timeout so that the program does not end.
12. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
13. When the module addition is done, remove the listener and quit.

After you successfully run the code, the module is added to the application.

The following example shows how to add a module to an application based on the previous steps:
//Inputs:
//moduleName specifies the name of the module that you add to the application.
//moduleURI specifies a URI that gives the target location of the module
// archive contents on a file system. The URI provides the location of the new
// module after installation. The URI is relative to the application URL.
//uniquemoduleURI specfies the URI that gives the target location of the
// deployment descriptor file. The URI is relative to the application URL.
//target specifies the cell, node, and server on which the module is installed.

String moduleName = "C:/apps/foo,jar";

String moduleURI = "Increment.jar";
String uniquemoduleURI = "Increment.jar+META-INF/ejb-jar.xml";
String target = "WebSphere:cell=cellname,node=nodename,server=servername";

//Create an application deployment controller instance, AppDeploymentController,

//to populate the Java aArchive (JAR) file with binding information.
//The binding information is WebSphere Application Server-specific deployment information.

Hashtable preferences = new Hashtable();

preferences.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());

Chapter 4. Using the administrative clients 839

preferences.put (AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.APPUPDATE_
CONTENT_MODULEFILE);
AppDeploymentController controller = AppManagementFactory.readArchiveForUpdate(
moduleName,
moduleURI,
AppConstants.APPUPDATE_ADD,
preferences,
null);

If the module that you add to the application lacks any bindings, add the bindings so that the module
addition works. Collect and add the bindings by using the public APIs provided with WebSphere
Application Server. Refer to Java documentation for the
com.ibm.websphere.management.application.client.AppDeploymentController instance to learn more about
how to collect and populate tasks with WebSphere Application Server specific-binding information.
//After you collect all the binding information, save it in the module.
controller.saveAndClose();

//Get the installation options.

Hashtable options = controller. getAppDeploymentSavedResults();

//Connect the administrative client, AdminClient, to WebSphere Application Server.

AdminClient client = ...;

//Create the application management proxy.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (client);

//Update the existing application, MyApp, by adding the module.

String appName = "MyApp";

options.put (AppConstants.APPUPDATE_CONTENTTYPE,
AppConstants. APPUPDATE_CONTENT_MODULEFILE);

//Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);
//Add the listener.
NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.UPDATE);

//Specify the target for the new module.

Hashtable mod2svr = new Hashtable();
options.put (AppConstants.APPDEPL_MODULE_TO_SERVER, mod2svr);
mod2svr.put (uniquemoduleURI, target);
proxy.updateApplication ( appName,
moduleURI,
moduleName,
AppConstants.APPUPDATE_ADD,
options,
null);

// Wait for some timeout. The installation application programming interface (API) is
// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.
}
catch (Exception e) {
e.printStackTrace();
}

}
// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener

840 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:

type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//When the installation is done, remove the listener and quit

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Preparing and updating a module through programming

You can update a module for an existing application through the administrative console, the wsadmin tool,
or programming. When you update a module, you replace the existing module with a new version. Use
this example to update a module through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can update a module on WebSphere Application Server, you must first install the application.

Perform the following tasks to update a module through programming.

1. Create an application deployment controller instance to populate the Java archive file with binding
information.
2. Save the binding information in the module.
3. Get the installation options.

Chapter 4. Using the administrative clients 841

 4. If the preparation phase (population of the EAR file) is not performed, the do the following actions:
a. Create an options table to be passed to the updateApplication MBean API.
b. Create a table for module to server relations and add the table to the options table.
5. Connect to WebSphere Application Server.
6. Create the application management proxy.
7. Create the notification filter.
8. Add the listener.
9. Replace the module in the application.
10. Specify the target for the new module.
11. Wait for some timeout so that the program does not end.
12. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
13. When the module addition is done, remove the listener and quit.

After you successfully run the code, the existing module is replaced with the new one.

The following example shows how to add a module to an application based on the previous steps:
//Inputs:
//moduleName specifies the name of the module that you add to the application.
//moduleURI specifies a URI that gives the target location of the module
// archive contents on a file system. The URI provides the location of the new
// module after installation. The URI is relative to the application URL.
//uniquemoduleURI specfies the URI that gives the target location of the
// deployment descriptor file. The URI is relative to the application URL.
//target specifies the cell, node, and server on which the module is installed.
//appName specifies the name of the application to update.
String moduleName = "C:/apps/foo,jar";
String moduleURI = "Increment.jar";
String uniquemoduleURI = "Increment.jar+META-INF/ejb-jar.xml";
String target = "WebSphere:cell=cellname,node=nodename,server=servername";
String appName = "MyApp";

//Get the administrative client to connect to

//WebSphere Application Server.
AdminClient client = ...;
AppManagement proxy = AppManagementProxy. getJMXProxyForClient (client);

Vector tasks = proxy.getApplicationInfo (appName, new Hashtable(), null);

//Create an application deployment controller instance, AppDeploymentController,

//to populate the Java archive (JAR) file with binding information.
//The binding information is WebSphere Application Server-specific deployment information.

Hashtable preferences = new Hashtable();

preferences.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());
preferences.put (AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.APPUPDATE_
CONTENT_MODULEFILE);
AppDeploymentController controller = AppManagementFactory.readArchiveForUpdate(
moduleName,
moduleURI,
AppConstants.APPUPDATE_UPDATE,
preferences,
tasks);

If the module that you update for the application lacks any bindings, add the bindings so that the module
update works. Collect and add the bindings by using the public APIs that are provided with WebSphere
Application Server. Refer to Java documentation for the AppDeploymentController instance to learn more
about how to collect and populate tasks with WebSphere Application Server-specific binding information.

842 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
//After you collect all the binding information, save it in the module.
controller.saveAndClose();

//Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);
//Add the listener.
NotificationListener listener = new AListener(_soapClient, myFilter, "Install:
" + appName, AppNotification.UPDATE);

//Get the installation options.

Hashtable options = controller. getAppDeploymentSavedResults();

//Update the existing application by adding the module.

options.put (AppConstants.APPUPDATE_CONTENTTYPE,
AppConstants. APPUPDATE_CONTENT_MODULEFILE);

//Specify the target for the new module

Hashtable mod2svr = new Hashtable();
options.put (AppConstants.APPDEPL_MODULE_TO_SERVER, mod2svr);
mod2svr.put (uniquemoduleURI, target);

proxy.updateApplication ( appName,
moduleURI,
moduleName,
AppConstants.APPUPDATE_UPDATE,
options,
null);
// Wait; the installation application programming interface (API) is
// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.
}
catch (Exception e) {
e.printStackTrace();
}

}
// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:type=

AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

Chapter 4. Using the administrative clients 843

 {
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//When the installation is done, remove the listener and quit

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Deleting a module through programming

You can delete a module from an existing application through the administrative console, the wsadmin
tool, or programming. Use this example to delete a module through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can delete a module from an application on WebSphere Application Server, you must first
install the application.

Perform the following tasks to delete a module through programming.

1. Connect to WebSphere Application Server.
2. Create the application management proxy.
3. Create the notification filter for listening to events.
4. Add the listener.
5. Delete the module.
6. Wait for some timeout so that the program does not end.
7. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
8. When the module is deleted, remove the listener and quit.

After you successfully run the code, the existing module is deleted from the application.

The following example shows how to delete a module from an application based on the previous steps:
//moduleURI specifies a URI that gives the target location of the module.
//appName specifies the name of the application to update.
String moduleURI = "Increment.jar";
String appName = "MyApp";

//Get the administrative client to connect to

//WebSphere Application Server.
AdminClient client = ...;

//Create the application management proxy.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (client);

844 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
//Create the notification filter.
NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);
//Add the listener.
NotificationListener listener = new AListener(_soapClient, myFilter, "Install: " + appName, AppNotification.UPDATE);

//Update the existing application, MyApp, by deleting the module.

Hashtable options = new Hashtable();
options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());
options.put (AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.APPUPDATE_CONTENT_MODULEFILE);

proxy.updateApplication ( appName,
moduleURI,
null,
AppConstants.APPUPDATE_DELETE,
options,
null);

// Wait; the installation application programming interface (API) is

// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.
}
catch (Exception e) {
e.printStackTrace();
}

}
// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:

type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//When the installation is done, remove the listener and quit

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))

Chapter 4. Using the administrative clients 845

 {
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Adding a file through programming

You can add a file to an existing application through the administrative console, the wsadmin tool, or
programming. This example describes how to add a file through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can add a file to an application on WebSphere Application Server, you must first install the
application.

Perform the following tasks to add a file to an application through programming.

1. Connect to WebSphere Application Server.
2. Create the application management proxy.
3. Create the notification filter for listening to events.
4. Add the listener.
5. Add the file to the application.
6. Wait for some timeout so that the program does not end.
7. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
8. When the file is added to the application, remove the listener and quit.

After you successfully run the code, the file is added to the application.

The following example shows how to add a file to an application based on the previous steps:
import java.lang.*;
import java.io.*;
import java.util.*;
import java.lang.reflect.*;
import com.ibm.websphere.management.application.*;
import com.ibm.websphere.management.application.client.*;
import com.ibm.websphere.management.*;

import javax.management.*;

public class FileAdd {

public static void main (String [] args) {

try {

// Get a connection to WebSphere Application Server.

String host = "localhost";
String port = "8880";
String target = "WebSphere:cell=cellName,node=nodeName,server=server1";

Properties config = new Properties();

config.put (AdminClient.CONNECTOR_HOST, host);

846 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 config.put (AdminClient.CONNECTOR_PORT, port);
config.put (AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
System.out.println ("Config: " + config);
AdminClient _soapClient = AdminClientFactory.createAdminClient(config);

// Create the application management proxy, AppManagement.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (_soapClient);

String appName = "MyApp";

String fileURI = "test.war/com/acme/abc.jsp";
String fileContents = "C:/temp/abc.jsp";

//Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);

//Add the listener.

NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.UPDATE);

Hashtable options = new Hashtable();

options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());
options.put (AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.APPUPDATE_CONTENT_FILE);

// Update the application

proxy.updateApplication ( appName,
fileURI,
fileContents,
AppConstants.APPUPDATE_ADD,
options,
null);

// Wait; the installation Application Programming Interface (API) is

// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(90000); // Wait so that the program does not end.

}
catch (Exception e) {
e.printStackTrace();
}

// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:

type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();

Chapter 4. Using the administrative clients 847

 System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//When the installation is done, remove the listener and quit

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Updating a file through programming

You can update a file for an existing application through the administrative console, the wsadmin tool, or
programming. This example describes how to update a file through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can update a file for an application on WebSphere Application Server, you must first install the
application.

Perform the following tasks to update a file through programming.

1. Connect to WebSphere Application Server.
2. Create the application management proxy.
3. Create the notification filter for listening to events.
4. Add the listener.
5. Update the file in the application.
6. Wait for some timeout so that the program does not end.
7. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
8. When the installation is done, remove the listener and quit.

After you successfully run the code, the file is updated for the application.

The following example shows how to add a file to an application based on the previous steps:
//Inputs:
//fileContents specifies the name of the file that you add to the application.
//appName specifies the name of the application.
//fileURI specifies a URI that gives the target location of the file. The URI
// provides the location of the new module after installation. The URI is
// relative to the application URL.

848 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
String fileContents = "C:/apps/test.jsp";
String appName = "MyApp";
String fileURI = "SomeWebMod.war/com/foo/abc.jsp";

//Get the administrative client to connect to

//WebSphere Application Server.
AdminClient client = ...;

//Create the application management proxy.

AppManagement proxy = AppManagementProxy. getJMXProxyForClient (client);

//Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);
//Add the listener.
NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.UPDATE);

Hashtable options = new Hashtable();

options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());
options.put (AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.APPUPDATE_CONTENT_FILE);

proxy.updateApplication ( appName,
fileURI,
fileContents,
AppConstants.APPUPDATE_UPDATE,
options,
null);

// Wait; the installation application programming interface (API) is

// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.
}
catch (Exception e) {
e.printStackTrace();
}

}
// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:

type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{

Chapter 4. Using the administrative clients 849

 AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//When the installation is done, remove the listener and quit.

if (ev.taskName.equals (eventTypeToCheck) &&

(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Deleting a file through programming

You can delete a file from an existing application through the administrative console, the wsadmin tool, or
programming. Use this example to delete a file through programming.

This task assumes a basic familiarity with MBean programming. For information on MBean programming
see MBean Java application programming interface (API) documentation.

Before you can delete a file from an application on WebSphere Application Server, you must first install the
application.

Perform the following tasks to delete a file through programming.

1. Connect to WebSphere Application Server.
2. Create the application management proxy.
3. Create the notification filter for listening to events.
4. Add the listener.
5. Delete the file from the application.
6. Wait for some timeout so that the program does not end.
7. Listen to Java Management Extensions (JMX) notifications to understand completion of the operation.
8. When the file is deleted from the application, remove the listener and quit.

After you successfully run the code, the file is deleted from the application.

The following example shows how to delete a file based on the previous steps:
//Inputs:
//fileURI specifies a URI that gives the target location of the file. The URI
// provides the location of the new module after installation. The URI is
// relative to the application URL.
//appName specifies the name of the application.

String fileURI = "Increment.jar/com/acme/Foo.class";

String appName = "MyApp";

//Get the administrative client to connect to

//WebSphere Application Server.
AdminClient client = ...;

850 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
//Create the application management proxy.
AppManagement proxy = AppManagementProxy. getJMXProxyForClient (client);

//Create the notification filter.

NotificationFilterSupport myFilter = new NotificationFilterSupport();
myFilter.enableType (NotificationConstants.TYPE_APPMANAGEMENT);
//Add the listener.
NotificationListener listener = new AListener(_soapClient, myFilter,
"Install: " + appName, AppNotification.UPDATE);

//Update the existing application, MyApp, by deleting the file.

Hashtable options = new Hashtable();
options.put (AppConstants.APPDEPL_LOCALE, Locale.getDefault());
options.put (AppConstants.APPUPDATE_CONTENTTYPE, AppConstants.APPUPDATE_CONTENT_FILE);

proxy.updateApplication ( appName,
fileURI,
null,
AppConstants.APPUPDATE_DELETE,
options,
null);

// Wait for some timeout. The installation Application Programming Interface (API) is
// asynchronous and so returns immediately.
// If the program does not wait here, the program ends.
Thread.sleep(300000); // Wait so that the program does not end.
}
catch (Exception e) {
e.printStackTrace();
}

}
// Specify the Java Management Extensions (JMX) notification listener for JMX events.
class AListener implements NotificationListener
{
AdminClient _soapClient;
NotificationFilterSupport myFilter;
Object handback;
ObjectName on;
String eventTypeToCheck;

public AListener(AdminClient cl, NotificationFilterSupport fl, Object h,

String eType) throws Exception
{
_soapClient = cl;
myFilter = fl;
handback = h;
eventTypeToCheck = eType;

Iterator iter = _soapClient.queryNames (new ObjectName("WebSphere:

type=AppManagement,*"), null).iterator();
on = (ObjectName)iter.next();
System.out.println ("ObjectName: " + on);
_soapClient.addNotificationListener (on, this, myFilter, handback);
}

public void handleNotification (Notification notf, Object handback)

{
AppNotification ev = (AppNotification) notf.getUserData();
System.out.println ("!! JMX event Recd: (handback obj= " +
handback+ "): " + ev);

//Once the installation is done, remove the listener and quit

Chapter 4. Using the administrative clients 851

 if (ev.taskName.equals (eventTypeToCheck) &&
(ev.taskStatus.equals (AppNotification.STATUS_COMPLETED) ||
ev.taskStatus.equals (AppNotification.STATUS_FAILED)))
{
try
{
_soapClient.removeNotificationListener (on, this);
}
catch (Throwable th)
{
System.out.println ("Error removing listener: " + th);
}
System.exit (0);
}
}
}

Using command line tools

There are several command line tools that you can use to start, stop, and monitor WebSphere server
processes and nodes. These tools only work on local servers and nodes. They cannot operate on a
remote server or node. To administer a remote server, you can use the wsadmin scripting program
connected to the deployment manager for the cell in which the target server or node is configured. See
Deploying and managing using scripting for more information about using the wsadmin scripting program.
You can also use the V5 administrative console which runs in the deployment manager for the cell. For
more information about using the administrative console, see Deploying and managing with the GUI.

All command line tools function relative to a particular profile. If you run a command from a
install_root/WebSphere/AppServer/bin directory, the command will run within the default profile. If you
want to specify a different profile, perform one of the following:
v Specify the -profileName option. The profile that you specify with this option will be used instead of the
default profile. For example:
1. Change to the install_root/WebSphere/AppServer/bin directory.
2. Type the following command: startServer server1 -profileName AppServerProfile
In this example, the command will function inside the AppServerProfile profile.
v Run the command from the bin directory of a specific profile. For example:
1. Change to the install_root/WebSphere/AppServer/profiles/MyProfile/bin directory.
2. Type the following command: startServer server1
In this example, the command will function inside the MyProfile profile.

For more information about using profiles, including how to obtain a list of profiles, see the wasprofile
command article.

To use the command line tools, perform the following steps:

1. Open a system command prompt.
2. Change to the bin directory.
3. Run the command.

The command runs the requested function and displays the results on the screen. Refer to the command
log file for additional information. When you use the -trace option for the command, the additional trace
data is captured in the command log file. The directory location for the log files is under the default system
log root directory, except for commands related to a specific server instance, in which case the log
directory for that server is used. You can override the default location for the command log file using the
-logfile option for the command.

852 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Example: Security and the command line tools
If you want to enable WebSphere Application Server security, you need to provide the command line tools
with authentication information. Without authentication information, the command line tools receive an
AccessDenied exception when you attempt to use them with security enabled. There are multiple ways to
provide authentication data:
v Most command line tools support a -username and -password option for providing basic authentication
data. Specify the user ID and password for an administrative user. For example, you can use a member
of the administrative console users with operator or administrator privileges, or the administrative user
ID configured in the user registry. The following example demonstrates the stopNode command, which
specifies command line parameters:
stopNode -username adminuser -password adminpw
v You can place the authentication data in a properties file that the command line tools read. The default
file for this data is the sas.client.props file in the properties directory for the WebSphere Application
Server.

startServer command
The startServer command reads the configuration file for the specified application server and starts the
server. Depending on the options you specify, you can launch a new Java virtual machine (JVM) API to
run the server process, or write the launch command data to a file. For more information about where to
run this command, see the Using command tools article.

If you are using the Windows platform and the you have the application server running as a Windows
service, the startServer command will start the associated Windows service and it will be responsible for
starting the application server.

Syntax

The command syntax is as follows:

startServer <server> [options]

where server is the name of the application server you want to start. This argument is required.

Parameters

The following options are available for the startServer command:

-nowait
Tells the startServer command not to wait for successful initialization of the launched server process.
-quiet
Suppresses the progress information that the startServer command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information is written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information to the log file for debugging purposes.
-timeout <seconds>
Specifies the waiting time before server initialization times out and returns an error.

Chapter 4. Using the administrative clients 853

-statusport <portNumber>
Specifies that an administrator can set the port number for server status callback.
-script [<script fileName>] -background
Generates a launch script with the startServer command instead of launching the server process
directly. The launch script name is an optional argument. If you do not supply the launch script name,
the default script file name is start_<server> based on the <server> name passed as the first
argument to the startServer command. The -background parameter is an optional parameter that
specifies that the generated script will run in the background when you execute it.
-J <java_option>
Specifies options to pass through to the Java interpreter.
-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:

startServer server1

startServer server1 -script (produces the start_server1.sh or .bat files)

startServer server1 -trace (produces the startserver.log file)

stopServer command
The stopServer command reads the configuration file for the specified server process. This command
sends a Java Management Extensions (JMX) command to the server telling it to shut down. By default,
the stopServer command does not return control to the command line until the server completes the shut
down process. There is a -nowait option to return immediately, as well as other options to control the
behavior of the stopServer command. For more information about where to run this command, see the
Using command tools article.

If you are using the Windows platform and the you have the application server running as a Windows
service, the stopServer command will start the associated Windows service and it will be responsible for
starting the application server.

Syntax

The command syntax is as follows:

stopServer <server> [options]

where server is the name of the configuration directory of the server you want to stop. This argument is
required.

Parameters

The following options are available for the stopServer command:

-nowait
Tells the stopServer command not to wait for successful shutdown of the server process.
-quiet
Suppresses the progress information that the stopServer command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information is written.

854 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into a file for debugging purposes.
-timeout <seconds>
Specifies the time to wait for server shutdown before timing out and returning an error.
-statusport <portNumber>
Supports an administrator in setting the port number for server status callback.
-conntype <type>
Specifies the Java Management Extensions (JMX) connector type to use for connecting to the
deployment manager. Valid types are Simple Object Access Protocol (SOAP), or Remote Method
Invocation (RMI).
-port <portNumber>
Specifies the server Java Management Extensions (JMX) port to use explicitly, so that you can avoid
reading the configuration files to obtain the information.
-username <name>
Specifies the user name for authentication if security is enabled in the server. Acts the same as the
-user option.
-user <name>
Specifies the user name for authentication if security is enabled in the server. Acts the same as the
-username option.
-password <password>
Specifies the password for authentication if security is enabled in the server.

Note: If you are running in a secure environment but have not provided a user ID and password, you
will receive the following error message:
ADMN0022E: Access denied for the stop operation on Server MBean due
to insufficient or empty credentials.

To solve this problem, provide the user ID and password information.

-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:

stopServer server1

stopServer server1 -nowait

stopServer server1 -trace (produces the stopserver.log file)

startManager command
The startManager command reads the configuration file for the Network Deployment manager process
and constructs a launch command. Depending on the options you specify, the startManager command

Chapter 4. Using the administrative clients 855

launches a new Java virtual machine (JVM) API to run the manager process, or writes the launch
command data to a file. You must run this command from the
install_root/WebSphere/AppServer/profiles/standalone/bin directory of a Network Deployment
installation.

If you are using the Windows platform and the you have the deployment manager running as a Windows
service, the startManager command will start the associated Windows service and it will be responsible
for starting the deployment manager.

Syntax

The command syntax is as follows:

startManager [options]

Parameters

The following options are available for the startManager command:

-nowait
Tells the startManager command not to wait for successful initialization of the deployment manager
process.
-quiet
Suppresses the progress information that the startManager command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information gets written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into a file using the startManager command for debugging purposes.
-timeout <seconds>
Specifies the waiting time before deployment manager initialization times out and returns an error.
-statusport <portNumber>
Specifies that an administrator can set the port number for deployment manager status callback.
-script [<script fileName>] -background
Generates a launch script with the startManager command instead of launching the deployment
manager process directly. The launch script name is an optional argument. If you do not provide the
launch script name, the default script file name is <start_dmgr>. The -background parameter is an
optional parameter that specifies that the generated script will run in the background when you
execute it.
-J-<java_option>
Specifies options to pass through to the Java interpreter.
-help
Prints a usage statement.
-? Prints a usage statement.

856 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Usage scenario

The following examples demonstrate correct syntax:

startManager

startManager -script (produces the start_dmgr.sh or .bat file)

startManager -trace (produces the startmanager.log file)

stopManager command
The stopManager command reads the configuration file for the Network Deployment manager process. It
sends a Java Management Extensions (JMX) command to the manager telling it to shut down. By default,
the stopManager command waits for the manager to complete the shutdown process before it returns
control to the command line. There is a -nowait option to return immediately, as well as other options to
control the behavior of the stopManager command. For more information about where to run this
command, see the Using command tools article.

If you are using the Windows platform and the you have the deployment manager running as a Windows
service, the stopManager command will start the associated Windows service and it will be responsible
for starting the deployment manager.

Syntax

The command syntax is as follows:

stopManager [options]

Parameters

The following options are available for the stopManager command:

-nowait
Tells the stopManager command not to wait for successful shutdown of the deployment manager
process.
-quiet
Suppresses the progress information that the stopManager command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information is written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information to a file for debugging purposes.
-timeout <seconds>
Specifies the waiting time for the manager to complete shutdown before timing out and returning an
error.
-statusport <portNumber>
Specifies that an administrator can set the port number for server status callback.

Chapter 4. Using the administrative clients 857

-conntype <type>
Specifies the Java Management Extensions (JMX) connector type to use for connecting to the
deployment manager. Valid types are Simple Object Access Protocol (SOAP) or Remote Method
Invocation (RMI).
-port <portNumber>
Specifies the deployment manager JMX port to use explicitly, so that you can avoid reading the
configuration files to obtain information.
-username <name>
Specifies the user name for authentication if security is enabled in the deployment manager. Acts the
same as the -user option.
-user <name>
Specifies the user name for authentication if security is enabled in the deployment manager. Acts the
same as the -username option.
-password <password>
Specifies the password for authentication if security is enabled in the deployment manager.

Note: If you are running in a secure environment but have not provided a user ID and password, you
receive the following error message:
ADMN0022E: Access denied for the stop operation on Server MBean due
to insufficient or empty credentials.

To solve this problem, provide the user ID and password information.

-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:

stopManager

stopManager -nowait

stopManager -trace (produces the stopmanager.log file)

startNode command
The startNode command reads the configuration file for the node agent process and constructs a launch
command. Depending on the options that you specify, the startNode command creates a new Java virtual
machine (JVM) API to run the agent process, or writes the launch command data to a file. For more
information about where to run this command, see the Using command tools article.

If you are using the Windows platform and the you have the node agent running as a Windows service,
the startNode command will start the associated Windows service and it will be responsible for starting
the node agent.

Syntax

The command syntax is as follows:

startNode [options]

Parameters

The following options are available for the startNode command:

858 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-nowait
Tells the startNode command not to wait for successful initialization of the node agent process.
-quiet
Suppresses the progress information that the startNode command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information gets written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into a file for debugging purposes.
-timeout <seconds>
Specifies the waiting time before node agent initialization times out and returns an error.
-statusport <portNumber>
Specifies that an administrator can set the port number for node agent status callback.
-script [<script fileName>] -background
Generates a launch script with the startNode command instead of launching the node agent process
directly. The launch script name is an optional argument. If you do not provide the launch script name,
the default script file name is start_<nodeName>, based on the name of the node. The -background
parameter is an optional parameter that specifies that the generated script will run in the background
when you execute it.
-J-<java_option>
Specifies options to pass through to the Java interpreter.
-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:

startNode

startNode -script (produces the start_node.bat or .sh file)

startNode -trace (produces the startnode.log file)

stopNode command
The stopNode command reads the configuration file for the Network Deployment node agent process and
sends a Java Management Extensions (JMX) command telling the node agent to shut down. By default,
the stopNode command waits for the node agent to complete shutdown before it returns control to the
command line. There is a -nowait option to return immediately, as well as other options to control the
behavior of the stopNode command. For more information about where to run this command, see the
Using command tools article.

If you are using the Windows platform and the you have the node agent running as a Windows service,
the stopNode command will start the associated Windows service and it will be responsible for starting
the node agent.

Chapter 4. Using the administrative clients 859

Syntax

The command syntax is as follows:

stopNode [options]

Parameters

The following options are available for the stopNode command:

-nowait
Tells the stopNode command not to wait for successful shutdown of the node agent process.
-quiet
Suppresses the progress information that the stopNode command prints in normal mode.
-logfile <fileNname>
Specifies the location of the log file to which information gets written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into a file for debugging purposes.
-timeout <seconds>
Specifies the waiting time for the agent to shut down before timing out and returning an error.
-statusport <portNumber>
Specifies that an administrator can set the port number for server status callback.
-stopservers
Stops all application servers on the node before stopping the node agent.
-conntype <type>
Specifies the Java Management Extensions (JMX) connector type to use for connecting to the
deployment manager. Valid types are Simple Object Access Protocol (SOAP) or Remote Method
Invocation (RMI).
-port <portNumber>
Specifies the node agent JMX port to use explicitly, so that you can avoid reading configuration files to
obtain the information.
-username <name>
Specifies the user name for authentication if security is enabled in the node agent. Acts the same as
the -user option.
-user <name>
Specifies the user name for authentication if security is enabled in the node agent. Acts the same as
the -username option.
-password <password>
Specifies the password for authentication if security is enabled in the node agent.

Note: If you are running in a secure environment but have not provided a user ID and password, you
receive the following error message:
ADMN0022E: Access denied for the stop operation on Server MBean due
to insufficient or empty credentials.

860 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 To solve this problem, provide the user ID and password information.
-help
Prints a usage statement.

Note: When requesting help for the usage statement for the stopNode command, a reference to the
stopServer command displays. All of the options displayed for this usage statement apply to
the stopNode command.
-? Prints a usage statement.

Note: When requesting help for the usage statement for the stopNode command, a reference to the
stopServer command displays. All of the options displayed for this usage statement apply to
the stopNode command.

Usage scenario

The following examples demonstrate correct syntax:

stopNode

stopNode -nowait

stopNode -trace (produces the stopnode.log file)

addNode command
The addNode command incorporates a WebSphere Application Server installation into a cell. For more
information about where to run this command, see the Using command tools article. Depending on the
size and location of the new node you incorporate into the cell, this command can take a few minutes to
complete.

The node agent server is automatically started as part of the addNode command unless you specify the
-noagent option. If you recycle the system that hosts an application server node, and did not set up the
node agent to act as an operating system daemon, you must issue a startNode command to start the
node agent before starting any application servers.

The following items are new in V6:

v Ports generated for the node agent are unique for all the profiles in the installation. For development
purposes, you can create multiple profiles on the same installation and add them to one or more cells
without worrying about ports conflicts.
v If you want to specify the ports that the node agent uses, specify it is a file with the file name passed
with the -portprops option. The format of the file is key=value pairs, one on each line, with the key being
the same as the port name in the serverindex.xml file.
v If you want to use a number of sequential ports, the -startingport option works the same as it does in
V5.x. This means that port conflicts with other profiles will not be detected.

Syntax

The command syntax is as follows:

addNode dmgr_host [dmgr_port] [-conntype type] [-includeapps]
[-startingport portnumber] [-portprops qualified_filename]
[-nodeagentshortname name] [-nodegroupname name] [-includebuses name]
[-registerservice] [-servicename name] [-servicepassword password]
[-coregroupname name] [-noagent] [-statusport port] [-quiet] [-nowait]
[-logfile filename] [-replacelog] [-trace] [-username uid]
[-password pwd] [-help]

Chapter 4. Using the administrative clients 861

The dmgr_host argument is required. All of the other arguments are optional. The default port number is
8879 for the default Simple Object Access Protocol (SOAP) port of the deployment manager. SOAP is the
default Java Management Extensions (JMX) connector type for the command. If you have multiple
WebSphere Application Server installations or multiple profiles, the SOAP port may be different than 8879.
Examine the deployment manager SystemOut.log to see the current ports in use.

Parameters

The following options are available for the addNode command:

-conntype <type>
Specifies the JMX connector type to use for connecting to the deployment manager. Valid types are
SOAP or RMI, which stands for Remote Method Invocation.
-includeapps
By default the addNode command does not carry over applications from the stand-alone servers on
the new node to the cell. In general, you should install applications using the deployment manager.
The -includeapps option tells the addNode command to carry over the applications from a node. If the
application already exists in the cell, a warning is printed and the application does not install in the
cell.
The applications will be mapped to the server that you federated using the addNode command. When
the addNode command operation completes, the applications will run on that server when the server
is started. Since these applications are part of the network deployment cell, you can map them to
other servers and clusters in the cell using the administrative console. See the Mapping modules to
servers article for more information.
By default, during application installation, application binaries are extracted in the
install_root/installedApps/cellName directory. After the addNode command, the cell name of the
configuration on the node that you added changes from the base cell name to the deployment
manager cell name. The application binaries are located where they were before the addNode
command ran, for example, install_root/installedApps/old_cellName.
If the application was installed by explicitly specifying the location for binaries as the following
example:
${INSTALL_ROOT}/${CELL}

where the variable ${CELL}, specifies the current cell name, then when the addNode command runs,
the binaries are moved to the following directory:
${INSTALL_ROOT}/currentCellName

Federating the node to a cell using the addNode command does not merge any cell level
configuration, including virtual host information. If the virtual host and aliases for the new cell do not
match WebSphere Application Server, you cannot access the applications running on the servers. You
have to manually add all the virtual host and host aliases to the new cell, using the administrative
console running on the deployment manager.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-user <name> or -username <name>
Specifies the user name for authentication if security is enabled. Acts the same as the -user option.
The user name that you choose must be a pre-existing user name.
-nowait
Tells the addNode command not to wait for successful initialization of the launched node agent
process.

862 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-quiet
Suppresses the progress information that the addNode command prints in normal mode.
-logfile <filename>
Specifies the location of the log file to which information gets written. By default, the log file is called
addNode.log and is created in the logs directory of the profile for the node being added.
-trace
Generates additional trace information in the log file for debugging purposes.
-replacelog
Replaces the log file instead of appending to the current log. By default, the addNode command
appends to the existing trace file. This option causes the addNode command to overwrite the trace
file.
-noagent
Tells the addNode command not to launch the node agent process for the new node.
-password <password>
Specifies the password for authentication if security is enabled. The password that you choose must
be one that is associated with a pre-existing user name.
-startingport <portNumber>
Supports the specification of a port number to use as the base port number for all node agent ports
created during the addNode command. With this support you can control which ports are defined for
these servers, rather than using the default port values. The starting port number is incremented to
calculate the port number for every node agent port configured during the addNode command.
-registerservice
(Windows only) Registers the node agent as a Windows service.
-servicename <user>
(Windows only) Use the given user name as the Windows service user.
-servicepassword <password>
(Windows password) Use the given password as the Windows service password.
-portprops <filename>
Passes the name of the file that contains key-value pairs of explicit ports that you want the new node
agent to use. For example, to set your SOAP and RMI ports to 3000 and 3001, create a file with the
following two lines and pass it as the parameter:
SOAP_CONNECTOR_ADDRESS=3000
BOOTSTRAP_ADDRESS=3001
-coregroupname <name>
The name of the core group in which to add this node. If you do not specify this option, the node will
be added to the DefaultCoreGroup.
-nodegroupname <name>
The name of the node group in which to add this node. If you do not specify, the node is added to the
DefaultNodeGroup.
-includebuses
Copies the buses from the node to be federated to the cell.
-nodeagentshortname <name>
The shortname to use for the new node agent.
-help
Prints a usage statement.
-? Prints a usage statement.

Chapter 4. Using the administrative clients 863

Usage scenario

The following examples demonstrate correct syntax:

addNode testhost 8879 (adds an Application Server to the deployment manager)

addNode deploymgr 8879 -trace (produces the addNode.log file)

addNode host25 8879 -nowait (does not wait for a node agent process)

where 8879 is the default port.

Best practices for adding nodes using command line tools

Use the addNode command to add a standalone node into a cell. The addNode command does the
following:
v Copies the base WebSphere Application Server cell configuration to a new cell structure. This new cell
structure matches the structure of deployment manager.
v Creates a new node agent definition for the node that the cell incorporates.
v Sends commands to the deployment manager to add the documents from the new node to the cell
repository.
v Performs the first configuration synchronization for the new node, and verifies that this node is
synchronized with the cell.
v Launches the node agent process for the new node.
v Updates the setupCmdLine.bat or setupCmdline.sh files and the wsadmin.properties file to point to the
new cell.
v After federating the node, the addNode command backs up the plugin-cfg.xml file from the
<install_root>/config/cells directory to the config/backup/base/cells directory. The addNode
command regenerates a new plugin-cfg.xml file at the Deployment Manger and the nodeSync
operation copies the files to the node level.
For information about port numbers, see port number settings in WebSphere Application Server
versions.

Tips for using the addNode command:

v Do not put WebSphere Application Server Jar files on the generic CLASSPATH variable (default class
path) for the overall system.
v Unix/Linux users: Some Unix or Linux systems create an association between the host name of the
machine and the loopback address -- 127.0.0.1 (Red Hat installations do this by default). In addition, the
/etc/nsswitch.conf file is set up to use the /etc/hosts path before trying to look up the server using a
name server. This setup can cause failures when trying to add or administrate nodes when the
deployment manager or application server is running on the Red Hat system or an Unix/Linux system
with the same setup.
If your deployment manager or your application server run on the Red Hat system, or an Unix/Linux
system with the same setup, perform the following operations to ensure that you can successfully add
and administer nodes:
– Remove the 127.0.0.1 mapping to the local host in the /etc/hosts path.
– Edit the /etc/nsswitch.conf file so that the hosts line reads:
hosts: dns files
v By default, applications that are installed on the node will not copy to the cell. If you install an
application after using the addNode command, the application will install on the cell. By specifying the
-includeapps option, you force the addNode command to copy applications from the node to the cell.
Applications with duplicate names will not copy to the cell.
v Cell-level documents are not merged. Any changes that you make to the standalone cell-level
documents before using the addNode command must be repeated on the new cell. For example, virtual
hosts.

864 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
serverStatus command
Use the serverStatus command to obtain the status of one or all of the servers configured on a node. For
more information about where to run this command, see the Using command tools article.

Syntax

The command syntax is as follows:

serverStatus <server>|-all [options]

The first argument is required. The argument is either the name of the server for which status is desired,
or the -all keyword which requests status for all servers defined on the node.

Parameters

The following options are available for the serverStatus command:

-quiet
Suppresses the progress information that the serverStatus command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information gets written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into a file for debugging purposes.
-username <name>
Specifies the user name for authentication if security is enabled. Acts the same as the -user option.
-user <name>
Specifies the user name for authentication if security is enabled. Acts the same as the -username
option.
-password <password>
Specifies the password for authentication if security is enabled.
-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:

serverStatus server1

serverStatus -all (returns status for all defined servers)

serverStatus -trace (produces the serverStatus.log file)

Chapter 4. Using the administrative clients 865

removeNode command
The removeNode command returns a node from a Network Deployment distributed administration cell to a
base WebSphere Application Server installation. For more information about where to run this command,
see the Using command tools article.

The removeNode command only removes the node-specific configuration from the cell. This command
does not uninstall any applications that were installed as the result of executing an addNode command.
Such applications can subsequently deploy on additional servers in the Network Deployment cell. As a
consequence, an addNode command with the -includeapps option executed after a removeNode
command does not move the applications into the cell because they already exist from the first addNode
command. The resulting application servers added on the node do not contain any applications. To deal
with this situation, add the node and use the deployment manager to manage the applications. Add the
applications to the servers on the node after it is incorporated into the cell.

The removeNode command does the following:

v Stops all of the running server processes in the node, including the node agent process.
v Removes the configuration documents for the node from the cell repository by sending commands to
the deployment manager.
v Copies the original application server cell configuration into the active configuration.

Depending on the size and location of the new node you remove from the cell, this command can take a
few minutes to complete.

Syntax

The command syntax is as follows:

removeNode [options]

All arguments are optional.

Parameters

The following options are available for the removeNode command:

-quiet
Suppresses the progress information that the removeNode command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information is written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into a file for debugging purposes.
-statusport <portNumber>
Specifies that an administrator can set the port number for the node agent status callback.
-username <name>
Specifies the user name for authentication if security is enabled. Acts the same as the -user option.

866 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-user <name>
Specifies the user name for authentication if security is enabled. Acts the same as the -username
option.
-password <password>
Specifies the password for authentication if security is enabled.
-force
Cleans up the local node configuration regardless of whether you can reach the deployment manager
for cell repository cleanup. After using the -force parameter, you may need to use the cleanupNode
command on the deployment manager.
-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:

removeNode -quiet

removeNode -trace (produces the removeNode.log file)

cleanupNode command
The cleanupNode command cleans up a node configuration from the cell repository. Only use this
command to clean up a node if you have a node defined in the cell configuration, but the node no longer
exists. For more information about where to run this command, see the Using command tools article.

Syntax

The command syntax is as follows:

cleanupNode <node name> <deploymgr host> <deploymgr port> [options]

where the first argument is required.

Parameters

The following options are available for the cleanupNode command:

-quiet
Suppresses the progress information that the cleanupNode command prints in normal mode.
-trace
Generates trace information into a file for debugging purposes.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.

Usage scenario

The following examples demonstrate correct syntax:

cleanupNode myNode
cleanupNode myNode -trace

Chapter 4. Using the administrative clients 867

syncNode command
The syncNode command forces a configuration synchronization to occur between the node and the
deployment manager for the cell in which the node is configured.

The node agent server runs a configuration synchronization service that keeps the node configuration
synchronized with the master cell configuration. If the node agent is unable to run because of a problem in
the node configuration, you can use the syncNode command to perform a synchronization when the
deployment manager is not running in order to force the node configuration back in sync with the cell
configuration.

For more information about where to run this command, see the Using command tools article.

Syntax

The command syntax is as follows:

syncNode <deploymgr host> <deploymgr port> [options]

where the <deploymgr host> argument is required.

Parameters

The following options are available for the syncNode command:

-stopservers
Tells the syncNode command to stop all servers on the node, including the node agent, before
performing configuration synchronization with the cell.
-restart
Tells the syncNode command to launch the node agent process after configuration synchronization
completes.
-nowait
Tells the syncNode command not to wait for successful initialization of the launched node agent
process.
-quiet
Suppresses the progress information that the syncNode command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information gets written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into a file for debugging purposes.
-timeout <seconds>
Specifies the waiting time before node agent initialization times out and returns an error.
-statusport <portnumber>
Specifies that an administrator can set the port number for node agent status callback.
-username <name>
Specifies the user name for authentication if security is enabled. Acts the same as the -user option.

868 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-user <name>
Specifies the user name for authentication if security is enabled. Acts the same as the -username
option.
-password <password>
Specifies the password for authentication if security is enabled.
-conntype <type>
Specifies the Java Management Extensions (JMX) connector type to use for connecting to the
deployment manager. Valid types are Simple Object Access Protocol (SOAP) or Remote Method
Invocation (RMI).
-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following examples demonstrate correct syntax:

syncNode testhost 8879

syncNode deploymgr 8879 -trace (produces the syncNode.log file)

syncNode host25 4444 -stopservers -restart (assumes that the deployment manager JMX port is 4444)

backupConfig command
The backupConfig command is a simple utility to back up the configuration of your node to a file. By
default, all servers on the node stop before the backup is made so that partially synchronized information
is not saved. For more information about where to run this command, see the Using command tools
article. If you do not have root authority, you must specify a path for the backup file in a location where
you have write permission. The backup file will be in zip format and a .zip extension is recommended.

Syntax

The command syntax is as follows:

backupConfig <backup_file> [options]

where backup_file specifies the file to which the backup is written. If you do not specify one, a unique
name is generated.

Parameters

The following options are available for the backupConfig command:

-nostop
Tells the backupConfig command not to stop the servers before backing up the configuration.
-quiet
Suppresses the progress information that the backupConfig command prints in normal mode.
-logfile <fileName>
Specifies the location of the log file to which information gets written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.

Chapter 4. Using the administrative clients 869

-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into the log file for debugging purposes.
-username <name>
Specifies the user name for authentication if security is enabled in the server. Acts the same as the
-user option.
-user <name>
Specifies the user name for authentication if security is enabled in the server. Acts the same as the
-username option.
-password <password>
Specifies the password for authentication if security is enabled in the server.
-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following example demonstrates correct syntax:

backupConfig

This example creates a new file that includes the current date. For example: WebSphereConfig_2003-04-
22.zip
backupConfig myBackup.zip -nostop

This example creates a file called myBackup.zip, and does not stop any servers before beginning the
backup process.

restoreConfig command
The restoreConfig command is a simple utility to restore the configuration of your node after backing up
the configuration using the backupConfig command. By default, all servers on the node stop before the
configuration restores so that a node synchronization does not occur during the restoration. If the
configuration directory already exists, it is renamed before the restoration occurs. For more information
about where to run this command, see the Using command tools article.

For AIX only, if you are using a logical directory for was_install/config, the restoreConfig command will
not work.

Syntax

The command syntax is as follows:

restoreConfig <backup_file> [options]

where backup_file specifies the file to be restored. If you do not specify one, the command will not run.

Parameters

The following options are available for the restoreConfig command:

-nowait
Tells the restoreConfig command not to stop the servers before restoring the configuration.

870 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-quiet
Suppresses the progress information that the restoreConfig command prints in normal mode.
-location <directory_name>
Specifies the directory where the backup file is restored. The location defaults to the
install_root/config directory.
-logfile <fileName>
Specifies the location of the log file to which information gets written.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-replacelog
Replaces the log file instead of appending to the current log.
-trace
Generates trace information into the log file for debugging purposes.
-username <name>
Specifies the user name for authentication if security is enabled in the server. Acts the same as the
-user option.
-user <name>
Specifies the user name for authentication if security is enabled in the server. Acts the same as the
-username option.
-password <password>
Specifies the password for authentication if security is enabled in the server.
-help
Prints a usage statement.
-? Prints a usage statement.

Usage scenario

The following example demonstrates correct syntax:

restoreConfig WebSphereConfig_2003-04-22.zip

The following example restores the given file to the /tmp directory and does not stop any servers before
beginning the restoration:
restoreConfig WebSphereConfig_2003-04-22.zip -location /tmp -nostop

Be aware that if you restore the configuration to a directory that is different from the directory that was
backed up when you performed the backupConfig command, you may need to manually update some of
the paths in the configuration directory.

EARExpander command
Use the EARExpander command to expand an enterprise archive file (EAR) into a directory to run the
application in that EAR file. You can collapse a directory containing application files into a single EAR file.
You can type EARExpander with no arguments to learn more about its options. For more information about
where to run this command, see the Using command tools article.

Syntax

The command syntax is as follows:

EarExpander -ear earName -operationDir dirName -operation <expand | collapse> [-expansionFlags <all|war>]

Chapter 4. Using the administrative clients 871

Parameters

The following options are available for the EARExpander command:

-ear
Specifies the name of the input EAR file for the expand operation or the name of the output EAR file
for the collapse operation.
-operationDir
Specifies the directory where the EAR file is expanded or specifies the directory from where files are
collapsed.
-operation <expand | collapse>
The expand value expands an EAR file into a directory structure required by the WebSphere
Application Server run time. The collapse value creates an EAR file from an expanded directory
structure.
-expansionFlags <all | war>
(Optional) The all value expands all files from all of the modules. The war value only expands the files
from Web archive file (WAR) modules.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.

Usage scenario

The following examples demonstrate correct syntax:

EARExpander -ear C:\WebSphere\AppServer\installableApps\DefaultApplication.ear
-operationDir C:\MyApps -operation expand -expansionFlags war

EARExpander -ear C:\backup\DefaultApplication.ear

-operationDir C:\MyAppsDefaultApplication.ear -operation collapse

GenPluginCfg command
This topic describes the command-line syntax for the GenPluginCfg command. This command is used to
regenerate the WebSphere Web server plug-in configuration file, plugin-cfg.xml. For more information
about where to run this command, see the Using command tools article.

CAUTION:
Regenerating the plug-in configuration can overwrite manual configuration changes that you might
want to preserve. Before performing this task, understand its implications as described in
“Communicating with Web servers” on page 116.

To regenerate the plug-in configuration, you can either click on Servers > Web Servers in the
administrative console, select a Web server and then click Generate Plug-in, or you can issue the
following command:
GenPluginCfg.sh|bat

Both methods for regenerating the plug-in configuration create a plugin-cfg.xml file in ASCII format,
which is the proper format for execution in a distributed environment.

You can use the -profileName option to define the profile of the Application Server process in a
multi-profile installation. The -profileName option is not required for running in a single profile environment.
The default for this option is the default profile.

872 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Syntax

The command syntax is as follows:

GenPluginCfg [[-option.name optionValue]...]

When the GenPluginCfg command is issued with the option -webserver.name webservrName, wsadmin
generates a plug-in configuration file for the Web server. This settings in this generated configuration file
are based on the list of applications that are deployed on the Web server. When this command is issued
without the option -webserver.name webservrName, the plug-in configuration file is generated based on
topology.

Parameters

The following options are available for the startServer command:

-config.root configroot_dir
Defaults to environment variable CONFIG_ROOT.
-profileName
Defines the profile of the Application Server process in a multi-profile installation. The -profileName
option is not required for running in a single profile environment. The default for this option is the
default profile.
-cell.name cell
Defaults to environment variable WAS_CELL.
-node.name node
Defaults to environment variable WAS_NODE.
-webserver.name webserver1
Required for creating plug-in configuration file for a given Web server.
-propagate yes/no
Applicable only when the option webserver.name is specified. Defaults to no.
-cluster.name cluster1,cluster2 | ALL
Optional list of clusters. Ignored when the option webserver.name is specified.
-server.name server1,server2
Optional list of servers. Required for single server plug-in generation. Ignored when the option
webserver.name is specified.
-output.file.name file_name
Defaults to the configroot_dir/plugin-cfg.xml file. Ignored when the option webserver.name is specified.
-destination.root root
Installation root of the machine configuration is used on. Ignored when the option webserver.name is
specified.
-destination.operating.system windows/unix
Operating system of the machine configuration is used on. Ignored when the option webserver.name is
specified.
-debug yes/no
Defaults to no.
-help
Prints a usage statement.
-? Prints a usage statement.

Chapter 4. Using the administrative clients 873

Usage scenario

To generate a plug-in configuration for all of the clusters in a cell:

GenPluginCfg -cell.name NetworkDeploymentCell

To generate a plug-in configuration for a single server:

GenPluginCfg -cell.name BaseApplicationServerCell -node.name appServerNode -server.name appServerName

To generate a plug-in configuration file for a Web server:

GenPluginCfg -cell.name BaseApplicationServerCell -node.name webserverNode -webserver.name webserverName

874 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 5. Starting and stopping quick reference
This topic describes how to start and stop the main operations in your application serving environment. It
also provides a quick guide to accessing the main tools that are provided with this product.
v Use commands to start and stop servers.

Quick reference: Issuing commands to start and stop servers

These examples are for starting and stopping the default profile on a server. Otherwise, you might need to be in the
install_root/profiles/profile_name/bindirectory to start and stop the server.
Deployment manager

Go to the install_root /bindirectory of a Network Deployment installation and run the following command. See
“startManager command” on page 855 for details and variations
startManager
Node

Go to the install_root /bindirectory of a WebSphere Application Server installation and run the following command.
See “startNode command” on page 858 for details and variations
startNode
Application server

Go to the install_root /bin directory of a WebSphere Application Server or Network Deployment installation and run
the following command. See “startServer command” on page 853 for details and variations
startServer server

where server is the application server that you want to start.

Stopping the servers

Use the same command as to start, except substitute stop for start. For example, to stop an application server, issue
the command:
stopServer server

To start and stop application server clusters, see “Starting clusters” on page 282.

v Use administrative clients and tools.

Quick reference: Opening the administrative console

To open the console, enter this Web address in your Web browser:
http://your_fully_qualified_server_name:9060/ibm/console

Depending on your configuration, your Web address might differ. Other factors can affect your ability to access the
console. See “Starting and stopping the administrative console” on page 349 for details, as needed.

– To launch a scripting client, see “Starting the wsadmin scripting client” on page 429.
– To learn about all available administrative clients, see Chapter 4, “Using the administrative clients,”
on page 349.
– For performance monitoring, see ″Monitoring performance with Tivoli Performance Viewer (TPV)″ in
the information center.
See the administrator commands that are listed in the Reference section of the information center.
v Use development and deployment tools. Use the following tools to edit deployment descriptors. A
deployment descriptor is an Extensible Markup Language (XML) file that describes how to deploy a
module or application by specifying configuration and container options. The tools are available for use
on distributed operating systems.

© Copyright IBM Corp. 2004 875

 Assembly tools
The assembly tools and Rational Web Developer provide a graphical interface for developing
code artifacts, assembling the code artifacts into various archives (modules), and configuring
related Java 2 Platform, Enterprise Edition (J2EE) Version 1.2, 1.3 or 1.4-compliant deployment
descriptors.
See ″Starting an assembly tool″ in the information center.
Application Client Resource Configuration Tool (ACRCT)
Use the ACRCT to configure deployment descriptors for client applications. See “Deploying
J2EE application clients on workstation platforms” on page 1073.
Text editor
It is not recommended because it has no built-in error checking or validation, but you can edit
deployment descriptors with any text editor with which you can edit XML files.
v Use installation and customization tools. Use the following tools to find planning information, start the
product installation, and perform customization and other activities after installation.
Launchpad
A graphical interface for launching the product installation. It also provides links to information
you might need for installation.
See ″Using the launchpad to start the installation″ in the information center.
First Steps
A desktop GUI from which you can start or stop the Application Server. It also provides access
to the administrative console.
See “firststeps command” on page 48.
Profile creation tool
The installation places the product binary files on a machine. You then must configure profiles.
Profiles are the files that define a standalone node, a managed node, or a deployment manager
node. A profile also includes all of the files that the node can change.
See “Using the Profile creation wizard” on page 54. The recommended way to access the
profile creation tool is through First Steps.
v Use troubleshooting tools - see ″Working with troubleshooting tools″ in the information center.

876 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 6. Class loading
Class loaders are part of the Java virtual machine (JVM) code and are responsible for finding and loading
class files. Class loaders enable applications that are deployed on servers to access repositories of
available classes and resources. Application developers and deployers must consider the location of class
and resource files, and the class loaders used to access those files, to make the files available to
deployed applications. Class loaders affect the packaging of applications and the run-time behavior of
packaged applications of deployed applications.

This article describes how to configure class loaders for application files or modules that are installed on
an application server.

To better understand class loaders in WebSphere Application Server, read “Class loaders.” The article
“Class loading: Resources for learning” on page 886 refers to additional sources.

Configure class loaders for application files or modules that are installed on an application server using the
administrative console. You configure class loaders to ensure that deployed application files and modules
can access the classes and resources that they need to run successfully.
1. If an installed application module uses a resource, create a resource provider that specifies the
directory name of the resource drivers. Do not specify the resource Java archive (JAR) file names. All
JAR files in the specified directory are added into the class path of the WebSphere Application Server
extensions class loader. If a resource driver requires a native library (.DLL or .so file), specify the name
of the directory that contains the library in the native path of the resource configuration.
2. Specify class-loader values for an application server.
3. Specify class-loader values for an installed enterprise application.
4. Specify the class-loader mode for an installed Web module.
5. If your deployed application uses shared library files, associate the shared library files with your
application. Use a library reference to associate a shared library file with your application.
a. If you have not done so already, define a shared library instance for each library file that your
applications need.
b. Define a library reference instance for each shared library that your application uses.
6. Optional: Configure class preloading.

Class loaders
Class loaders are part of the Java virtual machine (JVM) code and are responsible for finding and loading
class files. Class loaders enable applications that are deployed on servers to access repositories of
available classes and resources. Application developers and deployers must consider the location of class
and resource files, and the class loaders used to access those files, to make the files available to
deployed applications.

The run-time environment of WebSphere Application Server uses the following class loaders to find and
load new classes for an application in the following order:
1. The bootstrap, extensions, and CLASSPATH class loaders created by the Java virtual machine
The bootstrap class loader uses the boot class path (typically classes in jre/lib) to find and load
classes. The extensions class loader uses the system property java.ext.dirs (typically jre/lib/ext) to
find and load classes. The CLASSPATH class loader uses the CLASSPATH environment variable to
find and load classes.
The CLASSPATH class loader contains the Java 2 Platform, Enterprise Edition (J2EE) application
programming interfaces (APIs) of the WebSphere Application Server product in the j2ee.jar file.
Because the J2EE APIs are in this class loader, you can add libraries that depend on the J2EE APIs to

© Copyright IBM Corp. 2004 877

 the class path system property to extend a server class path. However, a preferred method of
extending a server class path is to add a shared library.
2. A WebSphere-specific extensions class loader
The WebSphere Application Server extensions class loader loads the WebSphere Application Server
run-time and J2EE classes that are required at run time. The extensions class loader uses a
ws.ext.dirs system property to determine the path that is used to load classes. Each directory in the
ws.ext.dirs class path and every Java archive (JAR) file or ZIP file in these directories is added to the
class path used by this class loader.
The WebSphere Application Server extensions class loader also loads resource provider classes into a
server if an application module installed on the server refers to a resource that is associated with the
provider and if the provider specifies the directory name of the resource drivers.
3. One or more application module class loaders that load elements of enterprise applications running in
the server
The application elements can be Web modules, enterprise bean (EJB) modules, resource adapters
archives (RAR files), and dependency JAR files. Application class loaders follow J2EE class-loading
rules to load classes and JAR files from an enterprise application. The WebSphere Application Server
run time enables you to associate a shared library class path with an application.

Each class loader is a child of the previous class loader. That is, the application module class loaders are
children of the WebSphere-specific extensions class loader, which is a child of the CLASSPATH Java class
loader. Whenever a class needs to be loaded, the class loader usually delegates the request to its parent
class loader. If none of the parent class loaders can find the class, the original class loader attempts to
load the class. Requests can only go to a parent class loader; they cannot go to a child class loader. If the
WebSphere Application Server class loader is requested to find a class in a J2EE module, it cannot go to
the application module class loader to find that class and a ClassNotFoundException error occurs. After a
class is loaded by a class loader, any new classes that it tries to load reuse the same class loader or go
up the precedence list until the class is found.

Class preloading

The first time that a WebSphere Application Server process starts, the name of each run-time class that is
loaded and the name of the JAR file that contains the class are written to a preload file. The names of
non-runtime classes such as custom services, resource classes such as db2java.zip, classes on the JVM
class path, and application classes are not written to the preload file. Subsequent startups of the process
use the preload file to start the process more quickly.

Preload files have the .preload extension. WebSphere Application Server processes that have preload
files include the following:

Process Preload file name

Application server cell_name.node_name.server_name.preload
startserver WsServerLauncher.preload
launchClient launchClient.preload

Running the startserver server1 command causes the startserver command to use a
WsServerLauncher.preload file and the server to use a cell_name.node_name.server1.preload file. Later,
running a command such as startserver server1 -script, where the -script option creates a new script,
uses the cell_name.node_name.server1.preload file only.

Preload files, by default, are installed in the install_root directory.

New classes required during the startup of a process are added to the preload file. Any classes that are
removed from a process are ignored during subsequent startups. Although it is not necessary, an
administrator can delete the preload file and force a refresh that removes the ignored classes from the file.
878 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Class-loader isolation policies

The number and function of the application module class loaders depend on the class-loader policies that
are specified in the server configuration. Class loaders provide multiple options for isolating applications
and modules to enable different application packaging schemes to run on an application server.

Two class-loader policies control the isolation of applications and modules:

Application class-loader policy
Application class loaders consist of EJB modules, dependency JAR files, resource adapters, and
shared libraries. Depending on the application class-loader policy, an application class loader can
be shared by multiple applications (Single) or unique for each application (Multiple). The
application class-loader policy controls the isolation of applications that are running in the system.
When set to Single, applications are not isolated. When set to Multiple, applications are isolated
from each other.
WAR class-loader policy
By default, Web module class loaders load the contents of the WEB-INF/classes and WEB-INF/lib
directories. The application class loader is the parent of the Web module class loader. You can
change the default behavior by changing the Web application archive (WAR) class-loader policy of
the application.
The WAR class-loader policy controls the isolation of Web modules. If this policy is set to
Application, then the Web module contents also are loaded by the application class loader (in
addition to the EJB files, RAR files, dependency JAR files, and shared libraries). If the policy is set
to Module, then each Web module receives its own class loader whose parent is the application
class loader.

Note: WebSphere Application Server class loaders never load application client modules.

For each application server in the system, you can set the application class-loader policy to Single or
Multiple. When the application class-loader policy is set to Single, then a single application class loader
loads all EJB modules, dependency JAR files, and shared libraries in the system. When the application
class-loader policy is set to Multiple, then each application receives its own class loader that is used for
loading the EJB modules, dependency JAR files, and shared libraries for that application.

This application class loader can load the Web modules for each application if the class-loader policy of
that WAR module is also set to Application. If the class-loader policy of the WAR module is set to
Application, then the application loader loads the WAR module classes. If the WAR class-loader policy is
set to Module, then each WAR module receives its own class loader.

The following example shows that when the application class-loader policy is set to Single, a single
application class loader loads all of the EJB modules, dependency JAR files, and shared libraries of all
applications on the server. The single application class loader can also load Web modules if an application
has its WAR class-loader policy set to Application. Applications that have a WAR class-loader policy set
to Module use a separate class loader for Web modules.
Application class-loader policy: Single

Application 1
Module: EJB1.jar
Module: WAR1.war
MANIFEST Class-Path: Dependency1.jar
WAR Classloader Policy = Module
Application 2
Module: EJB2.jar
MANIFEST Class-Path: Dependency2.jar
Module: WAR2.war
WAR Classloader Policy = Application

Chapter 6. Class loading 879

 WebSphere extensions classloader
Classpath:
WebSphere/AppServer/classes
WebSphere/AppServer/lib
WebSphere/AppServer/lib/ext

Application classloader
Classpath:
Ejb1.jar
Dependency1.jar
Ejb1.jar
Dependency2.jar
WAR2.war (WEB-INF/classes, ...)

WAR classloader
WAR1.war

The following example shows that when the application class-loader policy of an application server is set
to Multiple, each application on the server has its own class loader. An application class loader also loads
its Web modules if the application WAR class-loader policy is set to Application. If the policy is set to
Module, then a Web module uses its own class loader.
Application class-loader policy: Multiple

Application 1
Module: EJB1.jar
Module: WAR1.war
MANIFEST Class-Path: Dependency1.jar
WAR Classloader Policy = Module
Application 2
Module: EJB2.jar
MANIFEST Class-Path: Dependency2.jar
Module: WAR2.war
WAR Classloader Policy = Application

WebSphere extensions classloader

Classpath:
WebSphere/AppServer/classes
WebSphere/AppServer/lib
WebSphere/AppServer/lib/ext

Application classloader Application classloader

Classpath: Classpath:
Ejb1.jar Ejb2.jar
Dependency1.jar Dependency2.jar
WAR2.war (WEB-INF/classes, ...)

WAR classloader
WAR1.war

880 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Class-loader modes

Two values for a class-loader mode are supported:

Parent First
The Parent First class-loader mode causes the class loader to delegate the loading of classes to
its parent class loader before attempting to load the class from its local class path. This value is
the default for the class-loader policy and for standard JVM class loaders.
Parent Last
The Parent Last class-loader mode causes the class loader to attempt to load classes from its
local class path before delegating the class loading to its parent. Using this policy, an application
class loader can override and provide its own version of a class that exists in the parent class
loader.

The following settings determine the mode of a class loader:

v If the application class-loader policy of an application server is Single, the application class-loader
policy of an application server defines the mode for an application class loader.
v If the application class-loader policy of an application server is Multiple, the class-loader mode of an
application defines the mode for an application class loader.
v If the WAR class-loader policy of an application is Module, the WAR class-loader policy of a Web
module defines the mode for a WAR class loader.

Configuring class loaders of a server

You can configure the application class loaders for an application server. Class loaders enable applications
that are deployed on the application server to access repositories of available classes and resources.

This article assumes that an administrator created an application server on a WebSphere Application
Server product.

Configure the class loaders of an application server to set class-loader policy and mode values which
affect all applications that are deployed on the server. Use the administrative console to configure the
class loaders.
1. Click Servers > Application Servers >server_name to access the settings page for an application
server.
2. Specify the application class-loader policy for the application server. The application class-loader policy
controls the isolation of applications that run in the system (on the server). An application class loader
groups enterprise bean (EJB) modules, shared libraries, resource adapter archives (RAR files), and
dependency Java archive (JAR) files associated to an application. Dependency JAR files are JAR files
that contain code which can be used by both enterprise beans and servlets. The application
class-loader policy controls whether an application class loader can be shared by multiple applications
or is unique for each application. Use the settings page for the application server to specify the
application class-loader policy for the server:

Option Description
Single Applications are not isolated from each other. Uses a single application class
loader to load all of the EJB modules, shared libraries, and dependency JAR
files in the system.
Multiple Applications are isolated from each other. Gives each application its own
class loader to load the EJB modules, shared libraries, and dependency JAR
files of that application.

3. Specify the application class-loader mode for the application server. The application class loading
mode specifies the class-loader mode when the application class-loader policy is Single. On the
settings page for the application server, select either of the following values:

Chapter 6. Class loading 881

Option Description
Parent first Causes the class loader to delegate the loading of classes to its parent class
loader before attempting to load the class from its local class path. Parent
first is the default value for class loading mode.
Parent last Causes the class loader to attempt to load classes from its local class path
before delegating the class loading to its parent. Using this policy, an
application class loader can override and provide its own version of a class
that exists in the parent class loader.

4. Specify the class-loader mode for the class loader.

a. On the settings page for the application server, click Java and Process Management > Class
loader to access the Class loader page.
b. On the Class loader page, click New to access the settings page for a class loader.
c. On the settings page for a class loader, specify the class-loader mode. The Parent First value
causes the class loader to delegate the loading of classes to its parent class loader before
attempting to load the class from its local class path. The Parent Last value causes the class
loader to attempt to load classes from its local class path before delegating the class loading to its
parent.
d. Click OK.
An identifier is assigned to a class-loader instance. The instance is added to the collection of class
loaders shown on the Class loader page.

Save the changes to the administrative configuration.

Class loader collection

Use this page to manage class-loader instances on an application server. A class loader determines
whether an application class loader or a parent class loader finds and loads Java class files for an
application.

To view this administrative console page, click Servers > Application Servers >server_name > Java and
Process Management > Class loader.

Class loader ID
Provides a string that is unique to the server identifying the class-loader instance. The product assigns the
identifier.

Class loader mode

Specifies the class-loader mode when the application class-loader policy for the application server is
Single.

You specify a policy of Single on the settings page for the application server, accessed by clicking
Servers > Application Servers >server_name. When the policy is Single, applications are not isolated
from each other. A single application class loader contains all of the EJB modules, dependency JAR files,
and shared libraries in the system.

The Parent First value causes the class loader to delegate the loading of classes to its parent class
loader before attempting to load the class from its local class path. The Parent Last value causes the
class loader to attempt to load classes from its local class path before delegating the class loading to its
parent. Specifying the Parent Last value enables an application class loader to override and provide its
own version of a class that exists in the parent class loader.

882 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Class loader settings
Use this page to configure a class loader for applications that reside on an application server.

To view this administrative console page, click Servers > Application Servers >server_name > Java and
Process Management > Class loader >class_loader_ID.

Class loader ID
Provides a string that is unique to the server identifying the class-loader instance. The product assigns the
identifier.

Data type String

Class loader mode

Specifies the class-loader mode when the application class-loader policy for the application server is
Single.

You specify a policy of Single on the settings page for the application server, accessed by clicking
Servers > Application Servers >server_name. When the policy is Single, applications are not isolated
from each other. A single application class loader contains all of the EJB modules, dependency JAR files,
and shared libraries in the system.

The Parent First value causes the class loader to delegate the loading of classes to its parent class
loader before attempting to load the class from its local class path.

The Parent Last value causes the class loader to attempt to load classes from its local class path before
delegating the class loading to its parent. Specifying the Parent Last value enables an application class
loader to override and provide its own version of a class that exists in the parent class loader.

Data type String

Default Parent First

Configuring application class loaders

You can set values that control the class-loading behavior of an installed enterprise application. Class
loaders enable an application to access repositories of available classes and resources.

This article assumes that you installed an application on an application server.

Configure the class loaders of an enterprise application to set class-loader policy and mode values for this
application.

An application class loader groups enterprise bean (EJB) modules, shared libraries, resource adapter
archives (RAR files), and dependency Java archive (JAR) files associated to an application. Dependency
JAR files are JAR files that contain code which can be used by both enterprise beans and servlets.

An application class loader is the parent of a Web application archive (WAR) class loader. By default, a
Web module has its own WAR class loader to load the contents of the Web module. The WAR
class-loader policy value of an application class loader determines whether the WAR class loader or the
application class loader is used to load the contents of the Web module.

Use the administrative console to configure the class loaders.

1. Click Applications > Enterprise Applications >application_name to access the settings page for an
enterprise application.

Chapter 6. Class loading 883

2. Specify the class-loader mode for the application. The application class-loader mode specifies whether
the class loader searches in the parent class loader or in the application class loader first to load a
class. The default is to search in the parent class loader before searching in the application class
loader to load a class. Select either of the following values for Class loader mode:

Option Description
Parent First Causes the class loader to search in the parent class loader first to load a
class. This value is the standard for Development Kit class loaders and
WebSphere Application Server class loaders.
Parent Last Causes the class loader to search in the application class loader first to load
a class. By specifying Parent Last, your application can override classes
contained in the parent class loader.
Tip: Specifying the Parent Last value might result in LinkageErrors or
ClassCastException messages if you have mixed use of overridden classes
and non-overridden classes.

3. Specify whether to use a single or multiple class loaders to load Web application archives (WAR files)
of your application. By default, Web modules have their own WAR class loader to load the contents of
the WEB-INF/classes and WEB-INF/lib directories. The default WAR class loader value is Module, which
uses a separate class loader to load each WAR file. Setting the value to Application causes the
application class loader to load the Web module contents as well as the EJB modules, shared libraries,
RAR files, and dependency JAR files associated to the application. The application class loader is the
parent of the WAR class loader. Select either of the following values for WAR class loader policy:

Option Description
Module Uses a different class loader for each WAR file.
Application Uses a single class loader to load all of the WAR files in your application.

4. Specify whether to enable class reloading when application files are updated. By default, class
reloading is not enabled. See the description for Enable class reloading in “Enterprise application
settings” on page 908 for details on enabling and disabling reloading. You might specify different
values for EJB modules and for Web modules such as servlets and JavaServer page (JSP) files.
5. Specify the number of seconds to scan the application’s file system for updated files. The value
specified for Reloading interval takes effect only if class reloading is enabled. The default is the value
of the reloading interval attribute in the IBM extension (META-INF/ibm-application-ext.xmi) file of the
enterprise application (EAR file). You might specify different values for EJB modules and for Web
modules such as servlets and JSP files.
To enable reloading, specify an integer value that is greater than zero (for example, 1 to 2147483647).
To disable reloading, specify zero (0).
6. Click OK.

Save the changes to the administrative configuration.

Configuring Web module class loaders

You can set values that control the class-loading behavior of an installed Web module.

This article assumes that you installed a Web module on an application server.

Configure the class-loader mode value of an installed Web module. By default, a Web module has its own
Web application archive (WAR) class loader to load the contents of the Web module, which are in the
WEB-INF/classes and WEB-INF/lib directories.

884 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
An application class loader is the parent of a WAR class loader. The WAR class-loader policy value of an
application class loader determines whether the WAR class loader or the application class loader is used
to load the contents of the Web module. The default WAR class loader policy value is Module. If the policy
is set to Module, then each Web module receives its own class loader whose parent is the application
class loader. If the policy is set to Application on the settings page of an enterprise application, then the
application class loader loads the Web module contents as well as the enterprise bean (EJB) modules,
shared libraries, resource adapter archives (RAR files), and dependency Java archive (JAR) files
associated to an application. Thus, the configuration of the parent application class loader affects the WAR
class loader.

Use the administrative console to configure the application and WAR class loaders.
1. If you have not done so already, configure the application class loader. Settings such as WAR class
loader policy, Enable class reloading, and Reloading interval can affect Web module class loading.
If WAR class loader policy is set to Module, then the Web module receives its own class loader and
the WAR class-loader policy of the Web module defines the mode for a WAR class loader. If the policy
is set to Application, then the application class loader loads the Web module contents.
2. Click Applications > Enterprise Application >application_name > Web modules
>Web_module_name to access the settings page for a deployed Web module.
3. Specify the class-loader mode for the installed Web module. The Web module class-loader mode
specifies whether the class loader searches in the parent application class loader or in the WAR class
loader first to load a class. The default is to search in the parent application class loader before
searching in the WAR class loader to load a class. Select either of the following values for Class
loader mode:

Option Description
Parent first Causes the class loader to search in the parent application class loader first
to load a class. This is the standard for Development Kit class loaders and
WebSphere Application Server class loaders.
Tip: If classes and resources needed by the Web module cannot be
accessed by the application class loader, but can be accessed by the WAR
class loader, specify Parent last. If the application class loader cannot find
a class, the class loader delegates the request to find the class to its parent,
the WebSphere Application Server extensions class loader. If the WebSphere
Application Server extensions class loader cannot find the class, the class
loader delegates the request to its parent, the bootstrap, extensions, and
CLASSPATH class loaders created by the Java virtual machine. Requests
can only go to a parent class loader; they cannot go to a child class loader.
Thus, if Parent first is specified, the WAR class loader never receives a
request to load a class.
Parent last Causes the class loader to search in the WAR class loader first to load a
class. By specifying Parent last, your WAR class loader can override
classes contained in the parent application class loader.
Tip: Specifying the Parent last value might result in LinkageErrors or
ClassCastException messages if you have mixed use of overridden classes
and non-overridden classes.

4. Click OK.

Save the changes to the administrative configuration.

Configuring class preloading

Class preloading affects how quickly a WebSphere Application Server process starts.

Chapter 6. Class loading 885

The first time that a WebSphere Application Server process starts up, the name of each class that is
loaded and the name of the JAR file that contains the class are written to a preload file. Subsequent
startups of the process use the preload file to start the process more quickly.

No configuring of class preloading is necessary.

However, an administrator can disable or enable preloading explicitly. By default, class preloading is
enabled for WebSphere Application Server processes. To change the configuration for class preloading, an
administrator sets new values for system properties.
v Disable class preloading. Set the Java virtual machine (JVM) system property
ibm.websphere.preload.classes to false.
1. In the administrative console, click Servers > Application Servers >server_name > Java and
Process Management > Process Definition > Java Virtual Machine to access the Java Virtual
Machine page.
2. On the Java Virtual Machine page, specify -Dibm.websphere.preload.classes=false for Generic
JVM arguments.
3. Click OK.
4. Save your administrative configuration.
5. Stop the application server and then restart the application server.
v Enable class preloading again. If you disabled class preloading, you can enable it again by doing either
of the following:
– Set the JVM system property to true. On the Java Virtual Machine page, specify
-Dibm.websphere.preload.classes=true for Generic JVM arguments.
– Remove the JVM system property that was created to disable class preloading. On the Java Virtual
Machine page, remove the value -Dibm.websphere.preload.classes=false specified for Generic
JVM arguments.
After you change the JVM system property, click OK, save your administrative configuration, stop the
application server, and then restart the application server.
v Regenerate a class preload file. Delete the .preload file for the WebSphere Application Server process.
When the process next starts up, a new class preload file is generated for the process.

Class loading: Resources for learning

Use the following links to find relevant supplemental information about class loaders. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of the
information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

Refer to the information center for links to information applicable to WebSphere Application Server
generally, such as lists of IBM technical papers, Redbooks and samples.

For current information available from IBM Support on known problems and their resolution, see the IBM
Support page. IBM Support has documents that can save you time gathering information that is needed to
resolve this problem. Before opening a PMR, see the IBM Support page.

View links to additional information about:

v Programming model and decisions
v Programming instructions and examples
v Programming specifications

886 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Programming model and decisions
v J2EE Class Loading Demystified
v Understanding J2EE Application Server Class Loading Architectures

Programming instructions and examples

v Developing and Deploying Modular J2EE Applications with WebSphere Studio Application Developer
and WebSphere Application Server
v IBM WebSphere Application Server Programming

Programming specifications
v Sun’s J2EETM Platform Specification
v Sun’s J2EETM Extension Mechanism Architecture

Chapter 6. Class loading 887

888 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 7. Deploying and administering applications
Deploying an application file consists of installing the application file on a server configured to hold
installable modules.

Before installing an enterprise application or other installable module on an application server, you must
develop and assemble the module and configure the target server. Before choosing a server as a target
for the module, ensure that the node version for the server is compatible with your module

During installation, you can configure the module enough to enable it to run on the server. After
installation, you can configure the module further, start or stop the application, and otherwise manage its
activity.
v Install application files on an application server.
v Edit the administrative configuration for an application.
v Start and stop the application.
v Export applications.
v Export DDL files.
v Update an application or module.
v Uninstall applications.
v Remove a file from an application or module.

After making changes to administrative configurations of your applications in the administrative console,
ensure that you save the changes.

If a changed application or module is deployed on a cluster, click Rollout Update on the Enterprise
Applications page to propagate the changed configuration on all cluster members of the cluster on which
the application or module is deployed. Rollout Update sequentially updates the configuration on the
nodes that contain cluster members.

Enterprise (J2EE) applications

Enterprise applications (or J2EE applications) are applications that conform to the Java 2 Platform,
Enterprise Edition, specification.

Enterprise applications can consist of the following:

v Zero or more EJB modules
v Zero or more Web modules
v Zero or more connector modules (packaged in RAR files)
v Zero or more application client modules
v Additional JAR files containing dependent classes or other components required by the application
v Any combination of the above

A J2EE application is represented by, and packaged in, an enterprise archive (EAR) file.

System applications
A system application is a J2EE enterprise application that is central to a WebSphere Application Server
product.

Examples of system applications include adminconsole and filetransfer.

© Copyright IBM Corp. 2004 889

Because a system application is an important part of a WebSphere Application Server product, a system
application is deployed when the product is installed and is updated only through a product fix or upgrade.
Users cannot change the metadata for a system application such as its J2EE bindings or J2EE
extensions, unless the metadata assigns users and groups for security purposes. Non-security related
metadata requiring a change must be updated through a product fix or upgrade.

System applications are not shown in the list of installed applications on the console Enterprise
Applications page, or through wsadmin and Java application programming interfaces, to prevent users
from accidentally stopping, updating or removing the system applications.

Note that J2EE Samples are not system applications even though they are provided as part of a
WebSphere Application Server product. Similarly, applications that support changes to their metadata are
not system applications.

Installing application files

As part of deploying an application, you install application files on a server configured to hold installable
modules.

Before you can install your application files on an application server, you must configure the target
application server. As part of configuring the server, determine whether your application files can be
installed to your deployment targets.

Also, before you install the files, assemble modules as needed.

Installable modules include enterprise archive (EAR), enterprise bean (EJB), Web archive (WAR), and
resource adapter (connector or RAR) files. Complete the following steps to install your files.
1. Determine which method to use to install your application files. WebSphere Application Server provides
several ways to install modules.
2. Install the application files using
v Administrative console
v wsadmin scripts
v Java administrative programs that use JMX APIs
v Java programs that define a J2EE DeploymentManager object in accordance with J2EE Deployment
API Specification (JSR-88)
3. Start the deployed application files using
v Administrative console
v wsadmin startApplication
v Java programs that use ApplicationManager or AppManagement MBeans
v Java programs that define a J2EE DeploymentManager object in accordance with J2EE Deployment
API Specification (JSR-88)

Save the changes to your administrative configuration.

When saving the configuration, synchronize the configuration with the nodes where the application is
expected to run.

Next, test the application. For example, point a Web browser at the URL for a deployed application and
examine the performance of the application. If the application does not perform as desired, update the
application, then save and test it again.

890 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Installable module versions
The contents of a module affect whether you can install the module on a WebSphere Application Server
Version 6.0 and later (6.x) deployment target, or must install the module on a Version 5.0 and later (5.x)
deployment target.

Installable application modules

You can install an application, enterprise bean (EJB) module or Web module developed for a Version 5.x
product on a 5.x or 6.x deployment target, provided the module--
v Does not support Java 2 Platform, Enterprise Edition (J2EE) 1.4;
v Does not call any 6.x runtime application programming interfaces (APIs); and
v Does not use any 6.x product features.

If the module supports J2EE 1.4, calls a 6.x API or uses a 6.x feature, then you must install the module on
a 6.x deployment target.

Selecting options such as Pre-compile JSP, Use Binary Configuration, Deploy Web services or
Deploy enterprise beans during application installation to a 6.x server or a 6.x deployment manager
indicates that the application uses 6.x product features. You cannot deploy such applications on a 5.x
deployment target. You must deploy such applications on a 6.x deployment target.

Similarly, you must deploy an application that uses J2EE 1.4 features such as Java Authorization Contract
for Containers (JACC) provided by an application server on a 6.x deployment target.

Installable RAR files

You can install a standalone resource adapter (connector) module, or RAR file, developed for a Version
5.x product to a 5.x or 6.x deployment target, provided the module does not call any 6.x runtime APIs. If
the module calls a 6.x API, then you must install the module on a 6.x deployment target.

Deployment targets

A 5.x deployment target is a server or a cluster with at least one member on a WebSphere Application
Server Version 5 product.

A 6.x deployment target is a server or cluster with all members on a WebSphere Application Server
Version 6 product.
Table 14. Compatible deployment target versions for 5.x and 6.x modules
Module type Module Java Module calls 6.x Client versions that Deployment target
support runtime APIs or can install module versions
uses 6.x features?
Application, EJB, J2EE 1.3 No 5.x or 6.x 5.x or 6.x
Web, or client
Application, EJB, J2EE 1.3 Yes 6.x 6.x
Web, or client
Application, EJB, J2EE 1.4 Yes or No 6.x 6.x
Web, or client
Resource adapter JCA 1.0 No 5.x or 6.x 5.x or 6.x
Resource adapter JCA 1.0 Yes 6.x 6.x
Resource adapter JCA 1.5 Yes or No 6.x 6.x

Chapter 7. Deploying and administering applications 891

Ways to install applications or modules
WebSphere Application Server provides several ways to install application files on a server or cluster.

Installable files include enterprise archive (EAR), enterprise bean (EJB), Web archive (WAR), resource
adapter (connector or RAR), and application client modules.
Table 15. Ways to install application files
Option Method Modules Comments Starting after install
Administrative Click Applications > All EAR, EJB, WAR, Provides one of the Click Start on the
console install wizard Install New RAR, and application easier ways to install Enterprise
Application in the client files application files. See Applications page
See “Installing console navigation “Preparing for accessed by clicking
application files with tree and follow application installation Applications >
the console” on page instructions in the settings” on page 898 Enterprise
893. wizard. for guidance. For Applications in the
applications that do console navigation
not require changes tree.
to the default
bindings, select the
Generate Default
Bindings option and
then, on the Summary
panel, click Finish.
wsadmin scripts Invoke AdminApp All EAR, EJB, WAR, ″Getting started with v Invoke the
object install RAR, and application scripting″ in the AdminApp
commands in a script client files information center startApplication
or at a command provides an overview command.
prompt. of wsadmin. v Invoke the
startApplication
method on an
ApplicationManager
MBean using
AdminControl.
.
Java application Install programs by All EAR files Use MBeans to install Start the application
programming completing the steps the application. by calling the
interfaces in ″Managing startApplication
applications through method on a proxy.
programming″ in the
information center.
WebSphere rapid Briefly, do the All J2EE modules, WebSphere rapid Use any of the above
deployment following: including EAR files deployment offers the options to start the
1. Update your J2EE and standalone EJB, following advantages: application. Clicking
Refer to articles under application files. WAR, RAR, and v You do not need to Start on the
Rapid deployment of 2. Set up the rapid application client files Enterprise
assemble your
J2EE applications in deployment Applications page is
J2EE application
the information center. environment. the easiest option.
files prior to
3. Create a free-form deployment.
project.
v You do not need to
4. Launch a rapid
use other
deployment
installation tools
session.
mentioned in this
5. Drop your
table to deploy the
updated
files.
application files
into the free-form
project.

892 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Table 15. Ways to install application files (continued)
Java programs Code programs that All J2EE modules, v Uses J2EE Call the J2EE
use J2EE including EAR files Application DeploymentManager
DeploymentManager and standalone EJB, Deployment (JSR-88) method start
(JSR-88) methods. WAR, RAR, and Specification in a program to start
application client files (JSR-88). the deployed modules
when the module’s
v Can customize
running environment
modules using
initializes.
DConfigBeans.

Installing application files with the console

Installing application files consists of placing assembled enterprise application, Web, enterprise bean
(EJB), or other installable modules on a server or cluster configured to hold the files. Installed files that
start and run properly are considered deployed.

Before installing enterprise application files, ensure that you are installing your application files onto a
compatible deployment target. If the deployment target is not compatible, select a different target.

To install new enterprise application files to a WebSphere Application Server configuration, you can use
the administrative console, the wsadmin tool, or Java programs that call J2EE DeploymentManager
(JSR-88) methods. This article describes how to use the administrative console to install an application,
EJB component, or Web module.

Important: After you start performing the steps below, click Cancel to exit if you decide not to install the
application. Do not simply move to another administrative console page without first clicking
Cancel on an application installation page.
1. Click Applications > Install New Application in the console navigation tree. The first of two
Preparing for application installation pages is displayed.
2. On the first Preparing for application installation page:
a. Specify the full path name of the source enterprise application file (.ear file otherwise known as
an EAR file). The EAR file that you are installing can be either on the client machine (the machine
that runs the Web browser) or on the server machine (the machine to which the client is
connected). If you specify an EAR file on the client machine, then the administrative console
uploads the EAR file to the machine on which the console is running and proceeds with
application installation. You can also specify a standalone Web application archive (WAR) or Java
archive (JAR) file for installation.
b. If you are installing a standalone WAR file, specify the context root.
c. Click Next.
3. On the second Preparing for application installation page:
a. Select whether to generate default bindings. Using the default bindings causes any incomplete
bindings in the application to be filled in with default values. Existing bindings are not altered. You
can customize default values used in generating default bindings. For example, you can specify a
Java Naming and Directory Interface (JNDI) prefix for EJB files in EJB modules, default data
source and connection factory settings for EJB modules, virtual host for Web modules, and so on.
“Preparing for application installation settings” on page 898 describes available customizations
and provides sample bindings.
b. Click Next. If security warnings are displayed, click Continue. The Install New Application pages
are displayed. If you chose to generate default bindings, you can proceed to the Summary step
(last step below). “Example: Installing an EAR file using the default bindings” on page 903
provides sample steps.
4. On the Step: Select installation options panel, provide values for the following settings specific to
WebSphere Application Server. Default values are used if you do not specify a value.

Chapter 7. Deploying and administering applications 893

 a. For Pre-compile JSP, specify whether to precompile JavaServer page (JSP) files as a part of
installation. The default is not to precompile JSP files. Install onto a 6.x deployment target. If you
select Pre-compile JSP and try installing your application onto a 5.x deployment target, the
installation is rejected. For this option, install only onto a 6.x deployment target.
b. For Directory to install application, specify the directory to which the application EAR file will be
installed. The default value is the value of APP_INSTALL_ROOT/cell_name, where the
APP_INSTALL_ROOT variable is install_root/installedApps; for example,
C:\WebSphere\AppServer\profiles\profile _name\installedApps\cell_name.

Note: If an installation directory is not specified when an application is installed on a single-server

(base) configuration, the application is installed in APP_INSTALL_ROOT/base_cell_name.
When the base server is made a part of a Network Deployment configuration (using the
addNode utility), the cell name of the new configuration becomes the cell name of the
deployment manager node. If the -includeapps option is used for the addNode utility, then
the applications that are installed prior to the addNode operation still use the installation
directory APP_INSTALL_ROOT/base_cell_name. However, an application that is installed after
the base server is added to the network configuration uses the default installation directory
APP_INSTALL_ROOT/network_cell_name. To move the application to the
APP_INSTALL_ROOT/network_cell_name location upon running the addNode operation, you
should explicitly specify the installation directory as ${APP_INSTALL_ROOT}/${CELL} during
installation. In such a case, the application files can always be found under
APP_INSTALL_ROOT/current_cell_name.
c. For Distribute application, specify whether WebSphere Application Server expands or deletes
application binaries in the installation destination. The default is to enable application distribution.
As a result, when you save changes in the console, application binaries for newly installed
applications are expanded to the directory specified. The binaries are also deleted when you
uninstall and save changes to the configuration. If you disable this option, then you must ensure
that the application binaries are expanded appropriately in the destination directories of all nodes
where the application is expected to run.
d. For Use Binary Configuration, specify whether the application server uses the binding,
extensions, and deployment descriptors located with the application deployment document, the
deployment.xml file (default), or those located in the EAR file. The default is not to use the binary
configuration. If you select Use Binary Configuration, your application files must be installed
onto a 6.x deployment target. The files cannot be installed onto a 5.x deployment target.
e. For Deploy enterprise beans, specify whether the EJBDeploy tool runs during application
installation. The tool generates code needed to run EJB files. You must enable this setting in the
following situations:
v The EAR file was assembled using an assembly tool such as Rational Web Developer or
Application Server Toolkit (AST) and the EJBDeploy tool was not run during assembly.
v The EAR file was not assembled using an assembly tool.
v The EAR file was assembled using versions of the Application Assembly Tool (AAT) previous to
Version 5.
Enabling this setting might cause the installation program to run for several minutes. Also, install
onto a 6.x deployment target. If you select Deploy enterprise beans and try installing your
application onto a 5.x deployment target, the installation is rejected. For this option, install only
onto a 6.x deployment target.
f. For Application name, name the application. Application names must be unique within a cell and
cannot contain characters that are not allowed in object names.
g. For Create MBeans for resources, specify whether to create MBeans for various resources
(such as servlets or JSP files) within an application when the application is started. The default is
to create MBean instances.
h. For Enable class reloading, specify whether to enable class reloading when application files are
updated. The default is not to enable class reloading. For EJB modules or any non-Web modules,

894 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 enabling class reloading sets reloadEnabled to true in the deployment.xml file for the application.
If an application’s class definition changes, the application server run time stops and starts the
application to reload application classes.
For Web modules such as servlets and JSP files, a Web container reloads a Web module only
when the IBM extension reloadingEnabled in the ibm-web-ext.xmi file is set to true. You can set
reloadingEnabled to true when editing the extended deployment descriptors of your Web module
in an assembly tool.
To disable reloading of a Web module, set the IBM extension reloadingEnabled in the
ibm-web-ext.xmi file to false. Or, if the Web module has the IBM extension reloadingEnabled in
the ibm-web-ext.xmi file set to true, enable class loading, and set the Reload interval property
to zero (0).
i. For Reload interval in seconds, specify the number of seconds to scan the application’s file
system for updated files. The default is the value of the reload interval attribute in the IBM
extension (META-INF/ibm-application-ext.xmi) file of the EAR file. To enable reloading, specify a
value greater than zero (for example, 1 to 2147483647). To disable reloading, specify zero (0).
The reload interval specified here takes effect only if class reloading is enabled.
j. For Deploy Web services, specify whether the Web services deploy tool wsdeploy runs during
application installation. The tool generates code needed to run applications using Web services.
The default is not to run the wsdeploy tool. You must enable this setting if the EAR file contains
modules using Web services and has not previously had the wsdeploy tool run on it, either from
the Deploy menu choice of an assembly tool or from a command line. Note that if you select
Deploy and try installing your application onto a 5.x deployment target, the installation is rejected.
For this option, install only onto a 6.x deployment target.
k. For Validate Input off/warn/fail, specify whether WebSphere Application Server examines the
application references specified during application installation or updating and, if validation is
enabled, warns you of incorrect references or fails the operation. An application typically refers to
resources using data sources for container managed persistence (CMP) beans or using resource
references or resource environment references defined in deployment descriptors. The validation
checks whether the resource referred to by the application is defined in the scope of the
deployment target of that application. Select off for no resource validation, warn for warning
messages about incorrect resource references, or fail to stop operations that fail as a result of
incorrect resource references.
l. For Process embedded configuration, specify whether the embedded configuration should be
processed. An embedded configuration consists of files such as resource.xml and variables.xml.
When selected or true, the embedded configuration is loaded to the application scope from the
.ear file. If the .ear file does not contain an embedded configuration, the default is false. If the
.ear file contains an embedded configuration, the default is true.
5. On the Step: Map modules to servers panel, for every module select a target server or cluster from
the Clusters and Servers list. Select the check box beside Module to select all of the application
modules or select individual modules. Ensure that you are installing your application onto an
appropriate deployment target. You can specify Web servers as targets that route requests to the
application. The plug-in configuration file plugin-cfg.xml for each Web server is generated based on
the applications which are routed through it. If you want a Web server to serve the application, use
the Ctrl key to select an application server or cluster and the Web server together in order to have
the plug-in configuration file plugin-cfg.xml for that Web server generated based on the applications
which are routed through it.
6. If your application uses EJB modules, on the Step: Provide JNDI Names for Beans panel, specify a
JNDI name for each enterprise bean in every EJB module. You must specify a JNDI name for every
enterprise bean defined in the application. For example, for the EJB module MyBean.jar, specify
MyBean.
7. If your application uses EJB modules that contain Container Managed Persistence (CMP) beans that
are based on the EJB 1.x specification, for Step: Provide default datasource mapping for

Chapter 7. Deploying and administering applications 895

 modules containing 1.x entity beans, specify a JNDI name for the default data source for the EJB
modules. The default data source for the EJB modules is optional if data sources are specified for
individual CMP beans.
8. If your application has CMP beans that are based on the EJB 1.x specification, for Step: Map
datasources for all 1.x CMP, specify a JNDI name for data sources to be used for each of the 1.x
CMP beans. The data source attribute is optional for individual CMP beans if a default data source is
specified for the EJB module that contains CMP beans. If neither a default data source for the EJB
module nor a data source for individual CMP beans are specified, then a validation error displays
after you click Finish and the installation is cancelled.
9. If your application defines EJB references, for Step: Map EJB references to beans, specify JNDI
names for enterprise beans that represent the logical names specified in EJB references. Each EJB
reference defined in the application must be bound to an EJB file before clicking Finish on the
Summary panel.
10. If your application defines resource references, for Step: Map resource references to resources,
specify JNDI names for the resources that represent the logical names defined in resource
references. You can optionally specify login configuration name and authentication properties for the
resource. After specifying authentication properties, click OK to save the values and return to the
mapping step. Each resource reference defined in the application must be bound to a resource
defined in your WebSphere Application Server configuration before clicking on Finish on the
Summary panel.
11. If your application uses Web modules, for Step: Map virtual hosts for web modules, select a virtual
host from the list that should map to a Web module defined in the application. The port number
specified in the virtual host definition is used in the URL that is used to access artifacts such as
servlets and JSP files in the Web module. Each Web module must have a virtual host to which it
maps. Not specifying all needed virtual hosts will result in a validation error displaying after you click
Finish on the Summary panel.
12. If the application has security roles defined in its deployment descriptor then, for Step: Map security
roles to users/groups, specify users and groups that are mapped to each of the security roles.
Select Role to select all of the roles or select individual roles. For each role, you can specify if
predefined users such as Everyone or All authenticated users are mapped to it. To select specific
users or groups from the user registry:
a. Select a role and click Lookup users or Lookup groups.
b. On the Lookup users/groups panel displayed, enter search criteria to extract a list of users or
groups from the user registry.
c. Select individual users or groups from the results displayed.
d. Click OK to map the selected users or groups to the role selected on the Step: Map security
roles to users/groups panel.
13. If the application has Run As roles defined in its deployment descriptor, for Step: Map RunAs roles
to user, specify the Run As user name and password for every Run As role. Run As roles are used
by enterprise beans that must run as a particular role while interacting with another enterprise bean.
Select Role to select all of the roles or select individual roles. After selecting a role, enter values for
the user name, password, and verify password and click Apply.
14. If your application contains EJB 1.x CMP beans that do not have method permissions defined for
some of the EJB methods, for Step: Ensure all unprotected 1.x methods have the correct level of
protection, specify if you want to leave such methods unprotected or assign protection with deny all
access.
15. If your application contains message driven enterprise beans, for Step: Provide Listener Ports or
activation specification JNDI name for messaging beans, provide a listener port name or an
activation specification JNDI name for every message driven bean. A listener port name must be
provided when using the JMS providers: Version 5 default messaging, WebSphere MQ, or generic.
An activation specification must be provided when the application’s resources are configured using
the default messaging provider or any generic J2C resource adapter that supports inbound
messaging. If neither is specified, then a validation error is displayed after you click Finish on the

896 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Summary panel. Also, if the module containing the message driven bean is deployed on a 5.x
deployment target and a listener port is not specified, then a validation error is displayed after you
click Next.
16. If your application uses EJB modules that contain CMP beans that are based on the EJB 2.x
specification, for Step: Provide default datasource mapping for modules containing 2.x entity
beans, specify a JNDI name for the default data source and the type of resource authorization to be
used for the default data source for the EJB modules. You can optionally specify a login configuration
name and authentication properties for the data source. When creating authentication properties, you
must click OK to save the values and return to the mapping step. The default data source for EJB
modules is optional if data sources are specified for individual CMP beans.
17. If your application has CMP beans that are based on the EJB 2.x specification, on the Step: Map
datasources for all 2.x CMP panel, for each of the 2.x CMP beans specify a JNDI name and the
type of resource authorization for data sources to be used. You can optionally specify a login
configuration name and authentication properties for the data source. When creating authentication
properties, you must click OK to save the values and return to the mapping step. The data source
attribute is optional for individual CMP beans if a default data source is specified for the EJB module
that contains CMP beans. If neither a default data source for the EJB module nor a data source for
individual CMP beans are specified, then a validation error is displayed after you click Finish and
installation is cancelled.
18. If your application contains EJB 2.x CMP beans that do not have method permissions defined in the
deployment descriptors for some of the EJB methods, on the Step: Ensure all unprotected 2.x
methods have the correct level of protection panel, specify whether you want to assign a specific
role to the unprotected methods, add the methods to the exclude list, or mark them as unchecked.
Methods added to the exclude list are marked as uncallable. For methods marked unchecked no
authorization check is performed prior to their invocation.
19. If the Deploy enterprise beans setting is enabled on the Select installation options panel, then
you can specify options for the EJBDeploy tool on the Step: Provide options to perform the EJB
Deploy panel. On this panel, you can specify extra class paths, RMIC options, database types, and
database schema names to be used while running the EJBDeploy tool. The tool is run on the EAR
file during installation after you click Finish.
20. If your application contains resource environment references, for Step: Map resource environment
references to resources, specify JNDI names of resources that map to the logical names defined in
resource environment references. If each resource environment reference does not have a resource
associated with it, after you click Finish a validation error is displayed.
21. If your application defines Run-As Identity as System Identity, for Step: Replace RunAs System to
RunAs Roles, you can optionally change it to Run-As role and specify a user name and password
for the Run As role specified. Selecting System Identity implies that the invocation is done using the
WebSphere Application Server security server ID and should be used with caution as this ID has
more privileges.
22. If your application has resource references that map to resources that have an Oracle database doing
backend processing, for Step: Specify the isolation level for Oracle type provider, specify or
correct the isolation level to be used for such resources when used by the application. Oracle
databases support ReadCommitted and Serializable isolation levels only.
23. If your application uses message driven beans, for Step: Build message destination to
administered objects, specify the JNDI name of the J2C administered object to bind the message
destination reference to the message driven beans.
24. If your application contains an embedded .rar file, for Step: Map JCA resources to resources,
specify the name and JNDI name of each J2C connection factory, J2C administered object and J2C
activation specification.
25. If your application contains an embedded .rar file, its activationSpec property has the value
Destination, and its introspected type is javax.jms.Destination, for Step: Bind J2CActivationSpec
to Destination Jndi name, specify the jndiName value for each activation bound to it.

Chapter 7. Deploying and administering applications 897

26. If your application has EJB modules for which deployment code has been generated for multiple
backend databases using an assembly tool, for Step: Select a backend ID, specify the backend ID
representing the backend database to be used when the EJB module runs.
27. On the Summary panel, verify the cell, node, and server onto which the application modules will
install:
a. Beside Cell/Node/Server, click Click here.
b. Verify the settings.
c. Click Finish.

Several messages are displayed, indicating whether your application file is installing successfully.

If you receive an OutOfMemory exception and the source application file does not install, your system
might not have enough memory or your application might have too many modules in it to install
successfully onto the server. If lack of system memory is not the cause of the exception, package your
application again so the .ear file has fewer modules. If lack of system memory and the number of
modules are not the cause of the exception, check the options you specified on the Java Virtual Machine
page of the application server running the administrative console. Then, try installing the application file
again.

During installation certain application files are extracted in the directory represented by the
configuration session and, when the configuration is saved, these files are saved in the WebSphere
Application Server configuration repository. On Windows machines, there is a limit of 256 characters for
file paths. Therefore, the application installation might fail if the path for application files in the configuration
session or in the configuration repository exceeds the limit of 256 characters. You might see FileNotFound
exceptions with path name too long in the message. To overcome such problems, make application names
and module URI names shorter in length, which helps reduce the file path length. Then, try installing the
application file again.

After the application file installs successfully, do the following:

1. Associate any shared libraries that the application needs to the application.
2. Save the changes to your configuration. The application is registered with the administrative
configuration and application files are copied to the target directory, which is
install_root/installedApps/cell_name by default or the directory that you designate. For the Network
Deployment installation, files are copied to remote nodes when the configuration on the deployment
manager synchronizes with the configuration on individual nodes.
3. Start the application.
4. Test the application. For example, point a Web browser at the URL for the deployed application and
examine the performance of the application. If necessary, update the application.

Preparing for application installation settings

Use this page to install an application (EAR file) or module (JAR or WAR file).

To view this administrative console page, click Applications > Install New Application.

Follow the steps on this page to install an application or module. You must complete, at minimum, the first
step; you must complete some or all of the later steps, depending on whether you are installing an
application, EJB module, or Web module.

Path:

Specifies the fully qualified path to the .ear, .jar, or .war file for the enterprise application.

Use Local file system if the browser and application files are on the same machine (whether or not the
server is on that machine, too).

898 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Use Remote file system if the application file resides on any node in the current cell context.You can
browse the entire file system of a node if the node agent or deployment manager is running on that
selected node. Only .ear, .jar, or .war files are shown during the browsing.

During application installation, application files typically are uploaded from a client machine running the
browser to the server machine running the administrative console, where they are deployed. In such
cases, use the Web browser running the administrative console to select EAR, WAR, or JAR modules to
upload to the server machine.

In some cases, however, the application files reside on the file system of any of the nodes in a cell. To
have the application server install these files, use the Remote file system option.

Also use the Remote file system option to specify an application file already residing on the machine
running the application server. For example, the field value on a Windows machine might be
C:\WebSphere\AppServer\installableApps\test.ear. If you are installing a stand-alone WAR module, then
specify the context root as well.

After the application file is transferred, the Remote file system value shows the path of the temporary
location on the deployment manager orserver machine.

Context root:

Specifies the context root of the Web application (WAR).

This field is used only to install a stand-alone WAR file. The context root is combined with the defined
servlet mapping (from the WAR file) to compose the full URL that users type to access the servlet. For
example, if the context root is /gettingstarted and the servlet mapping is MySession, then the URL is
http://host:port/gettingstarted/MySession.

Generate Default Bindings:

Specifies whether to generate default bindings. If you place a check mark in the check box, then any
incomplete bindings in the application are filled in with default values. Existing bindings are not altered.

By choosing this option, you can directly jump to the Summary step and install the application if none of
the steps have a red asterisk (*) next to them. A red asterisk denotes that the step has incomplete data
and requires a valid value. On the Summary panel, verify the cell, node and server on which the
application is installed.

Bindings are generated as follows:

v EJB JNDI names are generated of the form prefix/ejb-name. The default prefix is ejb, but can be
overridden. The ejb-name is as specified in the deployment descriptors <ejb-name> tag.
v EJB references are bound as follows: If an <ejb-link> is found, it is honored. Otherwise, if a unique
enterprise bean is found with a matching home (or local home) interface as the referenced bean, the
reference is resolved automatically.
v Resource reference bindings are derived from the <res-ref-name> tag. Note that this action assumes
that the java:comp/env name is the same as the resource global JNDI name.
v Connection factory bindings (for EJB 2.0 JAR files) are generated based on the JNDI name and
authorization information provided. This action results in default connection factory settings for each EJB
2.0 JAR file in the application being installed. No bean-level connection factory bindings are generated.
v Data source bindings (for EJB 1.1 JAR files) are generated based on the JNDI name, data source user
name password options. This results in default data source settings for each EJB JAR file. No
bean-level data source bindings are generated.
v For EJB2.1 or EJB2.0 message-driven beans deployed as JCA 1.5-compliant resources, the JNDI
names corresponding to activationSpec instances are generated in the form eis/MDB_ejb-name.

Chapter 7. Deploying and administering applications 899

 Message Destination references are bound as follows: if a <message-destination-link> is found then
the JNDI name is set to ejs/message-destination-linkName. Otherwise the JNDI name is set to
eis/message-destination-refName.
v For EJB 2.0 message-driven beans deployed against a listener ports, the listener ports are derived from
the MDB <ejb-name> tag with the string Port appended.
v For .war files, the virtual host is set as default_host unless otherwise specified.

The default strategy suffices for most applications or at least for most bindings in most applications.
However, it does not work if:
v You want to explicitly control the global JNDI names of one or more EJB files.
v You need tighter control of data source bindings for container-managed persistence (CMP) beans. That
is, you have multiple data sources and need more than one global data source.
v You must map resource references to global resource JNDI names that are different from the
java:comp/env name.

In such cases, you can change the behavior with an XML document (a custom strategy). Use the Specific
bindings file field to specify a custom strategy and see the field’s help for examples.

Prefixes:

Specifies prefixes to use for generated JNDI names.

Override:

Specifies whether generated bindings are to override existing bindings.

If Override existing bindings is selected, the existing bindings are overridden by the generated ones.

Connection Factory Bindings:

Specifies the default data source JNDI name.

If Default connection factory bindings is selected, specify the JNDI name for the default data source to
be used with the bindings. Also specify the resource authorization.

Virtual Host:

Specifies the virtual host for the Web module.

Specific bindings file:

Specifies a bindings file that overrides the default binding.

Change the behavior of the default binding with an XML document (a custom strategy). Custom strategies
extend the default strategy so you only need to customize those areas where the default strategy is
insufficient. Thus, you only need to describe how you want to change the bindings generated by the
default strategy; you do not have to define bindings for the entire application.

Brief examples of how to override various aspects of the default bindings generator follow:

Controlling an EJB JNDI name

<?xml version="1.0"?>
<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<ejb-jar-binding>
<jar-name>helloEjb.jar</jar-name>

900 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 <ejb-bindings>
<ejb-binding>
<ejb-name>HelloEjb</ejb-name>
<jndi-name>com/acme/ejb/HelloHome</jndi-name>
</ejb-binding>
</ejb-bindings>
</ejb-jar-binding>
</module-bindings>
</dfltbndngs>

Note: Ensure that the setting for <ejb-name> matches the ejb-name entry in the EJB JAR deployment
descriptor. Here the setting is <ejb-name>HelloEjb</ejb-name>.

Setting the connection factory binding for an EJB JAR file

<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<ejb-jar-binding>
<jar-name>yourEjb20.jar</jar-name>
<connection-factory>
<jndi-name>eis/jdbc/YourData_CMP</jndi-name>
<res-auth>Container</res-auth>
</connection-factory>
</ejb-jar-binding>
</module-bindings>
</dfltbndngs>

Setting the connection factory binding for an EJB file

<?xml version="1.0">
<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<ejb-jar-binding>
<jar-name>yourEjb20.jar</jar-name>
<ejb-bindings>
<ejb-binding>
<ejb-name>YourCmp20</ejb-name>
<connection-factory>
<jndi-name>eis/jdbc/YourData_CMP</jndi-name>
<res-auth>PerConnFact</res-auth>
</connection-factory>
</ejb-binding>
</ejb-bindings>
</ejb-jar-binding>
</module-bindings>
</dfltbndngs>

Note: Ensure that the setting for <ejb-name> matches the ejb-name tag in the deployment descriptor. Here
the setting is <ejb-name>YourCmp20</ejb-name>.

Setting the message destination reference JNDI for a specific enterprise bean

Example XML extract in a custom strategy file for setting message-destination-refs for a specific enterprise
bean.
<?xml version="1.0">
<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<ejb-jar-binding>
<jar-name>yourEjb21.jar</jar-name>
<ejb-bindings>
<ejb-binding>
<ejb-name>YourSession21</ejb-name>

Chapter 7. Deploying and administering applications 901

 <message-destination-ref-bindings>
<message-destination-ref-binding>
<message-destination-ref-name>jdbc/MyDataSrc</message-destination-ref-name>
<jndi-name>eis/somAO</jndi-name>
</message-destination-ref-binding>
</message-destination-ref-bindings>
</ejb-binding>
</ejb-bindings>
</ejb-jar-binding>
</module-bindings>
</dfltbndngs>

Note: Ensure that the setting for <ejb-name> matches the ejb-name tag in the deployment descriptor. Here
the setting is <ejb-name>YourSession21</ejb-name>. Also ensure that the setting for
<message-destination-ref-name> matches the message-destination-ref-name tag in the
deployment descriptor. Here the setting is <message-destination-ref-
name>jdbc/MyDataSrc</message-destination-ref-name>.

Overriding a resource reference binding from a WAR, EJB JAR file, or J2EE client JAR file

Example code for overriding a resource reference binding from a WAR file follows. Use similar code to
override a resource reference binding from an enterprise bean (EJB) JAR file or a J2EE client JAR file.
<?xml version="1.0"?>
<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<war-binding>
<jar-name>hello.war</jar-name>
<resource-ref-bindings>
<resource-ref-binding>
<resource-ref-name>jdbc/MyDataSrc</resource-ref-name>
<jndi-name>war/override/dataSource</jndi-name>
</resource-ref-binding>
</resource-ref-bindings>
</war-binding>
</module-bindings>
</dfltbndngs>

Note: Ensure that the setting for <resource-ref-name> matches the resource-ref tag in the deployment
descriptor. Here the setting is <resource-ref-name>jdbc/MyDataSrc</resource-ref-name>.

Overriding the JNDI name for a message-driven bean deployed as a JCA 1.5-compliant resource

Example XML extract in a custom strategy file for overriding the JMS activationSpec JNDI name for an
EJB 2.1 or EJB 2.0 message-driven bean deployed as a JCA 1.5-compliant resource.
<?xml version="1.0"?>
<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<ejb-jar-binding>
<jar-name>YourEjbJar.jar</jar-name>
<ejb-bindings>
<ejb-binding>
<ejb-name>YourMDB</ejb-name>
<activationspec-jndi-name>activationSpecJNDI</activationspec-jndi-name>
</ejb-binding>
</ejb-bindings>
</ejb-jar-binding>
</module-bindings>
</dfltbndngs>

Overriding the JMS listener port name for an EJB 2.0 message-driven bean

902 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Example XML extract in a custom strategy file for overriding the JMS listener port name for an EJB 2.0
message-driven bean deployed against a listener port.
<?xml version="1.0"?>
<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<ejb-jar-binding>
<jar-name>YourEjbJar.jar</jar-name>
<ejb-bindings>
<ejb-binding>
<ejb-name>YourMDB</ejb-name>
<listener-port>yourMdbListPort</listener-port>
</ejb-binding>
</ejb-bindings>
</ejb-jar-binding>
</module-bindings>
</dfltbndngs>

Overriding an EJB reference binding from an EJB JAR, WAR file, or EJB file

Example code for overriding an EJB reference binding from an EJB JAR file follows. Use similar code to
override an EJB reference binding from a WAR file or an EJB file.
<?xml version="1.0"?>
<!DOCTYPE dfltbndngs SYSTEM "dfltbndngs.dtd">
<dfltbndngs>
<module-bindings>
<ejb-jar-binding>
<jar-name>YourEjbJar.jar</jar-name>
<ejb-ref-bindings>
<ejb-ref-binding>
<ejb-ref-name>YourEjb</ejb-ref-name>
<jndi-name>YourEjb/JNDI</jndi-name>
</ejb-ref-binding>
</ejb-ref-bindings>
</ejb-jar-binding>
</module-bindings>
</dfltbndngs>

Example: Installing an EAR file using the default bindings

If application bindings were not specified for all enterprise beans or resources in an application during
application development or assembly, you can select to generate default bindings. After application
installation, you can modify the bindings as needed using the administrative console.

An example of a simple .ear file installation using the default bindings follows:
1. Go to the Preparing for application install pages.
Click Applications > Install New Application in the console navigation tree.
2. For Path to the new application, specify the full path name of the .ear file.
For this example, the base file name is my_appl.ear and the file resides on a server at
C:\sample_apps.
a. Select the Remote file system radio button and click Browse.
b. On the Browse Remote Filesystems page, click on the name of the node that holds the
my_appl.ear file, C:\, sample_apps, my_appl.ear, and then OK.
3. Now that a value is given for Specify path, on the first Preparing for application installation page, click
Next.
4. On the second Preparing for application installation page, select Generate Default Bindings and click
Next.
Using the default bindings causes any incomplete bindings in the application to be filled in with default
values. Existing bindings are not changed. By choosing this option, you can skip many of the steps on
the Install New Application page and go directly to the Summary step.

Chapter 7. Deploying and administering applications 903

5. If application security warnings are displayed, read the warnings and click Continue.
6. On the Install New Application page, click on Summary, the last step.
7. On the Summary panel, verify the cell, node, and server onto which the application files will install.
a. Beside the Cell/Node/Server option, click Click here.
b. On the Map modules to servers panel, select the server onto which the application files will install
from the Clusters and Servers list, click Module to select all of the application modules, and click
Next.
Note that on the Map modules to servers panel, you can map modules to other servers such as
Web servers. If you want a Web server to serve the application, use the Ctrl key to select an
application server or cluster and the Web server together in order to have the plug-in configuration
file plugin-cfg.xml for that Web server generated based on the applications which are routed
through it.
Because my_appl.ear does not require any additional settings to complete an installation, the
Summary panel is displayed again.
8. On the Summary panel, click Finish.

Examine the application installation progress messages. If the application installs successfully, save your
administrative configuration. You can now see the name of your application in the list of deployed
applications on the Enterprise Applications page accessed by clicking Applications > Enterprise
Applications in the console navigation tree.

If the application does not install successfully, read the messages to identify why the installation failed.
Correct problems with the application as needed and try installing the application again.

Installing J2EE modules with JSR-88

You can install Java 2 Platform, Enterprise Edition (J2EE) modules on an application server provided by a
WebSphere Application Server product using the J2EE Deployment API Specification (JSR-88).

JSR-88 defines standard application programming interfaces (APIs) to enable deployment of J2EE
applications and stand-alone modules to J2EE product platforms. The J2EE Deployment Specification
Version 1.1 is available at http://java.sun.com/j2ee/tools/deployment/reference/docs/index.html as part of
the J2EE 1.4 Application Server Developer Release.

Read about JSR-88 and APIs used to manage applications at http://java.sun.com/j2ee/tools/deployment/.

JSR-88 defines a contract between a tool provider and a platform that enables tools from multiple vendors
to configure, deploy and manage applications on any J2EE product platform. The tool provider typically
supplies software tools and an integrated development environment (IDE) for developing and assembly of
J2EE application modules. The J2EE platform provides application management functions that deploy,
undeploy, start, stop, and otherwise manage J2EE applications.

WebSphere Application Server is a J2EE 1.4 specification-compliant platform that implements the JSR-88
APIs. Complete the following steps to deploy (install) J2EE modules on an application server provided by
the WebSphere Application Server platform.
1. Code a Java program that can access the JSR-88 DeploymentManager class for WebSphere
Application Server.
a. Write code that finds the JAR manifest file key J2EE-DeploymentFactory-Implementation-Class.
Under JSR-88, your code finds the DeploymentFactory using the JAR manifest file key
J2EE-DeploymentFactory-Implementation-Class. For WebSphere Application Server, the application
management JAR file containing this key and providing support is install_root/lib/wjmxapp.jar.
After your code finds the DeploymentFactory, the deployment tool can create an instance of the
WebSphere DeploymentFactory and register the instance with its DeploymentFactoryManager. For
example:

904 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
import javax.enterprise.deploy.shared.factories.DeploymentFactoryManager;
import javax.enterprise.deploy.spi.DeploymentManager;
import javax.enterprise.deploy.spi.factories.DeploymentFactory;
import java.util.jar.JarFile;

// Get the DeploymentFactory implementation class from the MANIFEST.MF file.

JarFile wjmxappJar = new JarFile(new File(wasHome + "/lib/wjmxapp.jar"));
java.util.jar.Manifest manifestFile = wjmxappJar.getManifest();
Attributes attributes = manifestFile.getMainAttributes();
String key = "J2EE-DeploymentFactory-Implementation-Class";
String className = attributes.getValue(key);
// Get an instance of the DeploymentFactoryManager
DeploymentFactoryManager dfm = DeploymentFactoryManager.getInstance();

// Create an instance of the WebSphere Application Server DeploymentFactory.

Class deploymentFactory = Class.forName(className);
DeploymentFactory deploymentFactoryInstance =
(DeploymentFactory) deploymentFactory.newInstance();

// Register the DeploymentFactory instance with the DeploymentFactoryManager.

dfm.registerDeploymentFactory(deploymentFactoryInstance);

// Provide WebSphere Application Server URL, user ID, and password.

// For more information, see the step that follows.
wsDM = dfm.getDeploymentManager(
"deployer:WebSphere:myserver:8880", null, null);
b. Write code that accesses the DeploymentManager instance for WebSphere Application Server. The
WebSphere Application Server URL for deployment has the format
"deployer:WebSphere:host:port"

The example in the previous step, ″deployer:WebSphere:myserver:8880″, tries to connect to host

myserver at port 8880 using the SOAP connector, which is the default.
The URL for deployment can have an optional parameter connectorType. For example, to use the
RMI connector to access myserver, code the URL as follows:
"deployer:WebSphere:myserver:2809?connectorType=RMI"
2. Optional: Code a Java program that can customize or deploy J2EE applications or modules using the
JSR-88 support provided by WebSphere Application Server.
3. Start the deployed J2EE applications or standalone J2EE modules using the JSR-88 API used to start
applications or modules.

Test the deployed applications or modules. For example, point a Web browser at the URL for a deployed
application and examine the performance of the application. If necessary, update the application.

Customizing modules using DConfigBeans

You can configure J2EE applications or stand-alone modules during deployment using the DConfigBean
class in the Java 2 Platform, Enterprise Edition (J2EE) Deployment API Specification (JSR-88).

This article assumes that you are deploying (installing) J2EE modules on an application server provided by
the WebSphere Application Server platform using the WebSphere Application Server support for JSR-88.

Read about the JSR-88 specification and using the DConfigBean class at
http://java.sun.com/j2ee/tools/deployment/.

The DConfigBean class in JSR-88 provides JavaBeans-based support for platform-specific configuration of
J2EE applications and modules during deployment. Your code can inspect DConfigBean instances to get
platform-specific configuration attributes. The DConfigBean instances provided by WebSphere Application
Server contain a single attribute which has an array of java.util.Hashtable objects. The hashtable entries
contain configuration attributes, for which your code can get and set values.

Chapter 7. Deploying and administering applications 905

1. Write code that installs J2EE modules on an application server using JSR-88.
2. Write code that accesses DConfigBeans generated by WebSphere Application Server during JSR-88
deployment. You (or a deployer) can then customize the accessed DConfigBeans instances. The
following pseudocode shows how a J2EE tool provider can get DConfigBean instance attributes
generated by WebSphere Application Server during JSR-88 deployment and set values for the
attributes:
import javax.enterprise.deploy.model.*;
import javax.enterprise.deploy.spi.*;
{
DeploymentConfiguration dConfig = ___; // Get from DeploymentManager
DDBeanRoot ddRoot = ___; // Provided by J2EE tool

// Obtain root bean.

DConfigBeanRoot dcRoot = dConfig.getDConfigBeanRoot(dr);

// Configure DConfigBean.
configureDCBean (dcRoot);
}

// Get children from DConfigBeanRoot and configure each child.

method configureDCBean (DConfigBean dcBean)
{
// Get DConfigBean attributes for a given archive.
BeanInfo bInfo = Introspector.getBeanInfo(dcBean.getClass());
IndexedPropertyDescriptor ipDesc =
(IndexedPropertyDescriptor)bInfo.getPropertyDescriptors()[0];

// Get the 0th table.

int index = 0;
Hashtable tbl = (Hashtable)
ipDesc.getIndexedReadMethod().invoke
(dcBean, new Object[]{new Integer(index)});

while (tbl != null)

{
// Iterate over the hashtable and set values for attributes.

// Set the table back into the DCBean.

ipDesc.getIndexedWriteMethod().invoke
(dcBean, new Object[]{new Integer(index), tbl});

// Get the next entry in the indexed property

tbl = (Hashtable)
ipDesc.getIndexedReadMethod().invoke
(dcBean, new Object[]{new Integer(++index)});
}
}

Enterprise application collection

Use this page to view and manage enterprise applications.

This page lists installed J2EE enterprise applications. System applications, which are central to the
product, are not shown in the list because users cannot edit them. Examples of system applications
include adminconsole and filetransfer.

To view this administrative console page, click Applications > Enterprise Applications.

To view the values specified for an application’s configuration, click the application name in the list. The
displayed application settings page shows the values specified. On the settings page, you can change
existing configuration values and link to additional console pages that assist you in configuring the
application.

906 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To manage an installed J2EE enterprise application, enable the Select check box beside the application
name in the list and click a button:

Button Resulting action

Start Attempts to run the application. After the application starts up successfully, the state of
the application changes to Started if the application starts up on all deployment
targets, else the state changes to Partial Started.
Stop Attempts to stop the processing of the application. After the application stops
successfully, the state of the application changes to Stopped if the application stops on
all deployment targets, else the state changes to Partial Stopped.
Install Opens a wizard that helps you deploy an application or a module such as a .jar, .war
or .rar file onto a server or a cluster.
Uninstall Deletes the application from the WebSphere Application Server configuration
repository and deletes the application binaries from the file system of all nodes where
the application modules are installed after the configuration is saved and synchronized
with the nodes.
Update Opens a wizard that helps you update application files deployed on a server. You can
update the full application, a single module, a single file, or part of the application. If a
new file or module has the same name as a file or module already existing on the
server, the new file or module replaces the existing file or module. If the new file or
module does not exist on the server, it is added to the deployed application.
Rollout Update Sequentially updates an application installed on multiple cluster members across a
cluster. After you update an application’s files or configuration, click Rollout Update to
install the application’s updated files or configuration on all cluster members of a
cluster on which the application is installed. Rollout Update does the following for
each cluster member in sequence:
1. Saves the updated application configuration.
2. Stops all of the cluster members on one node.
3. Updates the application on the node by synchronizing the configuration.
4. Restarts the stopped cluster members.
5. Repeats steps 2 through 4 for all of the nodes that have cluster members.
This action updates an application on multiple cluster members while providing
continuous availability of the application.
Remove File Deletes a file of the deployed application or module. Remove File deletes a file from
the WebSphere Application Server configuration repository and from the file system of
all nodes where the file is installed. If the application or module is deployed on a
cluster, after removing a file click Rollout Update to roll out the changes across the
entire cluster.
Export Accesses the Export Application EAR files page, which you use to export an enterprise
application to an EAR file at a location of your choice. Use the Export action to back
up a deployed application and to preserve its binding information.
Export DDL Accesses the Export Application DDL files page, which you use to export DDL files
(Table.ddl) in the EJB modules of an enterprise application to a location of your
choice.

Name
Specifies the name of the installed (or deployed) application. Application names must be unique within a
cell and cannot contain characters that are not allowed in object names.

Status
Indicates whether the application deployed on the application server is started, stopped, or unavailable.

Started Application is running.

Chapter 7. Deploying and administering applications 907

 Partial Start Application is in the process of changing from a Stopped state to a Started
state. Application is starting to run but is not fully running yet.
Stopped Application is not running.

Partial Stop Application is in the process of changing from a Started state to a Stopped
state. Application has not stopped running yet.
Unavailable Status cannot be determined.

Not applicable Application does not provide information as to whether it is running.

Enterprise application settings

Use this page to configure an enterprise application.

To view this administrative console page, click Applications > Enterprise Applications
>application_name.

Name
Specifies a logical name for the application. Application names must be unique within a cell and cannot
contain characters that are not allowed in object names.

Data type String

Application binaries
Specifies the directory to which the application EAR file will be installed. The default value is the value of
APP_INSTALL_ROOT/cell_name, where the APP_INSTALL_ROOT variable is install_root/installedApps; for
example, C:\WebSphere\AppServer\profiles\profile _name\installedApps\cell_name.

You can specify an absolute path or use a pathmap variable such as ${MY_APPS}. You can use a pathmap
variable in any installation though it is particularly needed when installing an application on a cluster with
members on heterogeneous nodes because, in such cases, there might not be a single way to specify an
absolute path. A WebSphere Application Server variable ${CELL} that denotes the current cell name can
also be in the pathmap variable; for example, ${MY_APP}/${CELL}.

You can define WebSphere Application Server variables on the WebSphere Variables page of the
administrative console, accessed by clicking Environment > WebSphere Variables.

Data type String

Units Full path name

Use metadata from binaries

Specifies whether the application server uses the binding, extensions, and deployment descriptors located
with the application deployment document, the deployment.xml file (default), or those located in the
enterprise application resource (EAR) file.

This Use metadata from binaries setting is the same as the Use Binary Configuration field on the
application installation and update wizards. Select this setting for applications installed on 6.x deployment
targets only. This setting is not valid for applications installed on 5.x deployment targets.

Data type Boolean

Default false

908 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Enable distribution
Specifies whether WebSphere Application Server expands or deletes application binaries in the installation
destination. The default is to enable application distribution. Application binaries for installed applications
are expanded to the directory specified. The binaries are also deleted when you uninstall and save
changes to the configuration. If you disable this option, then you must ensure that the application binaries
are expanded appropriately in the destination directories of all nodes where the application runs.

This Enable distribution setting is the same as the Distribute application field on the application
installation and update wizards.

Data type Boolean

Default true

Validation
Specifies whether WebSphere Application Server examines the application references specified during
application installation or updating and, if validation is enabled, warns the users of incorrect references or
fails the operation.

An application typically refers to resources using data sources for container managed persistence (CMP)
beans or using resource references or resource environment references defined in deployment descriptors.
The validation checks whether the resource referred to by the application is defined in the scope of the
deployment target of that application.

The resource can be defined on the server, its node, cell or the cluster if the server belongs to a cluster.
Select off for no resource validation, warn for warning messages about incorrect resource references, or
fail to stop operations that fail as a result of incorrect resource references.

This Validation setting is the same as the Validate Input off/warn/fail field on the application installation
and update wizards.

Data type String

Default warn

Class loader mode

Specifies whether the class loader searches in the parent class loader or in the application class loader
first to load a class. The standard for development kit class loaders and WebSphere Application Server
class loaders is Parent First. By specifying Parent Last, your application can override classes contained
in the parent class loader, but this action can potentially result in ClassCastException or LinkageErrors if
you have mixed use of overridden classes and non-overridden classes.

The options are Parent First and Parent Last. The default is to search in the parent class loader before
searching in the application class loader to load a class.

Data type String

Default Parent First

WAR class loader policy

Specifies whether to use a single class loader to load all WAR files of this application or to use a different
class loader for each WAR file.

The options are Application and Module. The default is to use a separate class loader to load each WAR
file.

Data type String

Chapter 7. Deploying and administering applications 909

Default Module

Enable class reloading

Specifies whether to enable class reloading when application files are updated.

For EJB modules or any non-Web modules, selecting Enable class reloading sets reloadEnabled to true
in the deployment.xml file for the application. If an application’s class definition changes, the application
server run time stops and starts the application to reload application classes.

For Web modules such as servlets and JavaServer page (JSP) files, a Web container reloads a Web
module only when the IBM extension reloadingEnabled in the ibm-web-ext.xmi file is set to true. You can
set reloadingEnabled to true when editing your Web module’s extended deployment descriptors in an
assembly tool.

To enable reloading of a Web module, where you also want reloading of EJB and non-Web modules
enabled:
1. Set the IBM extension reloadingEnabled in the ibm-web-ext.xmi file to true.
2. Select this Enable class reloading property.
3. Set the Reloading interval property to a value greater than zero (for example, 1 to 2147483647).

To enable reloading of a Web module only, and not enable reloading of EJB or non-Web modules:
1. Set the IBM extension reloadingEnabled in the ibm-web-ext.xmi file to true.
2. Set the IBM extension reload interval attribute in the ibm-web-ext.xmi file to a value greater than zero
(for example, 1 to 2147483647).
3. Do not select this Enable class reloading property.

To disable reloading of a Web module, set the IBM extension reloadingEnabled in the ibm-web-ext.xmi file
to false. Or, if the Web module has the IBM extension reloadingEnabled in the ibm-web-ext.xmi file set to
true, to disable reloading using the administrative console:
1. Select this Enable class reloading property.
2. Set the Reloading interval property to zero (0).

Data type Boolean

Default false

Reloading interval
Specifies the number of seconds to scan the application’s file system for updated files. The default is the
value of the reloading interval attribute in the IBM extension (META-INF/ibm-application-ext.xmi) file of
the EAR file.

This Reloading interval setting is the same as the Reload interval in seconds field on the application
installation and update wizards.

To enable reloading, specify a value greater than zero (for example, 1 to 2147483647). To disable
reloading, specify zero (0).

The reloading interval specified here overrides the value specified in the IBM extensions for each non-Web
module in the EAR file (which in turn overrides the reload interval specified in the IBM extensions for the
application in the EAR file). The reloading interval attribute takes effect only if class reloading is enabled.

The range is from 0 to 2147483647.

Data type Integer

Units Seconds

910 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Default 3

Starting weight
Specifies the order in which applications are started when the server starts. The application with the lowest
starting weight is started first.

Data type Integer

Default 1
Range 0 to 2147483647

Background application
Specifies whether the application must initialize fully before the server starts.

The default setting of false indicates that server startup will not complete until the application starts.

A setting of true informs WebSphere Application Server that the application might start on a background
thread and thus server startup might continue without waiting for the application to start. Thus, the
application might not be ready for use when the application server starts.

This setting applies only if the application is run on a Version 6 application server.

Data type Boolean

Default false

Create MBeans for resources

Specifies whether to create MBean files for various resources (such as servlets or JSP files) within an
application when the application starts. The default is to create MBean files.

Data type Boolean

Default true

Configuring an application
You can change the configuration of an application or module deployed on a server.

You can change the contents of and deployment descriptors for an application or module before
deployment, such as in an assembly tool. However, this article assumes that the module is already
deployed on a server.

Changing an application or module configuration consists of one or more of the following:

v Changing the settings of the application or module.
v Removing a file from an application or module.
v Updating the application or its modules.

This article describes how to change the settings of an application or module using the administrative
console.
v Change the settings of the application or module on the settings page for the enterprise application.
1. Click Applications > Enterprise Applications >application_name in the console navigation tree.
2. Change the values for settings as needed. The settings page help provides detailed information on
the settings and allowed values. When you installed the application or module, you specified most, if
not all, of the settings values. After installation, the settings on this page that you are likely to
change include the following:

Chapter 7. Deploying and administering applications 911

Enable class reloading and These settings control whether classes are reloaded when application files are
Reloading interval updated. For enterprise bean (EJB) modules or any non-Web modules, enabling class
reloading causes the application server run time to stop and start the application to
reload application classes. For Web modules such as servlets and JavaServer page
(JSP) files, a Web container reloads a Web module only when the IBM extension
reloadingEnabled in the ibm-web-ext.xmi file is set to true. Refer to the settings page
help for detailed information on enabling or disabling class reloading.
Starting weight If your application starts automatically when its server starts, this value controls how
quickly the application starts. Starting weight specifies the order in which applications
are started when the server starts. The application with the lowest starting weight is
started first.
Background application If your application starts automatically when its server starts, Background application
specifies whether the application must initialize fully before its server is considered
started. Background applications can be initialized on an independent thread, thus
allowing the server startup to complete without waiting for the application. This setting
applies only if the application is run on a Version 6 (or later) application server.

3. Click OK.
v Map each module of your application to a target server. Specify the application servers, clusters of
application servers, or Web servers onto which to install modules of your application.
v Change application bindings or other settings of the application or module.
1. Click Applications > Enterprise Applications >application_name > property_or_item_name in the
console navigation tree. From the application settings page, you can access console pages for
further configuring of the application or module.
– Stateful session bean failover
– Session management
– Application profiles
– Libraries or library references
– Target mappings
– Last participant support extension
– Deployment descriptors
– Publish WSDL files
– Provide JMS and EJB endpoint URL information
– Provide HTTP endpoint URL information
– Map security roles to users/groups
– Provide JNDI Names for Beans. For more information, refer to “Task overview: Using enterprise
beans in applications” on page 1010.
– Map resource references to resources
– Map EJB references to beans. For more information, refer to “Task overview: Using enterprise
beans in applications” on page 1010.
– Map data sources for all 2.x CMP beans
– Provide default data source mapping for modules containing 2.x entity beans. For more
information, refer to “Creating and configuring a data source using the administrative console” on
page 1370.
– Map virtual hosts for web modules. For more information, refer to ″Configuring virtual hosts″ in
the information center.
– Map modules to servers
– Web modules
– EJB modules
– Connector modules
2. Change the values for settings as needed, and click OK.
v Optional: Configure the application so it does not start automatically when the server starts. By default,
an installed application starts when the server on which the application resides starts. You can configure
the target mapping for the application so the application does not start automatically when the server
starts. To start the application, you must then start it manually.

912 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v If the installed application or module uses a resource adapter archive (RAR file), ensure that the
Classpath setting for the RAR file enables the RAR file to find the classes and resources that it needs.
Examine the Classpath setting on the console Resource adapter settings page.

The application or module configuration is changed. The application or standalone Web module is
restarted so the changes take effect.

Save changes to your administrative configuration.

In the Network Deployment product, the application binaries are transferred to nodes when the
configuration changes on the deployment manager synchronize with configurations for individual nodes on
which the application will run.

If the application or module is deployed on a cluster and you have no more configuration changes to
make, click Rollout Update on the Enterprise Applications page to propagate the changed configuration
on all cluster members of the cluster on which the application or module is deployed. Rollout Update
sequentially updates the configuration on the nodes that contain cluster members.

Application bindings
Before an application that is installed on an application server can start, all enterprise bean (EJB)
references and resource references defined in the application must be bound to the actual artifacts
(enterprise beans or resources) defined in the application server.

When defining bindings, you specify Java Naming and Directory Interface (JNDI) names for the
referenceable and referenced artifacts in an application. An example referenceable artifact is an EJB
defined in an application. An example referenced artifact is an EJB or a resource reference used by the
application. Binding definitions are stored in the ibm-xxx-bnd.xmi files of an application. The xxx can be
ejb-jar, web, application or application-client.

Times when bindings can be defined

You can define bindings at the following times:

v During application development
An application developer can create binding definitions in ibm-xxx-bnd.xmi files using a tool such as an
IBM Rational developer tool. The developer then gives an enterprise application (.ear file) complete
with bindings to a deployer. When assembling the application and then installing it onto a server
supported by WebSphere Application Server, the deployer does not modify or override the bindings or
generate default bindings unless changes to the bindings are necessary for successful deployment of
the application.
v During application assembly
An application assembler can define bindings when modifying deployment descriptors of an application.
Bindings are specified in the WebSphere Bindings section of a deployment descriptor editor. Modifying
the deployment descriptors might change the binding definitions in the ibm-xxx-bnd.xmi files created
when assembling an application. After defining the bindings, the deployer can install the application onto
a server supported by WebSphere Application Server without selecting to override the bindings or
generate default bindings unless changes to the bindings are necessary for successful deployment of
the application.
v During application installation
An application deployer or server administrator can modify the bindings when installing the application
onto a server supported by WebSphere Application Server using the administrative console. New
binding definitions can be specified on the install wizard pages.
If the deployer or administrator selects to override any existing bindings or to generate default bindings
during application installation, default bindings are assigned to the application and new bindings might
need to be specified using the console.

Chapter 7. Deploying and administering applications 913

 Selecting Generate Default Bindings during application installation causes any incomplete bindings in
the application to be filled in with default values. Existing bindings are not changed.

Note: Bindings can be defined or overridden during application installation for all modules except
application clients. For clients, you must define bindings for application client modules during
assembly and store the bindings in the ibm-application-client-bnd.xmi file.
v During configuration of an installed application
After an application is installed onto a server supported by WebSphere Application Server, an
application deployer or server administrator can modify the bindings by changing values in
administrative console pages such as those accessed from the settings page for the enterprise
application.

Required bindings

Before an application can be successfully deployed, bindings must be defined for references to the
following artifacts:
EJB JNDI names
For each enterprise bean (EJB), you must specify a JNDI name. The name is used to bind an
entry in the global JNDI name space for the EJB home object. An example JNDI name for a
Product EJB in a Store application might be store/ejb/Product. The binding definition is stored in
the META-INF/ibm-ejb-jar-bnd.xmi file.
If a deployer chooses to generate default bindings when installing the application, the install wizard
assigns EJB JNDI names having the form prefix/EJB_name to incomplete bindings. The default
prefix is ejb, but can be overridden. The EJB_name is as specified in the deployment descriptor
<ejb-name> tag.
During and after application installation, EJB JNDI names can be specified on the Provide JNDI
Names for Beans panel. After installation, click Applications > Enterprise Applications
>application_name > Provide JNDI Names for Beans in the administrative console.
Data sources for entity beans
Entity beans such as container-managed persistence (CMP) beans store persistent data in data
stores. With CMP beans, an EJB container manages the persistent state of the beans. You specify
which data store a bean uses by binding an EJB module or an individual EJB to a data source.
Binding an EJB module to a data source causes all entity beans in that module to use the same
data source for persistence.
An example JNDI name for a Store data source in a Store application might be store/jdbc/store.
The binding definition is stored in IBM binding files such as ibm-ejb-jar-bnd.xmi. A deployer can
also specify whether authentication is handled at the container or application level.
If a deployer chooses to generate default bindings when installing the application, the install wizard
generates the following for incomplete bindings:
v For EJB 2.x .jar files, connection factory bindings based on the JNDI name and authorization
information specified
v For EJB 1.1 .jar files, data source bindings based on the JNDI name, data source user name
and password specified

The generated bindings provide default connection factory settings for each EJB 2.x .jar file and
default data source settings for each EJB 1.1 .jar file in the application being installed. No
bean-level connection factory bindings or data source bindings are generated.

During and after application installation, data sources can be mapped to 2.x entity beans on the
Map data sources for all 2.x CMP beans panel and on the Provide default data source mapping
for modules containing 2.x entity beans panel. After installation, click Applications > Enterprise
Applications >application_name in the administrative console, then select Map data sources for

914 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 all 2.x CMP beans or Provide default data source mapping for modules containing 2.x entity
beans. Data sources can be mapped to 1.x entity beans on the Map data sources for all 1.x CMP
beans panel and on the Provide default data source mapping for modules containing 1.x entity
beans panel. After installation, access console pages similar to those for 2.x CMP beans, except
click links for 1.x CMP beans.
Backend ID for EJB modules
If an EJB .jar file that defines CMP beans contains mappings for multiple backend databases,
specify the appropriate backend ID that determines which persister classes are loaded at run time.
Specify the backend ID during application installation. You cannot select a backend ID after the
application is installed onto a server.
EJB references
An enterprise bean (EJB) reference is a logical name used to locate the home interface of an
enterprise bean. EJB references are specified during deployment. At run time, EJB references are
bound to the physical location (global JNDI name) of the enterprise beans in the target operational
environment. EJB references are made available in the java:comp/env/ejb Java naming
subcontext.
For each EJB reference, you must specify a JNDI name. An example JNDI name for a Supplier
EJB reference in a Store application might be store/ejb/Supplier. The binding definition is stored
in IBM binding files such as ibm-ejb-jar-bnd.xmi. When the referenced EJB is also deployed in
the same application server, you can specify a server-scoped JNDI name. But if the referenced
EJB is deployed on a different application server or if ejb-ref is defined in an application client
module, then you should specify the global cell-scoped JNDI name.
If a deployer chooses to generate default bindings when installing the application, the install wizard
binds EJB references as follows: If an <ejb-link> is found, it is honored. If the ejb-name of an EJB
defined in the application matches the ejb-ref name, then that EJB is chosen. Otherwise, if a
unique EJB is found with a matching home (or local home) interface as the referenced bean, the
reference is resolved automatically.
During and after application installation, EJB reference JNDI names can be specified on the Map
EJB references to beans panel. After installation, click Applications > Enterprise Applications
>application_name > Map EJB references to beans in the administrative console.
Resource references
A resource reference is a logical name used to locate an external resource for an application.
Resource references are specified during deployment. At run time, the references are bound to the
physical location (global JNDI name) of the resource in the target operational environment.
Resource references are made available as follows:

Resource reference type Subcontext declared in

Java DataBase Connectivity (JDBC) data source java:comp/env/jdbc
JMS connection factory java:comp/env/jms
JavaMail connection factory java:comp/env/mail
Uniform Resource Locator (URL) connection factory java:comp/env/url

For each resource reference, you must specify a JNDI name. If a deployer chooses to generate
default bindings when installing the application, the install wizard generates resource reference
bindings derived from the <res-ref-name> tag, assuming that the java:comp/env name is the same
as the resource global JNDI name.
During application installation, resource reference JNDI names can be specified on the Map
resource references to references panel. Specify JNDI names for the resources that represent the
logical names defined in resource references. You can optionally specify login configuration name
and authentication properties for the resource. After specifying authentication properties, click OK

Chapter 7. Deploying and administering applications 915

 to save the values and return to the mapping step. Each resource reference defined in an
application must be bound to a resource defined in your WebSphere Application Server
configuration. After installation, click Applications > Enterprise Applications >application_name
> Map resource references to resources in the administrative console to access the Map
resource references to references panel.
Virtual host bindings for Web modules
You must bind each Web module to a specific virtual host. The binding informs a Web server
plug-in that all requests that match the virtual host must be handled by the Web application. An
example virtual host to be bound to a Store Web application might be store_host. The binding
definition is stored in IBM binding files such as WEB-INF/ibm-web-bnd.xmi.
If a deployer chooses to generate default bindings when installing the application, the install wizard
sets the virtual host to default_host for each .war file.
During and after application installation, you can map a virtual host to a Web module defined in
your application. On the Map virtual hosts for Web modules panel, specify a virtual host. The port
number specified in the virtual host definition is used in the URL that is used to access artifacts
such as servlets and JSP files in the Web module. For example, an external URL for a Web
artifact such as a JSP file is http://host_name:virtual_host_port/context_root/jsp_path. After
installation, click Applications > Enterprise Applications >application_name > Map virtual
hosts for Web modules in the administrative console.
Message-driven beans
For each message-driven bean, you must specify a queue or topic to which the bean will listen. A
message-driven bean is invoked by a Java Messaging Service (JMS) listener when a message
arrives on the input queue that the listener is monitoring. A deployer specifies a listener port or
JNDI name of an activation spec as defined in a connector module (.rar file) under WebSphere
Bindings on the Beans page of an assembly tool EJB deployment descriptor editor. An example
JNDI name for a listener port to be used by a Store application might be StoreMdbListener. The
binding definition is stored in IBM bindings files such as ibm-ejb-jar-bnd.xmi.
If a deployer chooses to generate default bindings when installing the application, the install wizard
assigns JNDI names to incomplete bindings.
v For EJB 2.x message-driven beans deployed as JCA 1.5-compliant resources, the install wizard
assigns JNDI names corresponding to activationSpec instances in the form eis/MDB_ejb-name.
v For EJB 2.x message-driven beans deployed against listener ports, the listener ports are
derived from the message-driven bean <ejb-name> tag with the string Port appended.

During application installation using the administrative console, you can specify a listener port
name or an activation specification JNDI name for every message-driven bean on the panel
Provide Listener Ports or activation specification JNDI name for messaging beans. A listener
port name must be provided when using the JMS providers: Version 5 default messaging,
WebSphere MQ, or generic. An activation specification must be provided when the application’s
resources are configured using the default messaging provider or any generic J2C resource
adapter that supports inbound messaging. If neither is specified, then a validation error is
displayed after you click Finish on the Summary panel. Also, if the module containing the
message-driven bean is deployed on a 5.x deployment target and a listener port is not specified,
then a validation error is displayed after you click Next.

After application installation, you can specify JNDI names and configure message-driven beans on
console pages under Resources > JMS Providers or under Resources > Resource Adapters.
For more information, refer to ″Using asynchronous messaging″ in the information center.
Message destination references
A message destination reference is a logical name used to locate an enterprise bean in an EJB
module that acts as a message destination. Message destination references exist only in J2EE 1.4
artifacts such as--
v J2EE 1.4 application clients

916 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v EJB 2.1 projects
v 2.4 Web applications
If multiple message destination references are associated with a single message destination link,
then a single JNDI name for an enterprise bean that maps to the message destination link, and in
turn to all of the linked message destination references, is collected during deployment. At run
time, the message destination references are bound to the administered message destinations in
the target operational environment.
If a deployer chooses to generate default bindings when installing the application, the install wizard
assigns JNDI names to incomplete message destination references as follows: If a message
destination reference has a <message-destination-link>, then the JNDI name is set to
ejs/message-destination-linkName. Otherwise, the JNDI name is set to eis/message-
destination-refName.

Other bindings that might be needed

Depending on the references in and artifacts used by your application, you might need to define bindings
for references and artifacts not listed in this article.

Mapping modules to servers

Each module of a deployed application must be mapped to one or more target servers. The target server
can be an application server, cluster of application servers or Web server.

You can map modules of an application or standalone Web module to one or more target servers during or
after application installation using the console. This article assumes that the module is already installed on
a server and that you want to change the mappings.

Before you change a mapping, check the deployment targets. You must specify an appropriate deployment
target for a module. Modules that use Version 6.x features cannot be installed onto a Version 5.x target
server.

During application installation, different deployment targets might have been specified.

You use the Map modules to servers panel of the administrative console to view and change mappings.
This panel is displayed during application installation using the console and, after the application is
installed, can be accessed from the settings page for an enterprise application.

On the Map modules to servers panel, specify target servers where you want to install the modules
contained in your application. Modules can be installed on the same application server or dispersed
among several application servers. Also, specify the Web servers as targets that will serve as routers for
requests to your application. The plug-in configuration file plugin-cfg.xml for each Web server is
generated based on the applications which are routed through it.
1. Click Applications > Enterprise Applications >application_name > Map modules to servers in the
console navigation tree. The Selecting servers - Map modules to servers panel is displayed.
2. Examine the list of mappings. Ensure that each Module entry is mapped to the desired target(s),
identified under Server.
3. Change a mapping as needed.
a. Select each module that you want mapped to the same target(s). In the list of mappings, place a
check mark in the Select check boxes beside the modules.
b. From the Clusters and Servers drop-down list, select one or more targets. Use the Ctrl key to
select multiple targets. For example, to have a Web server serve your application, use the Ctrl key
to select an application server or cluster and the Web server together in order to have the plug-in
configuration file plugin-cfg.xml for that Web server generated based on the applications which
are routed through it.

Chapter 7. Deploying and administering applications 917

 c. Click Apply.
4. Repeat steps 2 and 3 until each module maps to the desired target(s).
5. Click OK.

The application or module configurations are changed. The application or standalone Web module is
restarted so the changes take effect.

Save changes to your administrative configuration.

In the Network Deployment product, the application binaries are transferred to nodes when the
configuration changes on the deployment manager synchronize with configurations for individual nodes on
which the application will run.

If the application or module is deployed on a cluster and you have no more configuration changes to
make, click Rollout Update on the Enterprise Applications page to propagate the changed configuration
on all cluster members of the cluster on which the application or module is deployed. Rollout Update
sequentially updates the configuration on the nodes that contain cluster members.

Starting and stopping applications

You can start an application that is not running (has a status of Stopped) or stop an application that is
running (has a status of Started).

This article assumes that the application is installed on a server. By default, the application starts
automatically when the server starts.

You can start and stop applications manually using the following:
v Administrative console
v wsadmin startApplication and stopApplication commands
v Java programs that use ApplicationManager or AppManagement MBeans

This article describes how to use the administrative console to start or stop an application.
1. Go to the Enterprise Applications page. Click Applications > Enterprise Applications in the console
navigation tree.
2. Select the check box for the application you want started or stopped.
3. Click a button:

Option Description
Start Runs the application and changes the state of the application to Started. The
status is changed to partially started if not all servers on which the
application is deployed are running.
Stop Stops the processing of the application and changes the state of the
application to Stopped.

To restart a running application, select the application you want to restart, click Stop and then click
Start.

The status of the application changes and a message stating that the application started or stopped
displays at the top the page.

You can configure an application so it does not start automatically when the server on which it resides
starts. You then start the application manually using options described in this article.

If you want your application to start automatically when its server starts, you can adjust values that control
how quickly the application or its server starts:

918 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
1. Go the settings page for your enterprise application. Click Applications > Enterprise Applications
>application_name.
2. Specify a different value for Starting weight.
This setting specifies the order in which applications are started when the server starts. The default
value is 1 in a range from 0 to 2147483647. The application with the lowest starting weight is started
first.
3. Specify a different value for Background application.
This setting specifies whether the application must initialize fully before its server starts. The default
value of false prevents the server from starting completely until the application starts. To reduce the
amount of time it takes to start the server, you can set the value to true and have the application start
on a background thread, thus allowing server startup to continue without waiting for the application
4. Save the changes to the application configuration.
5. If the application or module is deployed on a cluster and you have no more configuration changes to
make, click Rollout Update on the Enterprise Applications page to propagate the changed
configuration on all cluster members of the cluster on which the application or module is deployed.
Rollout Update sequentially updates the configuration on the nodes that contain cluster members.

Disabling automatic starting of applications

By default, an installed application starts automatically when the server on which the application resides
starts. You can disable the automatic starting of the application, and later enable the automatic starting
again.

This article assumes that the enterprise application is installed on an application server and that the
application starts automatically when the server starts.

You might want an application to run only after you start it manually and not to run every time after the
server starts. The target mapping for an application controls whether an application starts automatically
when the server starts or requires you to start the application manually.
1. Go to the Target Mapping settings page for your application. Click Applications > Enterprise
Applications >application_name > Target Mappings >target_name. The target_name is the server on
which the application resides. You use the Target Mapping settings page to map an installed
application or module to a server or cluster.
2. Clear the Enabled check box.
3. Click OK.
4. Save changes to the administrative configuration.

The application does not start when its server starts. You must start the application manually.

To enable automatic starting of the application, select the Enabled check box on the Target Mappings
settings page for the application, click OK, and then save changes to the configuration.

Target mapping collection

Use this page to view mappings of deployed applications or modules to servers or clusters.

To view this administrative console page, click Applications > Enterprise Applications
>application_name > Target Mappings.

Target
States the name of the target server or cluster to which the application or module maps. You specify the
target on the Map modules to servers page accessed from the settings for an application.

Node
Specifies the node name if the target is a server.

Chapter 7. Deploying and administering applications 919

Version
Specifies the version level of the target. The target can be a 5.x deployment target or a 6.x deployment
target.

A 5.x deployment target is a server or a cluster with at least one member on a WebSphere Application
Server Version 5 product.

A 6.x deployment target is a server or cluster with all members on a WebSphere Application Server
Version 6 product.

An application, enterprise bean (EJB) module, Web module or application client module developed for a
WebSphere Application Server Version 5.x product can reside on a 5.x or 6.x deployment target, provided
the module--
v Does not support Java 2 Platform, Enterprise Edition (J2EE) 1.4;
v Does not call any 6.x run-time application programming interfaces (APIs); and
v Does not use any 6.x product features.

Similarly, a resource adapter (connector) module, or RAR file, developed for a Version 5.x product can
reside on a 5.x or 6.x node, provided the module does not support Java Cryptography Architecture (JCA)
1.5 and does not call any 6.x run-time application programming interfaces (APIs). If the module supports
JCA 1.5 or calls a 6.x API, then the module must reside on a 6.x node.

Status
Indicates whether the status of the target server or cluster is started, stopped or unavailable.

Target mapping settings

Use this page to map a deployed application or module to a server or cluster.

To view this administrative console page, click Applications > Enterprise Applications
>application_name > Target Mappings >target_name.

Target:

States the name of the target server or cluster to which the application or module maps. You specify the
target on the Map modules to servers page accessed from the settings for an application.

Data type String

Enabled:

Indicates whether the application modules installed on the target server are started (or enabled) when the
server starts. This sets the initial state of application modules. A true value indicates that the
corresponding modules are enabled and thus are accessible when the server starts. A false value
indicates that the corresponding modules are not enabled and thus are not accessible when the server
starts.

Data type Boolean

Default true

Exporting applications
You can export an enterprise application to a location of your choice.

920 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Exporting applications enables you to back up your applications and preserve binding information for the
applications. You might export your applications before updating installed applications or migrating to a
later version of the WebSphere Application Server product.
1. Click Applications > Enterprise Applications in the console navigation tree to access the Enterprise
Applications page.
2. Select the check box beside the application and click Export.
3. On the Export Application EAR Files page, click on the link to download the exported EAR file.
4. Use the browser dialogue to specify a location at which to save the exported EAR file.
5. Click Back to return to the Enterprise Applications page.

The file containing binding information is exported to the specified node and directory, and has the name
enterprise_application_name.ear.

Exporting DDL files

You can export data definition language (DDL) files in the enterprise bean (EJB) modules of an
application.

Exporting DDL (Table.ddl) files in the EJB modules of an application downloads the DDL files to a
location of your choice.
1. Click Applications > Enterprise Applications in the administrative console navigation tree to access
the Enterprise Applications page.
2. Place a check mark in the check box beside the application and click Export DDL. If the application
has no DDL files in any of its EJB modules, then the message No DDL files were found is displayed at
the top of the page. If the application has DDL files in its EJB modules, then a page listing DDL files in
the format application_name.ear/_module.jar_Table.ddl is displayed.
3. Click on a file in the list and specify the location to which to download the file.

Tip: Mozilla browsers might display the contents of the Table.ddl file instead of saving the file to disk.
To save the file, edit the Helper Application preference settings of the Mozilla browser by adding
a new type for DDL and specifying that you want to save DDL files to disk. That is, set MIME type
= ddl and Extension = ddl.

The DDL file is downloaded to the specified location.

Updating applications
You can update application files deployed on a server.

Refer to “Ways to update application files” on page 924 and decide how to update your application files.
You can update enterprise applications or modules using the administrative console or a wsadmin tool.
Both ways provide identical updating capabilities. Further, in some situations, you can update applications
or modules without restarting the application server.

Note that Version 6 supports Java 2 Platform, Enterprise Edition (J2EE) 1.4 enterprise applications and
modules. If you are deploying J2EE 1.4 modules, ensure that the target server and its node support
Version 6. The administrative console Server collection pages show the versions for servers and cluster
members. You can deploy J2EE 1.4 modules to Version 6.x servers or to clusters that contain Version 6.x
cluster members only. You cannot deploy J2EE 1.4 modules to servers on Version 5.x nodes or to clusters
that contain Version 5.x cluster members. Refer to “Installable module versions” on page 891 for details.

This article describes how to update deployed applications or modules using the administrative console.

Chapter 7. Deploying and administering applications 921

Updating consists of adding a new file or module to an installed application, or replacing or removing an
installed application, file or module. After replacement of a full application, the old application is uninstalled.
After replacement of a module, file or partial application, the old installed module, file or partial application
is removed from the installed application.
1. Update your application or modules and reassemble them using an assembly tool. Typical tasks
include adding or editing assembly properties, adding or importing modules into an application, and
adding enterprise beans, Web components, and files.
2. Back up the installed application.
a. Go to the Enterprise Applications page of the administrative console. Click Applications >
Enterprise Applications in the console navigation tree.
b. Export the application to an EAR file. Select the application you want uninstalled and click Export.
Exporting the application preserves the binding information.
3. With the application selected on the Enterprise Applications page, click Update. The Preparing for
application update page is displayed.
4. Under Specify the EAR, WAR or JAR module to upload and install:
a. Ensure that Application name refers to the application to be updated.
b. Under Update options, select the installed application, module, or file that you want to update.
The online help Preparing for application update settings provides detailed information on the
options. Briefly, the options are as follows:
Full application
Replaces the installed (old) application with the updated (new) application on the server. If
you select Full application, specify the path for the new .ear file. The path provides the
location of the new .ear file before installation.
Single module
Adds a new module to, or replaces a module in, the installed application. Specify the path
for the new Web module (.war), EJB module (.jar), or resource adapter module (.rar).
The path provides the location of the new module before installation.
To replace a module, the value for Relative path to module (or module URI) must match
the path of the module to be updated in the installed application.
To add a new module to the installed application, the value for Relative path to module
must not match the path of a module in the installed application. The value specifies the
desired path for the new module.
If you are installing a standalone Web module, specify a value for Context root.
Single file
Adds a new file to, or replaces a file in, the installed application. Specify the path for the
new file. The path provides the location of the new file before installation.
To replace a file, the value for Relative path to file must match the path of the file to be
updated in the installed application.
To add a new file to the installed application, the value for Relative path to file must not
match the path of a file in the installed application. The value specifies the desired path for
the new file.
The relative path to a file from the root of the application is the concatenation of the
module path and the file path within the module. For example, if the file is
com/mycompany/abc.class within the module foo.jar, then the relative file path is
foo.jar/com/mycompany/abc.class.
Partial application
Updates multiple files of an installed application by uploading a compressed file.
Depending on the contents of the compressed file, a single use of this option can replace
files in, add new files to, and delete files from the installed application. Each entry in the
compressed file is treated as a single file and the path of the file from the root of the
compressed file is treated as the relative path of the file in the installed application.

922 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Specify a valid compressed file format such as .zip or .gzip. The path provides the
location of the compressed file before installation. This option unzips the compressed file
into the installed application directory.
To replace a file, a file in the compressed file must have the same relative path as the file
to be updated in the installed application.
To add a new file to the installed application, a file in the compressed file must have a
different relative path than the files in the installed application.
To remove a file from the installed application, specify metadata in the compressed file
using a file named META-INF/ibm-partialapp-delete.props at any archive scope. The
ibm-partialapp-delete.props file must be an ASCII file that lists files to be deleted in that
archive with one entry for each line. The entry can contain a string pattern such as a
regular expression that identifies multiple files. The file paths for the files to be deleted
must be relative to the archive path that has the META-INF/ibm-partialapp-delete.props
file. Refer to Preparing for application update settings for more information.
After you select an option, specify a path. Use Local file system if the browser and application files
are on the same machine (whether or not the server is on that machine, too). Use Remote file
system if the application file resides on any node in the current cell context. You can browse the entire
file system of a node if the node agent or deployment manager is running on that selected node. Only
.ear, .jar, or .war files are shown during the browsing.
During application updating, application files typically are uploaded from a client machine running the
browser to the server machine running the administrative console, where they are deployed. In such
cases, use the Web browser running the administrative console to select EAR, WAR, or JAR modules
to upload to the server machine.
In some cases, however, the application files reside on the file system of any of the nodes in a cell. To
have the application server install these files, use the Remote file system option.
Also use the Remote file system option to specify an application file already residing on the machine
running the application server. For example, the field value on a Windows machine might be
C:\WebSphere\AppServer\installableApps\test.ear. If you are installing a standalone WAR module,
then specify the context root as well.
After the application file is transferred, the Remote file system value shows the path of the temporary
location on the deployment manager orserver machine.
5. If you selected the Full application or Single module option:
a. Click Next to display a wizard for updating application files.
b. Complete the steps in the update wizard. This update wizard, which is similar to the installation
wizard, provides fields for specifying or editing application binding information. Refer to information
on installing applications and on the settings page for application installation for guidance. Note
that the installation steps have the merged binding information from the new version and the old
version. If the new version has bindings for application artifacts such as EJB JNDI names, EJB
references or resource references, then those bindings will be part of the merged binding
information. If new bindings are not present, then bindings are taken from the installed (old)
version. If bindings are not present in the old version and if the default binding generation option is
enabled, then the default bindings will be part of the merged binding information. You can select
whether to ignore bindings in the old version or ones in the new version.
6. Click Finish.
7. If you did not use the Map modules to servers page of the update wizard, after updating the
application, map the installed application or module to servers or clusters. Use the Map modules to
servers page accessed from the Enterprise Applications page.
a. Go to the Map modules to servers page. Click Applications > Enterprise Applications
>application_name > Map modules to servers.

Chapter 7. Deploying and administering applications 923

 b. Specify the application server where you want to install modules contained in your application and
click OK. You can deploy J2EE 1.4 modules to servers on Version 6.x nodes or to clusters that
contain cluster members on Version 6.x nodes only.

After the application file or module installs successfully, do the following:

1. Save the changes to your configuration.
In the Network Deployment product, after you click Save the old application files are deleted and new
files are copied when the configuration on the deployment manager synchronizes with the configuration
on the node where the application is installed.
If the application is running when you update it, the application stops running before its files are copied
to the destination directory of the node and restarts after the copy operation completes. Thus, the
application is unavailable on the node during the time the node is synchronizing its configuration with
the deployment manager.
2. Examine the values specified for Reload Enabled and Reload Interval on the settings page for your
enterprise application.
If reloading of application files is enabled and the reload interval is greater than zero (0), the
application’s files are reloaded after the application is updated. For Web modules such as servlets and
JavaServer page (JSP) files, a Web container reloads a Web module only when the IBM extension
reloadingEnabled in the ibm-web-ext.xmi file is also set to true. You can set reloadingEnabled to true
when editing your Web module’s extended deployment descriptors in an assembly tool.
3. If needed, restart the application manually so the changes take effect.
If the application is updated while it is running, WebSphere Application Server automatically stops the
application or only its changed components, updates the application logic, and restarts the stopped
application or its components.
4. If the application you are updating is deployed on a server that has its application class loader policy
set to Single, restart the server.
5. If a changed application or module is deployed on a cluster, click Rollout Update on the Enterprise
Applications page to propagate the changed configuration on all cluster members of the cluster on
which the application or module is deployed. Rollout Update sequentially updates the configuration on
the nodes that contain cluster members.

Ways to update application files

You can update application files deployed on a server or cluster in several ways.
Table 16. Ways to update application files
Option Method Comments Starting after update
Administrative Briefly, do the following: On the Preparing for application On the Enterprise
console update 1. Go to the Enterprise update page: Applications page,
wizard Applications page. Click v Use Full application to update an select the updated
Applications > Enterprise .ear file. application and click
See “Updating Applications in the console Start.
applications” on v Use Single module to update a
navigation tree.
page 921. .war, enterprise bean .jar, or
2. Select the application to update
connector .rar file.
and click Update.
3. On the Preparing for application v Use Single file to update a file
update page, identify the other than an .ear, .war, EJB
application, module or files to .jar, or .rar file.
update and click Next. v Use Partial application to update
4. Complete steps in the update or remove multiple files.
wizard and click Finish.
wsadmin scripts Invoke AdminApp object install ″Getting started with scripting″ in the Invoke the wsadmin
commands with the -update option information center provides an startApplication
in a script or at a command prompt. overview of wsadmin. command.

924 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Table 16. Ways to update application files (continued)
Java application Update deployed applications by Update an application in the Start the application
programming completing the steps in ″Managing following ways: by either of the
interfaces. applications through programming″ v Update the entire application following methods:
in the information center. v Add to, update or delete multiple v On the Enterprise
See ″Using files in an application Applications page,
administrative v Add a module to an application select the updated
programs (JMX)″ v Update a module in an application application and
in the v Delete a module in an application click Start.
information v Add a file to an application v Invoke the wsadmin
center. v Update a file in an application startApplication
v Delete a file in an application command.
WebSphere Briefly, do the following: WebSphere rapid deployment offers Use any of the above
rapid 1. Update your J2EE application the following advantages: options to start the
deployment files. v You do not need to assemble your application. Clicking
2. Set up the rapid deployment J2EE application files prior to Start on the
Refer to articles environment. Enterprise
deployment.
under Rapid 3. Create a free-form project. Applications page is
deployment of v You do not need to use other
4. Launch a rapid deployment the easiest option.
J2EE installation tools mentioned in this
session.
applications in table to deploy the files.
5. Drop your updated application
this information files into the free-form project.
center.
Hot deployment Briefly, do the following: If you are new to WebSphere Use any of the above
and dynamic 1. Update your application (.ear), Application Server, use the options to start the
reloading Web module (.war), enterprise administrative console to update application. Clicking
bean .jar or HTTP plug-in applications. That option is easier. Start on the
configuration file. Enterprise
2. Follow instructions in Hot Hot deployment and dynamic Applications page is
deployment and dynamic reloading is more difficult to the easiest option.
reloading to update your file. complete. You must directly
manipulate the application or module
file on the server where the
application is deployed.

You can update .ear, enterprise bean .jar, Web module .war, connector .rar, application client .jar, and
any other files used by an installed application.

If the application is updated while it is running, WebSphere Application Server automatically stops the
application, updates the application logic and restarts the application. If the application does not start
automatically, start it manually using one of the Starting options.

Preparing for application update settings

Use this page to update enterprise applications, modules or files already installed on a server.

To view this administrative console page, do the following:

1. Click Applications > Enterprise Applications.
2. Select the installed application or module that you want to update.
3. Click Update.

Clicking Update displays a page that helps you update application files deployed in the cell. You can
update the full application, a single module, a single file, or part of the application. If a new file or module
has the same relative path as a file or module already existing on the server, the new file or module
replaces the existing file or module. If the new file or module does not exist on the server, it is added to
the deployed application.

Chapter 7. Deploying and administering applications 925

Application name
Specifies the name of the installed (or deployed) application that you selected on the Enterprise
Applications page.

Full application
Under Update options, specifies to replace the application already installed on the server with a new
(updated) enterprise application .ear file.

After selecting this option, specify whether the .ear file is on a local or remote file system and the full path
name of the application. The path provides the location of the updated .ear file before installation.

Use Local file system if the browser and the updated files or modules are on the same machine, whether
or not the server is on that machine too. Local file system is available for all update options.

Use Remote file system if the application file resides on any node in the current cell context.You can
browse the entire file system of a node if the node agent or deployment manager is running on that
selected node. Only .ear, .jar, or .war files are shown during the browsing. Also use the Remote file
system option to specify an application file already residing on the machine running the application server.
For example, the field value on a Windows machine might be
C:\WebSphere\AppServer\installableApps\test.ear.

Note: During application installation, application files typically are uploaded from a client machine running
the browser to the server machine running the administrative console, where they are deployed. In
such cases, use the Web browser running the administrative console to select .ear, .war, or .jar
modules to upload to the server machine. In some cases, however, the application files reside on
the file system of any of the nodes in a cell. To have the application server install these files, use
the Remote file system option.

After specifying the required information on the .ear file, click Next to display a wizard for updating
application files. The update wizard, which is similar to the installation wizard, provides fields for specifying
or editing application binding information. Complete the steps in the update wizard as needed.

When the full application is updated, the old application is uninstalled and the new application is installed.
When the configuration changes are saved and subsequently synchronized, the application files are
expanded on the node where application will run. If the application is running on the node while it is
updated, then the application is stopped, application files are updated, and application is started.

Single module
Under Update options, specifies to replace a module in or add a module to an installed application. The
module can be a Web module (.war file), enterprise bean module (EJB .jar file), or resource adapter
module (connector .rar file).

After selecting this option, specify whether the module is on a local or remote file system and the full path
name of the module. The path provides the location of the updated module before installation. For
information on Local file system and Remote file system, refer to the description of Full application
above.

To replace a module, the value for Relative path to module (module URI) must match the path of the
module to be updated in the installed application.

To add a new module to the installed application, the value for Relative path to module must not match
the path of a module in the installed application. The value specifies the desired path for the new module.

If you are installing a standalone Web module, specify a value for Context root. The context root is
combined with the defined servlet mapping (from the .war file) to compose the full URL that users type to

926 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
access the servlet. For example, if the context root is /gettingstarted and the servlet mapping is
MySession, then the URL is http://host:port/gettingstarted/MySession.

After specifying the required information on the module, click Next to display a wizard for updating
application files. The update wizard, which is similar to the installation wizard, provides fields for specifying
or editing module binding information. Complete the steps in the update wizard as needed.

After a single module is added or updated, when configuration changes are saved, the new or updated
module is stored in the deployed application in the WebSphere Application Server configuration repository.
When these changes are synchronized with the node, the module is added or updated to the node’s file
system. If the application is running on the node when the module is added or updated, then one of the
following occurs:
v For updates to a Web module, the running Web module is stopped, Web module files are updated, and
then the Web module is started.
v For module additions, the added module is started on the application servers where the application is
running after it is expanded on the node. An application restart is not necessary.
v If the class loader policy for the application is set to Single so that all modules share a class loader,
then the entire application is stopped and restarted for module level changes.
v If the security provider configured with WebSphere Application Server does not support dynamic
updates, then the entire application is stopped and restarted for module level changes.
v For all other updates to a module, the entire application is stopped, the module files are updated, then
the entire application is started.

Single file
Under Update options, specifies to replace a file in or add a file to an installed application.

Use this option to update a file used by the application that is not an .ear, .war, .rar or, in some
instances, a .jar file. You can use this option to add or update .jar files that are not defined as modules in
the application. To update an .ear, file use the Full application option. To update a .war file, .rar file , or
.jar file that is defined as a module in the application, use the Single module option.

After selecting this option, specify whether the file is on a local or remote file system and the full path
name of the file. The path provides the location of the updated file before installation. For information on
Local file system and Remote file system, refer to the description of Full application above.

Next, specify a value for Relative path to file. The relative path of the file must start from the root of the
.ear file. For example, if the file is located at com/company/greeting.class in module hello.jar, specify a
relative path of hello.jar/com/company/greeting.class.

To replace a file, the value for Relative path to file must match the path of the file to be updated in the
installed application.

To add a new file to the installed application, the value for Relative path to file must not match the path
of a file in the installed application. The value specifies the desired path for the new file.

After a single file is added or updated, when configuration changes are saved, the new or updated file is
stored in the deployed application in the WebSphere Application Server configuration repository. When
these changes are synchronized with the node, the file is added or updated to the node’s file system. If
the application is running on the node when the file is added or updated, then one of the following occurs:
v For files added or updated at application scope or in non-Web modules, the entire application is
stopped, the file is added or updated, and then the entire application is restarted.
v For files added or updated to Web module metadata (META-INF or WEB-INF directory), the running Web
module is stopped, the Web module file is added or updated, and then the Web module is started.
v For all other files in Web modules, the file is added or updated on the node’s file system without
stopping the application or any of its components.

Chapter 7. Deploying and administering applications 927

Partial application
Under Update options, specifies to update multiple files of an installed application by uploading a
compressed file. Depending on the contents of the compressed file, a single use of this option can replace
files in, add new files to, and delete files from the installed application. Each entry in the compressed file is
treated as a single file and the path of the file from the root of the compressed file is treated as the relative
path of the file in the installed application.

After selecting this option, specify whether the compressed file is on a local or remote file system and the
full path name of the compressed file. You will likely use Local file system because you are uploading a
compressed file and remote browsing only works for .ear, .war or .jar files. Specify a valid compressed
file format such as .zip or .gzip. The path provides the location of the compressed file before installation.
This option unzips the compressed file into the installed application directory.

Use Local file system if the browser and the updated files or modules are on the same machine, whether
or not the server is on that machine too. Local file system is available for all update options.

To replace a file, a file in the compressed file must have the same relative path as the file to be updated in
the installed application.

To add a new file to the installed application, a file in the compressed file must have a different relative
path than the files in the installed application.

The relative path of a file in the installed application is formed by concatenation of the relative path of the
module (if the file is inside a module) and the relative path of the file from the root of the module
separated by /.

To remove a file from the installed application, specify metadata in the compressed file using a file named
META-INF/ibm-partialapp-delete.props at any archive scope. The ibm-partialapp-delete.props file must
be an ASCII file that lists files to be deleted in that archive with one entry for each line. The entry can
contain a string pattern such as a regular expression that identifies multiple files. The file paths for the files
to be deleted must be relative to the archive path that has the META-INF/ibm-partialapp-delete.props file.

Level of files to delete Metadata .props file to include in compressed file

Application Include META-INF/ibm-partialapp-delete.props in the compressed file. In
the metadata .props file, list files to be deleted. File paths are relative to the
location of the META-INF/ibm-partialapp-delete.props file.

For example, to delete a file named utils/config.xmi from the root of the
my.ear file, include the line utils/config.xmi in the META-INF/ibm-
partialapp-delete.props file.
Module Include module_uri/META-INF/ibm-partialapp-delete.props in the
compressed file.

To delete one file from a module, include the file path relative to the module
in the metadata .props file. For example, to delete a/b/c.jsp from the
my.jar module, include a/b/c.class in my.jar/META-INF/ibm-partialapp-
delete.props file in the compressed file.

To delete multiple files within a module, list the files to be deleted in the
metadata .props file with one entry on each line. For example, to delete all
JavaServer Pages (.jsp files) from the my.war file, include the line .*jsp in
the my.war/META-INF/ibm-partialapp-delete.props file. The line uses a
regular expression, .*jsp, to identify all .jsp files in my.war.

You can use a single partial application file to add, delete and update multiple files.

928 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
After a partial application update, when configuration changes are saved, the new or updated application
file is stored in the deployed application in the WebSphere Application Server configuration repository.
When these changes are synchronized with the node, the files are added or updated to the node’s file
system. Because the partial application option updates multiple files, the application components that are
restarted are determined using individual files in the partial application.

An example of entries in a partial application compressed file follows:

util.jar
META-INF/ibm-partialapp-delete.props
foo.jar/com/mycomp/xyz.class
xyz.war/welcome.jsp
xyz.war/WEB-INF/web.xml
webmod.war/META-INF/ibm-partialapp-delete.props

For this example, the META-INF/ibm-partialapp-delete.props file contains the .*.dat and tools/test.jar
files. The webmod.war/META-INF/ibm-partialapp-delete.props file contains the com/test/.*.jsp and
WEB-INF/test.xmi files.

The partial application update option does the following:

v Adds or replaces util.jar in the deployed application.
v Adds or replaces com/mycomp/xyz.class inside the foo.jar file of the deployed application.
v Deletes *.dat files from the application, but not from any modules.
v Deletes tools/test.jar from the application.
v Adds or replaces welcome.jsp inside the xyz.war module of the deployed application.
v Replaces WEB-INF/web.xml inside the xyz.war module of the deployed application.
v Deletes com/test/*.jsp from the webmod.war module.
v Deletes WEB-INF/test.xmi from the webmod.war module.

Hot deployment and dynamic reloading

You can make various changes to applications and their modules without having to stop the server and
start it again. Making these types of changes is known as hot deployment and dynamic reloading.

This article assumes that your application files are deployed on a server and you want to upgrade the files.

Hot deployment is the process of adding new components (such as WAR files, EJB Jar files, enterprise
Java beans, servlets, and JSP files) to a running server without having to stop the application server
process and start it again.

Dynamic reloading is the ability to change an existing component without needing to restart the server in
order for the change to take effect. Dynamic reloading involves:
v Changes to the implementation of a component of an application, such as changing the implementation
of a servlet
v Changes to the settings of the application, such as changing the deployment descriptor for a Web
module

As opposed to the changes made to a deployed application described in “Updating applications” on page
921, changes made using hot deployment or dynamic reloading do not use the administrative console or a
wsadmin scripting command. You must directly manipulate the application files on the server where the
application is deployed.

If the application you are updating is deployed on a server that has its application class loader policy set to
Single, you might not be able to dynamically reload your application. At minimum, you must restart the
server after updating your application.

Tip: Do not use hot deployment to update components in a production deployment manager managed
cell. Hot deployment is well-suited for development and testing, but poses unacceptable risks to

Chapter 7. Deploying and administering applications 929

 production environments. Full or partial resynchronization might erase hot deployed components.
Further, hot deployed components are not migrated between versions of WebSphere Application
Server. To add new components or modules to an enterprise application, reassemble the application
EAR file so it has the new components or modules and then redeploy the EAR file.
1. Locate your expanded application files. The application files are in the directory you specified when
installing the application or, if you did not specify a custom target directory, are in the default target
directory, install_root/installedApps/cell_name. Your EAR file,
${APP_INSTALL_ROOT}/cell_name/application_name.ear, points to the target directory. The
variables.xml file for the node defines ${APP_INSTALL_ROOT}. It is important to locate the expanded
application files because, as part of installing applications, a WebSphere application server unjars
portions of the EAR file onto the file system of the computer that will run the application. These
expanded files are what the server looks at when running your application. If you cannot locate the
expanded application files, look at the binariesURL attribute in the deployment.xml file for your
application. The attribute designates the location the run time uses to find the application files. For the
remainder of this information on hot deployment and dynamic reloading, application_root represents
the root directory of the expanded application files.
2. Locate application metadata files. The metadata files include the deployment descriptors (web.xml,
application.xml, ejb-jar.xml, and the like), the bindings files (ibm-web-bnd.xmi, ibm-app-bnd.xmi, and
the like), and the extensions files (ibm-web-ext.xmi, ibm-app-ext.xmi, and the like). Metadata XML
files for an application can be loaded from one of two locations. The metadata files can be loaded from
the same location as the application binary files (such as application_root/META-INF) or they can be
loaded from the WebSphere configuration tree, ${CONFIG_ROOT}/cells/cell_name/applications
/application_EAR_name/deployments/application_name/. The value of the useMetadataFromBinary flag
specified during application installation controls which location is used. If specified, the metadata files
are loaded from the same location as the application binary files. If not specified, the metadata files are
loaded from the application deployment folder in the configuration tree. For the remainder of this
information, metadata_root represents the location of the metadata files for the specified application or
module.
3. Required: If you are running WebSphere Application Server on a group of machines using Network
Deployment and you are changing an application on a particular node, disable automatic
synchronization.
a. Click System administration > Node agents >node_agent_name > File synchronization service
in the console navigation tree.
b. On the File synchronization service page, clear the check box for Automatic synchronization and
click OK.
When you run WebSphere Application Server on a group of machines using Network Deployment and
you change a file on the disk in the expanded application directory for a particular node, you can lose
those changes the next time node synchronization occurs. In the Network Deployment environment,
the configuration stored by the deployment manager is the master copy and any changes detected
between that master copy and the copy on a particular machine trigger the master copy to be
downloaded to the node.
4. Optional: Examine the values specified for Enable class reloading and Reloading interval on the
settings page for your enterprise application. If reloading of application files is enabled and the reload
interval is greater than zero (0), the application files are reloaded after the application is updated. For
Web modules such as servlets and JavaServer page (JSP) files, a Web container reloads a Web
module only when the IBM extension reloadingEnabled in the ibm-web-ext.xmi file is also set to true.
You can set reloadingEnabled to true when editing your Web module’s extended deployment
descriptors in an assembly tool.
5. Change or add the following components or modules as needed:
v Application files
v WAR files
v EJB Jar files
v HTTP plug-in configuration files

930 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
6. For changes to take effect, you might need to start, stop, or restart an application. “Starting and
stopping applications” on page 918 provides information on using the administrative console to start,
stop, or restart an application. ″Starting applications with scripting″ and ″Stopping applications with
scripting″ provide information on using the wsadmin scripting tool.
7. If you disabled automatic synchronization in step 3, enable automatic synchronization again:
a. Return to the File synchronization service page.
b. Select Automatic synchronization.
c. Click OK.

Changing or adding application files

You can change or add application files on application servers without having to stop the server and start it
again.

There are several changes that you can make to deployed application files without stopping the server and
starting it again. You can use the update wizard of the administrative console to make the changes without
having to stop and restart the server. This article describes how to make the following changes by
manipulating an application file on the server where the application is deployed:
v Updating an existing application on a running server, providing a new enterprise application (EAR file)
v Adding a new application to a running server
v Removing an existing application from a running server
v Changing or adding files to existing enterprise bean (EJB) or Web modules
v Changing the application.xml file for an application
v Changing the ibm-app-ext.xmi file for an application
v Changing the ibm-app-bnd.xmi file for an application
v Changing a non-module Jar file contained in the EAR file

Updating an existing application on a running server (providing a new EAR file)

Reinstall an updated application using the administrative console or the wsadmin $AdminApp install
command with the -update option.

Both reinstallation methods enable you to update an existing application using any of the other steps listed
in this file, including changing classes, adding modules, removing modules, changing modules, or
changing metadata files. The application reinstallation methods detect the changes in your application and
prompt you for additional binding data that might be needed to install the application. The reinstallation
process automatically stops and restarts your application on the appropriate servers.

Hot deployment Yes

Dynamic reloading Yes

Adding a new application to a running server

Install an application using the administrative console or the wsadmin install command.

Hot deployment Yes

Dynamic reloading No

Removing an existing application from a running server

Stop the application and then uninstall it from the server. Use the administrative console to stop the
application and then uninstall it. Or run the wasadmin stopApplication command and then the uninstall
command.

Hot deployment Yes

Chapter 7. Deploying and administering applications 931

Dynamic reloading No

Changing or adding files to existing EJB or Web modules

1. Update the application files in the application_root location.
2. Restart the application. Use the administrative console to restart the application. Or run the wasadmin
stopApplication and startApplication commands.

Hot deployment Yes

Dynamic reloading No

Changing the application.xml file for an application

Restart the application. Automatic reloading will not detect the change. Use the administrative console to
restart the application. Or run the wasadmin stopApplication and startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Changing the ibm-app-ext.xmi file for an application

Restart the application. Automatic reloading will not detect the change. Use the administrative console to
restart the application. Or run the wasadmin stopApplication and startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Changing the ibm-app-bnd.xmi file for an application

Restart the application. Automatic reloading will not detect the change. Use the administrative console to
restart the application. Or run the wasadmin stopApplication and startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Changing a non-module Jar file contained in the EAR file

1. Update the non-module Jar file in the application_root location.
2. If automatic reloading is not enabled, restart the application. Use the administrative console to restart
the application. Or run the wasadmin stopApplication and startApplication commands.
If automatic reloading is enabled, you do not need to take further action. Automatic reloading will
detect the change.

Hot deployment Yes

Dynamic reloading Yes

Changing or adding WAR files

You can change Web application archives (WAR files) on application servers without having to stop the
server and start it again.

There are several changes that you can make to WAR files without stopping the server and starting it
again. You can use the update wizard of the administrative console to make the changes without having to
stop and restart the server. This article describes how to make the following changes by manipulating a
WAR file on the server where the application is deployed:

932 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Changing an existing JavaServer Pages (JSP) file
v Adding a new JSP file to an existing application
v Changing an existing servlet class (editing and recompiling)
v Changing a dependent class of an existing servlet class
v Adding a new servlet using the Invoker (Serve Servlets by class name) facility or adding a dependent
class to an existing application
v Adding a new servlet, including a new definition of the servlet in the web.xml deployment descriptor for
the application
v Changing the web.xml file of a WAR file
v Changing the ibm-web-ext.xmi file of a WAR file
v Changing the ibm-web-bnd.xmi file of a WAR file

Changing an existing JSP file

Place the changed JSP file directly in the application_root/module_name directory or the appropriate
subdirectory. The change will be automatically detected and the JSP will be recompiled and reloaded.

Hot deployment Not applicable

Dynamic reloading Yes

Adding a new JSP file to an existing application

Place the new JSP file directly in the application_root/module_name directory or the appropriate
subdirectory. The new file will be automatically detected and compiled on the first request to the page.

Hot deployment Yes

Dynamic reloading Yes

Changing an existing servlet class (editing and recompiling)

1. Place the new version of the servlet .class file directly in the application_root/module_name/WEB-
INF/classes directory. If the .class file is part of a Jar file, you can place the new version of the Jar
file directly in application_root/module_name/WEB-INF/lib. In either case, the change will be detected,
the Web application will be shut down and reinitialized, picking up the new class.
2. If automatic reloading is not enabled, restart the application. Use the administrative console to restart
the application. Or run the wasadmin stopApplication and startApplication commands.
If automatic reloading is enabled, you do not need to take further action. Automatic reloading will
detect the change.

Hot deployment Not applicable

Dynamic reloading Yes

Changing a dependent class of an existing servlet class

1. Place the new version of the dependent .class file directly in the application_root/module_name/WEB-
INF/classes directory. If the .class file is part of a Jar file, you can place the new version of the Jar
file directly in application_root/module_name/WEB-INF/lib. In either case, the change will be detected,
the Web application will be shut down and reinitialized, picking up the new class.
2. If automatic reloading is not enabled, restart the application. Use the administrative console to restart
the application. Or run the wasadmin stopApplication and startApplication commands.
If automatic reloading is enabled, you do not need to take further action. Automatic reloading will
detect the change.

Hot deployment Not applicable

Dynamic reloading Yes

Chapter 7. Deploying and administering applications 933

Adding a new servlet using the Invoker (Serve Servlets by class name) facility or adding a
dependent class to an existing application
1. Place the new .class file directly in the application_root/module_name/WEB-INF/classes directory. If
the .class file is part of a Jar file, you can place the new version of the Jar file directly in
application_root/module_name/WEB-INF/lib. In either case, the change will be detected, the Web
application will be shut down and reinitialized, picking up the new class.
This case is treated the same as changing an existing class. The difference is that adding the servlet
or class does not immediately cause the Web application to reload because the class has never been
loaded before. The class simply becomes available for execution.
2. If automatic reloading is not enabled, restart the application. Use the administrative console to restart
the application. Or run the wasadmin stopApplication and startApplication commands.
If automatic reloading is enabled, you do not need to take further action. Automatic reloading will
detect the change.

Hot deployment Yes

Dynamic reloading Not applicable

Adding a new servlet, including a new definition of the servlet in the web.xml deployment
descriptor for the application
1. Place the new .class file directly in the application_root/module_name/WEB-INF/classes directory. If
the “.class” file is part of a Jar file, you can place the new version of the Jar file directly in
application_root/module_name/WEB-INF/lib.
You can edit the web.xml file in place or copy it into the application_root/module_name/WEB-
INF/classes directory. The new .class file will not trigger a reloading of the application.
2. Restart the application. Use the administrative console to restart the application. Or run the wasadmin
stopApplication and startApplication commands. After the application restarts, the new servlet is
available for service.

Hot deployment Yes

Dynamic reloading Not applicable

Changing the web.xml file of a WAR file

1. Edit the web.xml file in place or copy it into the metadata_root/module_name/WEB-INF directory.
2. Restart the application. Use the administrative console to restart the application. Or run the wasadmin
stopApplication and startApplication commands.

Hot deployment Yes

Dynamic reloading Yes

Changing the ibm-web-ext.xmi file of a WAR file

Edit the extension settings as needed. You can change all of the extension settings. The only warning is if
you set the reloadInterval property to zero (0) or the reloadEnabled property to false, the application no
longer automatically detects changes to class files. Both of these changes disable the automatic reloading
function. The only way to re-enable automatic reloading is to change the appropriate property and restart
the application. See other task descriptions in this file for information on restarting an application.

Hot deployment Not applicable

Dynamic reloading Yes

Changing the ibm-web-bnd.xmi file of a WAR file

1. Edit the bindings as needed. You can change all of the values but ensure that the entities you are
binding to are present in the configuration of the server.

934 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Restart the application. Use the administrative console to restart the application. Or run the wasadmin
stopApplication and startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Changing or adding EJB Jar files

You can change enterprise bean (EJB) Jar files on application servers without having to stop the server
and start it again.

There are several changes that you can make to EJB Jar files without stopping the server and starting it
again. You can use the update wizard of the administrative console to make the changes without having to
stop and restart the server. This article describes how to make the following changes by manipulating an
EJB file on the server where the application is deployed:
v Changing the ejb-jar.xml file of an EJB Jar file
v Changing the ibm-ejb-jar-ext.xmi or ibm-ejb-jar-bnd.xmi file of an EJB Jar file
v Changing the Table.ddl file for an EJB Jar file
v Changing the Map.mapxmi or Schema.dbxmi file for an EJB Jar file
v Updating the implementation class for an EJB file or a dependent class of the implementation class for
an EJB file
v Updating the Home/Remote interface class for an EJB file
v Adding a new EJB file to an existing EJB Jar file

Changing the ejb-jar.xml file of an EJB Jar file

Restart the application. Automatic reloading will not detect the change. Use the administrative console to
restart the application. Or run the wasadmin stopApplication and startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Change the ibm-ejb-jar-ext.xmi or ibm-ejb-jar-bnd.xmi file of an EJB Jar file

Restart the application. Automatic reloading will not detect the change. Use the administrative console to
restart the application. Or run the wasadmin stopApplication and startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Changing the Table.ddl file for an EJB Jar file

Rerun the DDL file on the user database server. Changing the Table.ddl file has no effect on the
application server and is a change to the database table schema for the EJB files.

Hot deployment Not applicable

Dynamic reloading Not applicable

Changing the Map.mapxmi or Schema.dbxmi file for an EJB Jar file

1. Change the Map.mapxmi or Schema.dbxmi file for an EJB Jar file.
2. Regenerate the deployed code artifacts for the EJB file.
3. Apply the new EJB Jar file to the server.
4. Restart the application. Use the administrative console to restart the application. Or run the wasadmin
stopApplication and startApplication commands.

Chapter 7. Deploying and administering applications 935

Hot deployment Not applicable
Dynamic reloading Yes

Updating the implementation class for an EJB file or a dependent class of the implementation
class for an EJB file
1. Update the class file in the application_root/module_name.jar file.
2. If automatic reloading is enabled, you do not need to take further action. Automatic reloading will
detect the change.
If automatic reloading is not enabled, restart the application of which the EJB file is a member. If the
updated module is used by other modules in other applications, restart those applications as well. Use
the administrative console to restart the application. Or run the wasadmin stopApplication and
startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Updating the Home/Remote interface class for an EJB file

1. Update the interface class of the EJB file.
2. Regenerate the deployed code artifacts for the EJB file.
3. Apply the new EJB Jar file to the server.
4. If automatic reloading is enabled, you do not need to take further action. Automatic reloading will
detect the change.
If automatic reloading is not enabled, restart the application of which the EJB file is a member. Use the
administrative console to restart the application. Or run the wasadmin stopApplication and
startApplication commands.

Hot deployment Not applicable

Dynamic reloading Yes

Adding a new EJB file to an existing EJB Jar file

1. Apply the new or updated Jar file to the application_root location.
2. If automatic reloading is enabled, you do not need to take further action. Automatic reloading will
detect the change.
If automatic reloading is not enabled, restart the application. Use the administrative console to restart
the application. Or run the wasadmin stopApplication and startApplication commands.

Hot deployment Yes

Dynamic reloading Yes

Changing the HTTP plug-in configuration

You can change the HTTP plug-in configuration without having to stop the server and start it again.

There are several change that you can make to the HTTP plug-in configuration without stopping the server
and starting it again. This file describes--
v Changing the application.xml file to change the context root of a Web application archive (WAR file)
v Changing the web.xml file to add, remove, or modify a servlet mapping
v Changing the server.xml file to add, remove, or modify an HTTP transport or changing the
virtualhost.xml file to add or remove a virtual host or to add, remove, or modify a virtual host alias

Changing the application.xml file to change the context root of a WAR file
1. Change the application.xml file.

936 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. If the plug-in configuration property Automatically propagate plug-in configuration file is selected for this
plug-in, it is automatically regenerated whenever the application.xml file changes. (See for
information on how to set this property.) You can also run the GenPluginCfg.bat/sh script, or issue a
wsadmin command to regenerate the plug-in configuration file.

Hot deployment Yes

Dynamic reloading No

Changing the web.xml file to add, remove, or modify a servlet mapping

1. Change the web.xml file.
2. If the plug-in configuration property Automatically propagate plug-in configuration file is selected for this
plug-in, it is automatically regenerated whenever the web.xml file changes. (See for information on how
to set this property.) You can also run the GenPluginCfg.bat/sh script, or issue a wsadmin command to
regenerate the plug-in configuration file.
If the Web application has file serving enabled or has a servlet mapping of /, the plug-in configuration
does not have to be regenerated. In all other cases a regeneration is required.

Hot deployment Yes

Dynamic reloading Yes

Changing the server.xml file to add, remove, or modify an HTTP transport or changing the
virtualhost.xml file to add or remove a virtual host or to add, remove, or modify a virtual host alias
1. Change the server.xml file to add, remove, or modify an HTTP transport or change the
virtualhost.xml file to add or remove a virtual host or to add, remove, or modify a virtual host alias.
2. If the plug-in configuration property Automatically propagate plug-in configuration file is selected
for this plug-in, it is automatically regenerated whenever the server.xml file changes. (See for
information on how to set this property.) You can also run the GenPluginCfg.bat/sh script, or issue a
wsadmin command to regenerate the plug-in configuration file.

Hot deployment Yes

Dynamic reloading Yes

Uninstalling applications
After an application no longer is needed, you can uninstall it.

Uninstalling an application deletes the application from the WebSphere Application Server configuration
repository and it deletes the application binaries from the file system of all nodes where the application
modules are installed.
1. Click Applications > Enterprise Applications in the administrative console navigation tree to access
the Enterprise Applications page.
2. If you need to retain a copy of the application, back up the application.
a. Select the application you want uninstalled.
b. Click Export.
The application is exported to an enterprise application (.ear file), preserving the binding information.
3. Uninstall the application.
a. Select the application you want uninstalled.
b. Click Uninstall.
4. Save changes made to the administrative configuration.

Chapter 7. Deploying and administering applications 937

Application binaries are deleted when configuration changes on the deployment manager synchronize with
configurations for individual nodes.

Removing a file
After a file is no longer needed, you can remove the file from an application or module deployed on a
server.

Removing a file deletes the file from the WebSphere Application Server configuration repository and it
deletes the file from the file system of all nodes where the file is installed.
v Remove a file from an application.
1. Go to the Enterprise Applications page. Click Applications > Enterprise Applications in the
console navigation tree.
2. Select the application that contains a file you want removed.
3. Click Remove File. The Remove a file from an application page is displayed
4. Select the URI of the file that you want removed from the application.
5. Select Export before removing file to back up the application.
6. Specify the location to which you want the file exported.
7. Click Back to return to the Enterprise Applications page.
v Remove a file from a module.
1. Go to the settings page for the application. Click Applications > Enterprise Applications
>application_name in the console navigation tree.
2. Under Related Items, click Web modules, EJB Modules, or Connector Modules.
3. Select the module from which you want to delete a file.
4. Click Remove File. The Remove a file from a module page is displayed.
5. Select the URI of the file that you want removed from the module.
6. Optional: Back up the application. Select the application name and then specify the location to which
you want the file exported.
7. Click OK to remove the file.

The file is exported to the designated location and removed from the application or module. The
application or standalone Web module that had a file removed is restarted so the changes take effect.

Save the changes to your administrative configuration. Application binaries are deleted when configuration
changes on the deployment manager synchronize with configurations for individual nodes.

If the application or module is deployed on a cluster and you have no more configuration changes to
make, click Rollout Update on the Enterprise Applications page to propagate the changed configuration
on all cluster members of the cluster on which the application or module is deployed. Rollout Update
sequentially updates the configuration on the nodes that contain cluster members.

Deploying and administering applications: Resources for learning

Use the following links to find relevant supplemental information about deploying and administering
applications using the administrative console. The information resides on IBM and non-IBM Internet sites,
whose sponsors control the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

938 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Refer to the information center for links to information applicable to WebSphere Application Server
generally, such as lists of IBM technical papers, Redbooks and samples.

View links to additional information about:

v Programming model and decisions
v Programming instructions and examples
v Programming instructions and examples

Programming model and decisions

v The J2EETM Tutorial: The Duke’s Bookstore Application
v Best Practices in WebSphere Application: Separating the developers from the administrators
v Designing Enterprise Applications with the JavaTM 2 Platform, Enterprise Edition, Second Edition
v Designing Enterprise Applications, Second Edition
v Building JavaTM Enterprise Applications Volume I: Architecture

Programming instructions and examples

v WebSphere Application Server education
v Developing and Testing a Complete ’Hello World’ J2EE Application with IBM WebSphere Studio
Application Developer for Linux
v Writing Enterprise Applications with JavaTM 2 Platform, Enterprise Edition

Administration
v Listing of all IBM WebSphere Application Server Redbooks

Chapter 7. Deploying and administering applications 939

940 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Chapter 8. Developing WebSphere applications
Use this section as a starting point to investigate the technologies used in and by applications that you
deploy on the application server. Also use this section to learn about developing WebSphere applications.

See Learn about WebSphere applications: Overview and new features for an introduction to each
technology.

Web applications How do I?... Overview Samples

EJB applications How do I?... Overview Tutorials Samples
Client applications How do I?... Overview Samples
Web services How do I?... Overview Tutorials Samples
Data access resources How do I?... Overview Tutorials Samples
Messaging resources How do I?... Overview Tutorials Samples
Mail, URLs, and other How do I?... Overview
J2EE resources
Security See the Securing WebSphere See the See the Securing See the Securing
applications PDF Administering WebSphere WebSphere
applications PDF applications PDF applications PDF
Naming and directory How do I?... Overview
Object Request Broker How do I?... Overview
Transactions How do I?... Overview Samples
ActivitySessions How do I?... Overview Samples
Application profiling How do I?... Overview Samples
Asynchronous beans How do I?... Overview Samples
Dynamic caching How do I?... Overview
Dynamic query How do I?... Overview Samples
Internationalization How do I?... Overview Samples
Object pools How do I?... Overview
Scheduler How do I?... Overview Samples
Startup beans How do I?... Overview
Work areas How do I?... Overview

Web applications

Task overview: Developing and deploying Web applications

A developer creates the files comprising a Web application, and then assembles the Web application
components into a Web module. Next, the deployer (typically the developer in a unit-testing environment
or the administrator in a production environment) installs the Web application on the server.
1. (Optional) Migrate existing Web applications to run in the new version of WebSphere.
2. Design the Web application and develop its code artifacts: Servlets, JavaServer Pages (JSP) files, and
static files, as for example, images and Hyper Text Markup Language (HTML) files. See the
″Resources for learning″ article for links to design documentation.

© Copyright IBM Corp. 2004 941

3. Develop the Web application, using WebSphere Application Server extensions to enhance its
functionality.
4. Assemble the Web application into a Web module using an assembly tool. Web module assembly
properties might include the ability to:
v Configure servlet page lists.
v Configure servlet filters.
v Serve servlets by class name.
v Enable file serving.
5. Deploy the Web module or application module that contains the Web application.
Following deployment, you might find it handy to use the tool that enables batch compiling of the JSP
files for quicker initial response times.
6. (Optional) Troubleshoot your Web application.
7. (Optional) Modify the default Web container configuration in the application server in which you
deployed the Web module or application module containing the Web application.
8. (Optional) Manage the deployed Web application.

Web applications
A Web application is comprised of one or more related servlets, JavaServer Pages technology (JSP files),
and Hyper Text Markup Language (HTML) files that you can manage as a unit.

The files in a Web application are related in that they work together to perform a business logic function.
For example, one of the WebSphere Application Server samples is a Simple Greeting Web application.
This application, comprised of a servlet and Web pages, greets new users when the application is
accessed.

The Web application is a concept supported by the Java Servlet Specification. Web applications are
typically packaged as .war files.

web.xml file
The web.xml file provides configuration and deployment information for the Web components that comprise
a Web application. Examples of Web components are servlet parameters, servlet and JavaServer Pages
(JSP) definitions, and Uniform Resource Locators (URL) mappings.

The Java Servlet 2.4 specification defines the web.xml deployment descriptor file in terms of an XML
schema document. For backwards compatibility of applications written to the Java Servlet 2.2
Specification, Web containers are also required to support the Java Servlet 2.2 specification. For
backwards compatibility of applications written to the Java Servlet 2.3 specification, Web containers are
also required to support the Java Servlet 2.3 specification.

Location

The web.xml file must reside in the WEB-INF directory under the context of the hierarchy of directories that
exist for a Web application. For example, if the application is client.war, then the web.xml file is placed in
the install_root/client war/WEB-INF directory.

Usage notes
v Is this file read-only?
No
v Is this file updated by a product component?
This file is updated by the Application Server Toolkit.
v If so, what triggers its update?
The Application Server Toolkit updates the web.xml file when you assemble Web components into a
Web module, or when you modify the properties of the Web components or the Web module.
v How and when are the contents of this file used?

942 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 WebSphere Application Server functions use information in this file during the configuration and
deployment phases of Web application development.

Sample file entry

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_9" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>Servlet 2.4 application</display-name>
<filter>
<filter-name>ServletMappedDoFilter_Filter</filter-name>
<filter-class>tests.Filter.DoFilter_Filter</filter-class>
<init-param>
<param-name>attribute</param-name>
<param-value>tests.Filter.DoFilter_Filter.SERVLET_MAPPED</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>ServletMappedDoFilter_Filter</filter-name>
<url-patter>/DoFilterTest</url-pattern>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>ServletMappedDoFilter_Filter</filter-name>
<url-patter>/IncludedServlet</url-pattern>
<dispatcher>INCLUDE</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>ServletMappedDoFilter_Filter</filter-name>
<url-patter>ForwardedServlet</url-pattern>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
<listener>
<listener-class>tests.ContextListener</listener-class>
</listener>
<listener>
<listener-class>tests.ServletRequestListener.RequestListener</listener-class>
</listener>
<servlet>
<servlet-name>welcome</servlet-name>
<servlet-class>WelcomeServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>ServletErrorPage</servlet-name>
<servlet-class>tests.Error.ServletErrorPage</servlet-class>
</servlet>
<servlet>
<servlet-name>IncludedServlet</servlet-name>
<servlet-class>tests.Filter.IncludedServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>ForwardedServlet</servlet-name>
<servlet-class>tests.Filter.ForwardedServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>welcome</servlet-name>
<url-pattern>/hello.welcome</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ServletErrorPage</servlet-name>
<url-pattern>/ServletErrorPage</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>IncludedServlet</servlet-name>
<url-pattern>/IncludedServlet</url-pattern>

Chapter 8. Developing WebSphere applications 943

 </servlet-mapping>
<servlet-mapping>
<servlet-name>ForwardedServlet</servlet-name>
<url-pattern>/ForwardedServlet</url-pattern>
</servlet-mapping>
<welcome-file-list>
<welcome-file>hello.welcome</welcome-file>
</welcome-file-list>
<error-page>
<exception-type>java.lang.ArrayIndexOutOfBoundsException</exception-type>
<location>/ServletErrorPage</location>
</error-page>
</web-app>

Default Application
The IBM WebSphere Application Server provides a default configuration that allows administrators to
easily verify that the Application Server is running. When the product is installed, it includes an application
server called server1 and an enterprise application called Default Application.

Default Application contains a Web Module called DefaultWebApplication and an enterprise bean JAR file
called Increment. The Default Application provides a number of servlets, described below. These servlets
are available in the product.

For additional code examples, visit the Samples Gallery. Learn how to locate and install the Samples
Gallery by viewing the Samples Gallery reference page.

The URL for accessing Samples is: http://localhost:9080/WSsamples/

Snoop

Use the Snoop servlet to retrieve information about a servlet request. This servlet returns the following
information:
v Servlet initialization parameters
v Servlet context initialization parameters
v URL invocation request parameters
v Perferred client locale
v Context path
v User principal
v Request headers and their values
v Request parameter names and their values
v HTTPS protocol information
v Servlet request attributes and their values
v HTTP session information
v Session attributes and their values

The Snoop servlet includes security configuration so that when WebSphere Security is enabled, clients
must supply a user ID and password to execute the servlet.

The URL for the Snoop servlet is: http://localhost:9080/snoop/.

HelloHTML

Use the HelloHTML pervasive servlet to exercise the PageList support provided by the WebSphere Web
container. This servlet extends the PageListServlet, which provides APIs that allow servlets to call other
Web resources by name or, when using the Client Type detection support, by type.

You can invoke the Hello servlet from an HTML browser, speech client, or most Wireless Application
Protocol (WAP) enabled browsers using the URL: http://localhost:9080/HelloHTML.jsp.

944 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
HitCount

Use the HitCount Demonstration application to demonstrate how to increment a counter using a variety of
methods, including:
v A servlet instance variable
v An HTTP session
v An enterprise bean

You can instruct the servlet to execute any of these methods within a transaction that you can commit or
roll back. If the transaction is committed, the counter is incremented. If the transaction is rolled back, the
counter is not incremented.

The enterprise bean method uses a Container- Managed Persistence enterprise bean that persists the
counter value to a Cloudscape database. This enterprise bean is configured to use the Default
Datasource, which is set to the DefaultDB database.

When using the enterprise bean method, you can instruct the servlet to look up the enterprise bean, either
in the WebSphere global namespace, or in the namespace local to the application.

The URL for the HitCount application is: http://localhost:9080/HitCount.jsp.

Servlets
Servlets are Java programs that use the Java Servlet Application Programming Interface (API). You must
package servlets in a Web archive (WAR) file or Web module for deployment to the application server.
Servlets run on a Java-enabled Web server and extend the capabilities of a Web server, similar to the way
applets run on a browser and extend the capabilities of a browser.

Servlets can support dynamic Web page content, provide database access, serve multiple clients at one
time, and filter data.

For the purposes of WebSphere Application Server, discussions of servlets focus on Hyper Text Transfer
Protocol (HTTP) servlets, which serve Web-based clients.

With the introduction of Java Servlet 2.4 specification, you can define servlets as welcome files. Non
servlet resources are served only when the FileServingEnabled attribute is set to true. Serving welcome
files is connected to serving static content, therefore fileServing enabled is set in the Web module.

JavaServer Pages
JavaServer Pages (JSP) are application components coded to the JavaServer Pages Specification.
JavaServer Pages enable the separation of the Hypertext Markup Language (HTML) code from the
business logic in Web pages so that HTML programmers and Java programmers can more easily
collaborate in creating and maintaining pages.

JSP files support a division of roles:

HTML authors
Develop JSP files that access databases and reusable Java components, such as servlets and
beans.
Java programmers
Create the reusable Java components and provide the HTML authors with the component names
and attributes.
Database administrators
Provide the HTML authors with the name of the database access and table information.

WebSphere Application Server 6.0 supports the JSP 2.0 specification. The sub-topics below discuss
WebSphere Application Server’s JSP 2.0 implementation, focusing on configuration, tools and extensions.

Chapter 8. Developing WebSphere applications 945

JSP engine:

The WebSphere Application Server JavaServer Pages (JSP) engine is the implementation of the
JavaServer Pages Specification.

WebSphere Application Server 6.0 supports the JSP 2.0 specification.

The JSP engine

v Validates JSP source, both classic and XML styles
v Translates JSP source to Java classes
v Compiles Java classes, reporting any errors
v Generates Java classes for any tag files that are used by the JSP
v Interfaces with the Web container to load JSP class files
v Supports JSP batch compilation, JSP compilation during application installation, and JSP compilation
during the build process of customer applications, through an Ant task.
v Loads class files, and manage life-cycle (reloading, unloading as necessary)
v Supports debugging of JavaServer Pages files through support for JSR 45 (Debugging Support for
Other Languages)

JSP engine configuration parameters: In WebSphere Application Server, you can configure the
JavaServer Pages (JSP) engine for optimal performance in a production server environment and for the
needs of developers in a development environment. The configuration parameters are described below.

The JSP engine parameters are case sensitive. If the value specified for a parameter is comprised of two
or more words separated by spaces, you must add quotation marks around the value. Some parameters
affect the Java source that is generated for a JSP or tag file. These parameters are identified by the
statement ″This parameter requires regeneration of Java source.″ This statement indicates that if the
configuration parameter is modified, the new value for the parameter does not have any effect until the
JSP files are retranslated and the Java sources are recompiled.
v compileWithAssert
Specifies whether the generated Java classes should contain support for the Developer Kit, Java
Technology Edition 1.4 Assertion facility. The effect of setting this parameter to true is that the –source
1.4 option is passed to the Java compiler. The default for this parameter is false. This parameter
requires regeneration of Java source.
v classdebuginfo
Indicates whether the compiler includes debugging information in the generated class file. When you set
this parameter to true, the –g option is passed to the Java compiler. The default for this parameter is
false. This parameter requires regeneration of Java source.
v deprecation
Specifies whether the compiler generates deprecation warnings when compiling the generated Java
source. When you set this parameter to true, the -deprecation option is passed to the Java compiler.
The default for this parameter is false. This parameter requires regeneration of Java source.
v disableJspRuntimeCompilation
If this option is set to true, the JSP engine at runtime does not translate and compile JSP files; the JSP
engine loads only precompiled class files. JSP source files do not need to be present in order to load
class files. When this option is set to true, you can install an application without JSP source, but the
application must have precompiled class files. There is a Web container custom property with the same
name that is used to determine the behavior of all Web modules installed in a server. If both the Web
container custom property and the JSP engine option are set, the JSP engine option takes precedence.
The default for this parameter is false.
v extendedDocumentRoot
To allow a JSP file resource to be shared across Web application archives, specify a comma delimited
list of directories and/or Java Archive (JAR) files as search paths to be used if the requested resource

946 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 cannot be located in the Web application archive’s public document tree. If the JSP file is located inside
a JAR file and reloadEnabled is true, the timestamp of the JAR file is used for isOutDated checks for
recompile purposes. The default for this parameter is null.
v ieClassID
Indicates the Java plug-in COM class ID for Internet Explorer. The <jsp:plugin> tags use this value.
The default classid is clsid:8AD9C840-044E-11D1-B3E9-00805F499D93. This parameter requires
regeneration of Java source.
v javaEncoding
Specifies the encoding that is used when the .java file is generated, and when it is compiled by the
Java compiler. Set this parameter when the page encoding of your JSP pages is not UTF-8 compatible.
When javaEncoding is set, the encoding is passed to the Java compiler through the -encoding
argument. Note that encoding is not supported by Jikes. The default is UTF-8. This parameter requires
regeneration of Java source.
v jspCompileClasspath
This parameter tells the JSP engine to use a small class path for the Java compilation phase. The small
class path speeds up the compilation process. This small class path is not used by default because it
includes only a subset of WebSphere JAR files and excludes many WebSphere JAR files that contain
WebSphere public APIs.
If your JSP files do not use WebSphere public APIs within scriptlets, you can enable the small class
path by using the jspCompileClasspath parameter with no value. If your JSP files do use WebSphere
public APIs within scriptlets, then add those additional JAR files to the jspCompileClasspath option. The
entries are separated by spaces, and are assumed to be relative to the WebSphere Application Server
installation root.
1. A space-separated list of JAR files, relative to the WebSphere installation directory. This instructs the
JSP engine to use the small class path, with the additional named JAR files.
2. No value at all. This instructs the JSP engine to use the small class path, without any additional
user-defined JAR files. See the example in ″Configuring JSP engine parameters″ in the information
center.
The entire WebSphere class path is used by default. This parameter requires regeneration of Java
source.
v jsp.file.extensions
For JSP files with extensions other than the four standard extensions, *.jsp, *.jspx, *.jsw, and *.jsv, you
can configure this the extensions using this parameter. These extensions are added to the standard
extensions. The preferred method for doing this is to create a <jsp-property-group>in web.xml, and
add a <url-pattern> tag for each extension.
The JSP engine can handle a list of file extensions that is separated by a colon or semi-colon. For
example, *.ext1;*.ext2:*.extn
v keepgenerated
Indicates that the Java files generated by the JSP compiler during the translation phase of the
processing are retained. The default for this parameter is false. This parameter requires regeneration of
Java source.
v keepGeneratedclassfiles
Indicates that the class files generated by the JSP compiler during the translation phase of the
processing are retained. The default for this parameter is true. This parameter requires regeneration of
Java source.
v reloadEnabled
Determines whether or not a JSP file is translated and compiled at runtime if the JSP file or its
dependencies (see trackDependencies) are modified. If reloadEnabled is false, a JSP file is still
compiled, if necessary, on the first request to it unless the parameter disableJspRuntimeCompilation is
true. The default for this parameter is false.

Chapter 8. Developing WebSphere applications 947

 If this JSP engine parameter is not specified, the equivalent Web container parameter for Web module
class reloading is used. However, for an application whose deployment descriptor is at the Servlet 2.2
level, the default is true. This is done for the support of applications being migrated from WebSphere
Application Server Version 4.x.
v reloadInterval
If reloading is enabled, reloadInterval determines the delay between checks to see if a JSP file is
outdated. For example, if reloadInterval is 5, the JSP engine checks to see if a JSP file is outdated only
when the last such check was done more than 5 seconds prior to the current request for the JSP file.
The larger the reloadInterval, the less frequently the JSP engine checks for the need to reload a JSP
file. If this JSP engine parameter is not specified, the equivalent Web container parameter for Web
module class reloading is used. However, for an application whose deployment descriptor is at the
Servlet 2.2 level, the default is 5 seconds. This is done for the support of applications being migrated
from WebSphere Application Server Version 4.x.
v scratchdir
Specifies the directory where the generated class files are created. The system property
com.ibm.websphere.servlet.temp.dir is used to set the scratchdir option on a server-wide basis. The
JSP engine scratchdir parameter takes precedence over the system property
com.ibm.websphere.servlet.temp.dir. The default for this parameter is
{WAS_ROOT}/profiles/profilename/temp. This parameter requires regeneration of Java source.
v trackDependencies
If reloading is enabled, trackDependencies determines whether the JSP engine tracks modifications to
the requested JavaServer Pages files dependencies as well as to the JSP file itself. The dependencies
tracked by the JSP engine are :
1. files statically included in the JSP file
2. tag files referenced in the JSP file (excluding tag files that are in JARs)
3. TLD files referenced in the JSP file (excluding TLDs that are in JARs)
The default is false.
v useFullPackageNames
If useFullPackageNames is true, the JSP engine generates and loads JSP classes using full package
names. The default is to generate all JSP classes in the same package. (For more information, see
Packages and directories for generated files). The JSP engine’s class loader knows how to load JSP
classes when they are all in the same package.
The default method of generating all JSP classes in the same package has the benefit of generating
smaller file-system paths. Full package names has the benefit of enabling the configuration of
precompiled JSP class files as servlets in the web.xml file without the use of the jsp-file attribute,
resulting in a single class loader, the Web application’s class loader, that is used to load all such JSP
classes. Similarly, when the JSP engine’s configuration attributes useFullPackageNames and
disableJspRuntimeCompilation are both true, a single class loader is used to load all JSP classes, even
if the JSP files are not configured as servlets in the web.xml file.
When useFullPackageNames is set to true, the batch compiler generates a file called
generated_web.xml in the Web module’s WEB-INF directory. This file contains servlet configuration
information for each JSP file that was successfully translated and compiled. The information can
optionally be copied into the Web module’s web.xml file so that the JSP files are loaded as servlets by
the Web container. Note that if a JSP file is configured as a servlet in this way, no reloading of the JSP
file is done at runtime if the JSP file is modified. This is because the JSP file is treated as a regular
servlet and requests for it do not pass through the JSP engine. This parameter requires regeneration of
Java source.
v useImplicitTagLibs
The JSP engine implicitly recognizes tsx and jsx as tag library prefixes for tag libraries supplied by the
JSP engine. If tsx or jsx are used as prefixes for a customer‘s tag library, the customer‘s tag library
overrides the implicit tag library. However, the implicit tag library is still cached by the JSP engine.
Explicitly setting this parameter to false tells the engine not to cache the implicit tag library, and save
resources. The default for this parameter is true.
v useJikes

948 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Specifies whether Jikes is used for compiling Java sources. NOTE: Jikes is not shipped with
WebSphere Application Server. The default for this parameter is false. This parameter requires
regeneration of Java source.
v usePageTagPool
*Enables or disables the reuse of custom tag handlers on an individual JavaServer Pages basis. The
default for this parameter is false. This parameter requires regeneration of Java source.
v useThreadTagPool
*When thread-level tag handler pooling is used, tag handlers may be reused among separate
occurrences of a custom action across all JSP pages in a single Web module across separate requests.
The default for this parameter is false. This parameter requires regeneration of Java source.
v verbose
Indicates that the compiler generates verbose output when compiling the generated Java source code.
The effect of setting this parameter to true is that the -verbose option is passed to the Java compiler.
The default for this parameter is false. This parameter requires regeneration of Java source.

*Enabling custom tag handler reuse might reveal problems in the tag handler code with regard to the tag’s
ability to be reused. A custom tag handler should always do two things:
v The release method of the tag handler should reset its state and release any private resources that it
might have used. The JSP engine ensures the release method is called before the tag handler is
garbage collected.
v In the doEndTag method, all instance states associated with this instance must be reset.

JSP class file generation: At runtime, the WebSphere Application Server JavaServer Pages (JSP)
engine loads JSP class files from either the WebSphere Application Server temp directory or a Web
module’s WEB-INF/classes directory. The WebSphere Application Server temp directory is typically
{WAS_ROOT}/profiles/profilename/temp. The JSP engine first searches for a class file in the temp
directory and then it searches in the Web module’s WEB-INF/classes directory. Figure 1 shows the
processing logic of the JSP engine at runtime.

Request for a JSP.

Is the class file found in No

Is the class file found in No
WebSphere Application Server
temp directory? WEB-INF/classes

Yes
Yes

No
Is the class file outdated?

Yes

Yes

Generate the class file

into WebSphere
Application Server Load the class file.
temp directory.

Chapter 8. Developing WebSphere applications 949

The batch compiler supports the generation of class files in both the WebSphere Application Server temp
directory and a Web module’s WEB-INF/classes directory, depending on the type of batch compiler target.
In addition, the batch compiler enables the generation of class files into any directory on the filesystem,
outside of the target application. Generating class files into a Web module’s WEB-INF/classes directory
enables you to deploy the Web module as a self-contained Web archive (WAR) file, or a WAR file inside
an enterprise archive (EAR) file. The following table shows the batch compiler’s behavior when compiling
class files.

ear.path or war.path supplied enterpriseApp.name supplied

compileToDir not supplied; The class files are compiled into the The class files are compiled into the Web
compileToWebInf not Web module’s WEB-INF/classes module’s WEB-INF/classes directory.
supplied, or is true directory.
compileToDir not supplied; The class files are compiled into the The class files are compiled into the
compileToWebInf is false Web module’s WEB-INF/classes WebSphere temp directory, usually
directory. {WAS_ROOT}/profiles/profilename/temp.
compileToDir is supplied; The class files are compiled into the The class files are compiled into the directory
compileToWebInf not directory indicated by compileToDir. indicated by compileToDir.
supplied, or is either true or
false

Packages and directories for generated .java and .class files:

By default, the .java files for all JavaServer Pages (JSP) files are generated with the package statement,
package com.ibm._jsp;. The JSP engine’s class loader knows how to load JSP classes when they are all
in the same package. The .java files are located in the filesystem within a directory structure mirroring the
JSP source directory structure.

If the JSP engine configuration parameter useFullPackageNames is set to true, the .java files are
generated with the package statement
Package _ibmjsp.<directory structure in which the jsp is located>;

The usage of full package names enables the configuration of a JSP as a servlet in the web.xml file. See
“JSP class loading” on page 952 for more information. The table below gives examples of packages and
directory structures for generated .java and .class files.

Java package Location of .java or .class files in file

system
JSP file default useFullPackage default useFullPackage
Names=true Names=true
/myJsp.jsp com.ibm._jsp _ibmjsp / /_ibmjsp
/jspFiles/jspOne.jsp com.ibm._jsp _ibmjsp.jspFiles /jspFiles /_ibmjsp/jspFiles
/dir with com.ibm._jsp _ibmjsp.dir_20_with /dir with spaces /_ibmjsp/dir_20_with
spaces/jspTwo.jsp _20_spaces _20_spaces

Generated .java files: When the JSP engine‘s keepgenerated configuration parameter is set to true, the
.java file that is generated for JavaServer Pages (JSP) is retained. This file contains information that is
useful in debugging.

Dependency information

In the .java file, immediately following the class declaration, an array of dependent files is defined, if the
source JSP has any dependencies. There are three types of files that are tracked as dependencies:
1. Files that are statically included in the JSP

950 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Tag files that are used by the JSP, but only tag files that are not in Java Archive (JAR) files
3. TLD files that are used by the JSP, but only TLDs that are not in JAR files

This array is always generated, but the JSP engine uses it, in determining whether a JSP needs to be
recompiled, only when the trackDependencies parameter is set to true.

In the example below, three JSP fragments, one TLD and one tag file are dependencies of the JSP
jsp1.jsp. There are three parts to each array entry:
1. The path to the dependency, relative to the Web module‘s context root. For example:
/dir1/frag1.jspf
2. The long value representing the time the file was last modified. For example: 1082407108000
3. The String representation of the long value. For example: Mon Apr 19 16:38:28 EDT 2004
public final class _jsp1 extends com.ibm.ws.jsp.runtime.HttpJspBase
implements com.ibm.ws.jsp.runtime.JspClassInformation {

private static String[] _jspx_dependants;

static {
_jspx_dependants = new String[5];
_jspx_dependants[0] = "/Banner.jspf^1082407108000^Mon Apr 19 16:38:28 EDT 2004";
_jspx_dependants[1] = "/Footer.jspf^1077657462000^Tue Feb 24 16:17:42 EST 2004";
_jspx_dependants[2] = "/dir1/frag1.jspf^1035396680000^Wed Oct 23 14:11:20 EDT 2002";
_jspx_dependants[3] = "/utility.tld^1080069938000^Tue Mar 23 14:25:38 EST 2004";
_jspx_dependants[4] = "/WEB-INF/tags/top.tag^1065440490000^Mon Oct 06 07:41:30 EDT 2003";
}

Version, JSP engine options, and WEB.XML information

The generated .java source contains a comment that lists information about the file which is located at the
bottom of the generated file. This information includes:
v The date and time the .java file was generated
v The version, build number and build date of the WebSphere Application Server on which the .java file
was generated
v The values of the JSP engine configuration parameters that were in effect when the file was generated
v The values of any <jsp-config> elements in the web.xml file that pertained to the source JSP file.
/*
C:/WebSphere_6.0/AppServer/profiles/AppSrv01/installedApps/MyCell/sampleApp.ear/examples.war
/WEB-INF/classes/_ibmjsp/_jsp1.java was generated @ Thu Oct 14 10:05:56 EDT 2004
IBM WebSphere Application Server - ND, 6.0.0.0
Build Number: o0441.04
Build Date: 10/12/04

********************************************************
The JSP engine configuration parameters were set as follows:

classDebugInfo = [false]
debugEnabled = [false]
deprecation = [false]
compileWithAssert = [false]
disableJspRuntimeCompilation =[false]
extendedDocumentRoot = [null]
ieClassId = [clsid:8AD9C840-044E-11D1-B3E9-00805F499D93]
keepGenerated = [true]
outputDir = [C:/WebSphere_6.0/AppServer/profiles/AppSrv01/
installedApps/MyCell/sampleApp.ear/examples.war/WEB-INF/classes]
reloadEnabled = [true]
reloadEnabledSet = [true]
reloadInterval = [5000]
trackDependencies = [false]
usePageTagPool = [false]
useThreadTagPool = [true]

Chapter 8. Developing WebSphere applications 951

useImplicitTagLibs = [true]
verbose = [false]
looseLibMap = [null]
useJikes = [false]
useFullPackageNames = [true]
translationContextClass = [null]
extensionProcessorClass = [null]
jspCompileClasspath = []
javaEncoding = [UTF-8]
autoResponseEncoding = [false]

********************************************************
The following JSP Configuration Parameters were obtained from web.xml:

prelude list = [[]]

coda list = [[]]
elIgnored = [false]
pageEncoding = [null]
isXML = [false]
scriptingInvalid = [false]
*/

JSP class loading:

You can configure a JavaServer Pages (JSP) class to be loaded by either the JSP engine‘s class loader or
by the Web module‘s class loader.

By default, a JSP class is loaded by a unique instance of the JSP engine‘s class loader. The JSP engine‘s
class loader enables runtime reloading of a JSP class when the JSP source or one of its dependents is
modified. This allows you to reload a single JSP class when necessary, without affecting any other loaded
JSP classes.

JSP classes are loaded by the Web module‘s class loader under either of the following scenarios.
1. 1. The JSP engine configuration parameter useFullPackageNames is set to true, and the JSP file is
configured as a servlet in the web.xml file using the <servlet-class> scenario in the table below.
2. 2. The JSP engine configuration parameters useFullPackageNames and
disableJspRuntimeCompilation are both set to true. In this case, you do not need to configure a JSP
file does as a servlet in the web.xml file.

Configuring JSP files as Servlets

You can configure a JSP file as a servlet in the web.xml file. There are two ways to do this. They are
described in the table below.

Before you configure a JSP file as a servlet, consider the following.

1. Reloading capability - If runtime reloading of JavaServer Pages files is desired, requests for
JavaServer Pages files must be handled by the JSP engine. The <servlet-class> scenario in the table
below disables runtime JSP file reloading, while the <jsp-file> scenario is compatible with reloading.
2. Reducing the number of class loaders - If you do not require runtime reloading of modified JSP pages
and you want to reduce the number of class loader instances, then you can use the <servlet-class>
scenario in the table below. Similarly, scenario 2 in section 1 above can be used without having to
configure a JSP file as a servlet.

Scenario Example compatible with multiple class useFullPackage

runtime loaders used? Names
reloading

952 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
<jsp-file> <servlet> Yes Yes Can be true or
false
<servlet-name>jspOne</servlet-name>

<jsp-file>jspOne.jsp</jsp-file>

</servlet>
<servlet-class> <servlet> No No Must be true

<servlet-name>jspTwo</servlet-name>

<servlet-class>_ibmjsp.jspTwo</servlet-
class>

</servlet>

The JSP batch compiler tool helps you configure JavaServer Pages files as servlets. When
useFullPackageNames is true, the JSP batch compiler generates <servlet> and <servlet-mapping>
elements for each JSP file that it successfully translates and compiles. The elements are written to a
web.xml fragment file named generated_web.xml which is located in the binaries WEB-INF directory of a
Web module processed by the JSP file batch compiler (this directory is located within the deployed
application‘s ear file). You can copy and paste all or some of these elements into the web.xml file to
configure JavaServer Pages files as servlets.

Take note of the location of the web.xml that is used by the application server. In WebSphere Application
Server 6.0, application specific configuration is obtained from either the application binaries (the
application‘s ear file) or from the configuration repository. If an application is deployed into WebSphere
Application Server with the flag Use Binary Configuration set to true, then the WEB-INF/web.xml file is
looked for in a Web module’s binaries directory, not in the configuration repository. Below are examples of
these two locations.
1. An example of a configuration repository directory is
{WAS_ROOT}/profiles/profilename/config/cells/cellname/applications/enterpriseappname
/deployments/deployedname/webmodulename
2. An example of an application binaries directory is:
{WAS_ROOT}/profiles/profilename/installedApps/nodename/EnterpriseAppName/WebModuleName/

If the JSP batch compiler is executed on a pre-deployed application then the web.xml file is in the Web
module‘s WEB-INF directory.

Configuring JSP runtime reloading: JSP files can be translated and compiled at runtime when the JSP
file or its dependencies are modified. This is known as JSP reloading. JSP reloading is enabled through
the reloadEnabled JSP engine parameter in the WEB-INF/ibm-web-ext.xmi file:
<jspAttributes xmi:id="JSPAttribute_1" name="reloadEnabled" value="true"/>

The following table contains the recommended reload settings for production and development
environments.

Recommended settings
Configuration Attribute Production Environment Development Environment
reloadEnabled false true
reloadInterval n/a (ignored if reloadEnabled is approximately 5 seconds
false)
trackDependencies n/a (ignored if reloadEnabled is true Alternatively, set this to false to
false) improve response time if
dependencies are not changing

Chapter 8. Developing WebSphere applications 953

disableJspRuntimeCompilation true - Alternatively, set this to false if false
JSPs are not pre-compiled and
therefore need to be compiled on
the first request.

If the reloadEnabled parameter is set to true, a JSP file is reloaded at runtime if the JSP file and its class
file do not have the same timestamp. In addition, if trackDependencies is set to true then the JSP file is
reloaded if the timestamp of any of its dependencies has changed since the JSP class file was last
generated. If the reloadEnabled parameter is set to false, a JSP file is still compiled if necessary on the
first request to it unless the parameter disableJspRuntimeCompilation is true. For example, when
disableJspRuntimeCompilation is false and reloadEnabled is false, a JSP file is compiled on the first
request if the class file is outdated. It would not compiled on subsequent requests even if the JSP source
file is modified or the class file is deleted unless reloadEnabled is true

Reload interval

The reload interval is set through the reloadInterval JSP engine parameter:
<jspAttributes xmi:id="JSPAttribute_1" name="reloadInterval" value="5"/>

If reloading is enabled, the reloadInterval parameter value determines the delay between checks to see if
a JSP file is outdated. For example, if reloadInterval is 5, the JSP engine checks to see if a JSP file is
outdated only when the last such check was done more than five seconds prior to the current request for
the JSP file. Once the reloadInterval is exceeded, reload checking is performed and the reload interval
timer is reset to 0 for that JSP file. The larger the reloadInterval, the less frequently the JSP engine
checks for the need to reload a JSP file.

Dependency tracking

Dependency tracking is set through the trackDependencies JSP engine parameter:

<jspAttributes xmi:id="JSPAttribute_1" name="trackDependencies" value="true"/>

If reloading is enabled, the trackDependencies parameter value determines whether the JSP engine
tracks modifications to the requested JSP file dependencies as well as to the JSP file itself. The three
types of dependencies tracked by the JSP engine are:
v files statically included in the JSP file
v tag files that are referenced in the JSP file (excluding tag files that are in JAR files)
v TLDs that are referenced in the JSP file (excluding TLDs that are in JAR files)

Dependency tracking information is always included in the generated class file even if trackDependencies
is false. The information is not used by the JSP engine or batch compiler unless the trackDependencies
parameter is true. This means that you can enable dependency tracking without having to recompile JSP
files.

For example, the toplevel.jsp file statically includes the footer.jspf file. When the toplevel.jsp file is
compiled, the path to the footer.jspf file and its timestamp are stored in the toplevel.jsp’s class file. As
a result, the footer.jspf file is modified and the toplevel.jsp file is requested. Now that the reload
interval for the toplevel.jsp file has been exceeded, the JSP engine compares the timestamp stored in
the class file with the footer.jspf file timestamp on disk. Because the timestamps are different, the
toplevel.jsp file is compiled, picking up the modification to the footer.jspf file. In order for dependency
tracking to work, the trackDependencies value must be set to true at the time a JSP file is requested at
runtime or is processed by the batch compiler.

954 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Disabling compilation

Disablement of runtime compilation of JavaServer Pages is set via the disableJspRuntimeCompilation JSP
engine parameter:
<jspAttributes xmi:id="JSPAttribute_1" name="disableJspRuntimeCompilation" value="true"/>

If the disableJspRuntimeCompilation parameter is set to true, the JSP engine at runtime does not
translate and compile JSP files; the JSP engine loads only precompiled class files. JSP source files do not
need to be present in order for the class files to be loaded. With this option set to true, an application can
be installed without JSP source, but must have precompiled class files. There is a Web container custom
property of the same name that can be used to determine the behavior of all web modules installed in a
server. If both the Web container custom property and the JSP engine option are set, the JSP engine
option takes precedence. Setting the disableJspRuntimeCompilation parameter to true automatically
sets reloadEnabled to false.

Reload processing sequence

The processing sequence pertaining to JSP file reloading when trackDependencies is false is shown in
Figure 1.

Request for a JSP.

disable
Yes Yes
JspRuntime Attempt to
Classfile exists?
Compilation? load classfile

No
No
Return error
to browser
Yes
First request to
this JSP?

No

Yes Yes Is JSP Yes

Is reloadedInterval Translate and
Is reloadEnabled? classfile
exceeded? compile JSP
outdated?

No No No

Successful
translation
and
compilation?

No

Attempt to load Return error

classfile to browser

Figure 6. Reload processing sequence when trackDependencies is false.

When trackDependencies is true, the JSP engine does additional file system processing to determine if
any of a JSP file’s dependencies have changed since the JSP file was last translated and compiled.

Chapter 8. Developing WebSphere applications 955

Figure 2 shows the additional processes that are performed on the ’No’ path of flow chart labeled ″is JSP
class file outdated?″. You can see that the path taken when disableJspRuntimeCompilation is true is the
most efficient path.

Is JSP Yes
classfile
outdated?

No

Has any
dependent Yes Translate and
file been compile JSP
modified?

No

Attempt to load
classfile

Figure 7. Additional reload processing performed when trackDependencies is true.

Disabling JavaServer Pages run-time compilation: By default, the JavaServer Pages (JSP) engine
translates a requested JSP file, compiles the .java file, and loads the compiled servlet into the run-time
environment. You can change the JSP engine default behaviour by indicating a JSP file should never be
translated or compiled at run-time, even when a .class file does not exist.

If run-time compilation is disabled, you must precompile the JSP files, which provides the following
advantages:
v Reduces compilation related disk operations.
v Minimizes disk storage requirements necessary for handling temporary .java files generated during a
run-time compilation.
v Allows you to not include the JSP source files in the application.
v Allows verification that a JSP file compiled successfully before deploying and installing the application in
WebSphere Application Server.

You can disable run-time JSP file compilation on a global or an individual Web application basis:
v To disable the translation and compilation of JSP files for all Web applications, set the Web container
custom property disableJspRuntimeCompilation to true.
Set this property through the Web container Custom properties panel in the administrative console. To
view this administrative console page, click:
Servers > Application servers > server_name > Web container settings >
Web container > Custom properties > property_name
Valid values for this setting are true or false. If this property is set to true, then translation and
compilation of the JSP files is disabled at run time for all Web applications.
v To disable the translation and compilation of JSP files for a specific Web application, set the JSP engine
initialization parameter disableJspRuntimeCompilation to true. This setting, if enabled, determines the
run-time behavior of the JSP engine and overrides the Web container custom property setting.
Set this parameter through the JavaServer Pages attribute assembly settings panel as described in
the ″Assembling applications″ topic in the information center.
Valid values for this setting are true or false. If this parameter is set to true, then, for that specific Web
application, translation and compilation of the JSP files is disabled at run time, and the JSP engine only
loads precompiled files.

956 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v If neither the Web container custom property nor the JSP parameter is set, the first request for a JSP
file results in the translation and compilation of the JSP file when the .class file does not exist or is
outdated. Subsequent requests for the file also result in translations and compilations, but only if the
following conditions are met:
– Translations are required because the .class file is outdated.
– Reloading is enabled for the Web module.
– Reload interval is exceeded.

If you disable run-time compilation and a request arrives for a JSP file that does not have a matching
.class file, the JSP engine returns HTTP error 500 (Internal server error) to the browser. In this case, an
exception is written to the System Out (SYSOUT) and First Failure Data Capture (FFDC) logs.

If a JSP file has a matching .class file but that file is out of date, the JSP engine still loads the .class file
into memory.

JSP batch compilation:

As an IBM enhancement to JavaServer Pages (JSP) support, IBM WebSphere Application Server provides
a batch JSP compiler that allows JSP page compilation before application deployment. The batch compiler
validates the syntax of JSP pages, translates the JSP pages into Java source files, and compiles the Java
source files into Java Servlet class files. The batch compiler also validates tag files and generates their
Java implementation classes.

Batch compilation of JSP pages in a predeployed application simplifies the deployment process and
improves the runtime performance of JSP page by eliminating first-request compilations. The batch
compiler also operates on enterprise applications that have been deployed into WebSphere Application
Server.

The JSP batch compiler works on Web modules that support Servlet 2.2 and up through Servlet 2.4 The
batch compiler works on JSP pages written to the JSP 2.0 specification or previous specifications back to
JSP 1.0. It recognizes a Servlet 2.4 deployment descriptor, web.xml, and can use any jsp-config elements
that it may contain. In a Servlet 2.3 (JSP 1.2) or Servlet 2.2 (JSP 1.1) deployment descriptor the batch
compiler recognizes and uses any taglib elements that the descriptor may contain.

Batch compiling makes the first request for a JSP page much faster because the JSP page is already
translated and compiled into a servlet. Batch compiling is also useful as a fast way to resynchronize all of
the JSP pages for an application.

The batch compiler supports the generation of class files in both the WebSphere Application Server temp
directory and a Web module’s WEB-INF/classes directory, depending on the type of batch compiler target.
In addition, the batch compiler enables generation of class files into any directory on the filesystem,
outside the target application. Generating class files into a Web module’s WEB-INF/classes directory
enables the Web module to be deployed as a self-contained WAR file, or a WAR inside an EAR.

JSP batch compiler tool: The batch compiler validates the syntax of JSP pages, translates the JSP pages
into Java source files, and compiles the Java source files into Java Servlet class files. The batch compiler
also validates tag files and generates their Java implementation classes. Use this function to batch
compile your JSP files and thereby enable faster responses to the initial client requests for the JSP files
on your production Web server.

The batch compiler can be executed against compressed or expanded enterprise archive (EAR) files and
Web application archive (WAR) files, as well as enterprise applications and Web modules that have been
deployed into WebSphere Application Server. When the target is a deployed enterprise application, the
server does not need to be running to execute the batch compiler. If the batch compiler is executed while

Chapter 8. Developing WebSphere applications 957

the target sever is running, the server is not aware of an updated class file and does not load that class
file unless the enterprise application is restarted. When the target is a compressed EAR file or WAR file,
the batch compiler must expand it before executing.

Processing of Web modules

The batch compiler operates on one Web module at a time. If the target is either an EAR file or an
installed enterprise application that contains more than one Web module, the batch compiler operates on
each Web module individually. This is done because JSP pages are configured on a Web module basis,
through the Web module’s web.xml deployment descriptor file. Within a Web module, the batch compiler
processes one directory at a time. It validates and translates each JSP page individually, and then invokes
the Java compiler for the entire group of generated Java sources files in that directory. If one JSP page
fails during the Java compilation phase, the Java compiler might not create class files for most or all of the
JSP pages that successfully compiled in that directory.

JSP file extensions

The batch compiler uses four things to determine what file extensions it should process:
1. Standard JSP file extensions
v *.jsp
v *.jspx
v *.jsw
v *.jsv
2. The url-pattern property of the jsp-property-group elements in the deployment descriptor file in Servlet
2.4 Web modules
3. The jsp.file.extensions JSP engine configuration parameter (for pre-Servlet 2.4 Web modules)
4. The batch compiler configuration parameter jsp.file.extensions

The standard extensions are always used by the batch compiler. If the Web module contains a Servlet 2.4
deployment descriptor, the batch compiler also processes any url-patterns found within the jsp-config
element. If the batch compiler target contains the JSP engine configuration parameter jsp.file.extensions,
then those extensions are also processed. If the batch compiler configuration parameter
jsp.file.extensions is present, the extensions given are also processed and will override the JSP engine
configuration parameter jsp.file.extensions.

It is a good idea to give JSP ’fragments’ an extension that is not processed by the batch compiler.
Statically-included fragments that do not stand alone generate translation or compilation errors if
processed. The JSP 2.0 Specification suggests that you use the extension .jspf for such files.

Batch compiler command

Both a Windows batch file, JspBatchCompiler.bat and Unix shell script JspBatchCompiler.sh for running
the batch compiler from the command line are found in the {WAS_ROOT}/bin directory. An Ant task
(described in the topic Batch Compiler Ant Task) is also available for executing the batch compiler using
Ant.

The batch compiler target is the only required parameter. The target is one of -ear.path, -war.path or
-enterpriseapp.name.
JspBatchCompiler -ear.path | -war.path | -enterpriseapp.name <name>
[-response.file <filename>]
[-webmodule.name <name>]
[-filename <jsp name | directory name>
[-recurse <true | false>]
[-config.root <path>]
[-cell.name <name>]

958 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 [-node.name <name>]
[-server.name <name>]
[-profileName <name>]
[-extractToDir <path>]
[-compileToDir <path>]
[-compileToWebInf <true | false>]
[-translate <true | false>]
[-compile <true | false>]
[-removeTempDir <true | false>]
[-forceCompilation <true | false>]
[-useFullPackageNames <true | false>]
[-trackDependencies <true | false>]
[-createDebugClassfiles <true | false>]
[-keepgenerated <true | false>]
[-keepGeneratedclassfiles <true | false>]
[-usePageTagPool <true | false>]
[-useThreadTagPool <true | false>]
[-classloader.parentFirst <true | false>]
[-classloader.singleWarClassloader <true | false>]
[-additional.classpath <classpath to additional JAR files and classes>]
[-jspCompileClasspath <classpath to Websphere Application Server public API JAR files;
or no value at all>]
[-verbose <true | false>]
[-deprecation <true | false>]
[-javaEncoding <encoding>
[-compileWithAssert <true | false>]
[-compilerOptions <space-separated list of java compiler options>]
[-useJikes <true | false>]
[-jsp.file.extensions <file extensions to process>]
[-log.level <SEVERE | WARNING | INFO | CONFIG | FINE | FINER | FINEST | OFF>]

**See batchcompiler.properties.default in {WAS_ROOT}/bin for more information.**

**See JspCBuild.xml in {WAS_ROOT}/bin for information about the public WebSphere Ant task JspC.**

The batch compiler is aware of three groups of configuration parameters:

1. JSP engine configuration parameters for a Web module.
See the topic, “JSP engine configuration parameters” on page 946.
2. Batch compiler response file configuration parameters.
These are the parameters that are found in a batch compiler response file. See -response.file, below.
3. Batch compiler command line configuration parameters.
These are the parameters entered on the command line when running the batch compiler.

The batch compiler looks at all three groups of configuration parameters in order to determine which value
for a parameter is used when compiling JSP pages. When resolving the value for a given parameter, the
precedence is:
1. If the parameter is found on the command line, its value is used.
2. If the parameter is not found on the command line, the batch compiler looks for the parameter in a
response file named on the command line.
3. If no response file is named, or if the parameter is not found therein, the batch compiler looks for the
parameter in the Web module’s JSP engine configuration parameters.

If a configuration parameter is not found among these three groups, then a default value is used. The
default values for the configuration parameters are given below along with the description of the
parameters.

With one exception, these parameters are not case sensitive; -profileName is case sensitive. If the values
specified for these arguments are comprised of two or more words separated by spaces, you must add
quotation marks around the values.

Chapter 8. Developing WebSphere applications 959

The batch compiler does not create, or set the values of, equivalent JSP engine parameters. This means
that if a JSP page in a deployed Web module is modified and is recompiled by the JSP engine at runtime,
the JSP engine’s configuration parameters will determine the engine’s behavior. For example, if you use
the batch compiler to compile a Web module and you use the -useFullPackageNames true option, the JSP
files will be compiled to support that option. But the JSP engine parameter useFullPackageNames must
also be set to true in order for the JSP Runtime to be able to load the compiled JSP pages. If JSP pages
are modified in a deployed Web module, then the engine’s parameters should be set to the same values
used in batch compilation.

To use the JSP batch compiler, enter the following command on a single line at an operating system
command prompt:

where:
v ear.path | war.path | enterpriseapp.name
Represents the full path to a single compressed or expanded enterprise application archive (EAR) file or
Web application archive (WAR) file, or the name of the deployed enterprise application that you want to
compile. For example:
– JspBatchCompiler -ear.path c:\myproject\sampleApp.ear
– JspBatchCompiler -war.path c:\myWars\examples.war
– JspBatchCompiler -enterpriseapp.name myEnterpriseApp -webmodule.name my.war -filename
/aDir/main.jsp
v response.file
Specifies the path to a file that contains configuration parameters used by the batch compiler. The
response.file is used only if it is given on the command-line; it is ignored if it is present in a response
file. A template response file, batchcompiler.properties.default, is found in {WAS_ROOT}/bin. Copy this
template to create your own response files containing defaults for the parameters in which you are
interested. All the required and optional parameters (except response.file) can be configured in a
response file.
Example: JspBatchCompiler -response.file c:\myproject\batchc.props
Default : null
v webmodule.name
Represents the name of the specific Web module that you want to batch compile. If this argument is not
set, all Web modules in the enterprise application are compiled. This parameter is used only when
ear.path or enterpriseapp.name is given. This parameter is useful when JSP pages in a specific Web
module within a deployed enterprise application need to be regenerated, because all Shared Library
dependencies will be picked up.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -webmodule.name myWebModule.war
Default: All Web modules in an EAR file or enterprise application are compiled if this parameter is not
given.
v filename
Represents the name of a single JSP file that you want to compile. If this argument is not set, all files in
the Web module are compiled. Alternatively, if filename is set to the name of a directory, only the JSP
files in that directory and that directory’s child directories are complied. The name is relative to the
context root of the Web module.
Example 1: If you want to compile the file, myTest.jsp, and it is found in /subdir/myJSPs, you would
enter -filename /subdir/myJSPs/myTest.jsp.
Example 2: If you want to compile all JSP files in /subdir/myJSPs and its child directories, you would
enter -filename subdir/myJSPs.
Default: All JSP files in the Web module are compiled. Entering -filename / is equivalent to the
default.
v recurse

960 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Determines whether subdirectories beneath the target directory are processed. This parameter is used
only when the filename parameter is given. Set value to false to process only the directory named
filename parameter; and not its subdirectories.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -filename /subdir1 -recurse false.
Default: true; All directories beneath the target directory are processed.
v config.root
Specifies the location of the WebSpehere Application Server configuration directory. This parameter is
used only when enterpriseapp.name is given.
Default: {WAS_ROOT}/profiles/profilename/config
v cell.name
Specifies the name of the cell in which the application is deployed. This parameter is used only when
enterpriseapp.name is given.
Default: The default is obtained from the profile script that is used. The symbolic name of this variable
is WAS_CELL.
v node.name
Specifies the name of the node in which the application is deployed. This parameter is used only when
enterpriseapp.name is given.
Default: The default is obtained from the profile script that is used. The symbolic name of this variable
is WAS_NODE.
v server.name
Represents the name of the server in which the application is deployed. This parameter is used only
when enterpriseapp.name is given.
Default: server1
v profileName
Specifies the name of the profile you want to use. This parameter is used only when
enterpriseapp.name is given.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -profileName AppServer-3
Default: The default profile is used. This is obtained from the file setupCmdLine.[bat/sh] in
{WAS_ROOT}/bin. The symbolic name is DEFAULT_PROFILE_SCRIPT.
v extractToDir
Specifies the directory into which predeployed enterprise archive (EAR) files and Web application
archive (WAR) files will be extracted before the batch compiler operates on them. This parameter is
ignored when enterpriseapp.name is given. The extractToDir parameter is used as described in the
table below.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -extractToDir c:\myTempDir.
Use-case: You must extract a compressed archive before it is batch compiled. You can also extract an
expanded archive to a new directory as well. In both cases, extraction leaves the original archive
untouched, which may be useful while development is underway.
Default values:

Expanded archive Compressed archive

extractToDir supplied The batch compiler extracts the archive to extractToDir before operating on it. If a
file or directory of the same name as the archive already exists in the extractToDir,
the batch compiler removes the archive completely before extracting that archive. If
the batch compiler exits with no errors, it compresses the archive in place in the
extractToDir, even if the original EAR file or WAR file was expanded. If errors are
encountered during compilation, the EAR file or WAR file is left in the expanded
state even if the original EAR file or WAR file was compressed.

Chapter 8. Developing WebSphere applications 961

extractToDir not supplied The batch compiler operates on the EAR The batch compiler extracts the archive
file or WAR file in place (does not extract to the directory returned by the JVM
it to another directory) and the archive property ″java.io.tmpdir″. The rest of the
remains expanded after the batch behavior described above, when
compiler finishes. extractToDir is supplied, is the same in
this case.

The default is server1.

v compileToDir
Specifies the directory into which JSP pages are translated into Java source files and compiled into
class files. This directory can be anywhere on the filesystem, but the batch compiler’s default behavior
is usually adequate. The batch compiler’s behavior when compiling class files is described in the table
below
Example:: JspBatchCompiler -enterpriseApp.name sampleApp -compileToDir c:\myTargetDir
Use-case: This parameter enables you to generate the Java and class files into a directory outside of
the target, which may be useful if you want to compare the newly generated files with their previous
versions which remain untouched within the target.
Default values:

ear.path or war.path supplied enterpriseApp.name supplied

compileToDir not supplied; The class files are compiled into the The class files are compiled into the
compileToWebInf not supplied, or is Web module’s WEB-INF/classes Web module’s WEB-INF/classes
true directory directory.
compileToDir not supplied; The class files are compiled into the The class files are compiled into the
compileToWebInf is false Web module’s WEB-INF/classes WebSphere temp directory (usually
directory. {WAS_ROOT}/temp).
compileToDir is supplied; The class files are compiled into the The class files are compiled into the
compileToWebInf not supplied, or is directory indicated by compileToDir. directory indicated by compileToDir.
either true or false

v compileToWebInf
Specifies whether the target directory for the compiled JSP class files should be the Web module’s
WEB-INF/classes directory. This parameter is used only when enterpriseApp.name is given, and it is
overridden by compileToDir if compileToDir is given.
The batch compiler’s default behavior is to compile to the Web module’s WEB-INF/classes directory. The
batch compiler’s behavior when compiling class files is described in the table above.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -compileToWebInf false.
Use-case: Set this parameter to false when enterpriseApp.name is supplied and you want the class
files to be compiled to the WebSphere Application Server temp directory instead of the Web module’s
WEB-INF/classes directory. Recommendation: if this parameter is set to false, set forceCompilation to
true if there are any JSP class files in the WEB-INF/classes directory.
Default: true; see the table above.
v forceCompilation
Specifies whether the batch compiler is forced to recompile all JSP resources regardless or whether the
JSP page is outdated.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -forceCompilation true.
Use-case: Especially useful when creating an archive for deployment, to make sure all JSP classes are
up to date.
Default: false
v useFullPackageNames
Specifies whether the batch compiler generates full package names for JSP classes. The default is to
generate all JSP classes in the same package. The JSP engine’s class loader knows how to load JSP

962 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 classes when they are all in the same package. The default has the benefit of generating smaller
file-system paths. Full package names have the benefit of enabling the configuration of precompiled
JSP class files as servlets in the web.xml file without use of the jsp-file attribute, resulting in a single
class loader (the Web application’s class loader) being used to load all such JSP classes. Similarly,
when the JSP engine’s configuration attributes useFullPackageNames and
disableJspRuntimeCompilation are both true, a single class loader is used to load all JSP classes,
even if the JSP pages are not configured as servlets in theweb.xml file.
When useFullPackageNames is set to true, the batch compiler generates a file called
generated_web.xml in the Web module’s WEB-INF directory. This file contains servlet configuration
information for each JSP page that is successfully translated and compiled. The information can
optionally be copied into the Web module’s web.xml file so that the JSP pages are loaded as servlets by
the Web container. Note that if a JSP page is configured as a servlet in this way, no reloading of the
JSP page is done at runtime if the JSP page is modified. This is because the JSP page is treated as a
regular servlet and requests for it do not pass through the JSP engine.
Example: JspBatchCompiler –enterpriseApp.name sampleApp –useFullPackageNames true
Use-case: Enables JSP classes to be loaded by a single class loader.
Default: false
v removeTempDir
Specifies whether the Web module’s temp directory is removed. The batch compiler by default
generates JSP class files into a Web module’s WEB-INF/classes directory. JSP class files are generated
into the temp directory at runtime if a JSP page is modified and JSP reloading is enabled. By batch
compiling all the JSP pages in a Web module and also removing the temp directory, disk resources are
preserved. You can only use the removeTempDir parameter when -enterpriseApp.name is given.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -removeTempDir true.
Use-case: Free up disk space by clearing out a Web application’s temp directory.
Default: false
v translate
Specifies whether JSP pages are translated and compiled. Set translate to false if you do not want JSP
pages to be translated and compiled. You must use this option in conjunction with -removeTempDir to tell
the batch compiler to remove only the temp directory and to do no further processing.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -translate false -removeTempDir true.
Use-case: Free up disk space by clearing out a Web application’s temp directory, without invoking JSP
processing.
Default: true
v compile
Specifies whether JSP pages go through the Java compilation phase. Set compile to false if you do not
want JSP pages to go through the Java compilation phase.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -compile false
Use-case: If you only want JSP pages to be syntax-checked, set -compile to false. You can set
-keepgenerated to true if you want to see the .java files that are generated during the translation
phase.
Default: true
v trackDependencies
Specifies whether the batch compiler recompiles a JSP page when any of its dependencies have
changed, even if the JSP page itself has not changed. Tracking dependencies incurs a significant
runtime performance penalty because the JSP Engine checks the filesystem on every request to a JSP
page to see if any of its dependencies have changed. The dependencies tracked by WebSphere
Application Server are :
1. Files statically included in the JSP page
2. Tag files used by the JSP page (excluding tag files that are in JAR files)
3. TLD files used by the JSP page (excluding TLD files that are in JAR files)

Chapter 8. Developing WebSphere applications 963

 Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -trackDependencies true.
Use-case: Useful in a development environment.
Default: false
v createDebugClassfiles
Specifies whether the batch compiler generates class files that contain SMAP information, as per JSR
45, Debugging support for Other Languages.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -createDebugClassfiles true
Use-case: Use this parameter when you want to be able to debug JSP pages in your JSR 45-compliant
IDE.
Default: false
v keepgenerated
Specifies whether the batch compiler saves or erases the generated Java source files created during
the translation phase.
If set to true, WebSphere Application Server saves the generated .java files used for compilation on
your server. By default, this argument is set to false and the .java files are erased after the class files
have compiled.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -keepgenerated true
Use-case: Use this parameter when you want to review the Java code generated by the batch compiler.
Default: false
v keepGeneratedclassfiles
Specifies whether the batch compiler saves or erases the class files generated during the compilation of
Java source files.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -keepGeneratedclassfiles false
-keepgenerated false
Use-case: Set this parameter to false if you only want to see if there are any translation or compilation
errors in your JSP pages. If paired with -keepgenerated false, this parameter results in all generated
files being removed before the batch compiler completes.
Default: true
v usePageTagPool
Enables or disables the reuse of custom tag handlers on an individual JSP page basis.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -usePageTagPool true
Use-case: Use this parameter to enable JSP-page-based reuse of tag handlers.
Default: false
v useThreadTagPool
Enables or disables the reuse of custom tag handlers on a per request thread basis per Web module.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -useThreadTagPool true
Use-case: Use this parameter to enable Web module-based reuse of tag handlers.
Default: false
v classloader.parentFirst
Specifies the search order for loading classes by instructing the batch compiler to search the parent
class loader prior to application class loader. This parameter is only used when ear.path or
enterpriseApp.name is given.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -classloader.parentFirst false
Use-case: Set this parameter to false when your Web module contains a JAR file that is also found in
the server lib directory, and you want your Web module’s JAR file to be picked up first.
Default: true
v classloader.singleWarClassloader

964 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Specifies whether to use one class loader per enterprise archive (EAR) file or one class loader per Web
application archive (WAR) file. Used only when ear.path or enterpriseApp.name is given.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -classloader.singleWarClassloader
true
Use-case: Set this parameter to true when a Web module depends on JAR files and classes in another
Web module in the same enterprise application.
Default: false; One class loader is created per WAR file with no visibility of classes in other Web
modules.
v additional.classpath
Specifies additional class path entries to be used when parsing and compiling JSP pages. This
parameter is used only when war.path is given. When war.path is the target, WebSphere Shared
Libraries are not picked up by the batch compiler. Therefore, if your WAR file relies on, for example, a
JAR file that is configured in WebSphere Application Server as a shared library, then use this option to
point to that JAR file. In addition, if you give war.path and also use the -extractToDir parameter, then
any JAR files that are in the WAR file’s manifest class-path is not added to the class path (since the
WAR file has now been extracted by itself outside the EAR file in which it resides). Use
-additional.classpath in this case to point to the necessary JAR files. Add the full path to needed
resources, separated by your system-dependent path separator.
Example: JspBatchCompiler -war.path c:\myproject\examples.war -additional.classpath
c:\myJars\someJar.jar;c:\myClasses
Use-case: Use this parameter to add to the class path JAR files and classes outside of your WAR file.
At runtime, these same JAR files and classes have to be made available through the standard
WebSphere Application Server configuration mechanisms.
Default: null
v jspCompileClasspath
This option instructs the batch compiler to use a small class path for the Java compilation phase. The
small class path greatly speeds up the compilation process. This small class path is not used by default
because it includes only a subset of WebSphere Application Server JAR files. The small class path
excludes many WebSphere Application Server JAR files, among which are those that contain
WebSphere public APIs.
If your JSP pages do not use any WebSphere public APIs within scriptlets you can enable the small
class path by using the jspCompileClasspath parameter with no value, as in Example 1 below.
If your JSP pages do use WebSphere public APIs within scriptlets, then add those additional JAR files
to the jspCompileClasspath option, as in Example 2 below.
The entries are separated by spaces, and are assumed to be relative to the WebSphere Application
Server installation root.
Example 1:If no public APIs are needed in JSP pages: JspBatchCompiler -enterpriseApp.name
sampleApp -jspCompileClasspath
Example 2: public APIs from the admin.jar file needed in JSP pages: JspBatchCompiler
-enterpriseApp.name sampleApp –jspCompileClasspath ″lib/admin.jar″
Use-case: Use this parameter to speed up the Java compilation step of JSP page processing.
Default: The entire WebSphere Application Server class path is used by default.
v verbose
Specifies whether the batch compiler should generate verbose output while compiling the generated
sources.
Example: JspBatchCompiler -war.path c:\myproject\examples.war -verbose true
Use-case: Set this parameter to true when you want to see Java compiler class loading and other
messages.
Default: false
v deprecation

Chapter 8. Developing WebSphere applications 965

 Indicates the compiler should generate deprecation warnings while compiling the generated sources.
Example: JspBatchCompiler -war.path c:\myproject\examples.war -deprecation true
Use-case: Set this parameter to true when you want to see Java compiler deprecation messages.
Default: false
v javaEncoding
Specifies the encoding that will be used when the .java file is generated, and when it is compiled by the
Java compiler. When -javaEncoding is set, that encoding is passed to the java compiler via the
-encoding argument. Note that encoding is not supported by Jikes.
Example: JspBatchCompiler -war.path c:\myproject\examples.war -javaEncoding Shift-JIS
Use-case: Set this parameter when the page encoding of your JSP pages is not UTF-8 compatible.
Default value: UTF-8.
v compileWithAssert
Tells the batch compiler to enable assertions. If compileWithAssert is true, the batch compiler will pass
the –source 1.4 option to the javac compiler. If compileWithAssert is false, no option is sent to the javac
compiler. The default behavior of javac is to compile code normally even if the word assert is used as
regular identifier.
Example: JspBatchCompiler -war.path c:\myproject\examples.war -compileWithAssert true
Use-case: Set this parameter to true when you want you use the assertion facility in your JSP pages
and you want to be able to turn on assertions at runtime.
Default value: false
v compilerOptions
Specifies a list of strings to be passed on the Java compiler command. This is a space-separated list of
the form ″arg1 arg2 argn″.
Example: JspBatchCompiler -war.path c:\myproject\examples.war -compilerOptions ″ -bootclasspath
<path>″
Use-case: Use this parameter if you need Java compiler arguments other than verbose, deprecation
and Assert facility support.
Default: null
v useJikes
Specifies whether Jikes should be used for compiling Java sources. NOTE: Jikes is not shipped with
WebSphere Application Server.
Example: JspBatchCompiler -ear.path c:\myproject\sampleApp.ear -useJikes true
Use-case: Set this parameter to true in order for the batch compiler to use Jikes as the Java compiler.
Default value: false
v jsp.file.extensions
Specifies the file extensions to be processed by the batch compiler. This is a semicolon- or
colon-separated list of the form ″*.ext1;*.ext2:*.extn″. Note that this parameter is not necessary for
Servlet 2.4 Web applications because the url-pattern property of the jsp-property-group elements in the
deployment descriptor can be used to identify extensions that should be treated as JSP pages.
Example: JspBatchCompiler -enterpriseApp.name sampleApp -jsp.file.extensions *jspz;*.jspt
Use-case: Use this parameter to add additional extensions to the be processed by the batch compiler.
Default: null; See the section, “JSP batch compiler tool” on page 957, for additional information.
v log.level
Specifies the level of logging that is directed to the console during batch compilation. Values are
SEVERE | WARNING | INFO | CONFIG | FINE | FINER | FINEST | OFF
Example: JspBatchCompiler -enterpriseApp.name sampleApp -log.level FINEST
Use-case: Set this parameter higher or lower to control logging output. FINEST generates the most
output useful for debugging.

966 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Default: CONFIG

Batch compiler ant task:

The ant task JspC exposes all the batch compiler configuration options. It executes the batch compiler
under the covers. It is backward compatible with the WebSphere Application Server 5.x version of the
JspC ant task. The following table lists all the ant task attribute and their batch compiler equivalents.

JspC attribute Equivalent batch complier parameter

earPath -ear.path
warPath -war.path
src -war.path

Same as warPath, for backward compatiblity

enterpriseAppName -enterpriseapp.name
responseFile -response.file
webmoduleName -webmodule.name
fileName -filename -config.root
configRoot -config.root
cellName -cell.name
nodeName -node.name
serverName -server.name
profileName -profileName
extractToDir -extractToDir
compileToDir -compileToDir -compileToDir

same as compileToDir, for backward compatibility

compileToWebInf -compileToWebInf
jspCompileClasspath -jspCompileClasspath
compilerOptions -compilerOptions
recurse -recurse
removeTempDir -removeTempDir
translate -translate
compile -compile
forceCompilation -forceCompilation
useFullPackageNames -useFullPackageNames
trackDependencies -trackDependencies
createDebugClassfiles -createDebugClassfiles
keepgenerated -keepgenerated
keepGeneratedclassfiles -keepGeneratedclassfiles
usePageTagPool -usePageTagPool
useThreadTagPool -useThreadTagPool
classloaderParentFirst -classloader.parentFirst
classloaderSingleWarClassloader -classloader.singleWarClassloader
additionalClasspath -additional.classpath

Chapter 8. Developing WebSphere applications 967

classpath -additional.classpath

same as additionalClasspath, for backward compatibility

verbose -verbose
deprecation -deprecation
javaEncoding -javaEncoding
compileWithAssert -compileWithAssert
useJikes -useJikes
jspFileExtensions -jsp.file.extensions
logLevel -log.level
wasHome none
Classpathref none

Below is an example of a build script with multiple targets, each with different attributes. The following
commands are used to execute the script:

On Windows:
ws_ant -Dwas.home=%WAS_HOME% -Dear.path=%EAR_PATH% -Dextract.dir=%EXTRACT_DIR%
ws_ant jspc2 -Dwas.home=%WAS_HOME% -Dapp.name=%APP_NAME% -Dwebmodule.name=%MOD_NAME%
ws_ant jspc3 -Dwas.home=%WAS_HOME% -Dapp.name=%APP_NAME% -Dwebmodule.name=%MOD_NAME% -Ddir.name=%DIR_NAME%

On Unix:
ws_ant -Dwas.home=$WAS_HOME -Dear.path=$EAR_PATH -Dextract.dir=$EXTRACT_DIR
ws_ant jspc2 -Dwas.home=$WAS_HOME -Dapp.name=$APP_NAME -Dwebmodule.name=$MOD_NAME
ws_ant jspc3 -Dwas.home=$WAS_HOME -Dapp.name=$APP_NAME -Dwebmodule.name=$MOD_NAME -Ddir.name=$DIR_NAME

Example build.xml Using the JspC Task

<project name="JSP Precompile" default="jspc1" basedir=".">
<taskdef name="wsjspc" classname="com.ibm.websphere.ant.tasks.JspC"/>
<target name="jspc1" description="example using a path to an EAR, and extracting the EAR to a directory">
<wsjspc wasHome="${was.home}"
earpath="${ear.path}"
forcecompilation="true"
extractToDir="${extract.dir}"
useThreadTagPool="true"
keepgenerated="true"
jspCompileClasspath=""

/>
</target>
<target name="jspc2" description="example using an enterprise app and webmodule">
<wsjspc wasHome="${was.home}"
enterpriseAppName="${app.name}"
webmoduleName="${webmodule.name}"
removeTempDir="true"
forcecompilation="true"
keepgenerated="true"
jspCompileClasspath=""

/>
</target>
<target name="jspc3" description="example using an enterprise app, webmodule and specific directory">
<wsjspc wasHome="${was.home}"
enterpriseAppName="${app.name}"
webmoduleName="${webmodule.name}"
fileName="${dir.name}"
recurse="false"

968 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 forcecompilation="true"
keepgenerated="true"
jspCompileClasspath=""

/>
</target>
</project>

Batch compiler class path:

The batch compiler builds its class path as shown in the table below. When the batch compiler target is a
Web archive (WAR) file and war.path is supplied, the configuration additional.classpath parameter is used
to give extra class path information.

Batch compiler target

Location added to class path enterpriseapp.name ear.path war.path
WebSphere Application Server yes yes yes
JAR files and classes
JAR files listed in manifest class yes yes yes, when the target WAR is inside
path for a Web module an EAR and –extractToDir is not
used; otherwise, no.
Shared libraries yes no no
Web module JAR files and classes yes yes yes
additional.classpath parameter to no no yes
batch compiler
jspCompileClassPath parameter When this parameter is used, the only change to the information above is that a
subset of WebSphere Application Server JAR files and classes is used for Java
compilation. All JAR files and classes, that are given in the value for the
jspCompileClassPath parameter are also added to the class path for Java
compilation.

Global tag libraries:

JavaServer Pages (JSP) tag libraries contain classes for common tasks such as processing forms and
accessing databases from JSP files.

Tag libraries encapsulate, as simple tags, core functionality common to many Web applications. The Java
Standard Tag Library (JSTL) supports common programming tasks such as iteration and conditional
processing, and provides tags for:
v manipulating XML documents
v supporting internationalization
v using Structured Query Language (SQL)

Tag libraries also introduce the concept of an expression language to simplify page development, and
include a version of the JSP expression language.

A tag library has two parts - a Tag Library Descriptor (TLD) file and a Java archive (JAR) file.

tsx:dbconnect tag JavaServer Pages syntax: Use the <tsx:dbconnect> tag to specify information needed
to make a connection to a database through Java DataBase Connectivity (JDBC) or Open Database
Connectivity (ODBC) technology.

The <tsx:dbconnect> syntax does not establish the connection. Use the <tsx:dbquery> and <tsx:dbmodify>
syntax instead to reference a <tsx:dbconnect> tag in the same JavaServer Pages (JSP) file to establish
the connection.

Chapter 8. Developing WebSphere applications 969

When the JSP file compiles into a servlet, the Java processor adds the Java coding for the
<tsx:dbconnect> syntax to the servlet service() method, which means a new database connection is
created for each request for the JSP file.

This section describes the syntax of the <tsx:dbconnect> tag.

<tsx:dbconnect id="connection_id"
userid="db_user" passwd="user_password"
url="jdbc:subprotocol:database"
driver="database_driver_name"
jndiname="JNDI_context/logical_name">
</tsx:dbconnect>

where:
v id
Represents a required identifier. The scope is the JSP file. This identifier is referenced by the
connection attribute of a <tsx:dbquery> tag.
v userid
Represents an optional attribute that specifies a valid user ID for the database that you want to access.
Specify this attribute to add the attribute and its value to the request object.
Although the userid attribute is optional, you must provide the user ID. See <tsx:userid> and
<tsx:passwd> for an alternative to hard coding this information in the JSP file.
v passwd
Represents an optional attribute that specifies the user password for the userid attribute. (This attribute
is not optional if the userid attribute is specified.) If you specify this attribute, the attribute and its value
are added to the request object.
Although the passwd attribute is optional, you must provide the password. See <tsx:userid> and
<tsx:passwd> for an alternative to hard coding this attribute in the JSP file.
v url and driver
Respresents a required attribute if you want to establish a database connection. You must provide the
URL and driver.
The application server supports connection to JDBC databases and ODBC databases.
– For a JDBC database, the URL consists of the following colon-separated elements: jdbc, the
subprotocol name, and the name of the database to access. An example for a connection to the
Sample database included with IBM DB2 is:
url="jdbc:db2:sample"
driver="COM.ibm.db2.jdbc.app.DB2Driver"
– For an ODBC database, use the Sun JDBC-to-ODBC bridge driver included in their Java2 Software
Developers Kit (SDK) or another vendor’s ODBC driver.
The url attribute specifies the location of the database. The driver attribute specifies the name of the
driver to use in establishing the database connection.
If the database is an ODBC database, you can use an ODBC driver or the Sun JDBC-to-ODBC
bridge. If you want to use an ODBC driver, refer to the driver documentation for instructions on
specifying the database location with the url attribute and the driver name.
If you use the bridge, the url syntax is jdbc:odbc:database. An example follows:
url="jdbc:odbc:autos"
driver="sun.jdbc.odbc.JdbcOdbcDriver"
Note: To enable the application server to access the ODBC database, use the ODBC Data Source
Administrator to add the ODBC data source to the System DSN configuration. To access the ODBC
Administrator, click the ODBC icon on the Windows NT Control Panel.
v jndiname
Represents an optional attribute that identifies a valid context in the application server Java Naming and
Directory Interface (JNDI) naming context and the logical name of the data source in that context. The
Web administrator configures the context using an administrative client such as the WebSphere
Administrative Console.

970 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 If you specify the jndiname attribute, the JSP processor ignores the driver and url attributes on the
<tsx:dbconnect> tag.

An empty element (such as <url></url>) is valid.

dbquery tag JavaServer Pages syntax: Use the <tsx:dbquery> tag to establish a connection to a
database, submit database queries, and return the results set.

The <tsx:dbquery> tag does the following:

1. References a <tsx:dbconnect> tag in the same JavaServer Pages (JSP) file and uses the information
the tag provides to determine the database URL and driver. You can also obtain the user ID and
password from the <tsx:dbconnect> tag if those values are provided in the <tsx:dbconnect> tag.
2. Establishes a new connection
3. Retrieves and caches data in the results object.
4. Closes the connection and releases the connection resource.

This section describes the syntax of the <tsx:dbquery> tag.

<%-- SELECT commands and (optional) JSP syntax can be placed within the tsx:dbquery. --%>
<%-- Any other syntax, including HTML comments, are not valid. --%>
<tsx:dbquery id="query_id" connection="connection_id" limit="value" >
</tsx:dbquery>

where:
v id
Represents the identifier of this query. The scope is the JSP file. Use id to reference the query. For
example, from the <tsx:getProperty> tag, use id to display the query results.
The id is a tsx reference to the bean and can be used to retrieve the bean from the page contect. For
example, if id is named mySingleDBBean, instead of using:
– if (mySingleDBBean.getValue(″UISEAM″,0).startsWith(″N″))
use:
– com.ibm.ws.webcontainer.jsp.tsx.db.QueryResults bean =
(com.ibm.ws.webcontainer.jsp.tsx.db.QueryResults)pageContext. findAttribute(″mySingleDBBean″); if
(bean.getValue(″UISEAM″,0).startsWith(″N″)). . .
The bean properties are dynamic and the property names are the names of the columns in the results
set. If you want different column names, use the SQL keyword for specifying an alias on the SELECT
command. In the following example, the database table contains columns named FNAME and LNAME,
but the SELECT statement uses the AS keyword to map those column names to FirstName and
LastName in the results set:
Select FNAME, LNAME AS FirstName, LastName from Employee where FNAME=’Jim’
v connection
Represents the identifier of a <tsx:dbconnect> tag in this JSP file. The <tsx:dbconnect> tag provides the
database URL, driver name, and optionally, the user ID and password for the connection.
v limit
Represents an optional attribute that constrains the maximum number of records returned by a query. If
this attribute is not specified, no limit is used. In such a case, the effective limit is determined by the
number of records and the system caching capability.
v SELECT command and JSP syntax
Represents the only valid SQL command, SELECT. The <tsx:dbquery> tag must return a results set.
Refer to your database documentation for information about the SELECT command. See other articles
in this section for a description of JSP syntax for variable data and inline Java code.

dbmodify tag JavaServer Pages syntax: The <tsx:dbmodify> tag establishes a connection to a database
and then adds records to a database table.

The <tsx:dbmodify> tag does the following:

Chapter 8. Developing WebSphere applications 971
1. References a <tsx:dbconnect> tag in the same JavaServer Pages (JSP) file and uses the information
provided by that tag to determine the database URL and driver.
Note: You can also obtain the user ID and password from the <tsx:dbconnect> tag if those values are
provided in the <tsx:dbconnect> tag.
2. Establishes a new connection.
3. Updates a table in the database.
4. Closes the connection and releases the connection resource.

This section describes the syntax of the <tsx:dbmodify> tag.

<%-- Any valid database update commands can be placed within the DBMODIFY tag. -->
<%-- Any other syntax, including HTML comments, are not valid. -->
<tsx:dbmodify connection="connection_id">
</tsx:dbmodify>

where:
v connection
Represents the identifier of a <tsx:dbconnect> tag in this JSP file. The <tsx:dbconnect> tag provides the
database URL, driver name, and (optionally) the user ID and password for the connection.
v Database commands
Represents valid database commands. Refer to your database documentation for details

tsx:getProperty tag JavaServer Pages syntax and examples: The <tsx:getProperty> tag gets the value
of a bean to display in a JavaServer Pages (JSP) file.

This IBM extension of the Sun JSP <jsp:getProperty> tag implements all of the <jsp:getProperty> function
and adds the ability to introspect a database bean created using the IBM extension <tsx:dbquery> or
<tsx:dbmodify>.

Note: You cannot assign the value from this tag to a variable. The value, generated as output from this
tag, displays in the browser window.

This section describes the syntax of the <tsx:getProperty> tag:

<tsx:getProperty name="bean_name"
property="property_name" />

where:
v name
Represents the name of the bean declared by the id attribute of a <tsx:dbquery> syntax within the JSP
file. See <tsx:dbquery> for an explanation. The value of this attribute is case-sensitive.
v property
Represents the property of the bean to access for substitution. The value of the attribute is
case-sensitive and is the locale-independent name of the property.

Tag example:
<tsx:getProperty name="userProfile" property="username" />

tsx:userid and tsx:passwd tag JavaServer Pages syntax: With the <tsx:userid> and <tsx:passwd> tags,
you do not have to hard code a user ID and password in the <tsx:dbconnect> tag.

Use the <tsx:userid> and <tsx:passwd> tags to accept user input for the values and then add that data to
the request object. You can access the request object with a JavaServer Pages (JSP) file, such as the
JSPEmployee.jsp example that requests the database connection.

You must use <tsx:userid> and <tsx:passwd> tags within a <tsx:dbconnect> tag.

972 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This section describes the syntax of the <tsx:userid> and <tsx:passwd> tags.
<tsx:dbconnect id="connection_id"
<font color="red"><userid></font>
<tsx:getProperty name="request" property=request.getParameter("userid") />
<font color="red"></userid></font>
<font color="red"><passwd></font>
<tsx:getProperty name="request" property=request.getParameter("passwd") />
<font color="red"></passwd></font>
url="protocol:database_name:database_table"
driver="JDBC_driver_name">
</tsx:dbconnect>

where:
v <tsx:getProperty>
Represents the syntax as a mechanism for embedding variable data.
v userid
Represents a reference to the request parameter that contains the user ID. You must add the parameter
to the request object that passes to this JSP file. You can set the attribute and its value in the request
object, using an HTML form or a URL query string to pass the user-specified request parameters.
v passwd
Represents a reference to the request parameter that contains the password. Add the parameter to the
request object that passes to this JSP file. You can set the attribute and its value in the request object,
using an HTML form or a URL query string, to pass user-specified values.

tsx:repeat tag JavaServer Pages syntax: The <tsx:getProperty> tag repeats a block of HTML tagging.

Use the <tsx:repeat> syntax to iterate over a database query results set. The <tsx:repeat> syntax iterates
from the start value to the end value until one of the following conditions is met:
v The end value is reached.
v An exception is thrown.

If an exception of the types ArrayIndexOutOfBoundsException or NoSuchElementException is created

before a block completes, output is written only for the iterations up to and not including the iteration
during which the exception was created. All other exceptions results in no output being written for that tag
instance.

This section describes the syntax of the <tsx:repeat> tag:

<tsx:repeat index="name" start="starting_index" end="ending_index">
</tsx:repeat>

where:
v index
Represents an optional name used to identify the index of this repeat block. The scope of the index is
NESTED. Its type must be integer.
v start
Represents an optional starting index value for this repeat block. The default is 0.
v end
Represents an optional ending index value for this repeat block. The maximum value is 2,147,483,647.
If the value of the end attribute is less than the value of the start attribute, the end attribute is ignored.

Example: Combining tsx:repeat and tsx:getProperty JavaServer Pages tags: The following code snippet
shows you how to code these tags:
<tsx:repeat>
<tr>
<td><tsx:getProperty name="empqs" property="EMPNO" />
<tsx:getProperty name="empqs" property="FIRSTNME" />

Chapter 8. Developing WebSphere applications 973

 <tsx:getProperty name="empqs" property="WORKDEPT" />
<tsx:getProperty name="empqs" property="EDLEVEL" />
</td>
</tr>
</tsx:repeat>

Example: tsx:dbmodify tag syntax: In the following example, a new employee record is added to a
database. The values of the fields are based on user input from this JavaServer Pages (JSP) file and
referenced in the database commands using the <tsx:getProperty> tag.
<tsx:dbmodify connection="conn" >
insert into EMPLOYEE
(EMPNO,FIRSTNME,MIDINIT,LASTNAME,WORKDEPT,EDLEVEL)
values
(’<tsx:getProperty name="request" property=request.getParameter("EMPNO") />’,
’<tsx:getProperty name="request" property=request.getParameter("FIRSTNME") />’,
’<tsx:getProperty name="request" property=request.getParameter("MIDINIT") />’,
’<tsx:getProperty name="request" property=request.getParameter("LASTNAME") />’,
’<tsx:getProperty name="request" property=request.getParameter("WORKDEPT") />’,
<tsx:getProperty name="request" property=request.getParameter("EDLEVEL") />)
</tsx:dbmodify>

Example: Using tsx:repeat JavaServer Pages tag to iterate over a results set: The <tsx:repeat> tag
iterates over a results set. The results set is contained within a bean. The bean can be a static bean, for
example, a bean created by using the IBM WebSphere Studio database wizard, or a dynamically
generated bean, for example, a bean generated by the <tsx:dbquery> syntax. The following table is a
graphic representation of the contents of a bean called, myBean:

col1 col2 col3

row0 friends Romans countrymen
row1 bacon lettuce tomato
row2 May June July

Some observations about the bean:

v The column names in the database table become the property names of the bean. The <tsx:dbquery>
section describes a technique for mapping the column names to different property names.
v The bean properties are indexed. For example, myBean.get(Col1(row2)) returns May.
v The query results are in the rows. The <tsx:repeat> tag iterates over the rows, beginning at the start
row.

The following table compares using the <tsx:repeat> tag to iterate over a static bean, versus a dynamically
generated bean:

974 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Static Bean Example <tsx:repeat> Bean Example
myBean.class JSP file
// Code to get a connection <tsx:dbconnect id="conn"
userid="alice"passwd="test"
// Code to get the data url="jdbc:db2:sample"
Select * from myTable; driver="COM.ibm.db2.jdbc.app.DB2Driver">
</tsx:dbconnect >
// Code to close the connection
<tsx:dbquery id="dynamic"
JSP file connection="conn" >
Select * from myTable;
<tsx:repeat index=abc> </tsx:dbquery>
<tsx:getProperty name="myBean"
property="col1(abc)" /> <tsx:repeat index=abc>
</tsx:repeat> <tsx:getProperty name="dynamic"
property="col1(abc)" />
Notes: </tsx:repeat>
v The bean (myBean.class) is a static bean.
v The method to access the bean properties is Notes:
myBean.get(property(index)). v The bean (dynamic) is generated by the <tsx:dbquery>
v You can omit the property index, in which case the tag and does not exist until the syntax executes.
index of the enclosing <tsx:repeat> tag is used. You v The method to access the bean properties is
can also omit the index on the <tsx:repeat> tag. dynamic.getValue(″property″, index).
v The <tsx:repeat> tag iterates over the bean properties v You can omit the property index, in which case the
row by row, beginning with the start row. index of the enclosing <tsx:repeat> tag is used. You
can also omit the index on the <tsx:repeat> tag.
v The <tsx:repeat> tag syntax iterates over the bean
properties row by row, beginning with the start row.

Implicit and explicit indexing

Examples 1, 2, and 3 show how to use the <tsx:repeat> tag. The examples produce the same output if all
indexed properties have 300 or fewer elements. If there are more than 300 elements, Examples 1 and 2
display all elements, while Example 3 shows only the first 300 elements.

Example 1 shows implicit indexing with the default start and default end index. The bean with the smallest
number of indexed properties restricts the number of times the loop repeats.
<table>
<tsx:repeat>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property="city" />
</tr></td>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property="address" />
</tr></td>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property="telephone" />
</tr></td>
</tsx:repeat>
</table>

Example 2 shows indexing, starting index, and ending index:

<table>
<tsx:repeat index=myIndex start=0 end=2147483647>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property=city(myIndex) />
</tr></td>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property=address(myIndex) />
</tr></td>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property=telephone(myIndex) />
</tr></td>
</tsx:repeat>
</table>

Chapter 8. Developing WebSphere applications 975

Example 3 shows explicit indexing and ending index with implicit starting index. Although the index
attribute is specified, you can still implicitly index the indexed property city because the (myIndex) tag is
not required.
<table>
<tsx:repeat index=myIndex end=299>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property="city" /t>
</tr></td>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property="address(myIndex)" />
</tr></td>
<tr><td><tsx:getProperty name="serviceLocationsQuery" property="telephone(myIndex)" />
</tr></td>
</tsx:repeat>
</table>

Nesting <tsx:repeat> blocks

You can nest <tsx:repeat> blocks. Each block is separately indexed. This capability is useful for
interleaving properties on two beans, or properties that have subproperties. In the example, two
<tsx:repeat> blocks are nested to display the list of songs on each compact disc in the user’s shopping
cart.
<tsx:repeat index=cdindex>
<h1><tsx:getProperty name="shoppingCart" property=cds.title /></h1>
<table>
<tsx:repeat>
<tr><td><tsx:getProperty name="shoppingCart" property=cds(cdindex).playlist />
</td></tr>
</tsx:repeat>
</table>
</tsx:repeat>

Web modules
A Web module represents a Web application. A Web module is created by assembling servlets,
JavaServer Pages (JSP) files, and static content such as Hype rText Markup Language (HTML) pages into
a single deployable unit. Web modules are stored in Web archive (WAR) files, which are standard Java
archive files.

A Web module contains:

v One or more servlets, JSP files, and HTML files.
v A deployment descriptor, stored in an Extensible Markup Language (XML) file.
The file, named web.xml, declares the contents of the module. It contains information about the structure
and external dependencies of Web components in the module and describes how the components are
used at run time.

You can create Web modules as stand-alone applications, or you can combine Web modules with other
modules to create Java 2 Platform, Enterprise Edition (J2EE) applications. You install and run a Web
module in the Web container of an application server.

Troubleshooting tips for Web application deployment

Deployment of a Web application is successful if you can access the application by typing a Uniform
Resource Locator (URL) in a browser, or if you can access the application by following a link.

If you cannot access your application, follow these steps to eliminate some common errors that can occur
during migration or deployment.

Web module does not run in WebSphere Application Server Version 5 or 6.

Symptom Your Web module does not run when you migrate it to Version 5 or 6

976 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Problem In Version 4.x, the classpath setting that affected visibility was Module Visibility Mode.
In Versions 5 and 6, you must use class loader policies to set visibility.
Recommended response Reassemble an existing module, or change the visibility settings in the class loader
policies.

Welcome page is not visible.

Symptom You cannot access an application with a Web path of:

/webapp/myapp
Problem The default welcome page for a Web application is assumed to be index.html. You
cannot access the default page of the myapp application unless it is named index.html.
Recommended response To identify a different welcome page, modify the properties of the Web module during
assembly. See the article ″Assembling Web applications″ for more information.

HTML files are not found.

Symptom Your Web application ran successfully on prior versions, but now you encounter errors
that the welcome page (typically index.html), or referenced HTML files are not found:
Error 404: File not found: Banner.html
Error 404: File not found: HomeContent.html
Problem For security and consistency reasons, Web application URLs are now case-sensitive on
all operating systems.

Suppose the content of the index page is as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 5.0 Frameset//EN">
<HTML>
<TITLE>
Insurance Home Page
</TITLE>
<frameset rows="18,80">
<frame src="Banner.html" name="BannerFrame" SCROLLING=NO>
<frame src="HomeContent.html" name="HomeContentFrame">
</frameset>
</HTML>

However the actual file names in the \WebSphere\AppServer\installedApps\...

directory where the application is deployed are:
banner.html
homecontent.html
Recommended response To correct this problem, modify the index.html file to change the names Banner.html
and HomeContent.html to banner.html and homecontent.html to match the names of
the files in the deployed application.

For current information available from IBM Support on known problems and their resolution, see the IBM
Support page.

IBM Support has documents that can save you time gathering information needed to resolve this problem.
Before opening a PMR, see the IBM Support page.

Web applications: Resources for learning

Use the following links to find relevant supplemental information about Web applications. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of the
information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links

Chapter 8. Developing WebSphere applications 977

are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

View links to additional information about:

v “Web applications: Resources for learning” on page 977
v “Web applications: Resources for learning” on page 977
v “Web applications: Resources for learning” on page 977

Programming model and decisions

v J2EE BluePrints for Web applications
v Redbook on the design and implementation of Servlets, JSP files, and enterprise beans

Programming instructions and examples

v Redbook on Servlet and JSP file Programming
v Sun’s JavaTM Tutorial on Servlets and JavaServer Pages
v Web delivered samples in the Samples Gallery

Programming specifications
v Java 2 Software Development Kit (SDK)
v Servlet 2.4 Specification
v JavaServer Pages 2.0 Specification
v Differences between JavaScript and ECMAScript
v ISO 8859 Specifications

Task overview: Managing HTTP sessions

IBM WebSphere Application Server provides a service for managing HTTP sessions: Session Manager.
The key activities for session management are summarized below.

Before you begin these steps, make sure you are familiar with the programming model for accessing
HTTP session support in the applications following the Servlet 2.4 API.
1. Plan your approach to session management, which could include session tracking and session
recovery.
2. Create or modify your own applications to use session support to maintain sessions on behalf of Web
applications.
3. Assemble your application. See ″Assembling applications″ in the information center.
4. Deploy your application.
5. Ensure the administrator appropriately configures session management in the administrative domain.
6. Adjust configuration settings and perform other tuning activities for optimal use of sessions in your
environment.

Sessions
A session is a series of requests to a servlet, originating from the same user at the same browser.

Sessions allow applications running in a Web container to keep track of individual users.

For example, a servlet might use sessions to provide ″shopping carts″ to online shoppers. Suppose the
servlet is designed to record the items each shopper indicates he or she wants to purchase from the Web
site. It is important that the servlet be able to associate incoming requests with particular shoppers.
Otherwise, the servlet might mistakenly add Shopper_1’s choices to the cart of Shopper_2.

A servlet distinguishes users by their unique session IDs. The session ID arrives with each request. If the
user’s browser is cookie-enabled, the session ID is stored as a cookie. As an alternative, the session ID
can be conveyed to the servlet by URL rewriting, in which the session ID is appended to the URL of the

978 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
servlet or JavaServer Pages (JSP) file from which the user is making requests. For requests over HTTPS
or Secure Sockets Layer (SSL), Another alternative is to use SSL information to identify the session.

Session security support

You can integrate HTTP sessions and security in WebSphere Application Server. When security integration
is enabled in the session management facility and a session is accessed in a protected resource, you can
access that session only in protected resources from then on. You cannot mix secured and unsecured
resources accessing sessions when security integration is turned on. Security integration in the session
management facility is not supported in form-based login with SWAM.

Security integration rules for HTTP sessions

Only authenticated users can access sessions created in secured pages and are created under the
identity of the authenticated user. Only this authenticated user can access these sessions in other secured
pages. To protect these sessions from unauthorized users, you cannot access them from an unsecured
page.

Programmatic details and scenarios

WebSphere Application Server maintains the security of individual sessions.

An identity or user name, readable by the com.ibm.websphere.servlet.session.IBMSession interface, is

associated with a session. An unauthenticated identity is denoted by the user name anonymous.
WebSphere Application Server includes the
com.ibm.websphere.servlet.session.UnauthorizedSessionRequestException class, which is used when a
session is requested without the necessary credentials.

The session management facility uses the WebSphere Application Server security infrastructure to
determine the authenticated identity associated with a client HTTP request that either retrieves or creates
a session. WebSphere Application Server security determines identity using certificates, LPTA, and other
methods.

After obtaining the identity of the current request, the session management facility determines whether to
return the session requested using a getSession call.

The following table lists possible scenarios in which security integration is enabled with outcomes
dependent on whether the HTTP request is authenticated and whether a valid session ID and user name
was passed to the session management facility.

Unauthenticated HTTP request is HTTP request is authenticated, with

used to retrieve a session an identity of ″FRED″ used to
retrieve a session
No session ID was passed in for A new session is created. The user A new session is created. The user
this request, or the ID is for a name is anonymous name is FRED
session that is no longer valid
A session ID for a valid session is The session is returned. The session is returned. session
passed in. The current session management changes the user name to
user name is ″anonymous″ FRED
A session ID for a valid session is The session is not returned. An The session is returned.
passed in. The current session UnauthorizedSessionRequestException
user name is FRED error is created*
A session ID for a valid session is The session is not returned. An The session is not returned. An
passed in. The current session UnauthorizedSessionRequestException UnauthorizedSessionRequestException
user name is BOB error is created* error is created*

Chapter 8. Developing WebSphere applications 979

* A com.ibm.websphere.servlet.session.UnauthorizedSessionRequestException error is created to the
servlet.

Session management support

WebSphere Application Server provides facilities, grouped under the heading Session Management, that
support the javax.servlet.http.HttpSession interface described in the Servlet API specification.

In accordance with the Servlet 2.3 API specification, the session management facility supports session
scoping by Web modules. Only servlets in the same Web module can access the data associated with a
particular session. Multiple requests from the same browser, each specifying a unique Web application,
result in multiple sessions with a shared session ID. You can invalidate any of the sessions that share a
session ID without affecting the other sessions.

You can configure a session timeout for each Web application. A Web application timeout value of 0 (the
default value) means that the invalidation timeout value from the Session Management facility is used.

When an HTTP client interacts with a servlet, the state information associated with a series of client
requests is represented as an HTTP session and identified by a session ID. Session Management is
responsible for managing HTTP sessions, providing storage for session data, allocating session IDs, and
tracking the session ID associated with each client request through the use of cookies or URL rewriting
techniques. Session Management can store session-related information in several ways:
v In application server memory (the default). This information cannot be shared with other application
servers.
v In a database. This storage option is known as database persistent sessions.
v In another WebSphere Application Server instance. This storage option is known as
memory-to-memory sessions.

The last two options are referred to as distributed sessions. Distributed sessions are essential for using
HTTP sessions for failover facility. When an application server receives a request associated with a
session ID that it currently does not have in memory, it can obtain the required session state by accessing
the external store (database or memory-to-memory). If distributed session support is not enabled, an
application server cannot access session information for HTTP requests that are sent to servers other than
the one where the session was originally created. Session Management implements caching optimizations
to minimize the overhead of accessing the external store, especially when consecutive requests are routed
to the same application server.

Storing session states in an external store also provides a degree of fault tolerance. If an application
server goes offline, the state of its current sessions is still available in the external store. This availability
enables other application servers to continue processing subsequent client requests associated with that
session.

Saving session states to an external location does not completely guarantee their preservation in case of a
server failure. For example, if a server fails while it is modifying the state of a session, some information is
lost and subsequent processing using that session can be affected. However, this situation represents a
very small period of time when there is a risk of losing session information.

The drawback to saving session states in an external store is that accessing the session state in an
external location can use valuable system resources. session management can improve system
performance by caching the session data at the server level. Multiple consecutive requests that are
directed to the same server can find the required state data in the cache, reducing the number of times
that the actual session state is accessed in external store and consequently reducing the overhead
associated with external location access.

Session tracking options

There are several options for session tracking, depending on what sort of tracking method you want to
use:

980 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Session tracking with cookies
v Session tracking with URL rewriting
v Session tracking with Secure Sockets Layer (SSL) information

Session tracking with cookies: Tracking sessions with cookies is the default. No special programming
is required to track sessions with cookies.

Session tracking with URL rewriting: An application that uses URL rewriting to track sessions must
adhere to certain programming guidelines. The application developer needs to do the following:
v Program servlets to encode URLs
v Supply a servlet or JavaServer Pages (JSP) file as an entry point to the application

Using URL rewriting also requires that you enable URL rewriting in the session management facility.

Note: In certain cases, clients cannot accept cookies. Therefore, you cannot use cookies as a session
tracking mechanism. Applications can use URL rewriting as a substitute.

Program session servlets to encode URLs

Depending on whether the servlet is returning URLs to the browser or redirecting them, include either the
encodeURL method or the encodeRedirectURL method in the servlet code. Examples demonstrating what
to replace in your current servlet code follow.

Rewrite URLs to return to the browser

Suppose you currently have this statement:

out.println("<a href=\"/store/catalog\">catalog<a>");

Change the servlet to call the encodeURL method before sending the URL to the output stream:
out.println("<a href=\"");
out.println(response.encodeURL ("/store/catalog"));
out.println("\">catalog</a>");

Rewrite URLs to redirect

Suppose you currently have the following statement:

response.sendRedirect ("http://myhost/store/catalog");

Change the servlet to call the encodeRedirectURL method before sending the URL to the output stream:
response.sendRedirect (response.encodeRedirectURL ("http://myhost/store/catalog"));

The encodeURL method and encodeRedirectURL method are part of the HttpServletResponse object.
These calls check to see if URL rewriting is configured before encoding the URL. If it is not configured, the
calls return the original URL.

If both cookies and URL rewriting are enabled and the response.encodeURL method or
encodeRedirectURL method is called, the URL is encoded, even if the browser making the HTTP request
processed the session cookie.

You can also configure session support to enable protocol switch rewriting. When this option is enabled,
the product encodes the URL with the session ID for switching between HTTP and HTTPS protocols.

Supply a servlet or JSP file as an entry point

The entry point to an application, such as the initial screen presented, may not require the use of
sessions. However, if the application in general requires session support (meaning some part of it, such as

Chapter 8. Developing WebSphere applications 981

a servlet, requires session support), then after a session is created, all URLs are encoded to perpetuate
the session ID for the servlet (or other application component) requiring the session support.

The following example shows how you can embed Java code within a JSP file:
<%
response.encodeURL ("/store/catalog");
%>

Session tracking with SSL information: No special programming is required to track sessions with
Secure Sockets Layer (SSL) information.

To use SSL information, turn on Enable SSL ID tracking in the session management property page.
Because the SSL session ID is negotiated between the Web browser and HTTP server, this ID cannot
survive an HTTP server failure. However, the failure of an application server does not affect the SSL
session ID if an external HTTP server is present between WebSphere Application Server and the browser.

SSL tracking is supported for the IBM HTTP Server and iPlanet Web servers only. You can control the
lifetime of an SSL session ID by configuring options in the Web server. For example, in the IBM HTTP
Server, set the configuration variable SSLV3TIMEOUT to provide an adequate lifetime for the SSL session
ID. An interval that is too short can cause a premature termination of a session. Also, some Web browsers
might have their own timers that affect the lifetime of the SSL session ID. These Web browsers may not
leave the SSL session ID active long enough to serve as a useful mechanism for session tracking. The
internal HTTP Server of WebSphere Application Server also supports SSL tracking.

When using the SSL session ID as the session tracking mechanism in a cloned environment, use either
cookies or URL rewriting to maintain session affinity. The cookie or rewritten URL contains session affinity
information that enables the Web server to properly route a session back to the same server for each
request.

Distributed sessions
WebSphere Application Server provides the following session mechanisms in a distributed environment:
v Database Session persistence, where sessions are stored in the database specified.
v Memory-to-memory Session replication, where sessions are stored in one or more specified
WebSphere Application Server instances.

When a session contains attributes that implement HttpSessionActivationListener, notification occurs

anytime the session is activated (that is, session is read to the memory cache) or passivated (that is,
session leaves the memory cache). Passivation can occur because of a server shutdown or when the
session memory cache is full and an older session is removed from the memory cache to make room for a
newer session. It is not guaranteed that a session is passivated in one application server prior to being
activated in another.

Session recovery support

For session recovery support, WebSphere Application Server provides distributed session support in the
form of database sessions and memory-to-memory replication. Use session recovery support under the
following conditions:
v When the user’s session data must be maintained across a server restart
v When the user’s session data is too valuable to lose through an unexpected server failure

All the attributes set in a session must implement java.io.Serializable if the session requires external
storage. In general, consider making all objects held by a session serialized, even if immediate plans do
not call for session recovery support. If the Web site grows, and session recovery support becomes
necessary, the transition occurs transparently to the application if the sessions only hold serialized objects.
If not, a switch to session recovery support requires coding changes to make the session contents
serialized.

982 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Distributed environment settings:

Use this page to specify a type for saving a session in a distributed environment.

To view this administrative console page, click Servers > Application servers > server_name > Web
container settings > Session management > Distributed environment settings.

Distributed sessions:

Specifies the type of distributed environment to be used for saving sessions.

None Specifies that the session management facility discards

the session data when the server shuts down.
Database Specifies that the session management facility stores
session information in the data source specified by the
data source connection settings. Click Database to
change these data source settings.
Memory-to-memory replication Specifies that the session management facility stores the
session information in a data source in memory. The
session information is copied to other session
management facilities for failure recovery.

Memory-to-memory replication
WebSphere Application Server supports session replication to another WebSphere Application Server
instance. This support is referred to as memory-to-memory session replication. In this mode, sessions can
replicate to one or more WebSphere Application Server instances to address HTTP Session single point of
failure (SPOF).

The WebSphere Application Server instance in which the session is currently processed is referred to as
the owner of the session. In a clustered environment, session affinity in the WebSphere Application Server
plug-in routes the requests for a given session to the same server. If the current owner server instance of
the session fails, then the WebSphere Application Server plug-in routes the requests to another
appropriate server in the cluster. In a peer-to-peer cluster, the hot failover feature causes the plug-in to
failover to a server that already contains the backup copy of the session, avoiding the overhead of session
retrieval from another server containing the backup. In a client/server cluster, the server retrieves the
session from a server that has the backup copy of the session. The server now becomes the owner of the
session and affinity is now maintained to this server.

There are three possible modes. You can set up a WebSphere Application Server instance to run in:
v Server mode: Only store backup copies of other WebSphere Application Server sessions and not to
send out copies of any session created in that particular server
v Client mode: Only broadcast or send out copies of the sessions it owns and not to receive backup
copies of sessions from other servers
v Both mode: Simultaneously broadcast or send out copies of the sessions it owns and act as a backup
table for sessions owned by other WebSphere Application Server instances

You can select the replication mode of server, client, or both when configuring the session management
facility for memory-to-memory replication. The default is both. This storage option is controlled by the
mode parameter.

The memory-to-memory replication function is accomplished by the creation of a data replication service
instance in an application server that talks to other data replication service instances in remote application
servers. You must configure this data replication service instance as a part of a replication domain. Data
replication service instances on disparate application servers that replicate to one another must be
configured as a part of the same domain. You must configure all session managers connected to a
replication domain to have the same topology. If one session manager instance in a domain is configured

Chapter 8. Developing WebSphere applications 983

to use the client/server topology, then the rest of the session manager instances in that domain must be a
combination of servers configured as Client only and Server only. If one session manager instance is
configured to use the peer-to-peer topology, then all session manager instances must be configured as
Both client and server. For example, a server only data replication service instance and a both client and
server data replication service instance cannot exist in the same replication domain. Multiple data
replication service instances that exist on the same application server due to session manager
memory-to-memory configuration at various levels that are configured to be part of the same domain must
have the same mode.

With respect to mode, the following are the primary examples of memory-to-memory replication
configuration:
v Peer-to-peer replication
v Client/server replication

Although the administrative console allows flexibility and additional possibilities for memory-to-memory
replication configuration, only the configurations provided above are officially supported.

There is a single replica in a cluster by default. You can modify the number of replicas through the
replication domain.

Memory-to-memory topology: Peer-to-peer function:

The basic peer-to-peer (both client and server function, or both mode) topology is the default configuration
and has a single replica. However, you can also add additional replicas by configuring the replication
domain.

Local

Backup

HTTP servers
with affinity

Local
Replication Domain

Backup

HTTP servers
with affinity

Local

Backup

In this basic peer-to-peer topology, each server Java Virtual Machine (JVM) can:
v Host the Web application leveraging the HTTP session
v Send out changes to the HTTP session that it owns

984 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Receive backup copies of the HTTP session from all of the other servers in the cluster

This configuration represents the most consolidated topology, where the various system parts are
collocated and requires the fewest server processes. When using this configuration, the most stable
implementation is achieved when each node has equal capabilities (CPU, memory, and so on), and each
handles the same amount of work.

Session hot failover

A new feature called session hot failover has been added to this release. This feature is only applicable to
the peer-to-peer mode. In a clustered environment, session affinity in the WebSphere Application Server
plug-in routes the requests for a given session to the same server. If the current owner server instance of
the session fails, then the WebSphere Application Server plug-in routes the requests to another
appropriate server in the cluster. For a cluster configured to run in the peer-to-peer mode this feature
causes the plug-in to failover to a server that already contains the backup copy of the session, therefore
avoiding the overhead of session retrieval from another server containing the backup.

You must upgrade all WebSphere Application Server plug-in instances that front the Application Server
cluster to version 6.0 to ensure session affinity when using the peer-to-peer mode.

Memory-to-memory topology: Client/server function: The following figure depicts the client/server
mode. There is a tier of applications servers that host Web applications using HTTP sessions, and these
sessions are replicated out as they are created and updated. There is a second tier of servers without a
Web application installed, where the session manager receives updates from the replication clients.

WebSphere Application Server

servers including HTTP sessions
with local tables.

WebSphere Application Server

servers including HTTP sessions
with backup tables.
Local

Backup

HTTP servers
with affinity

Local
Replication Domain

HTTP servers
with affinity
Backup
Local

Benefits of the client/server configuration include:

Isolation (for failure recovery)
In this case we are isolating the handling of backup data from local data; aside from isolating the

Chapter 8. Developing WebSphere applications 985

 moving parts in case of a catastrophic failure in one of them, you again free up memory and
processing in the servers processing the Web application
Isolation for stopping and starting
You can recycle a backup server without affecting the servers running the application (when there
are two or more backups, failure recovery is possible), and conversely recycle an application JVM
without potentially losing that backup data for someone.
Consolidation
There is most likely no need to have a one-to-one correspondence between servers handling
backups and those processing the applications; hence, you are again reducing the number of
places to which you transfer the data.
Disparate hardware:
While you run your Web applications on cheaper hardware, you may have one or two more
powerful computers in the back end of your enterprise that have the capacity to run a couple of
session managers in replication server mode; allowing you to free up your cheaper Web
application hardware to process the Web application.

Timing consideration: Start the backup application servers first to avoid unexpected timing windows. The
clients attempt to replicate information and HTTP sessions to the backup servers as soon as they come
up. As a result, HTTP sessions that are created prior to the time at which the servers come up might not
replicate successfully.

Memory-to-memory session partitioning

Session partitioning gives the administrator the ability to filter or reduce the number of destinations that the
session object gets sent to by the replication service. You can also configure session partitioning by
specifying the number of replicas on the replication domain. The Single replica option is chosen by default.
Since the number of replicas is global for the entire replication domain, all the session managers
connected to the replication domain use the same setting.
Single replica
You can replicate a session to only one other server, creating a single replica. When this option is
chosen, a session manager picks another session manager that is connected to the same
replication domain to replicate the HTTP session to during session creation. All updates to the
session are only replicated to that single server. This option is set at the replication domain level.
When this option is set, every session manager connected to this replication domain creates a
single backup copy of HTTP session state information on a backup server.
Full group replica
Each object is replicated to every application server that is configured as a consumer of the
replication domain. However, this topology is the most redundant because everyone replicates to
everyone and as you add servers, more overhead (both CPU and memory) is needed to deal with
replication. This mode is most useful for dynamic caching replication.
Specific number of replicas
You can specify a specific number of replicas for any entry that is created in the replication
domain. The number of replicas is the number of application servers that the user wants to use to
replicate in the domain. This option eliminates redundancy that occurs in a full group replica and
also provides additional backup than a single replica. The number of replicas cannot exceed the
total number of application servers in the cluster.

Clustered session support

A clustered environment supports load balancing, where the workload is distributed among the application
servers that compose the cluster. In a cluster environment, the same Web application must exist on each
of the servers that can access the session. You can accomplish this setup by installing an application onto
a cluster definition. Each of the servers in the group can then access the Web application

986 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
In a clustered environment, the session management facility requires an affinity mechanism so that all
requests for a particular session are directed to the same application server instance in the cluster. This
requirement conforms to the Servlet 2.3 specification in that multiple requests for a session cannot coexist
in multiple application servers. One such solution provided by IBM WebSphere Application Server is
session affinity in a cluster; this solution is available as part of the WebSphere Application Server plug-ins
for Web servers. It also provides for better performance because the sessions are cached in memory. In
clustered environments other than WebSphere Application Server clusters, you must use an affinity
mechanism (for example, IBM WebSphere Edge Server affinity).

If one of the servers in the cluster fails, it is possible for the request to reroute to another server in the
cluster. If distributed sessions support is enabled, the new server can access session data from the
database or another WebSphere Application Server instance. You can retrieve the session data only if a
new server has access to an external location from which it can retrieve the session.

Tuning session management

WebSphere Application Server session support has features for tuning session performance and operating
characteristics, particularly when sessions are configured in a distributed environment. These options
support the administrator flexibility in determining the performance and failover characteristics for their
environment.

The table summarizes the features, including whether they apply to sessions tracked in memory, in a
database, with memory-to-memory replication, or all. Click a feature for details about the feature. Some
features are easily manipulated using administrative settings; others require code or database changes.

Feature or option Goal Applies to sessions in memory,

database, or memory-to-memory
Write frequency Minimize database write operations. Database and Memory-to-Memory
Session affinity Access the session in the same All
application server instance.
Multirow schema Fully utilize database capacities. Database
Base in-memory session pool size Fully utilize system capacity without All
overburdening system.
Write contents Allow flexibility in determining what Database and Memory-to-Memory
session data to write
Scheduled invalidation Minimize contention between session Database and Memory-to-Memory
requests and invalidation of sessions
by the Session Management facility.
Minimize write operations to database
for updates to last access time only.
Tablespace and row size Increase efficiency of write operations Database (DB2 only)
to database.

Base in-memory session pool size: The base in-memory session pool size number has different
meanings, depending on session support configuration:
v With in-memory sessions, session access is optimized for up to this number of sessions.
v With distributed sessions (meaning, when sessions are stored in a database or in another WebSphere
Application Server instance); it also specifies the cache size and the number of last access time
updates saved in manual update mode.

For distributed sessions, when the session cache has reached its maximum size and a new session is
requested, the Session Management facility removes the least recently used session from the cache to
make room for the new one.

Chapter 8. Developing WebSphere applications 987

General memory requirements for the hardware system, and the usage characteristics of the e-business
site, determines the optimum value.

Note that increasing the base in-memory session pool size can necessitate increasing the heap sizes of
the Java processes for the corresponding WebSphere Application Servers.

Overflow in non-distributed sessions

By default, the number of sessions maintained in memory is specified by base in-memory session pool
size. If you do not wish to place a limit on the number of sessions maintained in memory and allow
overflow, set overflow to true.

Allowing an unlimited amount of sessions can potentially exhaust system memory and even allow for
system sabotage. Someone could write a malicious program that continually hits your site and creates
sessions, but ignores any cookies or encoded URLs and never utilizes the same session from one HTTP
request to the next.

When overflow is disallowed, the Session Management facility still returns a session with the
HttpServletRequest getSession(true) method when the memory limit is reached, and this is an invalid
session that is not saved.

With the WebSphere Application Server extension to HttpSession,

com.ibm.websphere.servlet.session.IBMSession, an isOverflow method returns true if the session is such
an invalid session. An application can check this status and react accordingly.

Tuning parameter settings:

Use this page to set tuning parameters for distributed sessions.

To view this administrative console page, click Servers > Application servers >server_name> Web
container settings > Session management >Distributed environment settings >Custom tuning
parameters.

Tuning level:

Specifies that the session management facility provides certain predefined settings that affect
performance.

Select one of these predefined settings or customize a setting. To customize a setting, select one of the
predefined settings that comes closest to the setting desired, click Custom settings, make your changes,
and then click OK.

Very high (optimize for performance)

Write frequency Time based

Write interval 300 seconds
Write contents Only updated attributes
Schedule sessions cleanup true
First time of day default 0
Second time of day default 2

High

Write frequency Time based

Write interval 300 seconds

988 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Write contents All session attributes
Schedule sessions cleanup false

Medium

Write frequency End of servlet service

Write contents Only updated attributes
Schedule sessions cleanup false

Low (optimize for failover)

Write frequency End of servlet service

Write contents All session attributes
Schedule sessions cleanup false

Custom settings

Write frequency default Time based

Write interval default 10 seconds
Write contents default All session attributes
Schedule sessions cleanup default false

Tuning parameter custom settings:

Use this page to customize tuning parameters for distributed sessions.

To view this administrative console page, click Servers > Application servers > server_nameWeb
container settings > Session management > Distributed environment settings > Custom tuning
parameters > Custom settings.

Write frequency:

Specifies when the session is written to the persistent store.

End of servlet service A session writes to a database or another WebSphere

Application Server instance after the servlet completes
execution.
Manual update A programmatic sync on the IBMSession object is required
to write the session data to the database or another
WebSphere Application Server instance.
Time based Session data writes to the database or another
WebSphere Application Server instance based on the
specified Write interval value. Default: 10 seconds

Write contents:

Specifies whether updated attributes are only written to the external location or all of the session attributes
are written to the external location, regardless of whether or not they changed. The external location can
be either a database or another application server instance.

Only updated attributes Only updated attributes are written to the persistent store.
All session attribute All attributes are written to the persistent store.

Chapter 8. Developing WebSphere applications 989

Schedule sessions cleanup:

Specifies when to clean the invalid sessions from a database or another application server instance.

Specify distributed sessions cleanup schedule Enables the scheduled invalidation process for cleaning
up the invalidated HTTP sessions from the external
location. Enable this option to reduce the number of
updates to a database or another application server
instance required to keep the HTTP sessions alive. When
this option is not enabled, the invalidator process runs
every few minutes to remove invalidated HTTP sessions.

When this option is enabled, specify the two hours of a

day for the process to clean up the invalidated sessions in
the external location. Specify the times when there is the
least activity in the application servers. An external
location can be either a database or another application
server instance.
First Time of Day (0 - 23) Indicates the first hour during which the invalidated
sessions are cleared from the external location. Specify
this value as a positive integer between 0 and 23. This
value is valid only when schedule invalidation is enabled.
Second Time of Day (0 - 23) Indicates the second hour during which the invalidated
sessions are cleared from the external location. Specify
this value as a positive integer between 0 and 23. This
value is valid only when schedule invalidation is enabled.

Best practices for using HTTP Sessions

v Enable Security integration for securing HTTP sessions
HTTP sessions are identified by session IDs. A session ID is a pseudo-random number generated at the
runtime. Session hijacking is a known attack HTTP sessions and can be prevented if all the requests
going over the network are enforced to be over a secure connection (meaning, HTTPS). But not every
configuration in a customer environment enforces this constraint because of the performance impact of
SSL connections. Due to this relaxed mode, HTTP session is vulnerable to hijacking and because of
this vulnerability, WebSphere Application Server has the option to tightly integrate HTTP sessions and
WebSphere Application Server security. Enable security in WebSphere Application Server so that the
sessions are protected in a manner that only users who created the sessions are allowed to access
them.
v Release HttpSession objects using javax.servlet.http.HttpSession.invalidate() when finished.
HttpSession objects live inside the Web container until:
– The application explicitly and programmatically releases it using the
javax.servlet.http.HttpSession.invalidate method; quite often, programmatic invalidation is part of an
application logout function.
– WebSphere Application Server destroys the allocated HttpSession when it expires (default = 1800
seconds or 30 minutes). The WebSphere Application Server can only maintain a certain number of
HTTP sessions in memory based on session management settings. In case of distributed sessions,
when maximum cache limit is reached in memory, the session management facility removes the
least recently used (LRU) one from cache to make room for a session.
.
v Avoid trying to save and reuse the HttpSession object outside of each servlet or JSP file.
The HttpSession object is a function of the HttpRequest (you can get it only through the req.getSession
method), and a copy of it is valid only for the life of the service method of the servlet or JSP file. You
cannot cache the HttpSession object and refer to it outside the scope of a servlet or JSP file.
v Implement the java.io.Serializable interface when developing new objects to be stored in the
HTTP session.

990 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 This action allows the object to properly serialize when using distributed sessions. Without this
extension, the object cannot serialize correctly and throws an error. An example of this follows:
public class MyObject implements java.io.Serializable {...}
Make sure all instance variable objects that are not marked transient are serializable.
v The HTTPSession API does not dictate transactional behavior for sessions.
Distributed HTTPSession support does not guarantee transactional integrity of an attribute in a failover
scenario or when session affinity is broken. Use transactional aware resources like enterprise Java
beans to guarantee the transaction integrity required by your application.
v Ensure the Java objects you add to a session are in the correct class path.
If you add Java objects to a session, place the class files for those objects in the correct class path (the
application class path if utilizing sharing across Web modules in an enterprise application, or the Web
module class path if using the Servlet 2.2-complaint session sharing) or in the directory containing other
servlets used in WebSphere Application Server. In the case of session clustering, this action applies to
every node in the cluster.
Because the HttpSession object is shared among servlets that the user might access, consider adopting
a site-wide naming convention to avoid conflicts.
v Avoid storing large object graphs in the HttpSession object.
In most applications each servlet only requires a fraction of the total session data. However, by storing
the data in the HttpSession object as one large object, an application forces WebSphere Application
Server to process all of it each time.
v Utilize Session Affinity to help achieve higher cache hits in the WebSphere Application Server.
WebSphere Application Server has functionality in the HTTP Server plug-in to help with session affinity.
The plug-in reads the cookie data (or encoded URL) from the browser and helps direct the request to
the appropriate application or clone based on the assigned session key. This functionality increases use
of the in-memory cache and reduces hits to the database or another WebSphere Application Server
instance
v Maximize use of session affinity and avoid breaking affinity.
Using session affinity properly can enhance the performance of the WebSphere Application Server.
Session affinity in the WebSphere Application Server environment is a way to maximize the in-memory
cache of session objects and reduce the amount of reads to the database or another WebSphere
Application Server instance. Session affinity works by caching the session objects in the server instance
of the application with which a user is interacting. If the application is deployed in multiple servers of a
server group, the application can direct the user to any one of the servers. If the users starts on server1
and then comes in on server2 a little later, the server must write all of the session information to the
external location so that the server instance in which server2 is running can read the database. You can
avoid this database read using session affinity. With session affinity, the user starts on server1 for the
first request; then for every successive request, the user is directed back to server1. Server1 has to
look only at the cache to get the session information; server1 never has to make a call to the session
database to get the information.
You can improve performance by not breaking session affinity. Some suggestions to help avoid breaking
session affinity are:
– Combine all Web applications into a single application server instance, if possible, and use modeling
or cloning to provide failover support.
– Create the session for the frame page, but do not create sessions for the pages within the frame
when using multi-frame JSP files. (See discussion later in this topic.)
v When using multi-framed pages, follow these guidelines:
– Create a session in only one frame or before accessing any frame sets. For example, assuming
there is no session already associated with the browser and a user accesses a multi-framed JSP file,
the browser issues concurrent requests for the JSP files. Because the requests are not part of any
session, the JSP files end up creating multiple sessions and all of the cookies are sent back to the
browser. The browser honors only the last cookie that arrives. Therefore, only the client can retrieve
the session associated with the last cookie. Creating a session before accessing multi-framed pages
that utilize JSP files is recommended.

Chapter 8. Developing WebSphere applications 991

 – By default, JSP files get a HTTPSession using request.getSession(true) method. So by default
JSP files create a new session if none exists for the client. Each JSP page in the browser is
requesting a new session, but only one session is used per browser instance. A developer can use
<% @ page session=″false″ %> to turn off the automatic session creation from the JSP files that do
not access the session. Then if the page needs access to the session information, the developer can
use <%HttpSession session = javax.servlet.http.HttpServletRequest.getSession(false); %> to
get the already existing session that was created by the original session creating JSP file. This
action helps prevent breaking session affinity on the initial loading of the frame pages.
– Update session data using only one frame. When using framesets, requests come into the HTTP
server concurrently. Modifying session data within only one frame so that session changes are not
overwritten by session changes in concurrent frameset is recommended.
– Avoid using multi-framed JSP files where the frames point to different Web applications. This action
results in losing the session created by another Web application because the JSESSIONID cookie
from the first Web application gets overwritten by the JSESSIONID created by the second Web
application.
v Secure all of the pages (not just some) when applying security to servlets or JSP files that use
sessions with security integration enabled, .
When it comes to security and sessions, it is all or nothing. It does not make sense to protect access to
session state only part of the time. When security integration is enabled in the session management
facility, all resources from which a session is created or accessed must be either secured or unsecured.
You cannot mix secured and unsecured resources.
The problem with securing only a couple of pages is that sessions created in secured pages are
created under the identity of the authenticated user. Only the same user can access sessions in other
secured pages. To protect these sessions from use by unauthorized users, you cannot access these
sessions from an unsecured page. When a request from an unsecured page occurs, access is denied
and an UnauthorizedSessionRequestException error is created. (UnauthorizedSessionRequestException
is a runtime exception; it is logged for you.)
v Use manual update and either the sync() method or time-based write in applications that read
session data, and update infrequently.
With END_OF_SERVICE as write frequency, when an application uses sessions and anytime data is
read from or written to that session, the LastAccess time field updates. If database sessions are used, a
new write to the database is produced. This activity is a performance hit that you can avoid using the
Manual Update option and having the record written back to the database only when data values
update, not on every read or write of the record.
To use manual update, turn it on in the session management service. (See the tables above for location
information.) Additionally, the application code must use the
com.ibm.websphere.servlet.session.IBMSession class instead of the generic HttpSession. Within the
IBMSession object there is a sync method. This method tells the WebSphere Application Server to write
the data in the session object to the database. This activity helps the developer to improve overall
performance by having the session information persist only when necessary.

Note: An alternative to using the manual updates is to utilize the timed updates to persist data at
different time intervals. This action provides similar results as the manual update scheme.
v Implement the following suggestions to achieve high performance:
– If your applications do not change the session data frequently, use Manual Update and the sync
function (or timed interval update) to efficiently persist session information.
– Keep the amount of data stored in the session as small as possible. With the ease of using sessions
to hold data, sometimes too much data is stored in the session objects. Determine a proper balance
of data storage and performance to effectively use sessions.
– If using database sessions, use a dedicated database for the session database. Avoid using the
application database. This helps to avoid contention for JDBC connections and allows for better
database performance.
– If using memory-to-memory sessions, employ partitioning (either group or single replica) as your
clusters grow in size and scaling decreases.
– Verify that you have the latest fix packs for the WebSphere Application Server.

992 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Utilize the following tools to help monitor session performance.
– Run the com.ibm.servlet.personalization.sessiontracking.IBMTrackerDebug servlet. - To run this
servlet, you must have the servlet invoker running in the Web application you want to run this from.
Or, you can explicitly configure this servlet in the application you want to run.
– Use the WebSphere Application Server Resource Analyzer which comes with WebSphere Application
Server to monitor active sessions and statistics for the WebSphere Application Server environment.
– Use database tracking tools such as ″Monitoring″ in DB2. (See the respective documentation for the
database system used.)

Managing HTTP sessions: Resources for learning

Use the following links to find relevant supplemental information about HTTP sessions. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of the
information.

These links are provided for convenience. Often, the information is not specific to the WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

View links to additional information about:

Programming model and decisions

v Best practices
v HTTP Session Persistence Best Practices
v Improving session persistence performance with DB2
v Persistent client state HTTP cookies specification

Programming instructions and examples

v Java Servlet documentation, tutorials, and examples site

Programming specifications
v Java Servlet 2.4 API specification download site
v J2EE 1.4 specification download site

Modifying the default Web container configuration

The Web container is created initially with default properties values suitable for simple Web applications.
However, these values might not be appropriate for more complex Web applications.

Your application is considered complex if it requires any of the following features:

v Virtual host
v Servlet caching
v Special client request loads
v Persistent HTTP session support
v Special HTTP transport settings
v Transaction class mappings

Make the following configuration changes if you have a complex application:

1. In the administrative console, click Servers > Application servers >server_name. Then under Web
container settings, click on one of the following:
a. Web container, if your Web application requires a virtual host, other than the default_host, or
requires servlet caching.
b. Web container transport chains, if you need to reconfigure your HTTP connections.
c. Session management, if your application requires persistent HTTP session support.

Chapter 8. Developing WebSphere applications 993

2. If your application handles special client request loads, in the administrative console, click Servers >
Application servers >server_name. Then under Additional Properties, click Thread Pools to modify
your thread pool settings.
3. If your application requires global settings for internal servlets for WAR files packaged by third-party
tools, iIn the administrative console, click Servers > Application servers >server_name > Web
container settings > Web container. Then under Additional Properties, click Custom Properties and
enter the appropriate custom property.

Web container
A Web container handles requests for servlets, JavaServer Pages (JSP) files, and other types of files that
include server-side code. The Web container creates servlet instances, loads and unloads servlets,
creates and manages request and response objects, and performs other servlet management tasks.

The Web server plug-ins, provided by the WebSphere Application Server, help supported Web servers
pass servlet requests to Web containers.

Web container settings

Use this page to configure the Web container settings.

To view this administrative console page, click Servers > Application servers > server_instance > Web
container settings > Web container.

Default virtual host:

Specifies a virtual host that enables a single host machine to resemble multiple host machines. Resources
associated with one virtual host cannot share data with resources associated with another virtual host,
even if the virtual hosts share the same physical machine.

Select a virtual host option:

default_host
The product provides a default virtual host with some common aliases, such as the machine IP
address, short host name, and fully qualified host name. The alias comprises the first part of the
path for accessing a resource such as a servlet. For example, it is localhost:9080 in the request
http://localhost:9080/myServlet.
admin_host
This is another name for the application server; also known as server1 in the base installation.
This process supports the use of the administrative console.

Enable servlet caching:

Specifies that if a servlet is invoked once and it generates output to be cached, a cache entry is created
containing not only the output, but also side effects of the invocation. These side effects can include calls
to other servlets or Java Server Pages (JSP) files, as well as metadata about the entry, including timeout
and entry priority information.

Web module deployment settings

Use this page to configure an instance of Web module deployment.

To view this administrative console page, click Applications > Enterprise Application >
application_instance > Web modules > Web_module_instance.

URI:

994 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies a URI that, when resolved relative to the application URL, specifies the location of the module
archive contents on a file system. The URI must match the ModuleRef URI in the deployment descriptor of
an application if the module was packaged as part of a deployed application or enterprise archive (EAR)
file.

Alternate deployment descriptor:

Specifies the file name for an alternative deployment descriptor file to use instead of the original
deployment descriptor file in the module JAR file.

This file is the post-assembly version of the deployment descriptor file. You can edit the original
deployment descriptor file to resolve dependencies and security information. Specifying the use of the
alternative deployment descriptor keeps the original deployment descriptor file intact.

The value of the Alternate deployment descriptor property must be the full path name of the deployment
descriptor file, relative to the module root directory. By convention, the file is in the ALT-INF directory. If this
property is not specified, the deployment descriptor file is read from the module JAR file.

Starting weight:

Specifies the order in which modules are started. Lower weighted modules are started before higher
weighted modules.

Class loader mode:

Specifies whether the class loader should search in the parent class loader or in the application class
loader first to load a class. The standard for JDK class loaders and WebSphere class loaders is Parent
First. By specifying Parent Last, your application can override classes contained in the parent class loader,
but this action can potentially result in ClassCastException or LinkageErrors if you have mixed use of
overriden classes and non-overriden classes.

The options are Parent First and Parent Last. The default is to search in the parent class loader before
searching in the application class loader to load a class.

Data type String

Default Parent First

Web container custom properties

Use this page to configure arbitrary name-value pairs of data, where the name is a property key and the
value is a string value that you can use to set internal system configuration properties. Defining a new
property enables you to configure a setting beyond that which is available in the administrative console.

To view this administrative console page, click Servers > Application servers >server_name > Web
container settings > Web container > Custom properties.

HTTP Transport custom properties can also be set at the Web container level. See HTTP transport custom
properties for a description of these properties.

Name:

Specifies the name or key for the property.

Value:

Specifies the value that is paired with the specified name.

Chapter 8. Developing WebSphere applications 995

Data type String

Description:

Specifies information about the name-value pair.

Data type String

Global settings for internal servlets

Web application archive (WAR) files that are packaged using third-party tools cannot specify behavior for
the services that are exposed by the Web container internal servlets. You can globally enable and disable
internal servlets for all Web applications at the Web container level by creating name-value pairs such as:

Name Value
fileServingEnabled true
directoryBrowsingEnabled true
serveServletsByClassnameEnabled true

Settings that are defined in an assembly tool take precedence over the global settings that are set through
the custom properties at the Web container level.

Web application deployment extensions continue to hold configuration information for the services that are
provided by the internal servlets, and take precedence over the global settings that are set through the
custom properties at the Web container level.

UTF-8 encoded URLs

The UTF-8 encoded URL feature, which provides UTF-8 encoded Uniform Resource Locators (URLs) to
support the double-byte characters in URLs is enabled by default. You can prevent the Web container from
explicitly decoding URLs in UTF-8 and have them use the ISO-8859 standard as per the current HTTP
specification by using the following name-value pair:

Name Value
DecodeUrlAsUTF8 false

Global configuration of servlet listeners

The servlet specification supports applications registering listeners for servlet-related events on an
individual application basis through the web.xml descriptor. However, using the listeners custom property, a
server can listen to servlet events across Web applications. To implement global listening, a listener is
registered at the Web container level and is propagated to all of the installed and new Web applications.
This global behavior of internal servlet listeners is controlled by the listeners custom property by using the
following name-value pair format:

Name Value
listeners listener_class

The values for this property is a string specifying a comma separated list of listener classes. The listener
supplied must implement standard listener classes from the Java Servlet API or IBM listener extension
classes.

996 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Binary Large Object (BLOB) data type for Oracle databases

The UseOracleBLOB custom property creates the HTTP session database table using the Binary Large
Object (BLOB) data type for the medium column. This property increases performance of persistent
sessions when Oracle databases are used. Due to an Oracle restriction, BLOB support requires use of the
Oracle’s oci database driver for more than 4000 bytes of data. You must also ensure that a new sessions
table is created before the server is restarted by dropping your old sessions table or by changing the
datasource definition to reference a database that does not contain a sessions table. To create a sessions
table using the BLOB data type, use the following name-vaule pair:

Name Value
UseOracleBLOB true

Detecting Session Data Crossover

The DebugSessionCrossover custom property enables code to perform additional checks to verify that
only the session associated with the request is accessed or referenced. Messages are logged if any
discrepancies are detected. To enable session data crossover detection, use the following name-vaule
pair:

Name Value
DebugSessionCrossover true

See article, ″Problems creating or using HTTP sessions″, for additional information.

Optimizing web services client to Web container communication

To improve performance, there is an optimized communication path between a Web services client
application and a Web container that are located in the same application server process. Requests from
the Web services client that are normally sent to the Web container using a network connection are
delivered directly to the Web container using an optimized local path. The local path is available because
the Web services client application and the Web container are running in the same process. This
optimized communication path is disabled by default. Before enabling this property, make sure that wild
cards are not specified for the Web container ports. Use specific ports for the web container when the
optimized communication path is enabled. To enable the optimized communication path, use the following
name-value pair:

Name Value
enableInProcessConnections true

See article, “Web services client to Web container optimized communication” on page 266, for additional
information.

Transaction class mapping file entries

Following is the syntax for entries in a transaction class mapping file:
TransClassMap host:port uritemplate tclass

where:
host Is the value compared against the hostname of the HOST: header of the request. This value can
be a wildcard ’*’.

Note: A value of ’*’ for the host:port value is acceptable and is equivalent to ’*:*’.

Chapter 8. Developing WebSphere applications 997

port Is the value compared against the port of the request. This value can be a wildcard ’*’.
uritemplate
Is the value compared against the URI of the request. Any query string will not be used in the
comparison. This value can be a wildcard ’*’, or end in a wildcard.
tclass Is the Workload Manager Transaction Class name that will be used in the creation of the enclave.

Examples:
TransClassMap www.ibm.com:80 /webap1/myservlet TCLASS1

TransClassMap www.ibm.com:* /webap1/myservlet TCLASS2

TransClassMap *:443 * TCLASS3

TransClassMap *:* /webap1/myservlet TCLASS4

TransClassMap www.ibm.com:* /webap2/* TCLASS5

TransClassMap * /myservlet TCLASS6

TransClassMap * * TCLASS6

Configuring session management by level

When you configure session management at the Web container level, all applications and the respective
Web modules in the Web container normally inherit that configuration, setting up a basic default
configuration for the applications and Web modules below it.

However, you can set up different configurations individually for specific applications and Web modules
that vary from the Web container default. These different configurations override the default for these
applications and Web modules only.

Note: When you overwrite the default session management settings on the application level, all the Web
modules below that application inherit this new setting unless they too are set to overwrite these
settings.
1. Open the Administrative console.
2. Select the level that this configuration applies to:
v For the web container level:
a. Click Servers > Application Servers.
b. Select a server from the list of application servers.
c. Under Additional Properties, click Web Container.
v For the enterprise application level:
a. Click Applications > Applications.
b. Select an applications from the list of applications.
v For the Web module level:
a. Click Applications > Enterprise Applications.
b. Select an applications from the list of applications.
c. Under Related Items, click Web Modules.
d. Select a Web module from the list of Web modules defined for this application.
3. Under Additional Properties, click Session Management.
4. Make whatever changes you need to manage sessions
5. If you are working on the Web module or application level and want these settings to override the
inherited Session Management settings, under General Properties, select Overwrite.
6. Click Apply and Save.

998 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring session tracking
To configure session tracking, complete the following:
1. Go to the appropriate level of Session Management.
2. Specify which session tracking mechanism you want to pass the session ID between the browser and
the servlet:
v To track sessions with cookies, click Enable Cookies.
To change the cookie settings, click Modify.
v To track sessions with URL rewriting, click Enable URL Rewriting.
If you want to enable protocol switch rewriting, click Enable protocol switch rewriting.
v To track sessions with SSL information, click Enable SSL ID tracking.
3. Click Apply.
4. Click Save.
5. Define the session recovery characteristics.

Serializing access to session data

The Servlet API supports concurrent access to a session in a given server instance. WebSphere
Application Server provides an option to prevent the concurrent access to a session in a given server
instance so that concurrent modification of a session does not occur in a given server instance. This
prevention is achieved by synchronizing the requests based on session. When this feature is turned on, a
session is obtained for the request before invoking the servlet and requests are synchronized by locking
the session for the servlet execution time. Note that synchronization is based on the memory copy of
session. So this feature cannot serialize requests across servers based on session when session affinity
fails.

Restriction: Use this feature only when concurrent modification of the same session data is possible and
is not desirable by the application. This feature has overhead of serializing the requests based on a
session.

Do the following to synchronize session access:

1. Select the level of Session Management on which you want to serialize session access.
2. Under Serialize Session access, click Allow serial access.
3. In the Maximum wait time box, type the amount of time, in milliseconds, a servlet waits on a session
before continuing execution. The default is 120000 milliseconds or two minutes.
4. Select Allow access on timeout if you want the servlet to gain access to the session and continue
normal execution even if the session is still locked by another servlet. If you do not select this box, the
servlet execution will abort when the session request times out.
5. Click Apply.
6. Click Save.

Session management settings

Use this page to manage HTTP session support. This support includes specifying a session tracking
mechanism, setting maximum in-memory session count, controlling overflow, and configuring session
timeout.

To view this administrative console page, click Servers > Application servers > server_name > Web
container settings > Session management.

Override session management:

Specifies whether or not these session management settings take precedence over those normally
inherited from a higher level for the current application or web module.

Chapter 8. Developing WebSphere applications 999

By default, web modules inherit session management settings from the application level above it, and
applications inherit session management settings from the Web container level above it.

Session tracking mechanism:

Specifies a mechanism for HTTP session management.

Mechanism Function Default

Enable SSL ID Tracking Specifies that session tracking uses 9600 seconds
Secure Sockets Layer (SSL)
information as a session ID. Enabling
SSL tracking takes precedence over
cookie-based session tracking and
URL rewriting.

There are two parameters available if

you enable SSL ID tracking:
SSLV3Timeout and Secure
Authentication Service (SAS).
SSLV3Timeout specifies the time
interval after which SSL sessions are
renegotiated. This is a high setting
and modification does not provide any
significant impact on performance.
The SAS parameter establishes an
SSL connection only if it goes out of
the Java Virtual Machine (JVM) to
another JVM. If all the beans are
co-located within the same JVM, the
SSL used by SAS does not hinder
performance.

These are set by editing the

sas.server.properties and
sas.client.props files located in the
product_installation_root\properties
directory, where
product_installation_root is the
directory where WebSphere
Application Server is installed.

1000 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Enable cookies Specifies that session tracking uses
cookies to carry session IDs. If
cookies are enabled, session tracking
recognizes session IDs that arrive as
cookies and tries to use cookies for
sending session IDs. If cookies are
not enabled, session tracking uses
Uniform Resource Identifier (URL)
rewriting instead of cookies (if URL
rewriting is enabled).

Enabling cookies takes precedence

over URL rewriting. Do not disable
cookies in the session management
facility of the application server that is
running the administrative application
because this action causes the
administrative application not to
function after a restart of the server.
As an alternative, run the
administrative application in a
separate process from your
applications.

Click Modify to change these settings.

Enable URL rewriting Specifies that the session
management facility uses rewritten
URLs to carry the session IDs. If URL
rewriting is enabled, the session
management facility recognizes
session IDs that arrive in the URL if
the encodeURL method is called in
the servlet.
Enable protocol switch rewriting Specifies that the session ID is added
to a URL when the URL requires a
switch from HTTP to HTTPS or from
HTTPS to HTTP. If rewriting is
enabled, the session ID is required to
go between HTTP and HTTPS.

Maximum in-memory session count:

Specifies the maximum number of sessions to maintain in memory.

The meaning differs depending on whether you are using in-memory or distributed sessions. For
in-memory sessions, this value specifies the number of sessions in the base session table. Use the Allow
overflow property to specify whether to limit sessions to this number for the entire session management
facility or to allow additional sessions to be stored in secondary tables. For distributed sessions, this value
specifies the size of the memory cache for sessions. When the session cache has reached its maximum
size and a new session is requested, the session management facility removes the least recently used
session from the cache to make room for the new one.

Allow overflow:

Specifies that the number of sessions in memory can exceed the value specified by the Max in-memory
session count property. This option is valid only in non-distributed sessions mode.

Session timeout:

Chapter 8. Developing WebSphere applications 1001

Specifies how long a session can go unused before it is no longer valid. Specify either Set timeout or No
timeout. Specify the value in minutes greater than or equal to two.

The value specified in a web module deployment descriptor file takes precedence over the administrative
console settings. However, the value of this setting is used as a default when the session timeout is not
specified in a web module deployment descriptor. Note that to preserve performance, the invalidation timer
is not accurate to the second. When the write frequency is time based, ensure that this value is least twice
as large as the write interval.

Security integration:

Specifies that when security integration is enabled, the session management facility associates the identity
of users with their HTTP sessions

Serialize session access:

Specifies that concurrent session access in a given server is not allowed.

Maximum wait time Specifies the maximum amount of time a servlet request
waits on an HTTP session before continuing execution.
This parameter is optional and expressed in seconds. The
default is 120 seconds, or 2 minutes. Under normal
conditions, a servlet request waiting for access to an
HTTP session gets notified by the request that currently
owns the given HTTP session when the request finishes.
Allow access on timeout Specifies whether the servlet is executed normally or
aborted in the event of a timeout. If this box is checked,
the servlet executes normally. If this box is not checked,
the servlet execution aborts and error logs are generated.

Cookie settings
Use this page to configure cookie settings for session management.

To view this administrative console page, click Servers > Application servers > server_name > Web
container settings > Session management > Enable cookies.

Cookie name:

Specifies a unique name for the session management cookie. The servlet specification requires the name
JSESSIONID. However, for flexibility this value can be configured.

Restrict cookies to HTTP sessions:

Specifies that the session cookies include the secure field. Enabling the feature restricts the exchange of
cookies to HTTPS sessions only.

Cookie domain:

Specifies the domain field of a session tracking cookie. This value controls whether or not a browser
sends a cookie to particular servers. For example, if you specify a particular domain, session cookies are
sent to hosts in that domain. The default domain is the server.

Cookie path:

Specifies that a cookie is sent to the URL designated in the path. Specify any string representing a path
on the server. ″/″ indicates root directory. Specify a value to restrict the paths to which the cookie will be

1002 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
sent. By restricting paths, you prevent the cookie from going to certain URLs on the server. If you specify
the root directory, the cookie is sent no matter which path on the given server is accessed.

Cookie maximum age:

Specifies the amount of time that the cookie lives on the client browser. Specify that the cookie lives only
as long as the current browser session, or to a maximum age. If you choose the maximum age option,
specify the age in seconds. This value corresponds to the Time to Live (TTL) value described in the
Cookie specification.

Default is the current browser session which is equivalent to setting the value to -1.

Session management custom properties

Custom properties for session management:
CloneSeparatorChange
Use this property to maintain session affinity. The clone ID of the server is appended to session
identifier separated by colon. On some Wireless Application Protocol (WAP) devices, a colon is not
allowed. Set this property to ″true″ to change clone separator to a plus sign (+).
HttpSessionCloneId
Use this property to change the clone ID of the cluster member. Within a cluster, this name must
be unique to maintain session affinity. When set, this name overwrites the default name generated
by WebSphere Application Server. Default clone ID length: 8 or 9.
HttpSessionIdLength
Use this property to configure the session identifier length. Do not use an extremely low value;
using a low value results in reduced number of combinations possible, thereby increasing risk of
guessing the session identifier. In a cluster, all cluster members should be configured with same ID
length. Allowed range: 8 to 128. Default length: 23.
HttpSessionReaperPollInterval
Use this property to set a wake-up interval for the process that removes invalid sessions. Default
is based on maximum inactive interval set in session management. Allowed value: integer.
NoAdditionalSessionInfo
Set this value to ″true″ to force removal of information that is not needed in session identifiers. In
WebSphere Application Server base edition,a clone ID of -1 is never used; therefore, a clone ID is
not included in base edition when this is set. Also, cache ID is not used with nonpersistent
sessions; so the cache ID is not included with nonpersistent sessions when this value is set.
NoAffinitySwitchBack
Set this property to ″true″ to maintain affinity to the new member even after original one comes
back up. When a cluster member fails, its requests routed to a different cluster member, and
sessions are activated in that other member. Thus, session affinity is maintained to the new
member, and when failed cluster member comes back up, the requests for sessions that were
created in the original cluster member are routed back to it. Allowed values, true or false. Default:
false.
It is recommended that you set this property to ″true″ when distributed sessions with time-based
write is configured. Note that this property has no affect on the behavior when distributed sessions
is not enabled.
SessionIdentifierMaxLength
Use this value to set maximum length that a session identifier can grow. In a cluster, because of
fail-over when a request goes to new cluster member, session management appends a new clone
ID to the existing clone ID. In a large cluster, if for some reason servers are failing more often,
then it is possible that the session identifier length can be more than expected reducing room for
URL. So this property helps to find out the condition and take appropriate action to address
servers fail-over. When this is specified, message is logged when specified maximum length is
reached. Allowed value: integer.
SessionRewriteIdentifier
Use this property to change the key used with URL rewriting. Default key: jsessionid.

Chapter 8. Developing WebSphere applications 1003

Configuring session tracking for Wireless Application Protocol (WAP)
devices
Most Wireless Application Protocol (WAP) devices do not support cookies. The preferred way to track
sessions for WAP devices is to use URL rewriting. However on most WAP devices, the maximum allowed
URL length is 128 characters. With URL rewriting, a session indentifier is added to the URL itself,
effectively decreasing the space available for the actual URL and the number of parameters that can be
sent on a request.

To reduce the length of session identifier, you can configure key (jsessionid), session ID length and clone
ID. To make these configuration changes, complete the following:
1. Open the Administrative console.
2. Click Servers > Application Servers.
3. Select a server from the list of application servers.
4. Under Additional Properties, click Web Container
5. Under Additional Properties, click Custom Properties.
6. Add the appropriate properties from the following list:
v HttpSessionIdLength
v SessionRewriteIdentifier
v HttpSessionCloneId
v CloneSeparatorChange
v NoAdditionalSessionInfo
v SessionIdentifierMaxLength
7. Click Apply and Save.

Configuring for database session persistence

To configure the session management facility for database session persistence, complete the following:
1. Create and configure a JDBC provider.
2. Create a data source pointing to an existing database, using the JDBC provider that you defined.
Resources > JDBC Providers > JDBC_provider > Data Sources > New. The data source should be
non-JTA, for example, non-XA enabled. Note the JNDI name of the data source.
3. Verify that the correct database is listed for the value of the databaseName property under Data
Sources > datasource_name > Custom Properties. If necessary, contact your database
administrator to verify the correct database name.
4. Go to the appropriate level of Session Management.
5. Click Distributed Environment Settings
6. Select and click Database.
7. Specify the Data Source JNDI name from step 2.
8. Specify the database user ID and password for accessing the database.
9. Retype the password for confirmation.
10. Configure a table space and page sizes for DB2 session databases.
11. Switch to a multirow schema.
12. Click OK.
13. If you want to change the tuning parameters, click Custom Tuning Parameters and select a setting
or customize one.
14. Click Apply.
15. Click Save.

1004 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Switching to a multirow schema
By default, a single session maps to a single row in the database table used to hold sessions. With this
setup, there are hard limits to the amount of user-defined, application-specific data that WebSphere
Application Server can access.
1. Modify the Session Management facility properties to switch from single to multirow schema.
2. Manually drop the database table or delete all the rows in the database table that the product uses to
maintain HttpSession objects.
To drop the table:
a. Determine which data source configuration Session Management is using.
b. In the data source configuration, look up the database name.
c. Use the database facilities to connect to the database.
d. Drop the SESSIONS table.

Configuring tablespace and page sizes for DB2 session databases

If you are using DB2 for session persistence, you can increase the page size to optimize performance for
writing large amounts of data to the database. Page sizes of 8K, 16K, and 32K are supported.

To use a page size other than the default (4K), do the following:
1. If the SESSIONS table already exists, drop it from the DB2 database.
2. Create a new DB2 buffer pool and table space, specifying the same page size (8K, 16K or 32K) for
both, and assign the new buffer pool to this table space.
DB2 Connect to session
DB2 CREATE BUFFERPOOL sessionBP SIZE 1000 PAGESIZE 8K
DB2 Connect reset
DB2 Connect to session
DB2 CREATE TABLESPACE sessionTS PAGESIZE 8K MANAGED BY SYSTEM
USING (’D:\DB2\NODE0000\SQL00005\sessionTS.0’) BUFFERPOOL sessionBP
DB2 Connect reset
Refer to DB2 product documentation for details.
3. Configure the correct table space name and page size in the Session Management facility. Page size
is referred to as row size on the Session Management page.)

When the product is restarted, the Session Management facility creates the new SESSIONS table in the
specified tablespace based on the indicated page size.

Database settings
Use this page to specify the settings for database session support.

To view this administrative console page, click Servers > Application servers > server_name > Web
container settings > Session management > Distributed environment settings > Database.

Datasource JNDI name:

Specifies the datasource description.

The JNDI name of the non-XA enabled data source from which session management obtains database
connections. For example, if the JNDI name of the datasource is ″jdbc/sessions″, specify ″jdbc/sessions.″
The data source represents a pool of database connections and a configuration for that pool (such as the
pool size). The data source must already exist as a configured resource in the environment.

User ID:

Specifies the user ID for database access.

Chapter 8. Developing WebSphere applications 1005

Password:

Specifies the password for database access.

DB2 row size:

Specifies the table space page size configured for the sessions table, if using a DB2 database. Possible
values are 4, 8, 16, and 32 kilobytes (KB). The default row size is 4KB.

The default row size is 4KB. In DB2, it can be updated to a larger value. This can help database
performance in some environments. When this value is other than 4, you must specify table space name
to use this property. For 4KB pages, the table space name is optional.

Table space name:

Specifies that table space to be used for the sessions table.

This value is required when the DB2 page size is other than 4KB.

Use multi row schema:

Specifies that each instance of application data be placed in a separate row in the database, allowing
larger amounts of data to be stored for each session. This action can yield better performance in certain
usage scenarios. If using multirow schema is not enabled, instances of application data can be placed in
the same row.

Multirow schema considerations

WebSphere Application Server supports the use of a multirow schema option in which each piece of
application specific data is stored in a separate row of the database. With this setup, the total amount of
data you can place in a session is now bound only by the database capacities. The only practical limit that
remains is the size of the session attribute object.

The multirow schema potentially has performance benefits in certain usage scenarios, such as when larger
amounts of data are stored in the session but only small amounts are specifically accessed during a given
servlet processing of an HTTP request. In such a scenario, avoiding unneeded Java object serialization is
beneficial to performance.

Understand that switching between multirow and single row is not a trivial proposition.

In addition to allowing larger session records, using multirow schema can yield performance benefits.
However, it requires a little work to switch from single-row to multirow schema, as shown in the
instructions below.

Coding considerations and test environment

Consider configuring direct single-row usage to one database and multirow usage to another database
while you verify which option suits your application needs. (Do this in code by switching the data source
used; then monitor performance.)

Programming issue Application scenario

Reasons to use single-row v You can read or write all values with just one record
read and write.
v This takes up less space in a database because you
are guaranteed that each session is only one record
long.
Reasons not to use single-row 2-megabyte limit of stored data per session.

1006 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Programming issue Application scenario
Reasons to use multirow v The application can store an unlimited amount of data;
that is, you are limited only by the size of the database
and a 2-megabyte-per-record limit.
v The application can read individual fields instead of the
whole record. When large amounts of data are stored
in the session but only small amounts are specifically
accessed during servlet processing of an HTTP
request, multirow sessions can improve performance
by avoiding unneeded Java object serialization.
Reasons not to use multirow If data is small in size, you probably do not want the extra
overhead of multiple row reads when you can store
everything in one row.

In the case of multirow usage, design your application data objects not to have references to each other,
to prevent circular references. For example, suppose you are storing two objects A and B in the session
using HttpSession.put(..) method, and A contains a reference to B. In the multirow case, because objects
are stored in different rows of the database, when objects A and B are retrieved later, the object graph
between A and B is different than stored. A and B behave as independent objects.

Configuring memory-to-memory replication for the peer-to-peer mode

(default memory-to-memory replication)
To configure the session management facility for memory-to-memory session replication for peer-to-peer
functions (both client and server function, or both mode) with a single replica, complete the following steps:
1. Create an application cluster. This cluster is used to deploy the application.
a. Go to the Server Cluster page. Click Servers> Clusters.
b. Click New.
c. Type a cluster name for this application cluster.
d. Define a replication domain. Select the Create a replication domain for this cluster check box.
e. Click Next.
f. Define each cluster member server. Type a cluster member name.
g. Click Apply. Repeat steps f through g for each server created in this cluster.
h. Click Next and review the summary of changes.
i. Click Finish to complete the configuration.
You have now created a cluster that contains the deployed application and the replication domain.
2. Enable memory-to-memory session replication for each server.
a. Go to the appropriate level of session management for the Web container level. Click Servers >
Application servers> server_name> Container Settings> Web Container Settings> Session
management
b. Click Distributed environment settings under Additional Properties.
c. Click Memory-to-memory replication.
d. Select the Replication domain that you want to use for the replication of sessions.
e. Select the both client and server Replication mode. You must configure all session managers
connected to a replication domain to have the same topology. If one session manager instance in a
domain is configured to use the client/server topology, then the rest of the session manager
instances in that domain must be a combination of servers configured as ″Client only″ and ″Server
only″. If one session manager instance is configured to use the peer-to-peer topology, then all
session manager instances must be configured as ″Both client and server″.
f. Click OK on the Memory-to-memory replication page.
Chapter 8. Developing WebSphere applications 1007
 g. Optional: If you want to change the tuning parameters, click Custom tuning parameters and
select a setting or customize one. Click OK. Click Save.

Note: Using the default tuning parameter custom settings, which specifies time based write interval
of 10 seconds, may result in data loss when an application server in your cluster fails.
However, this is just a small opportunity for lost data when compared to the significant
improvement in performance.
h. Click OK the Distributed environment settings page.
i. Click OK the Session management page.
j. Repeat a through i for each server.

Memory-to-memory replication settings

Use this page to configure memory-to-memory sessions.

To view the Memory-to-memory sessions page, click Servers > Application servers > server_name >
Web container settings > Web container > Session management > Distributed environment settings
> Memory-to-memory replication.

Replication domain:

Specifies the replication domain in which HTTP sessions are replicated.

Replication mode:

Select the mode in which this server has to run: Both, Client and Server. The mode implies whether data
is only sent (client), only received (server), or both. The default is both.

Configuring memory-to-memory replication for the client/server mode

To configure the session management facility for memory-to-memory replication using the clients/server
mode, complete the following steps:
1. Create an application cluster. This cluster is used to deploy the application.
a. Go to the Server Cluster page. Click Servers> Clusters.
b. Click New.
c. Type a cluster name for this application cluster.
d. Click Next.
e. Define each cluster member server. Type a cluster member name.
f. Click Apply. Complete steps e and f for each server created in this cluster.
g. Click Next and review the summary of changes.
h. Click Finish to complete the configuration.
Do not create a replication domain for the application cluster. You have now created a cluster that
contains the deployed application.
2. Create a cluster of session manager replication servers (backup cluster).
a. Go to the Server Cluster page. Click Servers> Clusters.
b. Click New.
c. Type a cluster name for the cluster of session manager replication servers.
d. Define a replication domain. Select the Create a replication domain for this cluster check box.
e. Click Next.
f. Define each cluster member server. Type a cluster member name.
g. Click Apply. Complete steps f through g for each server created in this cluster.

1008 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 h. Click Next and review the summary of changes.
i. Click Finish to complete the configuration.
This step creates a cluster of backup session manager replication servers and associates a replication
domain with that cluster.
3. Enable memory-to-memory session replication for each cluster member server in the application
cluster.
a. Go to the appropriate level of session management for the Web container level. Click Servers >
Application Servers> server_name> Container Settings> Web Container Settings> Session
management
b. Click Distributed Environment Settings under Additional Properties.
c. Click Memory-to-memory replication.
d. Select the Replication domain that you want to use for the replication of sessions.
e. Select the Client only Replication mode. You must configure all session managers connected to a
replication domain to have the same topology. If one session manager instance in a domain is
configured to use the client/server topology, then the rest of the session manager instances in that
domain must be a combination of servers configured as Client only and Server only. If one session
manager instance is configured to use the peer-to-peer topology, then all session manager
instances must be configured as Both client and server. Alternatively, if one DRS Instance is
configured in the client only mode then all DRS Instances in the domain must be configured in
either the client only or the server only modes.
f. Click OK on the Memory-to-memory replication page.
g. Optional: If you want to change the tuning parameters, click Custom tuning parameters and
select a setting or customize one. Click OK. Click Save.

Note: Using the default tuning parameter custom settings, which specifies time based write interval
of 10 seconds, may result in data loss when an application server in your cluster fails.
However, this is just a small opportunity for lost data when compared to the significant
improvement in performance.
h. Click OK the Distributed environment settings page.
i. Click OK the Session management page.
j. Repeat a through i for each server.
4. Enable memory-to-memory session replication for each cluster member server in the replication
cluster.
a. Go to the appropriate level of session management for the Web container level. Click Servers >
Application Servers> server_name> Container Settings> Web Container Settings> Session
management
b. Click Distributed Environment Settings under Additional Properties.
c. Click Memory-to-memory replication.
d. Select the Replication domain that you want to use for the replication of sessions.
e. Select the Server only Replication mode. You must configure all session managers connected to
a replication domain to have the same topology. If one session manager instance in a domain is
configured to use the client/server topology, then the rest of the session manager instances in that
domain must be a combination of servers configured as Client only and Server only. If one session
manager instance is configured to use the peer-to-peer topology, then all session manager
instances must be configured as Both client and server. Alternatively, if one DRS Instance is
configured in the client only mode then all DRS Instances in the domain must be configured in
either the client only or the server only modes.
f. Click OK on the Memory-to-memory replication page.
g. Optional: If you want to change the tuning parameters, click Custom tuning parameters and
select a setting or customize one. Click OK. Click Save.

Chapter 8. Developing WebSphere applications 1009

 Note: Using the default tuning parameter custom settings, which specifies time based write interval
of 10 seconds, may result in data loss when an application server in your cluster fails.
However, this is just a small opportunity for lost data when compared to the significant
improvement in performance.
h. Click OK the Distributed environment settings page.
i. Click OK the Session management page.
j. Repeat a through i for each server.

EJB applications

Task overview: Using enterprise beans in applications

1. Design a J2EE application and the enterprise beans that it needs. For links to design information that
is specific to enterprise beans, see “Data access : Resources for learning” on page 1353 and
“Messaging: Resources for learning” on page 1454.
2. Develop any enterprise beans that your application will use. See ″Developing enterprise beans″ in the
information center.
3. Prepare for assembly. For your EJB 2.x-compliant entity beans, decide on an appropriate access
intent policy.
4. Assemble the beans into one or more EJB modules using the assembly tool. See ″Assembling EJB
modules″ in the information center for more information. This process includes setting security, see
″Securing enterprise bean applications″. For your EJB 2.x-compliant entity beans, you might also
want to designate container-managed persistence (CMP) sequence groups. See ″Setting the run time
for CMP sequence groups″ in the information center.
5. Assemble the modules into a J2EE application using the assembly tool. See ″Assembling
applications″ in the information center.
6. For a given application server, update the EJB container configuration if needed for the application to
be deployed, and determine if you want to batch commands or defer commands for container
managed persistence. See ″Setting the run time for batched commands with JVM arguments″ and
″Setting the run time for deferred create with JVM arguments″ in the information center.
7. Deploy the application in an application server.
8. Test the modules.
v As needed, debug problems with the container.
v Debug access problems.
9. Assemble the production application using the assembly tools. See ″Assembling applications″ in the
information center
10. Deploy the application to a production environment.
11. Manage the application:
a. Manage installed EJB modules. After an application has been installed, you can manage its EJB
modules individually through the Assembly Service Toolkit.
b. Manage other aspects of the J2EE application.
12. Update the module and redeploy it using the assembly tools. See ″Assembling applications″ in the
information center.
13. Tune the performance of the application. See ″Best practices for developing enterprise beans″ in the
information center.

Enterprise beans
An enterprise bean is a Java component that can be combined with other resources to create J2EE
applications. There are three types of enterprise beans, entity beans, session beans, and message-driven
beans.

1010 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
All beans reside in EJB containers, which provide an interface between the beans and the application
server on which they reside.

Entity beans store permanent data, so they require connections to a form of persistent storage. This
storage might be a database, an existing legacy application, a file, or another type of persistent storage.

Session beans typically contain the high-level and mid-level business logic for an application. Each method
on a session bean typically performs a particular high-level operation. For example, submitting an order or
transferring money between accounts. Session beans often invoke methods on entity beans in the course
of their business logic.

Session beans can be either stateful or stateless. A stateful bean instance is intended for use by a single
client during its lifetime, where the client performs a series of method calls that are related to each other in
time for that client. One example is a ″shopping cart″ where the client adds items to the cart over the
course of an online shopping session. In contrast, a stateless bean instance is typically used by many
clients during its lifetime, so stateless beans are appropriate for business logic operations that can be
completed in the span of a single method invocation. Stateful beans should be used only where absolutely
necessary -- using stateless beans improves the ability to debug, maintain, and scale the application.

Message-driven beans enable asynchronous message servicing.

v The EJB container and a Java Message Service (JMS) provider work together to process messages.
When a message arrives from another application component through JMS, the EJB container forwards
it through an onMessage() call to a message-driven bean instance, which then processes the message.
In other respects, message-driven beans are similar to stateless session beans.
v The EJB container and a Java Connector Architecture (JCA) resource adapter work together to process
messages from an enterprise information system (EIS). When a message arrives from an EIS, the
resource adapter receives the message and forwards it to a message-driven bean, which then
processes the message. The message-driven bean is provided services such as transaction support by
the EJB container in the same way that other enterprise beans are provided service.

Beans that require data access use data sources, which are administrative resources that define pools of
connections to persistent storage mechanisms.

For more information about enterprise beans, see ″Resources for learning.″

EJB modules
An EJB module is used to assemble one or more enterprise beans into a single deployable unit. An EJB
module is stored in a standard Java archive (JAR) file.

An EJB module contains the following:

v One or more deployable enterprise beans.
v A deployment descriptor, stored in an Extensible Markup Language (XML) file. This file declares the
contents of the module, defines the structure and external dependencies of the beans in the module,
and describes how the beans are to be used at run time.

You can deploy an EJB module as a stand alone application, or combine it with other EJB modules or with
Web modules to create a J2EE application. An EJB module is installed and run in an enterprise bean
container.

For more information about EJB modules, see ″Resources for learning.″

EJB containers
An Enterprise JavaBeans (EJB) container provides a run-time environment for enterprise beans within the
application server. The container handles all aspects of an enterprise bean’s operation within the
application server and acts as an intermediary between the user-written business logic within the bean and
the rest of the application server environment.

Chapter 8. Developing WebSphere applications 1011

One or more EJB modules, each containing one or more enterprise beans, can be installed in a single
container.

The EJB container provides many services to the enterprise bean, including the following:
v Beginning, committing, and rolling back transactions as necessary.
v Maintaining pools of enterprise bean instances ready for incoming requests and moving these instances
between the inactive pools and an active state, ensuring that threading conditions within the bean are
satisfied.
v Most importantly, automatically synchronizing data in an entity bean’s instance variables with
corresponding data items stored in persistent storage.

By dynamically maintaining a set of active bean instances and synchronizing bean state with persistent
storage when beans are moved into and out of active state, the container makes it possible for an
application to manage many more bean instances than could otherwise simultaneously be held in the
application server’s memory. In this respect, an EJB container provides services similar to virtual memory
within an operating system.

Between transactions, the state of an entity bean can be cached. The EJB container supports option A, B,
and C caching.
v With option A caching, the application server assumes that the entity bean is used within a single
container. Clients of that bean must direct their requests to the bean instance within that container. The
entity bean has exclusive access to the underlying database, which means that the bean cannot be
cloned or participate in workload management if option A caching is used.
If you intend to use read-only scenarios, WebSphere Application Server provides an alternate,
higher-performance variation of option A entity beans. This caching option is called Multithreaded
Read-Only. Similar to standard option A behavior, the EJB container continues to activate the bean just
once and leave it active until the EJB container needs space in its active instance cache. However, the
EJB container differs from standard option A in the following behaviors:
– It reloads the state of the bean from persistent storage periodically in response to the user invoking a
method on it to pick up any changes that may have been made to the persistent store since the last
time the bean was loaded. You can configure this function through a Reload Interval setting in the
bean‘s deployment descriptor. For more information, see ″Developing read-only entity beans″ in the
information center.
– The state of the bean is not written to persistent store by the EJB container at the end of the
transaction, nor is the bean’s ejbStore() method be invoked.
– The EJB container permits method invocations from more than one client (thread) on the same bean
instance. This differs from the standard EJB component for the internals of a bean. You must keep
this aspect in mind when developing your bean, and ensure that any logic in the bean‘s business
methods is overall thread-safe.
v With option B caching, the entity bean remains active in the cache throughout the transaction but is
reloaded at the start of each method call.
v With option C caching (the default), the entity bean is always reloaded from the database at the
beginning of each transaction. A client can attempt to access the bean and start a new transaction on
any container that has been configured to host that bean. This is similar to the session clustering facility
described for HTTP sessions in that the entity bean’s state is maintained in a shared database that can
be accessed from any server when required.

This product supports the cloning of stateful session bean home objects among multiple application
servers. However, it does not support the cloning of a specific instance of a stateful session bean. Each
instance of a particular stateful session bean can exist in just one application server and can be accessed
only by directing requests to that particular application server. State information for a stateful session bean
cannot be maintained across multiple members of a server cluster. However, enabling stateful session
bean failover and configuring the EJB container to use memory-to-memory replication does enable stateful
session bean failover to be replicated to other servers in the cluster so that failover can occur to the

1012 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
backup server if the primary server for a stateful session bean stops for some reason. For more
information about stateful session bean failover, see ″Stateful session bean failover for the EJB container″
in the information center.

By default, an EJB container runs in the quick start mode. The EJB container startup logic delays the
loading and processing of all EJB types except Message Driven Beans (because they must exist before
messages are posted for them), Startup Beans (which must be processed at server startup time), and
those EJB types that you specify to initialize at server start. For more information about disabling quick
start for EJB types, see ″Changing enterprise bean types to initialize at application start time using the
Application Server Toolkit″ in the information center.

All other EJB initialization is delayed until the first use of the EJB type. When using Local Interfaces, the
first use is when you perform an InitialContext.lookup() method for the type. For Remote Interfaces, it is
when you call the first method on an EJB or its Home.

For more information about EJB containers, see ″Resources for learning.″

Enterprise beans: Resources for learning

Use the following links to find relevant supplemental information about enterprise beans. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of the
information.

These links are provided for convenience. Often, the information is not specific to this product but is useful
all or in part for understanding the product. When possible, links are provided to technical papers and
Redbooks that supplement the broad coverage of the release documentation with in-depth examinations of
particular product areas.

View links to additional information about:

v Planning, business scenarios, and IT architecture
v Programming model and decisions
v Programming instructions and examples
v Programming specifications

Planning, business scenarios, and IT architecture

v Mastering Enterprise JavaBeans
A comprehensive treatment of Enterprise JavaBeans (EJB) programming in nonprintable form (PDF).
One must be registered to download the PDF, but registration is free. Information about purchasing a
hardcopy is available on the Web site.
v Enterprise JavaBeans by Richard Monson-Haefel (O’Reilly and Associates, Inc.: Third Edition, 2001)

Programming model and decisions

v Read all about EJB 2.0
A comprehensive overview of the 2.0 specification that is still relevant to users of EJB 2.1.
v The J2EE Tutorial
This set of articles by Sun Microsystems covers several EJB-related topics, including the basic
programming models, persistence, and EJB Query Language.

Programming instructions and examples

v Rules and Patterns for Session Facades
EJB programming practice: Fronting entity beans with a session-bean facade.
v WebSphere Application Server Development Best Practices for Performance and Scalability
Programming practice for enterprise beans and other types of J2EE components.
v Optimistic Locking in IBM WebSphere Application Server 4.0.2
Examples of the effect of optimistic concurrency on application behavior. Although the paper is based on
a previous version of this product, the data access issues discussed in it are current.
Chapter 8. Developing WebSphere applications 1013
 This paper does not seem to be available directly by URL. To view this paper, visit the specified URL
and search on ″optimistic locking″

Programming specifications
v Enterprise JavaBeans 2.1 Specification
You can download the specification from this URL.
v JavaTM 2 Platform: Compatibility with Previous Releases
This Sun Microsystems article includes both source and binary compatibility issues.

EJB method Invocation Queuing

Method invocations to enterprise beans are only queued for remote clients, making the method call. An
example of a remote client is an enterprise Java bean (EJB) client running in a separate Java virtual
machine (JVM) (another address space) from the enterprise bean. In contrast, no queuing occurs if the
EJB client, either a servlet or another enterprise bean, is installed in the same JVM on which the EJB
method runs and on the same thread of execution as the EJB client.

Remote enterprise beans communicate by using the Remote Method Invocation over Internet Inter-ORB
Protocol (RMI-IIOP). Method invocations initiated over RMI-IIOP are processed by a server-side object
request broker (ORB). The thread pool acts as a queue for incoming requests. However, if a remote
method request is issued and there are no more available threads in the thread pool, a new thread is
created. After the method request completes the thread is destroyed. Therefore, when the ORB is used to
process remote method requests, the EJB container is an open queue, due to the use of unbounded
threads. The following illustration depicts the two queuing options of enterprise beans.
EJB Queuing

Servlet Engine

Request queued
in the Servlet Engine EJB Container
Threads

ORB Thread Pool

WebSphere
Servlet
Application Server
Request
EJB Client queued
in the ORB
REMOTE
Thread Pool
WebSphere
Application Server

The following are two tips for queueing enterprise beans:

v Analyze the calling patterns of the EJB client.
When configuring the thread pool, it is important to understand the calling patterns of the EJB client. If a
servlet is making a small number of calls to remote enterprise beans and each method call is relatively
quick, consider setting the number of threads in the ORB thread pool to a value lower than the Web
container thread pool size value.

1014 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Short-lived EJB calls

Remote Call Remote Call

Servlet service() Servlet service()

BEGIN END
Execution timeline

Longer-lived EJB calls

Remote Call Remote Call

Servlet service() Servlet service()

BEGIN END
Execution timeline
The degree to which the ORB thread pool value needs increasing is a function of the number of
simultaneous servlets, that is, clients, calling enterprise beans and the duration of each method call. If
the method calls are longer or the applications spend a lot of time in the ORB, consider making the
ORB thread pool size equal to the Web container size. If the servlet makes only short-lived or quick
calls to the ORB, servlets can potentially reuse the same ORB thread. In this case, the ORB thread
pool can be small, perhaps even one-half of the thread pool size setting of the Web container.
v Monitor the percentage of configured threads in use.
Tivoli Performance Viewer shows a metric called percent maxed, which is used to determine how often
the configured threads are used. A value that is consistently in the double-digits, indicates a possible
bottleneck a the ORB. Increase the number of threads.

See also ″Queuing network″ in the information center.

Using access intent policies

Apply access intent policies to methods of CMP entity beans.

Access intent policies

An access intent policy is a named set of properties (access intents) that governs data access for
Enterprise JavaBeans (EJB) persistence. You can assign policies to an entity bean and to individual
methods on an entity bean’s home, remote, or local interfaces during assembly. You can set access
intents only within EJB Version 2.x-compliant modules for entity beans with CMP Version 2.x.

This product supplies a number of access intent policies that specify permutations of read intent and
concurrency control; the pessimistic/update policy can be qualified further. The selected policy determines
the appropriate isolation level and locking strategy used by the run time environment.

Chapter 8. Developing WebSphere applications 1015

Access intent policies are specifically designed to supplant the use of isolation level and access intent
method-level modifiers found in the extended deployment descriptor for EJB version 1.1 enterprise beans.
You cannot specify isolation level and read-only modifiers for EJB version 2.x enterprise beans.

Access intent policies configured on an entity basis define the default access intent for that entity. The
default access intent controls the entity unless you specify a different access intent policy based on either
method-level configuration or application profiling.

Note: Method level access intent has been deprecated for Version 6.

You can use application profiling or method level access intent policies to control access intent more
precisely. Method-level access intent policies are named and defined at the module level. A module can
have one or many such policies. Policies are assigned, and apply, to individual methods of the declared
interfaces of entity beans and their associated home interfaces. A method-based policy is acted upon by
the combination of the EJB container and persistence manager when the method causes the entity to
load.

For entity beans that are backed by tables with nullable columns, use an optimistic policy with caution.
Nullable columns are automatically excluded from overqualified updates at deployment time; concurrent
changes to a nullable field might result in lost updates. When used with the IBM Rational Application
Developer product, this product provides support for selecting a subset of the non-nullable columns that
are to be reflected in the overqualified update statement that is generated in the deployment code to
support optimistic policies.

Concurrency control:

Concurrency control is the management of contention for data resources. A concurrency control scheme is
considered pessimistic when it locks a given resource early in the data-access transaction and does not
release it until the transaction is closed. A concurrency control scheme is considered optimistic when locks
are acquired and released over a very short period of time at the end of a transaction.

The objective of optimistic concurrency is to minimize the time over which a given resource would be
unavailable for use by other transactions. This is especially important with long-running transactions, which
under a pessimistic scheme would lock up a resource for unacceptably long periods of time.

Under an optimistic scheme, locks are obtained immediately before a read operation and released
immediately afterwards. Update locks are obtained immediately before an update operation and held until
the end of the transaction.

To enable optimistic concurrency, this product uses an overqualified update scheme to test whether the
underlying data source has been updated by another transaction since the beginning of the current
transaction. With this scheme, the columns marked for update and their original values are added explicitly
through a WHERE clause in the UPDATE statement so that the statement fails if the underlying column
values have been changed. As a result, this scheme can provide column-level concurrency control;
pessimistic schemes can control concurrency at the row level only.

Optimistic schemes typically perform this type of test only at the end of a transaction. If the underlying
columns have not been updated since the beginning of the transaction, pending updates to
container-managed persistence fields are committed and the locks are released. If locks cannot be
acquired or if some other transaction has updated the columns since the beginning of the current
transaction, the transaction is rolled back: All work performed within the transaction is lost.

Pessimistic and optimistic concurrency schemes require different transaction isolation levels. Enterprise
beans that participate in the same transaction and require different concurrency control schemes cannot
operate on the same underlying data connection.

1016 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Whether or not to use optimistic concurrency depends on the type of transaction. Transactions with a high
penalty for failure might be better managed with a pessimistic scheme. (A high-penalty transaction is one
for which recovery would be risky or resource-intensive.) For low-penalty transactions, it is often worth the
risk of failure to gain efficiency through the use of an optimistic scheme. In general, optimistic concurrency
is more efficient when update collisions are expected to be infrequent; pessimistic concurrency is more
efficient when update collisions are expected to occur often.

Read-ahead hints:

Read-ahead schemes enable applications to minimize the number of database round trips by retrieving a
working set of container-managed persistence (CMP) beans for the transaction within one query.
Read-ahead involves activating the requested CMP beans and caching the data for their related beans,
which ensures that data is present for the beans that are most likely to be needed next by an application.
A read-ahead hint is a representation of the related beans that are to be read. It is associated with the
findByPrimaryKey method for the requested bean type, which must be an EJB 2.x-compliant CMP entity
bean.

A read-ahead hint takes the form of a character string. You do not have to provide the string; the wizard
generates it for you based on CMRs defined for the bean. The following example is provided as
supplemental information only. Suppose a CMP bean type A has a finder method that returns instances of
bean A. A read-ahead hint for this method is specified using the following notation: RelB.RelC; RelD

Interpret the preceding notation as follows:

v Bean type A has a CMR with bean types B and D.
v Bean type B has a CMR with bean type C.

For each bean of type A that is retrieved from the database, its directly-related B and D beans and its
indirectly-related C beans are also retrieved. The order of the retrieved bean data columns in each row of
the result set is the same as their order in the read-ahead hint: an A bean, a B bean (or null), a C bean (or
null), a D bean (or null). For hints in which the same relationship is mentioned more than once (for
example, RelB.RelC;RelB.RelE), a bean’s data columns appear only once, at the position it first appears in
the hint.

The tokens shown in the notation (RelB and so on) must be CMR field names for the relationships as
defined in the deployment descriptor for the bean. In indirect relationships such as RelB.RelC, RelC is a
CMR field name defined in the deployment descriptor for bean type B.

A single read-ahead hint cannot refer to the same bean type in more than one relationship. For example, if
a Department bean has a relationship employees with the Employee bean and also has a relationship
manager with the Employee bean, the read-ahead hint cannot specify both employees and manager.

For more information about how to set read-ahead hints, see the documentation for the Rational
Application Developer product.

Some things to consider

When developing your read-ahead hints, you should keep the following in mind:
v Read ahead on long or complex paths can result in a query that is too complex to be useful. Read
ahead on root or leaf inheritance mappings need particular care. You should add up the number of
tables that are involved in the preload and then consider whether a join that complex is really a
reasonable query on your target database.
v Read ahead does NOT work in the following cases:
– preload paths across M:N relationships
– preload paths across recursive enterprise bean relationships or recursive fk relationships

Chapter 8. Developing WebSphere applications 1017

 – where multiple instances of the same table occur on the same path (whether through a recursive
relationship or not).
– when readAhead contains a table join. Different access intents can result in requiring a select for
update statement. Check the matrix on the JDBC driver and select for update support to see if
readAhead is enabled.

Configuring read-read consistency checking with the assembly tools

Read-read consistency checking only applies to LifeTimeInCache beans whose data is read from another
transaction. For the Access Intents that are for repeatable read (RR), this means the product checks that
the data is consistent with that in the data store, and ensures that no one updates it after the checking.
For the Access Intents that are for read committed (RC), this means the product checks that the data is
consistent at the point of checking, it does not guarantee that the data does not change after the
checking. This makes the behavior of the LifeTimeInCache bean the same as non-LifeTimeInCache beans.

To perform this checking, you need to configure CMP entity beans with read-read consistency checking.
You can do this using the Application Server Toolkit.
1. Start the Application Server Toolkit. See ″Starting an assembly tool″ in the information center
2. In the Project Explorer view of the J2EE perspective, right-click the Deployment Descriptor: EJB
Module Name under the EJB module for the bean instance, then select Open With > Deployment
Descriptor Editor. A property dialog notebook for the EJB project is displayed in the property pane.
3. Select the Access tab. The Add Access Intent window appears. There are two areas of the panel that
deal with adding access intent:
v Default Access Intent for Entities 2.x (Bean Level)
v Access Intent for Entities 2.x (Method Level)
4. Select the Bean or Method level. Another access intent window appears where you can set the
properties you wish to use.
5. Use the dropdown list to select the Access intent name.
6. Optional: Enter a description.
7. Check the Persistence Option box.
8. Check the Verify Read Only Data box.
9. Use the dropdown list to select your choice for read-read consistency checking. You have three
options:
NONE No read-read checking is done.
AT_TRAN_BEGIN
During ejbLoad, if the data is from cache, check the database to ensure that the data of the
bean has not changed since the last load (with proper locking based on access intent’s
concurrency control attribute.)
AT_TRAN_END
At the end of transaction, if the bean is not changed and did not load by the current
transaction, check the database to ensure that the data of the bean has not changed from
last load (with proper locking based on access intent’s concurrency control attribute.) If the
data has changed, fail the transaction.
10. Select Finish.

Examples: read-read consistency checking:

Usage Scenario

Read-read consistency checking only applies to LifeTimeInCache beans whose data is read from another
transaction. For the Access Intents that are for repeatable read (RR), this means the product checks that
the data is consistent with that in the data store, and ensures that no one updates it after the checking.
For the Access Intents that are for read committed (RC), this means the product checks that the data is
1018 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
consistent at the point of checking, it does not guarantee that the data does not change after the
checking. This makes the behavior of the LifeTimeInCache bean the same as non-LifeTimeInCache beans.

You have three options for setting consistency checking, as shown in the following scenarios concerning
the calculation of interest in ″Ann’s″ bank account. In each case, the data store is shared by this EJB CMP
application ( to calculate the interest) and other applications, such as EJB BMP, JDBC, or legacy
applications. Also in each case, the EJB Account is configured as a “long-lifetime” bean.

NONE
v The server is started.
v User1 in Transaction 1 calls Account.findByPrimaryKey(″10001″), account data for Ann is read from the
database, with a balance of $100.
v Ann‘s record is cached by the persistence manager (PM) on the server.
v User 2 writes a JDBC call and changes the balance to $120.
v User3 in Transaction 2 calls Account.findByPrimaryKey() for account ″10001″, Ann‘s data is read from
cache, with a balance of $100.
v Calculate Ann‘s interest, but the result might not be correct because of the data integrity issue.

Read-read checking AT_TRAN_BEGIN

v The server is started.
v User1 in Transaction 1 calls Account.findByPrimaryKey(″10001″), account data for Ann is read from the
database, with a balance of $100.
v Ann‘s record is cached by the persistence manager (PM) on the server.
v User 2 writes a JDBC call and changes the balance to $120.
v User3 in Transaction 2 calls Account.findByPrimaryKey() for account ″10001″, Ann‘s data is read from
cache, with a balance of $100.
v PM performs read-read check on Ann’s account and finds that the balance of 100 is changed. It issues
a database query to retrieve balance of $120, and Ann‘s data in the cache is refreshed.
v Calculate Ann‘s interest, proceed with the transaction because data integrity is protected.

Read-read checking AT_TRAN_END

v The server is started.
v User1 in Transaction 1 calls Account.findByPrimaryKey(″10001″), account data for Ann is read from the
database, with a balance of $100.
v Ann‘s record is cached by the persistence manager (PM) on the server.
v User 2 writes a JDBC call and changes the balance to $120.
v User 3 in Transaction 2 calls Account.findByPrimaryKey() for account ″10001″, Ann‘s data is read from
database, with balance of $100.
v Calculate Ann‘s interest.
v During end of transaction 2, PM performs read-read check on Ann’s account and finds that the balance
of 100 is changed.
v PM rolls back the transaction and invalidates the cache. The transaction fails and again data integrity is
protected.

Access intent service

Access intent is a WebSphere Application Server run-time service that enables you to more precisely
manage an application’s persistence. The access intent service defines a set of declarative annotations
used by the Enterprise JavaBeans (EJB) container and its agents to make performance optimizations for
entity bean access. These annotations are organized into sets called access intent policies.

Chapter 8. Developing WebSphere applications 1019

Access intent policies contain a set of annotations considered as hints by the EJB container and its
agents. Most access intent policies are hints representing high-level abstractions that can be mapped to a
specific back end resource manager. It is the responsibility of the EJB persistence machinery to ensure the
necessary concurrency control, connection, and cache management when carrying out the persistence
details. The EJB persistence manager can use access intent hints to make better performance decisions
when carrying out its assigned task. A smaller number of access intents are hints to the EJB container,
influencing the management of EJB collections.

Although it is recommended that you always configure bean level access intent for your applications, if you
find it necessary you can apply access intent policies to methods within the scope of an EJB module. In
such cases the policy becomes the default access intent for all requests upon the configured methods.

You can also apply access intent policies to beans within the scope of application profiles. Consequently,
you can configure beans with multiple and opposing access intent policies. The application profiling
documentation explains in more detail how to configure an application to apply a particular access intent
policy to a bean for one request, then apply another access intent policy to the same bean for a different
request.

Applying access intent policies to methods

You apply an access intent policy to a method, or set of methods, in an application’s entity beans through
the assembly tools. See ″Assembling applications″ in the information center.

Note: Method level access intent is deprecated in Version 6.0.

1. Start the Application Server Toolkit. See ″Starting an assembly tool″ in the information center.
2. Optional: Open the J2EE perspective to work with J2EE projects. Click Window > Open
Perspective > Other > J2EE.
3. Optional: Open the Project Explorer view. Click Window > Show View > Project Explorer. Another
helpful view is the Navigator view (Window > Show View > Navigator).
4. Create a new application EAR file or edit an existing one.
For example, to change attributes of an existing application, use the import wizard to import an EAR
file. To start the import wizard:
a. Select File > Import > EAR file > Next
b. Select the EAR file.
c. Create a WebSphere Application Server v6.0 type of Server Runtime. Select New to open the
New Server Runtime Wizard and follow the instructions.
d. In the Target server field, select WebSphere Application Server v6.0 type of Server Runtime.
e. Select Finish
5. In the Project Explorer view of the J2EE perspective, right-click the Deployment Descriptor: EJB
Module Name under the EJB module for the bean instance, then select Open With > Deployment
Descriptor Editor. A property dialog notebook for the EJB project is displayed in the property pane.
6. Select the Access tab.
7. On the right side of the Access Intent for Entities 2.x (Method Level) panel, select Add. The Add
Access Intent panel displays.
8. Specify the Name for your new intent policy.
9. Select the Access intent name from the drop-down list.
10. Enter a Description to help you remember what this policy does.
11. Optional: Select Read Ahead Hint. A single access intent read ahead hint might not refer to the
same bean type in more than one relationship. For example, if a Department enterprise bean has a
relationship employees with the Employee enterprise bean, and also has a relationship manager with
the Employee enterprise bean, then a read ahead hint cannot specify both employees and manager.
12. Click Next. The next Add Access Intent panel displays, with optional attributes.

1020 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
13. Optional: Decide whether or not to overwrite these optional access intent attributes. Click on those
you want to change.
14. Click Next. The next Add Access Intent panel, with a list of Enterprise Beans, displays.
15. Select one or more Enterprise Beans from the list.

Note: If you selected Read Ahead Hint in an earlier step, you can only select ONE bean at this
step.
16. Click Next. The next Add Access Intent panel, with a list of methods, displays.
17. Select the methods you want to use.
18. If you DID NOT select Read Ahead Hint in an earlier step, click Finish. If you DID select the Read
Ahead Hint option, you can click Next to specify your Read Ahead Hint for the specified bean. The
next Add Access Intent panel, with a list of EJB preload paths, displays.
19. Edit the EJB preload path by selecting relationship roles from the Relationship roles: window.
20. Click Finish. A new entry is created in the Access Intent for Entities 2.x (Method Level) panel

Access intent exceptions

The following exceptions are thrown in response to the application of access intent policies:
com.ibm.ws.ejbpersistence.utilpm.PersistenceManagerException
If the method that drives the ejbLoad() method is configured to be read-only but updates are then
made within the transaction that loaded the bean’s state, an exception is thrown during invocation
of the ejbStore() method, and the transaction is rolled back. Likewise, the ejbRemove() method
cannot succeed in a transaction that is set as read-only. If an update hint is applied to methods of
entity beans with bean-managed persistence, the same behavior and exception results. The
forwarded exception object contains the message string PMGR1103E: update instance level read
only bean beanName
This exception is also thrown if the applied access intent policy cannot be honored because a
finder, ejbSelect, or container-managed relationship (CMR) accessor method returns an inherently
read-only result. The forwarded exception object contains the message string PMGR1001: No such
DataAccessSpec - methodName
The most common occurrence of this error is when a custom finder that contains a read-only EJB
Query Language (EJB QL) statement is called with an applied access intent of
wsPessimisticUpdate or wsPessimisticUpdate-Exclusive. These policies require the use of a USE
AND KEEP UPDATE LOCKS clause on the SQL SELECT statement to be executed, but a
read-only query cannot support USE AND KEEP UPDATE LOCKS. Other examples of read-only
queries include joins; the use of ORDER BY, GROUP BY, and DISTINCT keywords.
To eliminate the exception, edit the EJB query so that it does not return an inherently read-only
result or change the access intent policy being applied.
v If an update access is required, change the applied access intent setting to
wsPessimisticUpdate-WeakestLockAtLoad or wsOptimisticUpdate.
v If update access is not truly required, use wsPessimisticRead or wsOptimisticRead.
v If connection sharing between entity beans is required, use wsPessimisticUpdate-
WeakestLockAtLoad or wsPessimisticRead.
com.ibm.websphere.ejb.container.CollectionCannotBeFurtherAccessed
If a lazy collection is driven after it is no longer in scope, and beyond what has already been
locally buffered, a CollectionCannotBeFurtherAccessed exception is thrown.
com.ibm.ws.exception.RuntimeWarning
If an application is configured incorrectly, a run-time warning exception is thrown as the application
starts; startup is ended. You can validate an application’s configuration by choosing the verify
function. Some examples of misconfiguration include:
v A method configured with two different access intent policies
v A method configured with an undefined access intent policy

Chapter 8. Developing WebSphere applications 1021

Access intent assembly settings
Access intent policies contain data-access settings for use by the persistence manager. Default access
intent policies are configured on the entity bean.

These settings are applicable only for EJB 2.x-compliant entity beans that are packaged in EJB
2.x-compliant modules. Connection sharing between beans with bean-managed persistence and those with
container-managed persistence is possible if they all use the same access intent policy.

Name:

Specifies a name for a mapping between an access intent policy and one or more methods.

Description:

Contains text that describes the mapping.

Methods - Name:

Specifies the name of an enterprise bean method, or the asterisk character (*). The asterisk is used to
denote all of the methods of an enterprise bean’s remote and home interfaces.

Methods - Enterprise bean:

Specifies which enterprise bean contains the methods indicated in the Name setting.

Methods - Type:

Used to distinguish between a method with the same signature that is defined in both the home and
remote interface. Use Unspecified if an access intent policy applies to all methods of the bean.

Data type String

Range Valid values are Home, Remote,Local, LocalHome or
Unspecified

Methods - Parameters:

Contains a list of fully qualified Java type names of the method parameters. This setting is used to identify
a single method among multiple methods with an overloaded method name.

Applied access intent:

Specifies how the container must manage data access for persistence. Configurable both as a default
access intent for an entity and as part of a method-level access intent policy.

Data type String

Range Valid settings are wsPessimisticUpdate,
wsPessimisticUpdate-NoCollision, wsPessimisticUpdate-
Exclusive, wsPessimisticUpdate-WeakestLockAtLoad,
wsPessimisticRead, wsOptimisticUpdate, or
wsOptimisticRead. Only wsPessimisticRead and
wsOptimisticRead are valid when class-level caching is
enabled in the EJB container.

This product supports lazy collections. For each segment of a collection, iterating through the collection
(next()) does not trigger a remote method call to retrieve the next remote reference. Two policies

1022 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
(wsPessimisticUpdate and wsPessimisticUpdate-Exclusive) are extremely lazy; the collection increment
size is set to 1 to avoid overlocking the application. The other policies have a collection increment size of
25.

Additional information about valid settings follows:

Profile name Concurrency control Access type Transaction isolation

wsPessimisticRead (Note 1) pessimistic read For Oracle, read committed.
Otherwise, repeatable read
wsPessimisticUpdate (Note pessimistic update For Oracle, read committed.
2) Otherwise, repeatable read
wsPessimisticUpdate- pessimistic update serializable
Exclusive (Note 3)
wsPessimisticUpdate- pessimistic update read committed
NoCollision (Note 4)
wsPessimisticUpdate- pessimistic update Repeatable read
WeakestLockAtLoad (Note
5)
wsOptimisticRead optimistic read read committed
wsOptimisticUpdate (Note optimistic update read committed
6)
Notes:
1. Read locks are held for the duration of the transaction.
2. The generated SELECT FOR UPDATE query grabs locks at the beginning of the transaction.
3. SELECT FOR UPDATE is generated; locks are held for the duration of the transaction.
4. Generated overqualified-update query forces failure if CMP column values have changed since the beginning of
the transaction.

Access intent best practices

This topic outlines issues to consider when applying access intent policies to Enterprise JavaBeans (EJB)
methods.
v Take care when applying wsPessimisticUpdate-NoCollision. This policy does not ensure data
integrity. No database locks are held, so concurrent transactions can overwrite each other’s updates.
Use this policy only if you can be sure that only one transaction will attempt to update persistent store
at any given time.

Frequently asked questions: Access intent

I have not applied any access intent policies at all. My application runs just fine with a DB2
database, but it fails with an Oracle database with the following message:
com.ibm.ws.ejbpersistence.utilpm.PersistenceManagerException: PMGR1001E: No such
DataAccessSpec :FindAllCustomers. The backend datastore does not support the SQLStatement
needed by this AccessIntent: (pessimistic update-weakestLockAtLoad)(collections: transaction/25)
(resource manager prefetch: 0) (AccessIntentImpl@d23690a). Why?

If you have not configured access intent, all of your data is accessed under the default access intent policy
(wsPessimisticUpdate-WeakestLockAtLoad). On DB2 databases, the weakest lock is a shared one, and the
query runs without a USE AND KEEP UPDATE LOCKS clause. On Oracle databases, however, the
weakest lock is an update lock; this means that the SQL query must contain a USE AND KEEP UPDATE
LOCKS clause. However, not every SQL statement necessarily supports USE AND KEEP UPDATE
LOCKS; for example, if the query is being run against multiple tables in a join, USE AND KEEP UPDATE
LOCKS is not supported. To avoid this problem, try either of the following:
v Modify your SQL query or reconfigure your application so that an update lock is supported
v Apply an access intent policy that supports optimistic concurrency

Chapter 8. Developing WebSphere applications 1023

I am calling a finder method and I get an InconsistentAccessIntentException at run time. Why?

This can occur when you use method-level access intent policies to apply more control over how a bean
instance is loaded. This exception indicates that the entity bean was previously loaded in the same
transaction. This could happen if you called a multifinder method that returned the bean instance with
access intent policy X applied; you are now trying to load the second bean again by calling its
findByPrimaryKey method with access intent Y applied. Both methods must have the same access intent
policy applied.

Likewise, if the entity was loaded once in the transaction using an access intent policy configured on a
finder, you might have called a container-managed relationship (CMR) accessor method that returned the
entity bean configured to load using that entity’s default access intent.

To avoid this problem, ensure that your code does not load the same bean instance twice within the same
transaction with different access intent policies applied. Avoid the use of method-level access intent unless
absolutely necessary.

I have two beans in a container-managed relationship. I call findByPrimaryKey() on the first bean
and then call getBean2( ), a CMR accessor method, on the returned instance. At that point, I get an
InconsistentAccessIntentException. Why?

You are probably using read-ahead. When you loaded the first bean, you caused the second bean to be
loaded under the access intent policy applied to the finder method for the first bean. However, you have
configured your CMR accessor method from the first bean to the second with a different access intent
policy. CMR accessor methods are really finder methods in disguise; the run-time environment behaves as
if you were trying to change the access intent for an instance you have already read from persistent store.

To avoid this problem, beans configured in a read-ahead hint are all driven to load with the same access
intent policy as the bean to which the read-ahead hint is applied.

I have a bean with a one-to-many relationship to a second bean. The first bean has a
pessimistic-update intent policy applied. When I try to add an instance of the second bean to the
first bean’s collection, I get an UpdateCannotProceedWithIntegrityException. Why?

The second bean probably has a read intent policy applied. When you add the second bean to the first
bean’s collection, you are not updating the first bean’s state, you are implicitly modifying the second
bean’s state. (The second bean contains a foreign key to the first bean, which is modified.)

To avoid this problem, ensure that both ends of the relationship have an update intent policy applied if you
expect to change the relationship at run time.

Managing EJB containers

Each application server can have a single EJB container; one is created automatically for you when the
application server is created. The following steps are to be performed only as needed to improve
performance after the EJB application has been deployed.
1. Adjust EJB container settings.
2. Adjust EJB cache settings.

If adjustments do not improve performance, consider adjusting access intent policies for entity beans,
reassembling the module, and redeploying the module in the application.

EJB container settings

Use this page to configure and manage the EJB container of this application server.

1024 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this administrative console page, click Servers > Application Servers > serverName > EJB
Container Settings > EJB container.

Passivation directory:

Specifies the directory into which the container saves the persistent state of passivated stateful session
beans.

Stateful session beans with an activation policy of TRANSACTION are passivated at the end of the
transaction in which they are enlisted, and stateful session beans with an activation policy of ONCE
(default) are passivated when the number of active bean instances becomes greater than the cache size
specified in the container configuration. When a stateful bean is passivated, the container serializes the
bean instance to a file in the passivation directory and discards the instance from the bean cache. If, at a
later time, a request arrives for the passivated bean instance, the container retrieves it from the
passivation directory, deserializes it, returns it to the cache, and dispatches the request to it. If any step
fails (for example, if the bean instance is no longer in the passivation directory), the method invocation
fails.

Inactive pool cleanup interval:

Specifies the interval at which the container examines the pools of available bean instances to determine if
some instances can be deleted to reduce memory usage.

Data type Integer

Units Milliseconds
Range 0 to 2 147 483 674

Default datasource JNDI name:

Specifies the JNDI name of a data source to use if no data source is specified during application
deployment. This setting is not applicable for EJB 2.x-compliant CMP beans.

Servlets and enterprise beans use data sources to obtain these connections. When configuring a
container, you can specify a default data source for the container. This data source becomes the default
data source used by any entity beans installed in the container that use container-managed persistence
(CMP).

The default data source for a container is secure. When specifying it, you must provide a user ID and
password for accessing the data source.

Specifying a default data source is optional if each CMP entity bean in the container has a data source
specified in its configuration. If a default data source is not specified and a CMP entity bean is installed in
the container without specifying a data source for that bean, applications cannot use that CMP entity bean.

Enable stateful session bean failover using memory-to-memory replication:

Specifies that failover is enabled for all stateful session beans installed in this EJB container.

This checkbox is disabled until you define a replication domain. This selection has a hyperlink to help you
configure the replication settings. If no replication domains are configured, the link takes you to a panel
where you can create one. If at least one domain is configured, the link takes you to a panel where you
can select the replication settings to be used by the EJB container.

Data type Checkbox

Default Unselected
Range Selected or unselected.

Chapter 8. Developing WebSphere applications 1025

Initial state:

Specifies the execution state requested when the server first starts.

Data type String

Default Started
Range Valid values are Started and Stopped

EJB container system properties

In addition to the settings accessible from the administrative console, you can set the following system
property by command-line scripting:
com.ibm.websphere.ejbcontainer.poolSize
Specifies the size of the pool for the specified bean type. This property applies to stateless,
message-driven and entity beans. If you do not specify a default value, the container defaults of
50 and 500 are used.
Set the pool size for a given entity bean as follows:
beantype=min,max[:beantype=min,max...]

beantype is the J2EE name of the bean, formed by concatenating the application name, the #
character, the module name, the # character, and the name of the bean (that is, the string
assigned to the <ejb-name> field in the bean’s deployment descriptor). min and max are the
minimum and maximum pool sizes, respectively, for that bean type. Do not specify the square
brackets shown in the previous prototype; they denote optional additional bean types that you can
specify after the first. Each bean-type specification is delimited by a colon (:).

Use an asterisk (*) as the value of beantype to indicate that all bean types are to use those values
unless overridden by an exact bean-type specification somewhere else in the string, as follows:
*=30,100

To specify that a default value be used, omit either min or max but retain the comma (,) between
the two values, as follows (split for publication):
SMApp#PerfModule#TunerBean=54,
:SMApp#SMModule#TypeBean=100,200

You can specify the bean types in any order within the string.
com.ibm.websphere.ejbcontainer.allowEarlyInsert

Note: This property is applicable to CMP 1.1 beans only.

By default, the EJB Container creates the entity bean representation in the database only after the
method ejbPostCreate(...) is called. However, some applications may rely on method ejbCreate(...)
to have created the entity bean in the database. For such a requirement, setting the JVM property
com.ibm.websphere.ejbcontainer.allowEarlyInsert to true overrides the default behavior.

Changing enterprise bean types to initialize at application start time using the
Application Server Toolkit
By default, the WebSphere Application Server’s Enterprise JavaBeans (EJB) Container delays the
initialization (loading and processing) of most EJB types until they are needed during runtime. This helps
to speed up the application start time.

EJB types can, however, be forced to initialize at application start time by setting a flag within the bean’s
deployment descriptor. If this flag is set to true then the bean is initialized at application start time.

1026 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
1. Start the Application Server Toolkit. See ″Starting an assembly tool″ in the information center.
2. Select EJB Deployment Descriptor.
3. In the property pane, select the WebSphere Extensions tab.
4. Check the box labeled Start EJB at Application Start.
5. Select OK.

Changing enterprise bean types to initialize at application start time using the
administrative console
By default, the WebSphere Application Server’s Enterprise JavaBeans (EJB) Container delays the
initialization (loading and processing) of most EJB types until they are needed during runtime. This helps
to speed up the application start time.

All EJB types within a server can, however, be forced to initialize at application start time by setting a
system property within the administrative console. If the value of this property is set to true then all beans
within the server are initialized at each application’s start time.
1. Open the administrative console.
2. Select Servers.
3. Select Application Servers.
4. Select the server you want to configure.
5. In the Server Infrastructure area, select Java and Process Management.
6. In the Server Infrastructure area, select Process Definition.
7. In the Additional Properties area, select Java Virtual Machine.
8. In the Additional Properties area, select Custom Properties.
9. Select the New box.
10. In the Name entry field, type com.ibm.websphere.ejbcontainer.initializeEJBsAtStartup.
11. In the Value entry field, type true. Entering true causes all Enterprise JavaBeans to initialize when
your application starts. Entering false causes initialization of all beans to be delayed.

Note: Setting com.ibm.websphere.ejbcontainer.initializeEJBsAtStartup to either true or false takes

precedence over any Start EJB at Application Start settings made on individual EJB types (see
“Changing enterprise bean types to initialize at application start time using the Application
Server Toolkit” on page 1026).
12. Select OK.

Stateful session bean failover for the EJB container

WebSphere Application Server Version 6.0 enables you to construct applications with the assumption that
your applications using stateful session beans are not limited by unexpected server failures. This version
of the product utilizes the functions of the Data Replication Service (DRS) and Workload Management
(WLM) so you can enable stateful session bean failover.

Because you might not want to enable failover for every single stateful session bean installed in the EJB
container, you can override the EJB container settings at either the application or EJB module level. You
can either enable or disable failover at each of these levels. For example, consider the following situations:
v You want to enable failover for all applications except for a single application. To do this, you enable
failover at the EJB container level and override the setting at the application level to disable failover on
the single application.
v You want to enable failover for a single installed application. To do this, disable failover at the EJB
container level and then override the setting at the application level to enable failover on the single
application.

Chapter 8. Developing WebSphere applications 1027

v You want to enable failover for all applications except for a single module of an application. To do this,
enable failover at the EJB container level, then override the setting at the module application level to
disable failover on the single module.
v You want to enable failover for a single installed EJB module. To do this, disable failover at the EJB
container level and then override the setting at the EJB module level to enable failover on the single
EJB module.

For information about enabling stateful session bean failover from the administrative console, see
“Enabling or disabling stateful session bean failover with the EJB container panel” on page 1031,
“Enabling or disabling stateful session bean failover with the enterprise applications panel” on page 1031,
and “Enabling or disabling stateful session bean failover with the EJB modules panel” on page 1032.

Stateful session bean activation policy with failover enabled

WebSphere Application Server enables an application assembler to specify an activation policy to use for
stateful session beans. It is important to consider that the only time the EJB container prepares for failover
(by replicating the stateful session bean data using DRS) is when the stateful session bean is passivated.
If you configure the bean with an activate once policy, the bean is essentially never passivated. If you
configure the activate at transaction boundary policy, the bean is passivated whenever the transaction that
the bean is enlisted in completes. For stateful session bean failover to be useful, the activate at
transaction boundary policy is required.

Rather than forcing you to edit the deployment descriptor of every stateful session bean and reinstall the
bean, the EJB container simply ignores the configured activation policy for the bean when you enable
failover. The container automatically uses the activate at transaction boundary policy.

Stateful session bean use of container managed units of work or bean managed units of work with
failover enabled

The relevant ″units of work″ in this case are transactions and activity sections. The product supports
stateful session bean failover for container managed transactions (CMT), bean managed transactions
(BMT), container managed activity sessions (CMAS), and bean managed activity sections (BMAS).
However, in the container managed cases, preparation for failover only occurs if trying to send a request
for an enterprise bean method invocation results in no connection to the server. Also, if the server fails
after a request is sent to it and acknowledged, failover does not occur. When a failure occurs in the middle
of a request or unit of work, WLM cannot safely fail over to another server without some compensation
code being executed by the application. When that happens, the application receives a Common Object
Request Broker Architecture (CORBA) exception and minor code telling it that transparent failover could
not occur because the failure happened during execution of a unit of work. The application should be
written to check for the CORBA exception and minor code, and compensate for the failure. After the
compensation code executes, the application can retry the requests and if a path exists to a backup server
WLM routes the new request to a new primary server for the stateful session bean. For more information,
see ″CORBA minor codes″ and “Workload management (WLM) for distributed platforms” on page 270 in
the information center.

The same is true for bean managed units of work (transactions or activity sessions). However, bean
managed work introduces a new possibility that needs to be considered.

For bean managed units of work, the failover process is not always able to detect that a BMT or BMAS
started by a stateful session bean method has not completed. Thus, it is possible that failover to a new
server can occur despite the unit of work failing during the middle of a transaction or session. Because the
unit of work is implicitly rolled back, WLM behaves as if it is safe to transparently fail over to another
server, when in fact some compensation code might be required. When this happens, the EJB container
detects this on the new server and initiates an exception. This exception occurs under the following
scenario:

1028 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
1. A method of a stateful session bean using bean managed transaction or activity session calls begin on
a UserTransaction it obtained from the SessionContext. The method does some work in the started
unit of work, but does not complete the transaction or session before returning to the caller of the
method.
2. During post invocation of the method started in step 1, the EJB container suspends the work started by
the method. This is the action required by Enterprise JavaBeans specification for bean managed units
of work when the bean is a stateful session bean.
3. The client starts several other methods on the stateful session bean. Each invocation causes the EJB
container to resume the suspended transaction or activity session, dispatch the method invocation, and
then suspend the work again before returning to the caller.
4. The client calls a method on the stateful session bean that completes the transaction or session
started in step 1.

This scenario depicts a sticky bean managed unit of work. The transaction or activity session sticks around
for more than a single stateful session bean method. If an application uses a sticky BMT or BMAS, and
the server fails after a sticky unit of work completes and before another sticky unit of work starts, failover
is successful. However, if the server fails before a sticky transaction or activity session completes, the
failover is not successful. Instead, when the failover process routes the stateful session bean request to a
new server, the EJB container detects that the failure occurred during an active sticky transaction or
activity session. At that time, the EJB container initiates an exception.

Essentially, this means that failover for both container managed and bean managed units of work is not
successful if the transaction or activity session is still active. The only real difference is the exception that
occurs.

Application Design Considerations

You should consider the following when designing applications that use the stateful session bean failover
process:
v To avoid the possibility described in the section above, you are encouraged to write your application to
configure stateful session beans to use container managed transactions (CMT) rather than bean
managed transactions (BMT).
v If you desire immediate failover, and your application creates either an HTTP session or a stateful
session bean that stores a reference to another stateful session bean, then the administrator must
ensure the HTTP session and stateful session bean are configured to use the same data replication
service (DRS) replication domain.
v Do Not use a local and a remote reference to the same stateful session bean.
Normally a stateful session bean instance with a given primary key can only exist on a single server at
any given moment in time. Failover might cause the bean to be moved from one server to another, but
it never exists on more than one server at a time. However, there are some unlikely scenarios that can
result in the same bean instance (same primary key) existing on more than one server concurrently.
When that happens, each copy of the bean is unaware of the other and no synchronization occurs
between the two instances to ensure they have the same state data. Thus, your application receives
unpredictable results.
Attention: To be sure to avoid this situation you must remember that with failover enabled, your
application should never get both a local (EJBLocalObject) and remote (EJBObject) reference to the
same stateful session bean instance.

Stateful session beans failover settings (applications):

Each Enterprise JavaBeans container provides a method for stateful session beans to fail over to other
servers. This enables you to specify whether failover occurs for the stateful session beans in this module.
You can also override the parent object’s stateful session bean replication settings for this module.

Chapter 8. Developing WebSphere applications 1029

To view this administrative console page, click Applications > Enterprise Applications > application >
Stateful Session Bean Failover Settings.

Note: These settings are ignored for 5.x application targets.

Enable stateful session bean failover using memory to memory replication:

Specifies whether the EJB Container attempts failover for all of the stateful session beans in this
application.

This checkbox overrides the default stateful session bean failover setting that the administrator configured
for an EJB container. De-selecting this checkbox disables failover for this application.

Data type Checkbox

Range Selected or unselected.

Use replication settings from the EJB container:

Specifies that the replication settings configured for the EJB container are used for this application. If you
select this option and you want the application to use stateful session bean failover, you must define
memory to memory replication for the EJB container on each server you want to use failover.

Data type Radio button

Range Selected or unselected.

Use application replication settings:

Specifies that the replication settings configured for this application are used for memory to memory
replication of the stateful session bean data.

If you select this button, you override the EJB container settings. This button is disabled until you define a
replication domain. This selection has a hyperlink to help you configure the replication settings. If no
replication domains are configured, the link takes you to a panel where you can create one. If at least one
domain is configured, the link takes you to a panel where you can select the replication settings to be
used by the application.

Data type Radio button

Range Selected or unselected.

Stateful session beans failover settings (EJB modules):

Each Enterprise JavaBeans container provides a method for stateful session beans to fail over to other
servers. This enables you to specify whether failover occurs for the stateful session beans in this module.
You can also override the parent object’s stateful session bean replication settings for this module.

To view this administrative console page, click Applications > Enterprise Applications > application >
EJB modules > .jar > Stateful session bean failover settings.

Note: These settings are ignored for 5.x application targets.

Enable stateful session bean failover using memory to memory replication:

Specifies whether the EJB Container attempts failover for all of the stateful session beans in this module.

1030 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This checkbox overrides the default stateful session bean failover setting that the administrator configured
for an EJB container or the module’s application. De-selecting this checkbox disables failover for this
module.

Data type Checkbox

Range Selected or unselected.

Use application or EJB container replication settings:

Specifies that the replication settings configured for the EJB container or application are used for this
module. If you select this option and you want the application to use stateful session bean failover, you
must define memory to memory replication for the EJB container on each server you want to use failover.

Data type Radio button

Range Selected or unselected.

Use EJB module replication settings:

Specifies that the replication settings configured for this EJB module are used for memory to memory
replication of the stateful session bean data.

If you select this button, you override the replication settings for the EJB container and application. This
button is disabled until you define a replication domain. This selection has a hyperlink to help you
configure the replication settings. If no replication domains are configured, the link takes you to a panel
where you can create one. If at least one domain is configured, the link takes you to a panel where you
can select the replication settings to be used by the EJB container.

Data type Radio button

Range Selected or unselected.

Enabling or disabling stateful session bean failover with the EJB container panel
You can use the EJB Container administrative console panel to enable stateful session bean failover.
Selecting the checkbox on the panel enables you to configure whether the failover is active for all stateful
session beans in the specified EJB container.
1. Start the administrative console.
2. Select Servers.
3. Select Application Servers.
4. Select the server you want to work with.
5. Select EJB Container Settings.
6. Select EJB container.
7. Check the box labeled Enable stateful session bean failover using memory-to-memory
replication. This checkbox is disabled until you define a replication domain. This selection has a
hyperlink to help you configure the replication settings. If no replication domains are configured, the
link takes you to a panel where you can create one. If at least one domain is configured, the link takes
you to a panel where you can select the replication settings to be used by the EJB container.
8. Select OK.

Enabling or disabling stateful session bean failover with the enterprise

applications panel
You can use the enterprise applications administrative console panel to enable or disable stateful session
bean failover for all stateful session beans in the specified application.

Chapter 8. Developing WebSphere applications 1031

1. Start the administrative console.
2. Select Applications.
3. Select Enterprise Applications.
4. Select the application you want to work with.
5. Under Additional Properties, select Stateful Session Bean Failover Settings. The Stateful Session
Bean Failover Settings panel appears.
6. Select Enable stateful session bean failover using memory to memory replication. This enables
failover for all stateful session beans in this application. If you want to disable the failover, clear this
checkbox.
7. Select your choice of Replication settings. You have a choice of two radio buttons:
Use replication settings from EJB container
If you select this button, any replication settings defined for this application are ignored.

Attention: Note to the system administrator: if you use this radio button, then memory to
memory replication must be configured at the EJB container level. Otherwise, the settings on
this panel are ignored by EJB container during server startup and the EJB container will log a
message indicating that stateful session bean failover is not enabled for this application.
Use application replication settings
If you select this button, you override the EJB container settings. This button is disabled until
you define a replication domain. This selection has a hyperlink to help you configure the
replication settings. If no replication domains are configured, the link takes you to a panel
where you can create one. If at least one domain is configured, the link takes you to a panel
where you can select the replication settings to be used by the application.
8. Select OK.

Enabling or disabling stateful session bean failover with the EJB modules panel
You can use the enterprise applications administrative console panel to enable or disable stateful session
bean failover for all stateful session beans in the specified module.
1. Start the administrative console.
2. Select Applications.
3. Select Enterprise Applications.
4. Select the application you want to work with.
5. Under Related items, select EJB modules.
6. Select the .jar file you want to work with.
7. Select Stateful session bean failover settings.
8. Select Enable stateful session bean failover using memory to memory replication.
9. Select your choice of Replication settings. You have a choice of two radio buttons:
Use application or EJB container replication settings
If you select this button, any replication settings defined for this EJB module are ignored.

Attention: Note to the system administrator: if you use this radio button, then memory to
memory replication must be configured at the EJB container level. Otherwise, the settings on
this panel are ignored by EJB container during server startup and the EJB container will log a
message indicating that stateful session bean failover is not enabled for this application.
Use EJB module replication settings
If you select this button, you override the replication settings for the EJB container and
application. This button is disabled until you define a replication domain. This selection has a
hyperlink to help you configure the replication settings. If no replication domains are

1032 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 configured, the link takes you to a panel where you can create one. If at least one domain is
configured, the link takes you to a panel where you can select the replication settings to be
used by the EJB container.
10. Select OK.

EJB cache settings

Use this page to configure and manage the cache for a specific EJB container. To determine the cache
absolute limit, multiply the number of enterprise beans active in any given transaction by the total number
of concurrent transactions expected. Then, add the number of active session bean instances.

To view this administrative console page, click Servers > Application Servers > serverName > EJB
Container Settings > EJB cache settings.

Cleanup interval:

Specifies the interval at which the container attempts to remove unused items from the cache in order to
reduce the total number of items to the value of the cache size.

The cache manager tries to maintain some unallocated entries that can be allocated quickly as needed. A
background thread attempts to free some entries while maintaining some unallocated entries. If the thread
runs while the application server is idle, when the application server needs to allocate new cache entries, it
does not pay the performance cost of removing entries from the cache. In general, increase this parameter
as the cache size increases.

Data type Integer

Units Milliseconds
Range 0 to 2 147 483 674
Default 3000

Cache size:

Specifies the number of buckets in the active instance list within the EJB container.

A bucket can contain more than one active enterprise bean instance, but performance is maximized if
each bucket in the table has a minimum number of instances assigned to it. When the number of active
instances within the container exceeds the number of buckets, that is, the cache size, the container
periodically attempts to reduce the number of active instances in the table by passivating some of the
active instances. For the best balance of performance and memory, set this value to the maximum number
of active instances expected during a typical workload.

Data type Integer

Units Buckets in the hash table
Range Greater than 0. The container selects the next largest
prime number equal to or greater than the specified value.
Default 2053

Container interoperability
Container interoperability describes the ability of WebSphere Application Server clients and servers at
different versions to successfully negotiate differences in native Enterprise JavaBeans (EJB) finder
methods support and Java 2 Platform, Enterprise Edition (J2EE) compliance.

The product uses interoperable versions of some class types to enable interoperability. However, older
4.0.x client and application server versions do not support the interoperability classes, which makes them
uninteroperable with versions that use the classes. The system property
com.ibm.websphere.container.portable remedies this situation by enabling newer versions of the

Chapter 8. Developing WebSphere applications 1033

application server to turn off the interoperability classes. This lets a more recent application server return
class types that are interoperable with an older client.

Depending on the value of com.ibm.websphere.container.portable, application servers at versions 5 and

later, and 4.0.3 and later, return different classes for the following:
v Enumerations and collections returned by EJB 1.1 finder methods
v EJBMetaData
v Handles to:
– Entity beans
– Session beans
– Home interfaces

If the property is set to false, application servers return the old class types, to enable interoperability with
4.0.2 and earlier. If the property is set to true, application servers return the new classes.

The following tables show interoperability characteristics for various version combinations of application
servers and clients as well as default property values for each combination.

Interoperability of Version 4.0.x client with Version 5 (and later) application server

Ideally, all 4.0.x clients that use Version 5 or later application servers should be at Version 4.0.3 or later.

Version 5 and later application servers return the interoperability class types by default (true). This can
cause interoperability problems for distributed clients at versions 4.0.1 or 4.0.2. In particular, problems can
occur with collections and enumerations returned by Enterprise JavaBeans Version 1.1 finder methods.

Although it is strongly discouraged, you can set com.ibm.websphere.container.portable to false on a

Version 5 and later application server. This causes the application server to return the old class types,
providing interoperability with clients at Version 4.0.2 and earlier. This is discouraged because:
v The Version 5 application server instance would become non-J2EE 1.3 (and later) compliant with regard
to handles, home interface handles, and EJBMetaData.
v EJB 1.x finder methods return collection and enumeration objects that do not originate from
ejbportable.jar.
v Interoperability restrictions still exist with the property set to false.
v Version 5 and later client handles to entity beans and home interfaces do not work across domains for
the server you set to false.
If you would like to use updated Handle classes in EJB 2.x-compliant beans but have one of the older
clients (versions 4.0.2 and earlier) installed, set the system property
com.ibm.websphere.container.portable.finder to false. With this setting in place, the Version 5 and later
application server uses the updated handles but returns the enumerations and collections that were
used in the earlier clients.

Interoperability of client at Version 4.0.2 and earlier with Version 5 (and later) application server

Client at Version 4.0.2 and earlier, Application server at Version 5 and Application server at Version 5 and
using this function later, property true (default) later, property false
EJBMetaData Does not work Works for 4.0.2 client
Handle to session bean Does not work Works
Handle to entity bean Does not work Does not work across cells
Enumeration returned by EJB 1.x Does not work Works
finder method
Collection returned by EJB 1.x finder Does not work Works
method
Handle to home interface Does not work Does not work across cells

1034 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If you would like to use updated Handle classes in EJB 2.x-compliant beans but have one of the older
clients (versions 4.0.2 and earlier) installed, set the system property
com.ibm.websphere.container.portable.finder to false. With this setting in place, the Version 5 and later
server uses the new Handle classes but returns the older enumeration and collection classes.

Interoperability of client at Version 4.0.3 and later with Version 5 and later application server

Clients at Version 4.0.3 and later work well with Version 5 and later application servers. However, if you
set the com.ibm.websphere.container.portable to false, client handles to entity beans and home interfaces
do not work across domains for the server you set to false.

Client at Version 4.0.3 and later, Application server at Version 5 and Application server at Version 5 and
using this function later, property true (default) later, property false
EJBMetaData Works Works
Handle to session bean Works Works
Handle to entity bean Works Does not work across cells
Enumeration returned by EJB 1.x Works Works
finder method
Collection returned by EJB 1.x finder Works Works
method
Handle to home interface Works Does not work across cells

Interoperability of Version 5 and later client with Version 4.0.x application server

Clients at Version 5 and later work well with Version 4.0.3 application servers if you set
com.ibm.websphere.container.portable to true. Client handles to entity beans and home interfaces do not
work across domains for any Version 4.0.3 server with com.ibm.websphere.container.portable at the
default value, false. Version 5 client handles to application servers at Version 4.0.2 and earlier also have
restrictions.

Client at Version 5 and Application server at Application server at Application server at

later, using this function Version 4.0.3, property Version 4.0.3, property Version 4.0.2 or earlier
true false (default)
EJBMetaData Works Works Works for 4.0.2 server only
Handle to session bean Works Works Works
Handle to entity bean Works Does not work across Does not work across
domains domains
Enumeration returned by Works Works Works
EJB 1.x finder method
Collection returned by EJB Works Works Works
1.x finder method
Handle to home interface Works Does not work across Does not work across
domains domains

Interoperability of zSeries Version 4.0.x client with Version 5 and later application server

The only valid configuration for container interoperability with zSeries Version 4.0.x clients is the default
configuration for the Version 5 application server.

Chapter 8. Developing WebSphere applications 1035

Interoperability of Version 5 and later client with zSeries Version 4.0.x application server

Version 5 clients should work with a zSeries Version 4.0.x application server with the correct
interoperability fixes described in the zSeries documentation. The interoperability characteristics should be
the same as for a Version 4.0.3 distributed application server with the property set to true.

Client at Version 5 and later, using this function zSeries application server at Version 4.0.x
EJBMetaData Works
Handle to session bean Works
Handle to entity bean Works
Enumeration returned by EJB 1.x finder method Works
Collection returned by EJB 1.x finder method Works
Handle to home interface Works

Deploying EJB modules

When you deploy an EJB module, you install that module on a server that has been configured to support
deployed modules.

Assemble one or more EJB modules, assemble one or more Web modules, and assemble them into a
J2EE application. See ″Assembling EJB modules″, ″Assembling Web applications″, and ″Assembling
applications″ in the information center.
1. Prepare the deployment environment.
2. Update the configuration for each EJB module as needed for the deployment environment. See
″Preparing to host applications″ in the information center.
3. Deploy the application.

If you specify that EJB deploy be run during application installation and the installation fails with a
NameNotFoundException message, ensure that the input JAR or EAR file does not contain source files.
Either remove the source files or include all dependent classes and resource files on the class path. If
there are source files in the input JAR or EAR file, the EJB deployment tools runs a rebuild before
generating the deployment code.

If the module deploys successfully, test and debug the module.

EJB module collection

Use this page to manage the EJB modules deployed in a specific application.

To view this administrative console page, click Applications > Enterprise Applications >
applicationName > EJB modules. Click the check boxes to select one or more of the EJB modules in
your collection.

Remove: Removes a module from the deployed application. The module is deleted from the application
in the WebSphere Application Server configuration repository and also from all the nodes where the
application is installed and running (or expected to run). If the application is running on a node when the
module file is deleted from the node as a result of configuration synchronization then the application is
stopped, the module file is deleted from the node’s file system, and then the application is restarted.

Update: Opens a wizard that helps you update module in an application. If a module has the same URI
as a module already existing in the application, the new module replaces the existing module. If the new
module does not exist in the application, it is added to the deployed application. If the application is

1036 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
running on a node when the module file is updated on the node as a result of configuration
synchronization then the application is stopped, the module file is updated on the node’s file system, and
then the application is restarted.

Remove File: Deletes a file from a module of a deployed application. The file is also deleted from all the
nodes where the module is installed after configuration is synchronized with nodes. If the application is
running on a node when the module file is updated on the node as a result of configuration
synchronization then the application is stopped, the module file is updated on the node’s file system, and
then the application is restarted.

URI:

When resolved relative to the application URL, this specifies the location of the module’s archive contents
on a file system. The URI matches the <ejb> or <web> tag in the <module> tag of the application
deployment descriptor.

There are three buttons on this panel.

Remove
removes the EJB Module
Remove File
removes the specified file from the EJB Module
Update
updates the module or the application. With Update, you can add, remove, or replace modules

EJB module settings

Use this page to configure and manage a specific deployed EJB module.

Note: You cannot start or stop an individual EJB module for modification. You must start or stop the
appropriate application entirely.

To view this administrative console page, click Applications > Enterprise Applications >
applicationName > EJB modules > moduleName.

URI:

When resolved relative to the application URL, this specifies the location of the module archive contents
on a file system. The URI must match the URI of a ModuleRef URI in the deployment descriptor of the
deployed application (EAR).

Alternate DD:

Specifies a deployment descriptor to be used at run time instead of the one installed in the module.

Starting weight:

Specifies the order in which modules are started when the server starts. The module with the lowest
starting weight is started first.

Data type Integer

Default 5000
Range Greater than 0

Chapter 8. Developing WebSphere applications 1037

Client applications

Using application clients

An application client module is a Java Archive (JAR) file that contains a client for accessing a Java
application. Complete the following steps for developing different types of application clients.
1. Decide on a type of application client.
2. Develop the application client code.
a. Develop ActiveX application client code.
b. Develop J2EE application client code.
c. Develop pluggable application client code.
d. Develop thin application client code.

View the WebSphere Application Server Clients Samples Gallery for more information. To access these
samples, install WebSphere Application Server Clients, and retrieve the samples from your local file
system as the following command indicates:
<install_root>/samples/index.html

Application Client for WebSphere Application Server

In a traditional client-server environment, the client requests a service and the server fulfills the request.
Multiple clients use a single server. Clients can also access several different servers. This model persists
for Java clients except that now these requests use a client run-time environment.

In this model, the client application requires a servlet to communicate with the enterprise bean, and the
servlet must reside on the same machine as the WebSphere Application Server.

The Application Client for WebSphere Application Server Version 6 (Application Client) consists of the
following client applications:
v J2EE application client application (Uses services provided by the J2EE Client Container)
v Thin application client application (Does not use services provided by the J2EE Client Container)
v Applet application client application
v ActiveX to EJB Bridge application client application

The Application Client is packaged with the following components:

v Java Runtime Environment (JRE) (or an optional full Software Development Kit) that IBM provides
v WebSphere Application Server run time for J2EE application client applications or Thin application client
applications.
v An ActiveX to EJB Bridge run time for ActiveX to EJB Bridge application client applications (only for
Windows)
v IBM plug-in for Java platforms for Applet client applications (Windows only).

Note: The Pluggable application client is a kind of Thin application client. However, the Pluggable
application client uses a Sun JRE and Software Development Kit instead of the JRE and
Software Development Kit that IBM provides.

The ActiveX application client model, uses the Java Native Interface (JNI) architecture to programmatically
access the Java virtual machine (JVM) API. Therefore the JVM code exists in the same process space as
the ActiveX application (Visual Basic, VBScript, or Active Server Pages (ASP) files) and remains attached
to the process until that process terminates.

1038 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
In the Applet client model, a Java applet embeds in a HyperText Markup Language (HTML) document
residing on a remote client machine from the WebSphere Application Server. With this type of client, the
user accesses an enterprise bean in the WebSphere Application Server through the Java applet in the
HTML document.

The J2EE application client is a Java application program that accesses enterprise beans, Java DataBase
Connectivity (JDBC) APIs, and Java Message Service message queues. The J2EE application client
program runs on client machines. This program follows the same Java programming model as other Java
programs; however, the J2EE application client depends on the Application Client run time to configure its
execution environment, and uses the Java Naming and Directory Interface (JNDI) name space to access
resources.

The Pluggable and Thin application clients provide a lightweight Java client programming model. These
clients are useful in situations where a Java client application exists but the application needs
enhancements to use enterprise beans, or where the client application requires a thinner, more lightweight
environment than the one offered by the J2EE application client. The difference between the Thin
application client and the Pluggable application client is that the Thin application client includes a Java
virtual machine (JVM) API, and the Pluggable application client requires the user to provide this code. The
Pluggable application client uses the Sun Java Development Kit, and the Thin application client uses the
IBM Developer Kit for the Java platform.

The J2EE application client programming model provides the benefits of the J2EE platform for the Java
client application. Use the J2EE application client to develop, assemble, deploy and launch a client
application. The tooling provided with the WebSphere platform supports the seamless integration of these
stages to help the developer create a client application from start to finish.

When you develop a client application using and adhering to the J2EE platform, you can put the client
application code from one J2EE platform implementation to another. The client application package can
require redeployment using each J2EE platform deployment tool, but the code that comprises the client
application remains the same.

The Application Client run time supplies a container that provides access to system services for the client
application code. The client application code must contain a main method. The Application Client run time
invokes this main method after the environment initializes and runs until the Java virtual machine code
terminates.

The J2EE platform supports the Application Client use of nicknames or short names, defined within the
client application deployment descriptor. These deployment descriptors identify enterprise beans or local
resources (JDBC, Java Message Service (JMS), JavaMail and URL APIs) for simplified resolution through
JNDI. This simplified resolution to the enterprise bean reference and local resource reference also
eliminates changes to the client application code, when the underlying object or resource either changes
or moves to a different server. When these changes occur, the Application Client can require
redeployment.

The Application Client also provides initialization of the run-time environment for the client application. The
deployment descriptor defines this unique initialization for each client application. The Application Client
run time also provides support for security authentication to enterprise beans and local resources.

The Application Client uses the Java Remote Method Invocation-Internet InterORB Protocol (RMI-IIOP).
Using this protocol enables the client application to access enterprise bean references and to use
Common Object Request Broker Architecture (CORBA) services provided by the J2EE platform
implementation. Use of the RMI-IIOP protocol and the accessibility of CORBA services assist users in
developing a client application that requires access to both enterprise bean references and CORBA object
references.

Chapter 8. Developing WebSphere applications 1039

When you combine the J2EE and CORBA environments or programming models in one client application,
you must understand the differences between the two programming models to use and manage each
appropriately.

View the Samples gallery for more information about the Application Client.

Application client functions: Use the following table to identify the available functions in the different
types of clients.

Available functions ActiveX client Applet client J2EE Pluggable client Thin client
client
Provides all the benefits of a Yes No Yes No No
J2EE platform
Portable across all J2EE No No Yes No No
platforms
Provides the necessary run-time Yes Yes Yes Yes Yes
support for communication
between a client and a server
Supports the use of nicknames in Yes No Yes No No
the deployment descriptor files.
Note: Although you can edit
deployment descriptor files, do
not use the administrative
console to modify them.
Supports use of the RMI-IIOP Yes Yes Yes Yes Yes
protocol
Browser-based application No Yes No No No
Enables development of client Yes Yes Yes Yes Yes
applications that can access
enterprise bean references and
CORBA object references
Enables the initialization of the Yes No Yes No No
client application run-time
environment
Supports security authentication Yes Limited Yes Yes Yes
to enterprise beans
Supports security authentication Yes No Yes No No
to local resources
Requires distribution of Yes No Yes Yes Yes
application to client machines
Enables access to enterprise Yes No No No No
beans and other Java classes
through Visual Basic, VBScript,
and Active Server Pages (ASP)
code
Provides a lightweight client No Yes No Yes Yes
suitable for download
Enables access JNDI APIs for Yes Yes Yes Yes Yes
enterprise bean resolution
Runs on client machines that use No No No Yes No
the Sun Java Runtime
Environment

1040 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Supports CORBA services (using No No Yes No No
CORBA services can render the
application client code
nonportable)

ActiveX application clients:

WebSphere Application Server provides an ActiveX to EJB bridge that enables ActiveX programs to
access enterprise beans through a set of ActiveX automation objects.

The bridge accomplishes this access by loading the Java virtual machine (JVM) into any ActiveX
automation container such as Visual Basic, VBScript, and Active Server Pages (ASP).

There are two main environments in which the ActiveX to EJB bridge runs:
v Client applications, such as Visual Basic and VBScript, are programs that a user starts from the
command line, desktop icon, or Start menu shortcut.
v Client services, such as Active Server Pages, are programs started by some automated means like the
Services control panel applet.

The ActiveX to EJB bridge uses the Java Native Interface (JNI) architecture to programmatically access
the JVM code. Therefore the JVM code exists in the same process space as the ActiveX application
(Visual Basic, VBScript, or ASP) and remains attached to the process until that process terminates. To
create JVM code, an ActiveX client program calls the XJBInit() method of the XJB.JClassFactory object.
For more information about creating JVM code for an ActiveX program, see ″ActiveX to EJB bridge,
initializing JVM code’ in the information center.

After an ActiveX client program has initialized the JVM code, the program calls several methods to create
a proxy object for the Java class. When accessing a Java class or object, the real Java object exists in the
JVM code; the automation container contains the proxy for that Java object. The ActiveX program can use
the proxy object to access the Java class, object fields, and methods. For more information about using
Java proxy objects, see ″Example: Developing an ActiveX application client to enterprise beans″. For more
information about calling methods and access fields, see ″Example: Calling Java methods in the ActiveX
to enterprise beans″ and ″Java field programming tips″ in the information center.

The client program performs primitive data type conversion through the COM IDispatch interface (use of
the IUnknown interface is not directly supported). Primitive data types are automatically converted between
native automation types and Java types. All other types are handled automatically by the proxy objects For
more information about data type conversion, see ″ActiveX to Java primitive data type conversion values″
in the information center.

Any exceptions thrown in Java code are encapsulated and thrown again as a COM error, from which the
ActiveX program can determine the actual Java exceptions. For more information about handling
exceptions, see ActiveX to EJB bridge, handling errors.

The ActiveX to EJB bridge supports both free-threaded and apartment-threaded access and implements
the free threaded marshaler (FTM) to work in a hybrid environment such as Active Server Pages. For
more information about the support for threading, see ″Threading tips″ for ActiveX to EJB bridge, using
threading.

Applet clients:

The applet client provides a browser-based Java run time capable of interacting with enterprise beans
directly, instead of indirectly through a servlet.

Chapter 8. Developing WebSphere applications 1041

This client is designed to support users who want a browser-based Java client application programming
environment that provides a richer and more robust environment than the one offered by the Applet >
Servlet > enterprise bean model.

The programming model for this client is a hybrid of the Java application thin client and a servlet client.
When accessing enterprise beans from this client, the applet can consider the enterprise bean object
references as CORBA object references.

No tooling support exists for this client to develop, assemble or deploy the applet. You are responsible for
developing the applet, generating the necessary client bindings for the enterprise beans and CORBA
objects, and bundling these pieces together to install or download to the client machine. The Java applet
client provides the necessary run time to support communication between the client and the server. The
applet client run time is provided through the Java applet browser plug-in that you install on the client
machine.

Generate client-side bindings using an assembly tool such as the Application Server Toolkit (AST) or
Rational Web Developer. See ″Assembly tools″ in the information center for additional information. An
applet can utilize these bindings, or you can generate client-side bindings using the rmic command. This
command is part of the IBM Developer Kit, Java edition that is installed with the WebSphere Application
Server.

The applet client uses the RMI-IIOP protocol. Using this protocol enables the applet to access enterprise
bean references and CORBA object references, but the applet is restricted in using some supported
CORBA services.

If you combine the enterprise bean and CORBA environments in one applet, you must understand the
differences between the two programming models, and you must use and manage each model
appropriately.

The applet environment restricts access to external resources from the browser run-time environment. You
can make some of these resources available to the applet by setting the correct security policy settings in
the WebSphere Application Server client.policy file. If given the correct set of permissions, the applet
client must explicitly create the connection to the resource using the appropriate API. This client does not
perform initialization of any service that the client applet can need. For example, the client application is
responsible for the initialization of the naming service, either through the CosNaming, or the Java Naming
and Directory Interface (JNDI) APIs.

J2EE application clients:

The J2EE application client programming model provides the benefits of the Java 2 Platform for
WebSphere Application Server Enterprise product.

The J2EE platform offers the ability to seamlessly develop, assemble, deploy and launch a client
application. The tooling provided with the WebSphere platform supports the seamless integration of these
stages to help the developer create a client application from start to finish.

When you develop a client application using and adhering to the J2EE platform, you can put the client
application code from one J2EE platform implementation to another. The client application package can
require redeployment using each J2EE platform deployment tool, but the code that comprises the client
application does not change.

The J2EE application client run time supplies a container that provides access to system services for the
application client code. The J2EE application client code must contain a main method. The J2EE
application client run time invokes this main method after the environment initializes and runs until the
Java virtual machine application terminates.

1042 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Application clients can use nicknames or short names, defined within the client application deployment
descriptor with the J2EE platform. These deployment descriptors identify enterprise beans or local
resources (JDBC data sources, J2C connection factories, Java Message Service (JMS), JavaMail and
URL APIs) for simplified resolution through JNDI use. This simplified resolution to the enterprise bean
reference and local resource reference also eliminates changes to the application client code, when the
underlying object or resource either changes or moves to a different server. When these changes occur,
the application client can require redeployment. Although you can edit deployment descriptor files, do not
use the administrative console to modify them.

The J2EE application client also provides initialization of the run-time environment for the client application.
The deployment descriptor defines this unique initialization for each client application. The J2EE
application client run time also provides support for security authentication to the enterprise beans and
local resources.

The J2EE application client uses the Java Remote Method Invocation technology run over Internet
Inter-Orb Protocol (RMI-IIOP). Using this protocol enables the client application to access enterprise bean
references and to use Common Object Request Broker Architecture (CORBA) services provided by the
J2EE platform implementation. Use of the RMI-IIOP protocol and the accessibility of CORBA services
assist users in developing a client application that requires access to both enterprise bean references and
CORBA object references.

When you combine the J2EE and the CORBA WebSphere Application Server Enterprise environments or
programming models in one client application, you must understand the differences between the two
programming models to use and manage each appropriately.

Pluggable application clients:

The Pluggable application client provides a lightweight, downloadable Java application run time capable of
interacting with enterprise beans.

The Pluggable application client requires that you have previously installed the Sun Java Runtime
Environment (JRE) files. In all other aspects, the Pluggable application client, and the Thin application
client are similar.

Note: The Pluggable application client is only available on the Windows platform.

This client is designed to support those users who want a lightweight Java client application programming
environment, without the overhead of the J2EE platform on the client machine. The programming model
for this client is heavily influenced by the CORBA programming model, but supports access to enterprise
beans.

When accessing enterprise beans from this client, the client application can consider the enterprise beans
object references as CORBA object references.

Tooling does not exist on the client; however, tooling does exists on the server. You are responsible for
developing the client application, generating the necessary client bindings for the enterprise bean and
CORBA objects, and after bundling these pieces together, installing them on the client machine.

The Pluggable application client provides the necessary run time to support the communication needs
between the client and the server.

The Pluggable application client uses the RMI-IIOP protocol. Using this protocol enables the client
application to access enterprise bean references and CORBA object references and use any supported
CORBA services. Using the RMI-IIOP protocol along with the accessibility of CORBA services can assist a
user in developing a client application that needs to access both enterprise bean references and CORBA
object references.

Chapter 8. Developing WebSphere applications 1043

When you combine the J2EE and CORBA environments in one client application, you must understand the
differences between the two programming models to use and manage each appropriately.

The Pluggable application client run time provides the necessary support for the client application for
object resolution, security, Reliability Availability and Serviceability (RAS), and other services. However,
this client does not support a container that provides easy access to these services. For example, no
support exists for using nicknames for enterprise beans or local resource resolution. When resolving to an
enterprise bean (using either the Java Naming and Directory Interface (JNDI) API or CosNaming) sources,
the client application must know the location of the name server and the fully qualified name used when
the reference was bound into the name space.

When resolving to a local resource, the client application cannot resolve to the resource through a JNDI
lookup. Instead the client application must explicitly create the connection to the resource using the
appropriate API (JDBC, Java Message Service (JMS), and so on). This client does not perform
initialization of any of the services that the client application might require. For example, the client
application is responsible for the initialization of the naming service, either through CosNaming or JNDI
APIs.

The Pluggable application client offers access to most of the available client services in the J2EE
application client. However, you cannot access the services in the Pluggable application client as easily as
you can in the J2EE application client. The J2EE client has the advantage of performing a simple Java
Naming and Directory Interface (JNDI) name space lookup to access the desired service or resource. The
Pluggable application client must code explicitly for each resource in the client application. For example,
looking up an enterprise bean Home object requires the following code in a J2EE application client:
java.lang.Object ejbHome = initialContext.lookup("java:/comp/env/ejb/MyEJBHome"
);
MyEJBHome = (MyEJBHome)javax.rmi.PortableRemoteObject.narrow(ejbHome,
MyEJBHome.class);

However, you need more explicit code in a Pluggable application client for Java:

java.lang.Object ejbHome = initialContext.lookup("the/fully/qualified

/path/to/actual/home/in/namespace/MyEJBHome");
MyEJBHome = (MyEJBHome)javax.rmi.PortableRemoteObject.narrow(ejbHome,
MyEJBHome.class);

In this example, the J2EE application client accesses a logical name from the java:/comp name space.
The J2EE client run time resolves that name to the physical location and returns the reference to the client
application. The pluggable client must know the fully qualified physical location of the enterprise bean
Home object in the name space. If this location changes, the pluggable client application must also change
the value placed on the lookup() statement.

In the J2EE client, the client application is protected from these changes because it uses the logical name.
A change can require a redeployment of the EAR file, but the actual client application code remains the
same.

The Pluggable application client is a traditional Java application that contains a main function. The
WebSphere Pluggable application client provides run-time support for accessing remote enterprise beans,
and provides the implementation for various services (security, Workload Management (WLM), and
others). This client can also access CORBA objects and CORBA-based services. When using both
environments in one client application, you need to understand the differences between the enterprise
bean and the CORBA programming models to manage both environments.

For instance, the CORBA programming model requires the CORBA CosNaming name service for object
resolution in a name space. The enterprise beans programming model requires the JNDI name service.
The client application must initialize and properly manage these two naming services.

1044 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Another difference applies to the enterprise bean model. Use the Java Naming and Directory Interface
(JNDI) implementation in the enterprise bean model to initialize the Object Request Broker (ORB). The
client application is unaware that an ORB is present. The CORBA model, however, requires the client
application to explicitly initialize the ORB through the ORB.init() static method.

The Pluggable application client provides a batch command that you can use to set the CLASSPATH and
JAVA_HOME environment variables to enable the Pluggable application client run time.

Thin application clients:

The thin application client provides a lightweight, downloadable Java application run time capable of
interacting with enterprise beans.

This client is designed to support those users who want a lightweight Java client application programming
environment, without the overhead of the J2EE platform on the client machine. The programming model
for this client is heavily influenced by the CORBA programming model, but supports access to enterprise
beans.

When accessing enterprise beans from this client, the client application can consider the enterprise beans
object references as CORBA object references.

Tooling does not exist on the client, it exists on the server. You are responsible for developing the client
application, generating the necessary client bindings for the enterprise bean and CORBA objects, and
bundling these pieces together to install on the client machine.

The thin application client provides the necessary run-time to support the communication needs between
the client and the server.

The thin application client uses the RMI-IIOP protocol. Using this protocol enables the client application to
access not only enterprise bean references and CORBA object references, but also allows the client
application to use any supported CORBA services. Using the RMI-IIOP protocol along with the accessibility
of CORBA services can assist a user in developing a client application that needs to access both
enterprise bean references and CORBA object references.

When you combine the J2EE and CORBA environments in one client application, you must understand the
differences between the two programming models, to use and manage each appropriately.

The thin application client run time provides the necessary support for the client application for object
resolution, security, Reliability Availability and Servicability (RAS), and other services. However, this client
does not support a container that provides easy access to these services. For example, no support exists
for using nicknames for enterprise beans or local resource resolution. When resolving to an enterprise
bean (using either Java Naming and Directory Interface (JNDI) or CosNaming) sources, the client
application must know the location of the name server and the fully qualified name used when the
reference was bound into the name space. When resolving to a local resource, the client application
cannot resolve to the resource through a JNDI lookup. Instead the client application must explicitly create
the connection to the resource using the appropriate API (JDBC, Java Message Service (JMS), and so
on). This client does not perform initialization of any of the services that the client application might
require. For example, the client application is responsible for the initialization of the naming service, either
through CosNaming or JNDI APIs.

The thin application client offers access to most of the available client services in the J2EE application
client. However, you cannot access the services in the thin client as easily as you can in the J2EE
application client. The J2EE client has the advantage of performing a simple Java Naming and Directory
Interface (JNDI) name space lookup to access the desired service or resource. The thin client must code
explicitly for each resource in the client application. For example, looking up an enterprise bean Home
requires the following code in a J2EE application client:

Chapter 8. Developing WebSphere applications 1045

 java.lang.Object ejbHome = initialContext.lookup("java:/comp/env/ejb/MyEJBHome");
MyEJBHome = (MyEJBHome)javax.rmi.PortableRemoteObject.narrow(ejbHome, MyEJBHome.class);

However, you need more explicit code in a Java thin application client:

java.lang.Object ejbHome =
initialContext.lookup("the/fully/qualified/path/to/actual/home/in/namespace/MyEJBHome");
MyEJBHome = (MyEJBHome)javax.rmi.PortableRemoteObject.narrow(ejbHome, MyEJBHome.class);

In this example, the J2EE application client accesses a logical name from the java:/comp name space.
The J2EE client run time resolves that name to the physical location and returns the reference to the client
application. The thin client must know the fully qualified physical location of the enterprise bean Home in
the name space. If this location changes, the thin client application must also change the value placed on
the lookup() statement.

In the J2EE client, the client application is protected from these changes because it uses the logical name.
A change might require a redeployment of the EAR file, but the actual client application code remains the
same.

The thin application client is a traditional Java application that contains a main function. The WebSphere
thin application client provides run-time support for accessing remote enterprise beans, and provides the
implementation for various services (security, Workload Management (WLM), and others). This client can
also access CORBA objects and CORBA based services. When using both environments in one client
application, you need to understand the differences between the enterprise bean and CORBA
programming models to manage both environments.

For instance, the CORBA programming model requires the CORBA CosNaming name service for object
resolution in a name space. The enterprise beans programming model requires the JNDI name service.
The client application must initialize and properly manage these two naming services.

Another difference applies to the enterprise bean model. Use the Java Naming and Directory Interface
(JNDI) implementation in the enterprise bean model to initialize the Object Request Broker (ORB). The
client application is unaware that an ORB is present. The CORBA model, however, requires the client
application to explicitly initialize the ORB through the ORB.init() static method.

The thin application client provides a batch command that you can use to set the CLASSPATH and
JAVA_HOME environment variables to enable the thin application client run time.

Application client troubleshooting tips

This section provides some debugging tips for resolving common Java 2 Platform Enterprise Edition
(J2EE) application client problems. To use this troubleshooting guide, review the trace entries for one of
the J2EE application client exceptions, and then locate the exception in the guide. Some of the errors in
the guide are samples, and the actual error you receive can be different than what is shown here. You
might find it useful to rerun the launchClient command specifying the -CCverbose=true option. This option
provides additional information when the J2EE application client run time is initializing

Error: java.lang.NoClassDefFoundError

Explanation This exception is thrown when Java code cannot load the specified class.
Possible causes v Invalid or non-existent class
v Class path problem
v Manifest problem

1046 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Recommended Check to determine if the specified class exists in a Java Archive (JAR) file within your
response Enterprise Archive (EAR) file. If it does, make sure the path for the class is correct. For
example, if you get the exception:
java.lang.NoClassDefFoundError:
WebSphereSamples.HelloEJB.HelloHome

verify that the HelloHome class exists in one of the JAR files in your EAR file. If it exists,
verify that the path for the class is WebSphereSamples.HelloEJB.

If both the class and path are correct, then it is a class path issue. Most likely, you do not
have the failing class JAR file specified in the client JAR file manifest. To verify this situation,
perform the following steps:
1. Open your EAR file with the Application Server Toolkit or the Rational Web Developer
assembly tool, and select the Application Client.
2. Add the names of the other JAR files in the EAR file to the Classpath field.

This exception is generally caused by a missing Enterprise Java Beans (EJB) module name
from the Classpath field.

If you have multiple JAR files to enter in the Classpath field, be sure to separate the JAR
names with spaces.

If you still have the problem, you have a situation where a class is loaded from the file
system instead of the EAR file. This error is difficult to debug because the offending class is
not the one specified in the exception. Instead, another class is loaded from the file system
before the one specified in the exception. To correct this error, review the class paths
specified with the -CCclasspath option and the class paths configured with the Application
Client Resource Configuration Tool. Look for classes that also exist in the EAR file. You must
resolve the situation where one of the classes is found on the file system instead of in the
.ear file. Remove entries from the classpaths, or include the .jar files and classes in the
.ear file instead of referencing them from the file system.

If you use the -CCclasspath parameter or resource classpaths in the Application Client
Resource Configuration Tool, and you have configured multiple JAR files or classes, verify
they are separated with the correct character for your operating system. Unlike the Classpath
field, these class path fields use platform-specific separator characters, usually a colon (on
UNIX platforms) or a semi-colon (on Windows systems).
Note: The system class path is not used by the Application Client run time if you use the
launchClient batch or shell files. In this case, the system class path would not cause this
problem. However, if you load the launchClient class directly, you do have to search through
the system class path as well.

Error: com.ibm.websphere.naming.CannotInstantiateObjectException: Exception occurred while

attempting to get an instance of the object for the specified reference object. [Root exception is
javax.naming.NameNotFoundException: xxxxxxxxxx]

Explanation This exception occurs when you perform a lookup on an

object that is not installed on the host server. Your
program can look up the name in the local client Java
Naming and Directory Interface (JNDI) name space, but
received a NameNotFoundException exception because it
is not located on the host server. One typical example is
looking up an EJB component that is not installed on the
host server that you access. This exception might also
occur if the JNDI name you configured in your Application
Client module does not match the actual JNDI name of
the resource on the host server.

Chapter 8. Developing WebSphere applications 1047

Possible causes v Incorrect host server invoked
v Resource is not defined
v Resource is not installed
v Application server is not started
v Invalid JNDI configuration
Recommended response If you are accessing the wrong host server, run the
launchClient command again with the -CCBootstrapHost
parameter specifying the correct host server name. If you
are accessing the correct host server, use the product
dumpnamespace command line tool to see a listing of the
host server JNDI name space. If you do not see the failing
object name, the resource is either not installed on the
host server or the appropriate application server is not
started. If you determine the resource is already installed
and started, your JNDI name in your client application
does not match the global JNDI name on the host server.
Use the Application Server Toolkit to compare the JNDI
bindings value of the failing object name in the client
application to the JNDI bindings value of the object in the
host server application. The values must match.

Error: javax.naming.ServiceUnavailableException: A communication failure occurred while

attempting to obtain an initial context using the provider url: ″iiop://[invalidhostname]″. Make sure
that the host and port information is correct and that the server identified by the provider URL is a
running name server. If no port number is specified, the default port number 2809 is used. Other
possible causes include the network environment or workstation network configuration. Root
exception is org.omg.CORBA.INTERNAL: JORB0050E: In Profile.getIPAddress(),
InetAddress.getByName[invalidhostname] threw an UnknownHostException. minor code: 4942F5B6
completed: Maybe

Explanation This exception occurs when you specify an invalid host

server name.
Possible causes v Incorrect host server invoked
v Invalid host server name
Recommended response Run the launchClient command again and specify the
correct name of your host server with the
-CCBootstrapHost parameter.

Error: javax.naming.CommunicationException: Could not obtain an initial context due to a

communication failure. Since no provider URL was specified, either the bootrap host and port of an
existing ORB was used, or a new ORB instance was created and initialized with the default
bootstrap host of ″localhost″ and the default bootstrap port of 2809. Make sure the ORB bootstrap
host and port resolve to a running name server. Root exception is
org.omg.CORBA.COMM_FAILURE: WRITE_ERROR_SEND_1 minor code: 49421050 completed: No

Explanation This exception occurs when you run the launchClient

command to a host server that does not have the
Application Server started. You also receive this exception
when you specify an invalid host server name. This
situation might occur if you do not specify a host server
name when you run the launchClient tool. The default
behavior is for the launchClient tool to run to the local
host, because WebSphere Application Server does not
know the name of your host server. This default behavior
only works when you are running the client on the same
machine with WebSphere Application Server is installed.

1048 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Possible causes v Incorrect host server invoked
v Invalid host server name
v Invalid reference to localhost
v Application server is not started
v Invalid bootstrap port
Recommended response If you are not running to the correct host server, run the
launchClient command again and specify the name of
your host server with the -CCBootstrapHost parameter.
Otherwise, start the Application Server on the host server
and run the launchClient command again.

Error: javax.naming.NameNotFoundException: Name comp/env/ejb not found in context ″java:″

Explanation This exception is thrown when the Java code cannot

locate the specified name in the local JNDI name space.
Possible causes v No binding information for the specified name
v Binding information for the specified name is incorrect
v Wrong class loader was used to load one of the
program classes
v A resource reference does not include any client
configuration information
Recommended response Open the EAR file with the Application Server Toolkit, and
check the bindings for the failing name. Ensure this
information is correct. If you are using Resource
References, open the EAR file with the Application Client
Resource Configuration Tool, and verify that the Resource
Reference has client configuration information and the
name of the Resource Reference exactly matches the
JNDI name of the client configuration. If the values are
correct, you might have a class loader error.

Error: java.lang.ClassCastException: Unable to load class:

org.omg.stub.WebSphereSamples.HelloEJB._HelloHome_Stub at
com.ibm.rmi.javax.rmi.PortableRemoteObject.narrow(portableRemoteObject.java:269)

Explanation This exception occurs when the application program

attempts to narrow to the EJB home class and the class
loaders cannot find the EJB client side bindings.
Possible causes v The files, *_Stub.class and _Tie.class, are not in the
EJB .jar file
v Class loader could not find the classes
Recommended response Look at the EJB .jar file located in the .ear file and verify
the class contains the Enterprise Java Beans (EJB) client
side bindings. These are class files with file names that
end in _Stub and _Tie. If the binding classes are in the
EJB .jar file, then you might have a class loader error.

Error: WSCL0210E: The Enterprise archive file [EAR file name] could not be found.
com.ibm.websphere.client.applicationclient.ClientContainerException:
com.ibm.etools.archive.exception.OpenFailureException

Explanation This error occurs when the application client run time
cannot read the Enterprise Archive (EAR) file.
Possible causes The most likely cause of this error is that the system
cannot find the EAR file cannot be found in the path
specified on the launchClient command.

Chapter 8. Developing WebSphere applications 1049

Recommended response Verify that the path and file name specified on the
launchclient command are correct. If you are running on
the Windows operating system and the path and file name
are correct, use a short version of the path and file name
(8 character file name and 3 character extension).

The launchClient command appears to hang and does not return to the command line when the
client application has finished.

Explanation When running your application client using the

launchClient command the WebSphere Application
Server run time might need to display the security login
dialog. To display this dialog, WebSphere Application
Server run time creates an Abstract Window Toolkit (AWT)
thread. When your application returns from its main
method to the application client run time, the application
client run time attempts to return to the operating system
and end the Java virtual machine (JVM) code. However,
since there is an AWT thread, the JVM code will not end
until System.exit is called.
Possible causes The JVM code does not end because there is an AWT
thread. Java code requires that System.exit() be called
to end AWT threads.
Recommended response v Modify your application to call System.exit(0) as the
last statement.
v Use the -CCexitVM=true parameter when you call the
launchClient command.

For current information available from IBM Support on known problems and their resolution, see the IBM
customer support page.

IBM Support has documents that can save you time gathering information needed to resolve this problem.
Before opening a PMR, see the IBM customer support page.

Running application clients

The J2EE specification requires support for a client container that runs stand-alone Java applications
(known as J2EE application clients) and provides J2EE services to the applications. J2EE services include
naming, security, and resource connections.

You are ready to run your application client using this tool after you have:
1. Written the application client program.
2. Assembled and installed an application module (.ear file) in the application server run time.
3. Deployed the application using the Application Client Resource Configuration Tool (ACRCT).

This task only applies to J2EE application clients.

1. Open a command window and invoke the following script to launch J2EE application clients using the
launchClient shell:
install_root/bin/launchClient.bat
The launchClient batch command starts the application client run time, which:
v Initializes the client run time.
v Loads the class that you designated as the main class with an assembly tool. See ″Starting an
assembly tool″ in the information center.
v Runs the main method of the application client program.

1050 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 When your program terminates, the application client run time cleans up the environment and the Java
virtual machine (JVM) code ends.
2. Pass parameters to the launchClient command or to your application client program as well. The
launchClient command allows you to do both. The launchClient command requires that the first
parameter is either:
v An EAR file specifying the application client to launch.
v A request for launchClient usage information.
The following example illustrates the command line invocation syntax for the launchClient tool (shown
here on 2 lines for publication):
launchClient [-profileName pName | -JVMOptions options | -help | -?] <userapp>
[-CC<name>=<value>] [app args]
where
v userapp.ear is the path and the name of the EAR file that contains the application client.
v -CC<name>=<value> is the client container name-value pair parameter. See the client container
parameters section, for supported name-value pair arguments.
v app args are arguments that pass to the application client.
v -profileName defines the profile of the Application Server process in a multi-profile installation. The
-profileName option is not required for running in a single profile environment or in an Application
Clients installation. The default is default_profile.
v -JVMOptions is a valid Java standard or non-standard option string. Insert quotation marks around
the string.
v -help, -? prints the usage information.
All other parameters intended for the launchClient command must begin with the -CC prefix.
Parameters that are not EAR files, or usage requests, or that do not begin with the -CC prefix, are
ignored by the application client run time, and are passed directly to the application client program.
The launchClient command retrieves parameters from three places:
v The command line
v A properties file
v System properties
The parameters are resolved in the order listed above, with command line values having the highest
priority and system properties the lowest. Using this prioritization you can set and override default
values.
3. Specify the server name. By default, the launchClient command uses the localhost for the
BootstrapHost property value. This setting is effective for testing your application client when it is
installed on the same computer as the server. However, in other cases override this value with the
name of your server.
You can override the BootstrapHost value by invoking launchClient command with the following
parameters:
launchClient myapp.ear -CCBootstrapHost=abc.midwest.mycompany.com
You can also override the default by specifying the value in a properties file and passing the file name
to the launchClient shell.
Security is controlled by the server. You do not need to configure security on the client because the
client assumes that security is enabled. If server security is not enabled, then the server ignores the
security request, and the application client functions as expected.

You can store launchClient values in a properties file, which is a good method for distributing default
values. You can then override one or more values on the command line. The format of the file is one
launchClient -CC parameter per line without the -CC prefix. For example:
verbose=true classpath=c:\mydir\util.jar;c:\mydir\harness.jar;c:\production\G19
\global.jar BootstrapHost=abc.westcoast.mycompany.com tracefile=c:\WebSphere\mylog.txt

Chapter 8. Developing WebSphere applications 1051

launchClient tool
This section describes the Java 2 Platform Enterprise Edition (J2EE) command line syntax for the
launchClient tool for WebSphere Application Server. You can use the launchClient command from a node
within a Network Deployment environment. However, do not attempt to use the launchClient command
from the Deployment Manager.

The following example illustrates the command line invocation syntax for the launchClient tool (shown here
on 2 lines for publication):
launchClient [-profileName pName | -JVMOptions options | -help | -?]
<userapp> [-CC<name>=<value>] [app args]

where
v userapp.ear is the path and the name of the EAR file that contains the application client.
v -CC<name>=<value> is the client container name-value pair parameter. See the client container
parameters section, for supported name-value pair arguments.
v app args are arguments that pass to the application client.
v -profileName defines the profile of the Application Server process in a multi-profile installation. The
-profileName option is not required for running in a single profile environment or in an Application
Clients installation. The default is default_profile.
v -JVMOptions is a valid Java standard or nonstandard option string. Insert quotation marks around the
string.
v -help, -? prints the usage information.

The first parameter must be -help, -? or contain no parameter at all. The -profileName pName and
-JVMOptions options are optional parameters. If used, they must appear before the <userapp> parameter.
All other parameters are optional and can appear in any order after the <userapp> parameter. The J2EE
Application client run time ignores any optional parameters that do not begin with a -CC prefix and passes
those parameters to the application client.

Client container parameters

Supported arguments include:

-CCsoapConnectorPort
The Simple Object Access Protocol (SOAP) connector port. If you do not specify this argument, the
WebSphere Application Server default value is used.
-CCverbose
This option displays additional information messages. The default is false.
-CCclasspath
A class path value. When you launch an application, the system class path is used. If you want to
access classes that are not in the EAR file or part of the system class paths, specify the appropriate
class path here. Multiple paths can be concatenated.
-CCjar
The name of the client Java Archive (JAR) file that resides within the EAR file for the application you
wish to launch. Use this argument when you have multiple client JAR files in the EAR file.
-CCadminConnectorHost
Specifies the host name of the server from which configuration information is retrieved. The default is
the value of the -CCBootstrapHost parameter or the value, localhost, if the -CCBootstrapHost
parameter is not specified.

1052 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
-CCadminConnectorPort
Indicates the port number for the administrative client function to use. The default value is 8880 for
SOAP connections and 2809 for Remote Method Invocation (RMI) connections.
-CCadminConnectorType
Specifies how the administrative client connects to the server. Specify RMI to use the RMI connection
type, or specify SOAP to use the SOAP connection type. The default value is SOAP.
-CCadminConnectorUser
Administrative clients use this user name when a server requires authentication. If the connection type
is SOAP, and security is enabled on the server, this parameter is required. The SOAP connector does
not prompt for authentication.
-CCadminConnectorPassword
The password for the user name that the -CCadminConnectorUser parameter specifies.
-CCaltDD
The name of an alternate deployment descriptor file. This parameter is used with the -CCjar parameter
to specify the deployment descriptor to use. Use this argument when a client JAR file is configured
with more than one deployment descriptor. Set the value to null to use the client JAR file standard
deployment descriptor.
-CCBootstrapHost
The name of the host server you want to connect to initially. The format is:
your_server_of_choice.com
-CCBootstrapPort
The server port number. If you do not specify this argument, the WebSphere Application Server default
value is used.
-CCproviderURL
Provides bootstrap server information that the initial context factory can use to obtain an initial context.
WebSphere Application Server initial context factory can use either a Common Object Request Broker
Architecture (CORBA) object URL or an Internet Inter-ORB Protocol (IIOP) URL. CORBA object URLs
are more flexible than IIOP URLs and are the recommended URL format to use. This value can
contain more than one bootstrap server address. This feature can be used when attempting to obtain
an initial context from a server cluster. You can specify bootstrap server addresses, for all servers in
the cluster, in the URL. The operation will succeed if at least one of the servers is running, eliminating
a single point of failure. The address list does not process in a particular order. For naming operations,
this value overrides the -CCBootstrapHost and -CCBootstrapPort parameters. A CORBA object URL
specifying multiple systems is illustrated in the following example:
-CCproviderURL=corbaloc:iiop:myserver.mycompany.com:9810,:mybackupserver.mycompany.com:2809

This value is mapped to the java.naming.provider.url system property.

-CCinitonly
Use this option to initialize application client run time for ActiveX application clients without launching
the client application. The default is false.
-CCtrace
Use this option to obtain debug trace information. You might need this information when reporting a
problem to IBM customer support. The default is false For more information, read the topic ″Enabling
trace″ in the Troubleshooting and support PDF.
-CCtracefile
Indicates the name of the file to which trace information is written. The default is to write output to the
console.
-CCpropfile
Indicates the name of a properties file that contains launchClient properties. Specify the properties
without the -CC prefix in the file. For example: verbose=true.

Chapter 8. Developing WebSphere applications 1053

-CCsecurityManager
Enables and runs the WebSphere Application Server with a security manager. The default is disable.
-CCsecurityMgrClass
Indicates the fully qualified name of a class that implements a security manager. Only use this
argument if the -CCsecurityManager parameter is set to enable. The default is
java.lang.SecurityManager.
-CCsecurityMgrPolicy
Indicates the name of a security manager policy file. Only use this argument if the -CCsecurityManager
parameter is set to enable. When you enable this parameter, the java.security.policy system
property is set. The default is <install_root>/ properties/client.policy.
-CCD
Use this option to have the WebSphere Application Server set the specified system property during
initialization. Do not use the equals (=) character after the -CCD. For example:
-CCDcom.ibm.test.property=testvalue. You can specify multiple -CCD parameters. The general format
of this parameter is -CCD<property key>=<property value>.
-CCexitVM
Use this option to have the WebSphere Application Server call the System.exit() method after the
client application completes. The default is false.
-CCdumpJavaNameSpace
Prints out the Java portion of the Java Naming and Directory Interface (JNDI) name space for
WebSphere Application Server. The true value uses the short format that prints out the binding name
and the type of the object bound at that location. The long value uses the long format that prints out
the binding name, bound object type, local object, type and string representation of the local object, for
example, IORs and string values. The default value is false.
-CCtraceMode
Specifies the trace format to use for tracing. If the valid value, basic, is not specified the default is
advanced. Basic tracing format is a more compact form of tracing. For more information on basic and
advanced trace formatting, read the topic ″Interpreting trace output″ in the Troubleshooting and
support PDF.
-CCclassLoaderMode
Specifies the class loader mode. If PARENT_LAST is specified, the class loader loads classes from
the local class path before delegating the class loading to its parent. The classes loaded for the
following are affected:
v Classes defined for the J2EE application client
v Resources defined in the J2EE application
v Classes specified on the manifest of the J2EE client JAR file
v Classes specified using the -CCclasspath option
If PARENT_LAST is not specified, then the default mode, PARENT_FIRST, causes the class loader to
delegate the loading of classes to its parent class loader before attempting to load the class from its
local class path.

The following examples demonstrate correct syntax.

On the Windows operating system:
launchClient c:\earfiles\myapp.ear -CCBootstrapHost=myWASServer -CCverbose=true
app_parm1 app_parm2
On the UNIX operating system:
./launchClient.sh /usr/earfiles/myapp.ear -CCBootstrapHost=myWASServer -CCverbose=true
app_parm1 app_parm2

Specifying the directory for an expanded EAR file:

1054 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Each time the launchClient tool is called, it extracts the Enterprise Archive (EAR) file to a random directory
name in the temporary directory on your hard drive. Then the tool sets up the thread ClassLoader to use
the extracted EAR file directory and JAR files included in the Manifest.mf client Java Archive (JAR) file. In
a normal J2EE Java client, these files are automatically cleaned up after the application exits. This
cleanup occurs when the client container shutdown hook is called. To avoid extracting the EAR file (and
removing the temporary directory) each time the launchClient tool is called, complete the following steps:
1. Specify a directory to extract the EAR file by setting the
com.ibm.websphere.client.applicationclient.archivedir Java system property. If the directory does
not exist or is empty, the EAR file is extracted normally. If the EAR file was previously extracted, the
launchClient tool reuses the directory.
2. Delete the directory before running the launchClient tool again, if you need to update your EAR file.
When you call the launchClient command, it extracts the new EAR file to the directory. If you do not
delete the directory or change the system property value to point to a different directory, the
launchClient tool reuses the currently extracted EAR file and does not use your changed EAR file.
When specifying the com.ibm.websphere.client.applicationclient.archivedir property, make sure
that the directory you specify is unique for each EAR file you use. For example, do not point the
MyEar1.ear and the MyEar2.ear files to the same directory.

Java Web Start architecture for deploying application clients

Java Web Start is an application-deployment technology that includes the portability of applets, the
maintainability of servlets and JavaServer Pages (JSP) file technology, and the simplicity of mark-up
languages such as XML and HTML. It is a Java application that allows full-featured Java 2 client
applications to be launched, deployed and updated from a standard Web server. Upon launching Java
Web Start for the first time, you might download new client applications from the Web. Each time you
launch JWS thereafter, you can initiate applications either through a link on a Web page or (in Windows)
from desktop icons or the Start menu. You can deploy applications quickly using Java Web Start, cache
applications on the client machine, and launch applications remotely offline. Additionally, because Java
Web Start is built from the J2EE infrastructure, the technology inherits the complete security architecture of
the J2EE platform.

The technology underlying Java Web Start is the Java Network Launching Protocol & API (JNLP). Java
Web Start is a JNLP client and it reads and parses a JNLP descriptor file (JNLP file). Base on the JNLP
descriptor, it downloads appropriate pieces of a client application and any of its dependencies. If any of the
pieces of the application are already cached on the client machine, then those components are not
downloaded again, unless they have been updated on the server machine. After you download and cache
the client application, JWS launches it natively on the client machine.

The following diagram shows an overview of launching a client application, include the Application Client
for WebSphere Application Server, Version 6 as a dependent resource, using Java Web Start.

Chapter 8. Developing WebSphere applications 1055

 WebSphereClientLauncher.jar
Web application-desc
EAR file for a J2EE application
browser JNLP
or JAR file for a non-J2EE application

Java Network
Launching Protocol
(JNLP) files component-desc
JNLP
WebSphere JARs

Java WebStart WASClient6.0_runtime.jar

installer-desc
(JWS) JNLP WebSphereClientRuntimeInstaller.jar

The Web browser running on a client machine connects to a Web application located on a server
machine. The client application JNLP descriptor file is downloaded and processed by Java Web Start on
the client machine.

In this diagram, there are three JNLP descriptor files:

v Client application JNLP descriptor (application-desc in the diagram)
v Application Clients run-time installer JNLP descriptor (installer-desc in the diagram)
v Application Clients run-time library component JNLP descriptor (component-desc in the diagram)

Each of these JNLP descriptor files, the client application (JAR or EAR) and the dependent resource JAR
files are packaged as Web applications in an EAR file. This EAR file is deployed to an Application server.
The client machine with JWS installed uses a Web browser to connect to the url of the client application
JNLP descriptor file to download and run the client application.

Using Java Web Start product version 1.4.2 or later is highly recommended. The following operating
systems support running J2EE application client applications and or Thin application client applications
using Java Web Start:
v Red Hat Enterprise Linux for Intel, Version 3.0
v SuSE Linux Enterprise Server, Versions 8 and 9
v Windows 2000 Professional, Windows 2000 Professional, Windows Advance Server, and Windows 2000
Advance Server
v AIX, Versions 5.1, 5.2, and 5.3
v Solaris, Versions 8 and 9
v HP-UX 11i

You can use Java Web Start on the Java 2 Standard Edition Developer Kits that IBM provides, packaged
in Application Client for WebSphere Application Server, Version 6; Java Web Start on Sun Microsystems
J2SE Software Development Kit or J2SE Java Runtime Environment 1.4.2, which you can download from
the Sun Microsystems Web site for Windows, Linux and Solaris operating systems, or the Java Web Start
on HP SDK or RTE for Java 2 version 1.4.2, which you can download from the HP Web site.

1056 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Using Java Web Start
Before you begin this task, see the following topics to understand Java Web Start technology and its
components:
v “Java Web Start architecture for deploying application clients” on page 1055
v “Client application Java Network Launcher Protocol deployment descriptor file”
v “ClientLauncher class” on page 1060

Note: You can use Java Web Start on Java 2 Standard Edition Developer Kits that IBM provides,
packaged in the Application Client for WebSphere Application Server, Version 6; Java Web Start on
Sun Microsystems J2SE Software Development Kit or J2SE Java Runtime Environment 1.4.2,
which you can download from the Sun Microsystems Web site for Windows, Linux and Solaris
operating systems, or the Java Web Start on HP SDK or RTE for Java 2 version 1.4.2, which you
can download from the HP Web site.
1. Prepare the Application Clients run-time dependency component for JWS.
2. Prepare the Application Clients run-time library component for JWS.
3. Optional: Run the Java Web Start sample.

Note: Problem: When you run Web services clients from Java Web Start using a Mozilla browser, you
might get errors if the client argument contains quotations in the jnlp.jsp file. For example, the
following argument (shown here on 2 lines for publication) )results in an error:
<argument>-url="wsejb:/com.ibm.wssvt.tc.pli.ejb.WSMultiProtocolHome?jndiName=com/ibm
/wssvt/tc/pli/ejb/WSMultiProtocolHome&"</argument>

Error: The following errors display in the Java Web Start console:
Client caught exception getting the InsuranceWebServicesPort
using the URL
"wsejb:/com.ibm.wssvt.tc.pli.ejb.WSMultiProtocolHome?jndiName=
com/ibm/wssvt/tc/pli/ejb/WSMultiProtocolHome&"
java.net.MalformedURLException: no protocol:
"wsejb:/com.ibm.wssvt.tc.pli.ejb.WSMultiProtocolHome?jndiName=
com/ibm/wssvt/tc/pli/ejb/WSMultiProtocolHome&"
at java.net.URL.<init>(URL.java(Compiled Code))
at java.net.URL.<init>(URL.java(Compiled Code))
at java.net.URL.<init>(URL.java:411)
at com.ibm.wssvt.tc.pli.webservice.InsuranceWebServicesClient.getInsuranceServicesClientURL(
InsuranceWebServicesClient.java:231)
at com.ibm.wssvt.tc.pli.webservice.InsuranceWebServicesClient.main(
InsuranceWebServicesClient.java:748)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:85)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:58)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:60)
at java.lang.reflect.Method.invoke(Method.java:391)
at com.ibm.websphere.client.applicationclient.launchClient.createContainerAndLaunchApp(
launchClient.java:649)

Solution: Update the jnlp.jsp file to remove the quotation marks (″ ″) from the argument. Use
the following example argument (shown here on 2 lines for publication) to correct the errors:
<argument>-url=wsejb:/com.ibm.wssvt.tc.pli.ejb.WSMultiProtocolHome?jndiName=
com/ibm/wssvt/tc/pli/ejb/WSMultiProtocolHome&</argument>

Now rerun the client from Java Web Start.

Client application Java Network Launcher Protocol deployment descriptor file: The deployment
descriptor file is the main Java Network Launcher Protocol (JNLP) descriptor file for the client application.
The client application has an Application Clients run-time dependency that provides the Java 2 Runtime
Environment from IBM, Application Clients run-time properties, the SSL KeyStore and TrustStore file, and

Chapter 8. Developing WebSphere applications 1057

the Application Clients run-time library JAR files (optional for Thin Application client applications). If the
Application Clients run-time dependency is not met, it is downloaded and installed in Java Web Start
(JWS), as described by the Application Clients run-time installer JNLP descriptor file.
<j2se version="WASclient6.0" href="/WebSphereClientRuntimeWeb/Runtime/jnlp.jsp"/>

It must also include the WebSphereClientLauncher.jar file, which contains the launcher class,
com.ibm.websphere.client.launcher.ClientLauncher, that completes one of the following actions:
v If it is a J2EE Application client application (that is the resources for the application contain an EAR file
with a client application), then the launcher class starts a second Java Virtual Machine (JVM) using the
JRE provided by the Application Clients run-time dependency and launches the J2EE Application client
application which is packaged in the EAR file.
The EAR file must be specified as a JAR resource so that it can be downloaded to JWS and specified
in the system property, com.ibm.websphere.client.launcher.ear. See the following example for details:
<resources>
<j2se version="WASclient6.0" href="/WebSphereClientRuntimeWeb/Runtime/jnlp.jsp"/>
<jar href="Launcher/WebSphereClientLauncher.jar" main="true"/>
<jar href="lib/j2eeclient.ear"/>
<property name="com.ibm.websphere.client.launcher.ear" value="j2eeclient.ear"/>
</resources>
v If it is a Thin Application client application, then the launcher class uses the current JVM from the
Application Clients run-time dependency and invokes the Thin Application client application main
method.
The Thin Application client application JAR file must be specified as a JAR resource so that it can be
download to JWS and the name of the class containing main method entry point is specified in the
system property, com.ibm.websphere.launcher.main.
<resources>
<j2se version="WASclient6.0" href="/WebSphereClientRuntimeWeb/Runtime/jnlp.jsp"/>
<extension name="WebSphere Runtime"
href="/WebSphereClientRuntimeWeb/Runtime/WebSphereJars/jnlp.jsp"/>
<jar href="Launcher/WebSphereClientLauncher.jar" main="true"/>
<jar href="lib/thinclient.jar"/>
<property name="com.ibm.websphere.client.launcher.main"
value="myapp.sample.thinclient.ThinClientMain”/>

</resources>
Unlike the J2EE Application client application, the Thin Application client application is not loading the
Application Clients run-time library JAR files from the Application Clients run-time dependency. It is
downloaded from the server directly as it is for the Thin Application client application JAR file. An
Application Clients run-time library component JNLP descriptor is used for specifying the Application
Clients run-time library JAR files resources, as shown in the following example:
<extension name="WebSphere Runtime"
href="/WebSphereClientRuntimeWeb/Runtime/WebSphereJars/jnlp.jsp"/>
The JNLP specification requires all the resource (JAR or EAR) files used in a JNLP file to be signed.
You can specify the –CC arguments defined in the launchClient tool for a J2EE Application client
application in application arguments section of the JNLP descriptor files. However, only –CCD is
supported for a Thin Application client application to define system properties and the JNLP <property>
tag can also be used to define system properties. See the following example for details:
<property name="java.naming.provider.url" value="corbaloc:iiop:myserver.com:9089"/>
For a J2EE Application client application, specify the following application arguments as defined in the
JNLP.
1. Specify your target server provider URL, as shown in the following example:
<argument> >-CCDjava.naming.provider.url =corbaloc:iiop:myserver.mydomain.com:9080</argument>
2. Specify the SSL Key File and SSL Trust File location. These files are expected to be available in the
client machine. To use the ones in the Application Clients run-time dependency installed in JWS
cache, specify these application arguments:

1058 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 <argument> -CCDcom.ibm.ssl.keyStore=${WAS_ROOT}/etc/DummyClientKeyFile.jks </argument>
<argument>-CCDcom.ibm.ssl.trustStore=${WAS_ROOT}/etc/DummyClientTrustFile.jks </argument>
3. Specify the initial naming context factor, as shown in the following example:
<argument>-CCDjava.naming.factory.initial=
com.ibm.websphere.naming.WsnInitialContextFactory </argument>
For a Thin Application client application, you also need to specify the actual location of the
sas.client.props file located in the Application Clients run-time dependency that is installed in the
JWS cache.
<argument>-CCDcom.ibm.CORBA.ConfigURL=file:${WAS_ROOT}/properties/sas.client.props</argument>
If any of the default settings in the sas.client.props file need modifying, use the –CCD to change
the settings through the system properties, as shown in the following example:
<argument>-CCDjavacom.ibm.CORBA.securityEnabled=false </argument>

Note: The ${install_root} token used in the JNLP file is replaced by the launcher class,
com.ibm.websphere.client.launcher.ClientLauncher, to the actual location of the Application
Clients run-time dependency installation in the JWS cache. If you are using JSP to
dynamically create this JNLP description file, you must escape this token because it has a
different meaning in JSP 2.0. See the following example for details:
<argument>-CCDcom.ibm.ssl.keyStore=\${WAS_ROOT}/etc/DummyClientKeyFile.jks </argument>
<argument>-CCDcom.ibm.ssl.trustStore=\${WAS_ROOT}/etc/DummyClientTrustFile.jks </argument>

Here is an example of the client application JNLP descriptor file for a J2EE Application client application.
<%-- This is a generic jnlp for a client app. It will specify the WAS JRE
as a dependency as well as the client launcher
-->
<%! private final String description="J2EE Client Example"; private final
String earName="J2EEWebStart.ear";
%>
<% // locally declared variable

String urlSt = request.getRequestURL().toString();

String jnlpCodeBase=urlSt.substring(0,urlSt.lastIndexOf(’/’));
String jnlpRefURL=urlSt.substring(urlSt.lastIndexOf(’/’)+1,urlSt.length());
// The client application descriptor noted a resource reference to be resolved
// at deploy time as following
%>
<%--
Need to set a JNLP mime type - if Web Start is installed on the client,
this header will induce the browser to drive the Web Start Client

--%><%
response.setContentType("application/x-java-jnlp-file"); 1
response.setHeader("Cache-Control", null);
response.setHeader("Set-Cookie", null);
response.setHeader("Vary", null);
%>
<?xml version="1.0" encoding="utf-8"?
<!-- JNLP File for <%=description %> -->
<jnlp
spec="1.0+"
<%-- Automate the code base response
-->% codebase="<%=jnlpCodeBase%>"
href="<%=jnlpRefURL%>"
<information>
<title><%=description %></title>
<description kind="short"><%=description %></description>
<description kind="tooltip"><%=description %></description>
<offline-allowed></offline-allowed>
</information>
<security>
<all-permissions></all-permissions>

Chapter 8. Developing WebSphere applications 1059

</security>
<resources>
<%-- The URL for the Client JRE installer --%>
WASclient6.0"
href="/WebSphereClientRuntimeWeb/Runtime/jnlp.jsp"></j2se> 2

<%-- Specify the client launcher --%>

<jar href="../Launcher/WebSphereClientLauncher.jar" main="true"> </jar> 3

<%-- Ear we want to download to the client --%>

<jar href="<%=earName%>"></jar> 4
<%-- The launcher depends on this property to be set --%>
<property name="com.ibm.websphere.client.launcher.ear"
value="<%=earName%>"><property> 5

<resources>
<%-- Web Start will consider the Launcher as the application to run -->
<application-desc> 6
<argument>-CCproviderURL=corbaloc:iiop:your_server_hostname </argument> 7
<
<argument>-
CCDcom.ibm.ssl.keyStore=\${install_root}/etc/DummyClientKeyFile.jks</argument> 8

<argument>-
CCDcom.ibm.ssl.trustStore=
\${install_root}/etc/DummyClientTrustFile.jksCCDcom.ibm.ssl.trustStore=
\${install_root}/etc/DummyClientTrustFile.jks</argument> 9
</application-desc>
</jnlp>
v 1--Specifies the mime type of the file must be JNLP so that the browser will know what to do with the
file.
v 2--Specifies that the application is depending on the WASclient6.0 Java Runtime Environment and
specifies the URL of the JNLP for the Application Clients run-time dependency.
v 3--Specifies the JAR file containing the launcher class. This should be the first jar specified and must
contain the URL of the JAR file.
v 4--Specifies the EAR file to be downloaded, which is similar to the one you run on an Application Client
for WebSphere Application Server installation.
v 5--Specifies the value of the EAR file name of the J2EE application.
v 6--Specifies an application descriptor.
v 7--Specifies the arguments for the J2EE Application client application as they are specified on the
launchClient call.
v 8, 9--Overrides the values in the sas.client.props file. They are needed because the installation
location of the Application Clients run-time dependency component is unknown before it is actually
installed. By default, security is turned on for the client application, and these values are required. The
${install_root} directory name is substituted with the Application Clients run-time dependency component
installation location at run time.

ClientLauncher class: The class, com.ibm.websphere.client.installer.ClientLauncher, contains a main()

method that is called by Java Web Start (JWS) to launch the client application. It is packaged in the
WebSphereClientLauncher.jar file that is located in a WebSphere Application Server clients installation
under the <install_root>/ JWS directory.

This launcher class configures the run-time environment for J2EE application clients and thin client
applications (not J2EE application clients).

1060 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The launcher class requires that the following properties are defined. These properties are not defined in a
separate properties file. Instead, they are defined as part of the Java Network Launching Protocol (JNLP)
files.
com.ibm.websphere.client.launcher.main
If the client application is a Thin Application client, then this property should be specified. It
specifies the class where the main entry point of the client application resides.
com.ibm.websphere.client.launcher.ear
If the client application is a J2EE Application client, then this property should be specified. It
specifies the name of the EAR file to be executed. This property takes precedence over
com.ibm.websphere.client.launcher.main. However, only one of the two properties should be
specified.
com.ibm.websphere.client.launcher.classpath.* (required for J2EE client applications only)
There can be a set of properties that are prefixed with
com.ibm.websphere.client.launcher.classpath. Each property specifies a JAR file that is to be
added to the class path of the client application. This JAR file is a JAR file that is already defined
as a resource for the client application. This file is needed so that the correct elements of the class
path of the Java Virtual Machine (JVM) starting the client launcher can be retrieved and added to
the class path of the (JVM) that is to be spawned for the client application.

Preparing the Application Client run-time dependency component for Java Web Start:

For a J2EE application client application and or Thin application client application to be launched using
Java Web Start (JWS), an Java Runtime Environment that IBM provides, the library JAR files and
properties files bundled in Application Client for WebSphere Application Server must be installed in the
JWS. This article provides the steps to build the Application Client run-time dependency component from
an Application Client installation. It is packaged as a Web Archive Resource (WAR) file that can be
installed in an Application Server.

Install the Application Client for WebSphere Application Server for the platform to which the client
application deploys. If there is a requirement to deploy the client application to multiple platforms, the
Application Client run-time dependency component must be built separately for each platform that client
application supports.

For example, if the client application deploys to both the Windows platform and Linux platform, follows the
steps for this task to build the Application Client run-time dependency component for Windows on a
Windows platform machine with the Application Client for WebSphere Application Server for Windows
installed. Now, repeat the steps for this task to build the Application Client run-time dependency
component for Linux on a Linux platform machine with the Application Client for WebSphere Application
Server for Linux installed.
1. Install the Application Client for WebSphere Application Server for the client application supported
operating systems. Install Application Client in the C:\Program Files\IBM\WebSphere\AppClient
directory.
2. Change the directory to the installation bin directory. See the following example for help:
CD C:\Program files\IBM\WebSphere\AppClient\bin
3. Run the buildClientRuntime tool to generate the Application Client run-time JAR file in a temporary
directory which contains the Java 2 Runtime Environment, Application Client run-time properties, the
SSL KeyStore and TrustStore file, and the Application Client run-time library JAR files. See the
following example for help:
buildClientRuntime C:\WebApp1\runtime\WASClient6.0_windows.jar
If you are building an Application Client run-time JAR file only for serving Thin application client
applications and not for J2EE application client applications, you can reduce the size of the generated
JAR file by not including the Application Client run-time library JAR files. An extra parameter is passed
to the buildClientRuntime tool, as the following example shows:

Chapter 8. Developing WebSphere applications 1061

 buildClientRuntime C:\WebApp1\runtime\WASClient6.0_windows.jar
buildThin
4. Copy the WebSphereClientRuntimeInstaller.jar file to the same location of the JAR file generated in
the previous step. This JAR file is located in the JWS directory of the WebSphere Application Server
clients installation. See the following example for help:
copy ..\JWS\WebSphereClientRuntimeInstaller.jar C:\WebApp1\runtime
5. Sign the JAR files created from the previous steps, using the Java 2 SDK jarsigner utility, as the
following example shows:
cd C:\WebApp1\runtime

jarsigner -keystore myKeystore -storepass myPassword

WASClient6.0_windows.jar myKeyAliasName

jarsigner -keystore myKeystore -storepass myPassword

WebSphereClientRuntimeInstaller.jar myKeyAliasName
a. This step also requires you to create a keystore file, such as myKeystore.
b. You must also create a self-signed certificate for the myKeystore file. For more information, see the
topic, ″Creating self-signed personal certificates″ in the Securing applications and their environment
PDF.
6. Create an Application Client run-time installer JNLP descriptor file or a JavaServer Pages (JSP) file if it
is generated dynamically in the same temporary directory as previous step. See the sample JNLP file
shown in the Example section of this topic.
7. Package the two signed JAR files and the Application Client run-time installer JNLP descriptor file into
a WAR file. This WAR file is packaged into an EAR file that can be deployed to an Application Server.

Your Web application is ready to serve the Application Client run time and the JRE environment.

<%--
This is an Installer JNLP
It will download two .jars:
WebSphereClientRuntimeInstaller.jar - includes the installer utility
WASClient6.0_<platform>.jar - the client runtime JRE image

The installer will unzip the client runtime jar on the client machine, and register
it with Java Web Start

--%>
<%! private final String description=″WebSphere Client 6.0 Runtime JRE″;
// The version here is (WAS based) JRE version - as to be managed on the client
private final String JREversion=″WASclient6.0″;%>
<%
// locally declared variable
String url=request.getRequestURL().toString();
String jnlpCodeBase=url.substring(0,url.lastIndexOf(’/’));
String jnlpRefURL=url.substring(url.lastIndexOf(’/’)+1,url.length());

// Need to set a JNLP mime type - if Web Start is installed on the client,
// this header will induce the browser to drive the Web Start Client
response.setContentType(″application/x-java-jnlp-file″); 1
response.setHeader(″Cache-Control″, null);
response.setHeader(″Set-Cookie″, null);
response.setHeader(″Vary″, null);

// An installer must reply with the version number for a given install
if (response.containsHeader(″x-java-jnlp-version-id″))

1062 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 response.setHeader(″x-java-jnlp-version-id″, JREversion); 2
else
response.addHeader(″x-java-jnlp-version-id″, JREversion);

%>
<?xml version=″1.0″ encoding=″utf-8″?>
<!-- JNLP File for <%=description %> -->
<jnlp
spec=″1.0+″ <%--
Automate the code base response --%>
codebase=″<%=jnlpCodeBase%>″
href=″<%=jnlpRefURL%>″>
<information>
<title><%=description%></title>
<vendor>IBM</vendor>
<icon href=″icon.gif″>
<description><%=description%></description>
<description kind=″short″><%=description></description>
<description kind=″tooltip″><%=description></description
<offline-allowed/>
</information>
<security>
</all-permissions>
</security>
<resources>
<j2se version=″1.4+″/><%-- The installer can use any 1.4 JRE --%> 3
<jar href=″WebSphereClientRuntimeInstaller.jar″ main=″true″/> 4

<%-- JRE version registration with Web Start --%>

<property name=″com.ibm.websphere.client.jre.version″ value=″<%=JREversion%>″/> 5

</resources>
<resources os=″Windows″> 6
<jar href=″windows/WASClient6.0_windows.jar″/> 7

<%-- relative path of the jre executable --%>

<property name=″com.ibm.websphere.client.jre.launch.java″
value=″java\jre\bin\java.exe″/> 8
<resources os=″Linux″>
<jar href=″linux/WASClient6.0_linux.jar″/>

<property name=″com.ibm.websphere.client.jre.launch.java″ value=″java/jre/bin/java″/>

</resources>
<installer-desc />
</jnlp>
1. Specifies that the file is a JNLP mime type so that the browser can process the JNLP file.
2. Specifies the exact version of this Application Client run-time dependency component in the response
by setting the HTTP header field: x-java-jnlp-version-id.
3. Specifies the required JRE version to run the installer program.
4. Specifies the installer WebSphereClientRuntimeInstaller.jar file, which contains the
ClientRuntimeInstaller class.
5. Specifies a system property that defines the version of Application Client run-time dependency
component. This version is registered to the JNLP client.

Chapter 8. Developing WebSphere applications 1063

6. Specifies resources for a particular platform. Each supported client application platform needs its own
separate JAR file.
7. Specifies the Application Client run-time dependency component JAR file.
8. Specifies the program to call that starts a JVM for the client application.

Preparing Application Client run-time library component for Java Web Start.

buildClientRuntime tool: The buildClientRuntime tool builds the required components from the WebSphere
Application Server clients installation into the JAR file specified on the command. This JAR file contains:
v License files
v Java 2 Runtime Environment (JRE) that IBM provides
v Application Clients run-time properties and configuration
v SSL KeyStore and TrustStore files
v Run-time library JAR files

In the case of building an Application Clients run-time JAR file only for serving Thin Application client
applications and not for J2EE Application client applications, the run-time library JAR files and the
Application Clients run-time properties files are not included, except the two configuration files,
sas.client.props and soap.client.props.

The command-line invocation syntax for the buildClientRuntime tool is shown in the following example:
Windows Usage: buildClientRuntime .bat jar_file [type]
Unix Usage: buildClientRuntime.sh jar_file [type]
Where:
jar_file Specifies the target jar file name.
type Range:
buildJ2EE - Default value that builds a Application Clients
run-time library for J2EE application.
buildThin - Builds a Application Clients run-time library
for Thin application.

ClientRuntimeInstaller class: This class, com.ibm.websphere.client.installer.ClientRuntimeInstaller,

contains a main() method that Java Web Start (JWS) calls to install the Application Client for WebSphere
Application Server run-time dependency component in JWS cache. It is packaged in
WebSphereClientRuntimeInstaller.jar file located in the Application Client for WebSphere Application
Server installation in the <install_root>/JWS directory.

Specify the WebSphereClientRuntimeInstaller.jar file and the Application Client run-time dependency
component JAR file as JAR resources in the Application Client run-time installer Java Network Launcher
Protocol (JNLP) descriptor file. See the following example for details:
<jar href="Launcher/WebSphereClientRuntimeInstall.jar" main="true"/>
<jar href="Launcher/WASClient6.0_windows.jarRuntimeInstall.jar" main="true"/>

The ClientRuntimeInstaller class main method requires the following properties to be set in the JNLP file:
com.ibm.websphere.client.jre.version
Specifies a Java Runtime Environment (JRE) version name that is to be used when referring to
the Application Client run-time dependency component.
com.ibm.websphere.client.jre.launch.java
Specifies the relative location of the javaw.exe program in the Application Client run-time
dependency component JAR file.

The previously mentioned properties, JRE version name and the location of the javaw.exe program are
registered to the Java Web Start Application Manager, as shown in the following example:
<property name="com.ibm.websphere.client.jre.version" value="java\jre\bin\javaw.exe"/>
<property name="com.ibm.websphere.client.jre.launch.java" value="WASclient6.0"/>

1064 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Preparing Application Clients run-time library component for Java Web Start:

For a Thin Application client application to be launched using Java Web Start (JWS), you also need to
create a Java Network Launching Protocol (JNLP) component to serve the Application Clients run-time
library JAR files from the Application server. This JNLP component is referenced in the client application
JNLP file with the <extension> tag. This article provides the steps to build the Application Clients run-time
library component from an Application Clients installation. It is packaged as its own Web Archive Resource
(WAR) file or to the same WAR file that contains the Application Clients run-time dependency component,
and can be installed in an Application server.

Install the Application Client for WebSphere Application Server for the platform to which client applications
deploy.
1. Install the Application Clients on the client application supported operating system. For example, install
Application Clients in the C:\Program Files\IBM\WebSphere\AppClient directory.
2. Change directory to the installation bin directory. See the following example for help:
CD C:\Program files\IBM\WebSphere\AppClient\bin
3. Run buildClientLibJars to copy the Application Clients run-time library JAR files from the Application
Clients installation to a temporary directory. All the JAR files in the temporary directory are signed, as
shown in the following example.
buildClientLibJars C:\WebApp1\runtime\WebSphereJars
myKeystore myPassword myKeyAliasName
a. This step also requires you to create a keystore file, such as myKeystore.
b. You must also create a self-signed certificate for the myKeystore file. For more information, see the
topic, ″Creating self-signed personal certificates″ in the Securing applications and their environment
PDF.
4. Create an Application Clients run-time installer JNLP descriptor file or a JavaServer Pages (JSP) file, if
it is generated dynamically in the same temporary directory as previous step. See the sample JNLP file
shown in the Example section of this topic.
5. Package these JAR files and the Application Clients run-time library component JNLP descriptor file
into a WAR file. You can also package both Application Clients run-time library component and
Application Clients run-time dependency component in the same WAR file. This WAR file is packaged
into an EAR file that can deployed to an Application server.
<!--
"This sample program is provided AS IS and may be used, executed, copied
and modified without royalty payment by customer (a) for its own instruction
and study, (b) in order to develop applications designed to run with an IBM
WebSphere product, either for customer’s own internal use or for redistribution
by customer, as part of such an application, in customer’s own products."
Product 5630-A36, (C) COPYRIGHT International Business Machines Corp., 2004
All Rights Reserved * Licensed Materials - Property of IBM
-->
<%! private final String description="WebSphere Jars";
%>
<% // locally declared variable

String urlSt = request.getRequestURL().toString();

String jnlpCodeBase=urlSt.substring(0,urlSt.lastIndexOf(’/’));
String jnlpRefURL=urlSt.substring(urlSt.lastIndexOf(’/’)+1,urlSt.length());
// The client application descriptor noted a resource reference to be resolved at deploy time as following
%>
<%--
Need to set a JNLP mime type - if Web Start is installed on the client,
this header will induce the browser to drive the Web Start Client

--%><%
response.setContentType("application/x-java-jnlp-file"); 1
response.setHeader("Cache-Control", null);
response.setHeader("Set-Cookie", null);

Chapter 8. Developing WebSphere applications 1065

 response.setHeader("Vary", null);
response.setDateHeader("Last-Modified", lastModified); 2
%>
<?xml version="1.0" encoding="utf-8"?>
<!-- JNLP File for <%=description %> -->
<jnlp
spec="1.0+"
<%-- Automate the code base response
--%> codebase="<%=jnlpCodeBase%>"
href="<%=jnlpRefURL%>">
<information>
<title><%=description %></title>
<description kind="short"><%=description %></description>
<description kind="tooltip"><%=description %></description>
<offline-allowed></offline-allowed>
</information>
<security>
<all-permissions></all-permissions>
</security>
<resources>
<jar href="activation-impl.jar"/> 3
<jar href="activity.jar"/>
<jar href="activityImpl.jar"/>
<jar href="activitySession.jar"/>
<jar href="activitySessionPrivate.jar"/>
<jar href="acwa.jar"/>
<jar href="admin.jar"/>
<jar href="annotations-core.jar"/>
<jar href="appprofile-impl.jar"/>
<jar href="appprofile.jar"/>
<jar href="b2bjaxp.jar"/>

<!-- ======================================== -->

<!-- -->
<!-- specify all the signed jars created by -->
<!-- buildClientlibJars tool -->
<!-- -->
<!-- ======================================== -->

<jar href="wsif-j2c.jar"/>
<jar href="wsif.jar"/>
<jar href="wssec.jar"/>
<jar href="wtp-util.jar"/>
<jar href="wtpemf.jar"/>
<jar href="xsd.jar"/>
<jar href="xsd.resources.jar"/>
<jar href="xss4j-dsig.jar"/>
<jar href="xss4j-enc.jar"/>
</resources>
<component-desc/>
</jnlp>
v 1--Specifies that the file is a JNLP mime type so that the browser can process the JNLP file.
v 2--Specifies the Last-Modified header so that any changes to this JSP file are downloaded to the JNLP
client.
v 3--Specifies all the JAR files in the Application Clients run-time library component that are generated by
the buildClientLibJars tool.

buildClientLibJars tool: The buildClientLibJars tool copies the JAR files from the Application Client for
WebSphere Application Server installation and creates a properties.jar file, which contains the properties
files from the Application Clients installation properties directory to a specified location. When this property
is created, the tool uses the value of keystore, storepass and alias to sign all the JAR files in the
specified location.

1066 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Windows Usage: buildClientLibJars.bat target_dir keystore storepass alias
Unix Usage: buildClientLibJars.sh target_dir keystore storepass alias
Where:
target_dir Specifies the target directory where the Application
Clients library JAR files copied to.
keystore Specifies a keystore file.
storepass Specifies the keystore password.
alias Specifies an alias for the key object in the key file.

Using the Java Web Start sample:

The EAR file, WebSphereClientRuntime.ear, is provided in the JWS directory of the Client Application for
WebSphere Application Server installation. This EAR file provides a sample Application Clients run-time
installer JNLP descriptor file and a sample Application Clients run-time library component JNLP descriptor
file. Follow the steps in this task to build the Application Clients run-time dependency component and the
Application Clients run-time library component. Add these components to the WebSphereClientRuntime.ear
file, and then install the EAR file in an Application Server to be used by the client application.

Install the Application Client for WebSphere Application Server for the platform to which the client
application deploys. If there is a requirement to deploy the client application to multiple platforms, the
Application Clients run-time dependency component must be built separately for each platform that the
client application supports.
1. Install the Application Clients on the client application supported operating system. For example, install
Application Clients in the C:\Program Files\IBM\WebSphere\AppClient directory.
2. Create the following temporary working directories:
MKDIR C:\WebApp1
MKDIR C:\WebApp1\runtime
MKDIR C:\WebApp1\runtime\Widnows
MKDIR C:\WebApp1\runtime\WebSphereJars
3. Change directory to the installation bin directory. See the following example for help:
CD C:\Program files\IBM\WebSphere\AppClient\bin
4. Run the buildClientRuntime tool to generate the Application Clients run-time JAR file in a temporary
directory that contains the Java 2 Runtime Environment that IBM provides, Application Clients run-time
properties, the SSL KeyStore and TrustStore files, and the Application Clients run-time library JAR
files. See the following example for details:
buildClientRuntime C:\WebApp1\runtime\windows\WASClient6.0_windows.jar
5. Copy the WebSphereClientRuntimeInstaller.jar file to the same location of the JAR file generated in
the previous step. This JAR file is located in the JWS directory of the Application Client for WebSphere
Application Server installation. For example, copy the ..\JWS\WebSphereClientRuntimeInstaller.jar
file to the C:\WebApp1\runtime directory.
6. Sign the JAR files created from the previous steps, using the Java 2 SDK jarsigner utility. See the
following example for details:
cd C:\WebApp1\runtime

jarsigner -keystore myKeystore -storepass myPassword

WASClient6.0_windows.jar myKeyAliasName

jarsigner -keystore myKeystore -storepass myPassword

WebSphereClientRuntimeInstaller.jar myKeyAliasName
a. This step also requires you to create a keystore file, such as myKeystore.
b. You must also create a self-signed certificate for the myKeystore file. For more information, see the
topic, ″Creating self-signed personal certificates″ in the Securing applications and their environment
PDF.
7. Run buildClientLibJars to copy the Application Clients run-time library JAR files from the Application
Client for WebSphere Application Server installation to a temporary directory. All the JAR files in the
temporary directory are signed. See the following example for details:

Chapter 8. Developing WebSphere applications 1067

 buildClientLibJars C:\WebApp1\runtime\WebSphereJars
myKeystore myPassword myKeyAliasName
a. This step also requires you to create a keystore file, such as myKeystore.
b. You must also create a self-signed certificate for the myKeystore file. For more information, see the
topic, ″Creating self-signed personal certificates″ in the Securing applications and their environment
PDF.
8. Add all the JAR files created in the previous steps in the C:\WebApp1 directory to the WAR file within
the WebSphereClientRuntime.ear file. The contents of the WAR file are shown in the following example:
The root of the WAR
├───META-INF
│ MANIFEST.MF
│
├───Runtime
│ │ jnlp.jsp
│ │ WebSphereClientRuntimeInstaller.jar
│ ├───windows │
│ │ WASClient6.0_windows.jar
│ │
│ └───WebSphereJars
│ jnlp.jsp
│ activities.jar
│ :
│ (all the jars created in step 7 under
│ c:\WebApp1\Runtime\WebSphereJars)
│
├───theme
│ Master.css
│
└───WEB-INF
ibm-web-bnd.xmi
ibm-web-ext.xmi
web.xml
9. Install the WebSphereClientRuntime.ear file to an Application Server. You have just created an
Application Clients run-time dependency component and Application Clients run-time libraries for
serving J2EE Application client applications and Thin Application client applications using Java Network
Launching Protocol (JNLP) or Java Web Start (JWS).

Installing Application Client for WebSphere Application Server

Running J2EE and Thin application clients that communicate with WebSphere Application Server requires
that elements of the Application Server are installed on the machine on which the client runs. However, if
the system does not have the Application Server installed, you can install Application Clients, which
provide a stand-alone client run-time environment for your client applications. See the Supported
Prerequisites page for more information on supported product platforms.

This article describes how to install the Application Client for WebSphere Application Server using the
installation image on the product CD-ROM. The steps that follow provide enough detail to guide you
through preparing for, choosing, and installing the variety of options and features provided. To prepare for
installation and to make yourself familiar with installation options, complete the steps in this article and
read the related topics, before you start to use the installation tools. Specifically, read these topics before
installing the product:
v Installing silently
v Best practices for installing

As a general rule, if you launch an installation and there is a problem such as not having enough
temporary space or not having the right packages on your Linux or UNIX systems, then cancel the
installation, and make the required changes. Restart the installation to initiate your changes.

1068 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Although it is not supported or recommended, you can install this product as a non-root user on a UNIX
operating system. However, you must use a user ID that is part of the administrator group on Windows
platforms.

In Version 6, the Application Server for WebSphere Application Server is installable on a machine with a
previous version of Application Clients. However, you cannot install a Version 6 Application Client on top of
a previous version of the Application Client. For example, if a Version 5 Application Clients install under the
C:\WebSphere\AppClient directory, you can not choose the same install location for your V6 Application
Clients installation.

Note: For Application Client coexisting, there is a limitation on Applet client and ActiveX client on Windows
that can not be coexisted with V5.0.x and V4.x of the clients. For example, the Applet client feature
in Version 6 cannot coexist with the Applet client feature in any previous release. This coexistence
is not available because the installation of Applet client feature in Version 6 sets the browser default
Java Virtual Machine (JVM) using the Java Runtime Environment (JRE) from the Version 6
installation, which is Java Runtime Environment Version 1.4.2. Similarly, the ActiveX to EJB Bridge
feature in Version 6 sets the Windows system path to use the JRE from the Version 6 installation.
1. Install Application Client for WebSphere Application Server using the launchpad. The launchpad
program is available on the root directory of the product CD in the program, launchpad.sh, on Linux
and UNIX platforms and launchpad.bat on Windows platforms.

Note: The free download Application Client installation is not packaged with the launchPad program.
a. Click Launch the installation wizard for Application Client for WebSphere Application Server
from the launchpad tool to launch the InstallShield for MultiPlatforms installation wizard. This action
launches the installation wizard.
The Readme documentation to which the launchpad links is the readme.html file in the CD root
directory. The readme directory off the root of the CD has more detailed Readme files. The
Installation Guide is in the /docs directory of the CD root directory.

Note: Readme file names are based on product offerings.

When you install application clients, the current working directory must be the directory where the
installer binary program is located. This placement is important because the resolution of the class
files location is done in the current working directory. For example:
cd /install_root/AppClient

./install
or
cd <CD mount point>/AppClient

./install
Failing to use the correct working directory can cause ISMP errors that abort the installation.
The installation wizard does not upgrade or remove previous Application Clients installation
automatically. However, you must change the directory of any previously installed versions of the
Application Client because you cannot install Version 6 on top of previously existing Application
Client.
b. As indicated in the previous example, you can start the installation wizard from the product
CD-ROM, using the command line.
On other Linux platforms and UNIX-based platforms, run the ./install command.
On Windows platforms, run the Install.exe command.
c. You can also perform a silent installation using the -options responsefile parameter, which
causes the installation wizard to read your responses from the options response file, instead of
from the interactive graphical user interface. Customize the response file before installing silently.
After customizing the file, issue the command to silently install. Silent installation is particularly
useful if you install the product often.
Chapter 8. Developing WebSphere applications 1069
 The rest of this procedure assumes that you are using the installation wizard. There are
corresponding entries in the response file for every prompt that is described as part of the wizard.
Review the description of the response file for more information. Comments in the file describe how
to customize its options.
2. Click Next to continue when the Welcome panel is displayed.
a. Click the radio button beside the I accept the terms in the license agreement message if you
agree to the license agreement, and click Next to continue.
3. Specify a destination directory. Click Next to continue.
a. Ensure that there is adequate space available in the target directory.
b. Specify a target directory for the Application Client product.
c. Enter the required target directory to proceed to the next panel. Deleting the default target location
and leaving an installation directory field empty prevents you from continuing the installation
process.
4. Choose a type of installation, and click Next.
If you use the GUI, you can choose a Typical installation type, which installs J2EE and Thin application
client, Samples and IBM Developer Kit, Java 2 Technology Edition or a Custom installation type.
The Custom installation type lets you select which features to install. However you can not install the
J2EE and Java Thin application client feature and the Pluggable application client feature together.
(Windows Only) If you select the ActiveX to EJB Bridge feature, then the following is displayed in a
dialog box: Do you want to add Java runtime to the system path and make it the default JRE? If
you answer Yes, then the Java run time is added to the beginning of the system path. If you answer
No, then the ActiveX to EJB Bridge does not function from the Active Server Pages (ASP), unless you
add the Java run time to the path. To add the Java run time later, see the topic ActiveX application
clients or reinstall the Application Client.(Windows Only) If you select the Applet client feature, then
the following message might be displayed: An existing JDK or JRE has been detected on your
computer. You chose to install the Applet Client, which will overwrite the registry entries
for this JDK or JRE. Do you want to continue and install the Applet Client? If you select Yes,
the installation overrides the registry on your machine. If you select No, the Applet client feature is not
installed, and you are directed back feature dialog box.
5. Install the Software Developer Kit, if you need to use any of the utilities that it provides, such as the
javaccompiler, the jarutility or the jarsinger utility. The Java 2 Development Kit that IBM provides has
two components, Java Runtime Environment (JRE) and a complete Software Developer Kit (SDK). The
JRE sub feature is selected by default when the J2EE or Thin application client feature is selected.
The SDK component is optional; however, you must install the SDK component to compile the sample.
6. Enter the host name of the WebSphere Application Server machine. Click Next to continue. The
default port number for product Version 6 server is 2809.
7. Review the summary information, and click Next to install the product code or you might also click
Back to change your specifications.
8. Click Finish to exit the wizard, after the Application Client installs.
9. Verify the success of the installer program by examining the Completion panel and the
<install_root>/logs/WAS.Client.isntall.log file for installation status. The installer program records
the following indicators of success in the logs:
v INSTCONFSUCCESS indicates that the installation is successful and that no further log analysis is
required.
v INSTCONFFAILED indicates an installation failure that you cannot retry or recover from without
reinstalling.

You successfully installed the Application Client for WebSphere Application Server and the features you
selected.

If the installation is not successful, fix the error as indicated in the installation error message. For example,
if you do not have enough disk space, add more space, and reinstall the Application Client.

1070 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Best practices for installing application clients
The following table offers tips for installing application clients on multiple platforms.

Operating environment Tip

Linux and UNIX systems Spaces are not supported in the name of the installation directory on
Linux and UNIX platforms.
UNIX systems When the application client installations are successful, the return
code 1 is issued from the UNIX shell where you issued the /install
command. Any other return code indicates an unsuccessful
installation.
Solaris systems Double-byte character set (DBCS) characters are not supported in the
name of the installation directory on Solaris systems.
All platforms Reserve at least 4 to 5MB free space in the target platform temporary
directory.
All platforms When specifying a different temporary directory while installing
application clients, the following message is displayed if the target
platform default temporary directory does not have enough free space
to install application clients:
Error writing file = There may not be enough
temporary disk space.
Try using -is:tempdir to use a temporary
directory on a partition with more disk
space.

Use the -is:tempdir installation option to specify a different

temporary directory. For example, the following command uses /swap
as a temporary directory during installation:
./install -is:tempdir /swap
All platforms After the installation, when changing the installation settings for the
WebSphere Application Server host name and the port number, edit
the setupClient.bat for Windows or setupClient.sh for UNIX.
Change the DEFAULTSERVERNAME and SERVERPORTNUMBER to the new
WebSphere Application Server host name and port number,
respectively. If the SERVERPORTNUMBER is not set, then the default is
2809. Review the following example:
set DEFAULTSERVERNAME=NDServerName
set SERVERPORTNUMBER=9810

The setupClient.bat file or setupClient.sh file is located in the bin

sub-directory under the application clients installation destination.

Installing application clients silently

Use these steps to perform a silent installation, which uses the installation wizard to install the product.
Instead of displaying a user interface, the silent installation provides interaction between you and the
wizard by reading all of your responses from a file that you must customize.
1. Verify that the user ID that you are using to run the silent installation has sufficient authority to perform
the task.
2. Customize the option response file.
a. Locate the sample options response file. The file name is setup.response in the operating system
platform directory on the product CD-ROM.
b. Make a copy to preserve the original response file. For example, copy the file as myoptionsfile.
c. Edit the copy in your flat file editor of choice, on the target operating system. Read the directions
within the response file to choose appropriate values.

Chapter 8. Developing WebSphere applications 1071

 Note: To prepare the file for a silent installation on AIX, use UNIX line-end characters (0x0D0A) to
terminate each line of the options response file.
d. Make a non-commented option to have a silent install.
e. Include custom option responses that reflect parameters for your system.
f. Follow the instructions in the response file to choose appropriate values.
g. Save the file.
3. Issue a command to use your custom response file: Install.exe -options myoptionsfile for
Windows platforms and install -options ./myoptionsfile for Linux and UNIX platforms.
The sample options response file is located in the operating-system platform directory on the product
CD-ROM.
a. Issue the following command from a command prompt to update your response file: -W
silentInstallLicenseAcceptance.value=″true’.
Issuing this command changes the value for silentInstallLicenseAcceptance.value from false to
true, which is necessary for installing application clients.
4. Optional: Restart your machine in response to the prompt that appears on Windows platforms when
the installation is complete.

You installed application clients silently by using the response file.

To verify the silent install, look for the string RC=INSTCONFSUCCESS in the log file for successful installation
and RC=INSTCONFFAILED for a failed install installation.

For UNIX platforms, the install command returns a return code of 1 to indicate a successful installation.
Any other return code means that the installation failed.

Uninstalling Application Client for WebSphere Application Server

This task describes using the uninstaller program to uninstall the Application Client for WebSphere
Application Server.

Before uninstalling, verify that you have no open Web browsers that are accessing the administrative
console.

If you want to uninstall Application Clients manually, see the topic, ″Manually uninstalling on a Windows
system″ in the information center.
1. Stop any browsers and any Java processes related to WebSphere Application Server products as
described in ″Uninstalling the product″ in the information center.
2. Change directories to the _uninst directory before issuing the uninstall command. The command file is
located in the install_root/product/_uninst directory on a Linux or UNIX platform, and in the
install_root\product\_uninst directory on a Windows system.
For example, to change directories before uninstalling the product from a Linux platform, issue this
command if your installation root is /opt/IBM/WebSphere/AppServer:
cd /opt/IBM/WebSphere/AppServer/product/_uninst
3. Issue the uninstaller command. The command file is named uninstaller.bin for Linux and UNIX
platforms and uninstaller.exe on Windows platforms.

On Linux and UNIX platforms, issue the uninstaller.bin command from the
install_root/product/_uninst directory:
./uninstaller.bin

On Windows platforms, call the uninstaller.exe command:

install_root\product\_uninst\uninstaller.exe

1072 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Call the program directly from the install_root\product\_uninst directory. For example, if
the installation root is C:\IBM\WebSphere\AppServer, issue the following command:
C:\IBM\WebSphere\AppServer\product\_uninst> uninstaller.exe
The Uninstaller wizard begins and displays the Welcome panel.
4. Click Next to begin uninstalling the product. The Uninstaller wizard displays a Confirmation panel that
lists the product and features that you are uninstalling.
5. Click Next to continue uninstalling the product. The Uninstaller wizard deletes existing profiles first.
After deleting profiles, the Uninstaller wizard deletes core product files by component.
6. Click Finish to close the wizard after the wizard removes the product.

Application Client for WebSphere Application Server is uninstalled.

Verify the uninstall procedure by viewing the install_root/product/logs/uninstlog.txt log file for errors.
Look for the INSTCONFSUCCESS, indicating a successful uninstall in the log file:
Uninstall, com.ibm.ws.install.ni.ismp.actions.ISMPLogSuccessMessageAction, msg1,
INSTCONFSUCCESS

Deploying J2EE application clients on workstation platforms

After developing an application client, deploy this application on client machines. Deployment consists of
pulling together the various artifacts that the application client requires.

The Application Client Resource Configuration Tool (ACRCT) defines resources for the application client.
These configurations are stored in the client .jar file within the application .ear file. The application client
run time uses these configurations for resolving and creating an instance of the resources for the
application client.

Note: This task only applies to J2EE application clients. Only perform this task if you configured your
J2EE application client to use resource references.
1. Start the ACRCT and open an EAR file.
2. Configure new data source providers.
3. Configure mail providers and sessions.
4. Configure URL providers and sessions.
5. Configure Java messaging resources.
6. Configure new environment entries.
7. (Optional) Remove application client resources.
8. Save the EAR file.

Resource Adapters for the client

A resource adapter is a system-level software driver that a Java application uses to connect to an
enterprise information system (EIS). A resource adapter plugs into an application client and provides
connectivity between the EIS and the enterprise application.

The resource adapter support for the J2EE client applications is a subset of the support for the server. For
any resource adapter installed using the clientRAR tool, the client resource adapter is used in a
non-managed environment and must conform to the J2EE Connector Architecture Specification Version 1.5
or higher. Only outbound connections to the EIS are supported through the ManagedConnectionFactory
interfaces. The inbound messaging support (from the EIS), life cycle management, and work management
aspects of the specification are not supported on the client.

For a client application to use a resource adapter, it must be installed in the directory specified by the
environment variable, CLIENT_CONNECTOR_INSTALL_ROOT, defined when the setupCmdLine.bat

Chapter 8. Developing WebSphere applications 1073

command (on Windows systems) or setupCmdLine.sh (on UNIX platforms) command runs. The
launchClient tool, Application Client Resource Configuration Tool (ACRCT) and clientRAR tool all use this
variable to find the default location of all installed resource adapters. To install a resource adapter in the
client, use the clientRAR tool. Once the resource adapter is installed, it must be configured using the
ACRCT. The client configuration tool adds the resource adapter configuration to the EAR file. Then,
connection factories and administered objects are defined.

When running J2EE application clients, the launchClient script specifies a system property called
com.ibm.ws.client.installedConnector, which is set to the same value as the
CLIENT_CONNECTOR_INSTALL_ROOT variable. This is the default location for installed resource adapters and
can be overridden for each launchClient call by specifying the -CCD parameter. When the client container
is activated, all resource adapter subdirectories under the specified default location for the resource
adapters directory are added to the classpath. This action allows the client application to use the resource
adapters without using the ACRCT to specify any of the client resources.

Using resource adapters is a new mechanism for easily extending client applications.

Configuring resource adapters

1. Start the Application Client Resource Configuration Tool (ACRCT).
2. Open the EAR file for which you want to configure new resource adapters. The EAR file contents
display in a tree view.
3. Select the JAR file in which you want to configure the new resource adapters from the tree.
4. Expand the JAR file to view its contents.
5. Right-click the Resource Adapters folder, and click New.
6. Configure the resource adapter settings in the resulting property dialog.
7. Click OK.
8. Click File > Save on the menu bar to save your changes.

Resource adapter settings:

Use this panel to view or change the configuration properties of the resource adapter. These configuration
properties control how resource adapters are created.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Resource Adapter. Right-click
Resource Adapter and click New. The following fields appear on the General tab.

Name:

The name by which this Resource Adapter is known for administrative purposes within IBM WebSphere
Application Server. The name must be unique within the Resource Adapters across the product
administrative domain.

Data type String

Description:

A description of this resource adapter for administrative purposes within IBM WebSphere Application
Server.

Data type String

Class Path:

1074 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Any additional class path. The path to the resource adapter directory is automatically added.

Data type String

Default The path to your Resource Adapter directory.

Native Path:

The native path where the Resource Adapter is located. Enter any additional native class path here.

Data type String

Resource Adapter Name:

A mandatory field that points to an installed resource adapter subdirectory. The entry does not represent
the full directory name for the resource adapter. The full directory name is the installed resource adapter
path, plus the resource adapter name.

Data type String

Installed Resource Adapter Path:

The directory where resource adapters are installed. If you do not complete this field, then the default
takes effect.

If you specify the value, ${CONNECTOR_INSTALL_ROOT}, then this value replaces the value of the
CLIENT_CONNECTOR_INSTALL_ROOT variable on the machine on which the client application runs. This action
allows the application to run easily on different machines, where the client installation might be in different
locations.

Data type String

Default ${CONNECTOR_INSTALL_ROOT}

clientRAR tool:

This section describes the command line syntax for the client resource adapter installation tool. If this tool
is used to add or delete resource adapters on the server, then only the client can use the resource
adapter. If the resource adapter is installed on the server using the wsadmin tool or the administrative
console, then do not use the clientRAR tool remove it. Only resource adapters that are installed using the
clientRAR tool should be removed using the clientRAR tool.

The command line invocation syntax for the clientRAR tool follows:
clientRAR [-help | -?] [-CRDcom.ibm.ws.client.installedConnectors=<dir>] <task> <archive>

where
-help, -?
Print the usage information.
-CRDcom.ibm.ws.client.installedConnectors
The directory where resource adapters are installed.
This will override the system property of the same name (com.ibm.ws.client.installedConnectors).

<task>
The task to perform: add - install, delete - uninstall.

Chapter 8. Developing WebSphere applications 1075

<archive>
if task=add then this is the fully qualified name of the resource adapter archive file.
If task=delete then this is the filename of the resource adapter archive to be uninstalled.

The following examples demonstrate correct syntax.

On the Windows operating systems:

v clientRAR add c:\rars\myrar.rar
v clientRAR delete myrar.rar

On the UNIX operating systems:

v ./clientRAR add /usr/rars/myrar.rar
v ./clientRAR delete myrar.rar

Configuring new connection factories for resource adapters:

Complete this task to configure new connection factories for resource adapters.
1. Start the Application Client Resource Configuration Tool (ACRCT).
2. Open the EAR file for which you want to configure new connection factories. The EAR file contents
display in a tree view.
3. Select the JAR file in which you want to configure the new connection factories from the tree.
4. Expand the JAR file to view its contents.
5. Click the Resource Adapters folder.
6. Expand the resource adapter for which you want to create connection factories.
7. Right-click the Connection Factories folder and click New.
8. Configure the connection factory properties in the resulting property dialog.
9. Click OK.
10. Click File > Save on the menu bar to save your changes.

Resource adapter connection factory settings:

Use this panel to view or change the configuration properties of the selected resource adapter connection
factory.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Resource Adapters. Right-click the
Connection Factories folder, and click New. The following fields appear on the General tab.

Name:

The name by which this connection factory is known for administrative purposes within WebSphere
Application Server. The name must be unique within the resource adapter connection factories across the
product administrative domain.

Data type String

Description:

An optional description of this connection factory for administrative purposes within IBM WebSphere
Application Server.

Data type String

1076 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
JNDI Name:

The JNDI name that is used to match this resource adapter connection factory definition to the deployment
descriptor. This entry should be a resource-ref name.

Data type String

User Name:

The User Name used, with the Password property, for authentication if the calling application does not
provide a userid and password explicitly when getting a connection. If this field is used, then the Properties
field UserName is ignored.

If you specify a value for the User Name property, you must also specify a value for the Password
property.

The connection factory User Name and Password properties are used if the calling application does not
provide a userid and password explicitly when getting a connection.

Data type String

Password:

Specifies an encrypted password. If you complete this field, then the Password field in the Properties box
is ignored.

If you specify a value for the UserName property, you must also specify a value for the Password
property.

Data type String

Re-Enter Password:

Confirms the password.

Type:

A drop-down list of all the connectionFactoryInterfaces as defined for the factories in the Resource
Adapter Archive.

For each Type, there is a set of properties specified in the Properties box. This set of properties is
constructed by retrieving the properties from each connection definition object. For any existing connection
factories that are displayed for updating, this list of properties is overlaid with the properties specified for
the objects. When the Type field is changed, the properties also change to reflect the correct properties for
that type.

Data type String

Configuring administered objects:

Before you configure new administered objects, you must complete the following prerequisites:
1. Install the Resource Adapter Archive file (RAR) using the clientRAR tool.
2. Configure the resource adapter for the .ear file, using the Application Client Resource Configuration
Tool (ACRCT) tool.
Chapter 8. Developing WebSphere applications 1077
Complete this task to configure new administered objects for installed resource adapters.
1. Start the Application Client Resource Configuration Tool (ACRCT).
2. Open the EAR file for which you want to configure new administered objects. The EAR file contents
display in a tree view.
3. Select the JAR file in which you want to configure the new administered objects from the tree.
4. Expand the JAR file to view its contents.
5. Click the Resource Adapters folder.
6. Expand the resource adapter for which you want to create administered objects.
7. Right-click the Administered Objects folder and click New.
8. Configure the administered object properties in the resulting property dialog.
9. Click OK.
10. Click File > Save on the menu bar to save your changes.

Administered objects settings:

Use this panel to view or change the configuration properties of the selected administered objects.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Resource Adapters >
resource_adapter_instance. Right-click Administered Objects and click New. The following fields appear
on the General tab.

The settings for administered objects are handled similarly to connection factories. When updating
administered objects, use the same panels that you used to create administered objects.

Name:

The name by which this administered object is known for administrative purposes within IBM WebSphere
Application Server. The name must be unique within the resource adapter administered objects across the
product administrative domain.

Data type String

Description:

An optional description of this connection factory for administrative purposes within IBM WebSphere
Application Server.

Data type String

JNDI Name:

This entry is a resource-env-ref name, a message-destination-ref name (if the message-destination-

ref has no link), or a message-destination link.

Data type String

Type:

A drop-down list of all the administered object class-interface pairs as defined for the admin objects in the
Resource Adapter Archive (RAR) file.

1078 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
For each Type, there is a set of properties specified in the Properties box. This set of properties is
constructed by retrieving the properties from each administered object definition. For any existing
administered objects that are displayed for updating, this list of properties is overlaid with the properties
specified for the objects. When the Type field is changed, the properties also change to reflect the correct
properties for that type.

Data type String

Starting the Application Client Resource Configuration Tool and opening an EAR
file
Note: This task only applies to J2EE application clients.

Use these steps to start the Application Client Resource Configuration Tool. When you start the tool, one
of the most common tasks that you perform is opening and modifying the components of EAR files.
1. Open a command prompt and change to the install_root\bin directory.
2. Run the clientConfig.bat file for a Windows system or the clientConfig.sh file for a UNIX system.
3. Open an EAR file within the Application Client Resource Configuration Tool (ACRCT):
v Click File > Open.
v Select the file and click Open.
4. Save your changes to the file and close the tool:
v Click File > Save.
v Click File > Exit.

Data sources for the Application Client

WebSphere Application Server and the Application Client for WebSphere Application Server do not provide
client database drivers to be used directly from a J2EE application client. If your application client
accesses a database directly, you must provide the database drivers on the client machine. You might
contact your database vendor to acquire client database driver code and licenses. In addition, data
sources configured on the server and looked up on the client do not participate in global transactions.
Instead of accessing the database directly, it is recommended that your client application use an enterprise
bean. Accessing a database through an enterprise bean eliminates the need to have database drivers on
the client machine, since the database access is handled by the enterprise bean running on WebSphere
Application Server. For a current list of providers that are supported on WebSphere Application Server visit
the Supported hardware, software, and APIs Web site:

Configuring new data source providers (JDBC providers) for application clients
During this task, you create new data source providers, also known as JDBC providers, for your
application client. In a separate administrative task, install the Java code for the required data source
provider on the client machine on which the application client resides.

Use this task to connect application clients to relational databases.

1. Start the Application Client Resource Configuration Tool (ACRCT) and open the EAR file for which you
want to configure the new data source provider. The EAR file contents display in a tree view.
2. Select the JAR file in which you want to configure the new data source provider from the tree.
3. Expand the JAR file to view its contents.
4. Click the Data Source Providers folder. Do one of the following:
v Right-click the folder and click New Provider.
v Click Edit > New on the menu bar.
5. Configure the data source provider properties in the resulting property dialog.
6. Click OK when you finish.
7. Click File > Save on the menu bar to save your changes.

Chapter 8. Developing WebSphere applications 1079

Example: Configuring data source provider and data source settings: The purpose of this article is
to help you to configure data source provider and data source settings.
v Required fields:
– Data Source Provider Properties page: name
– Data Source Properties page: name, jndiName
v Special cases:
– The user name and password fields have no equivalent XMI tags. You must specify these fields in
the custom properties.
– The password is encrypted when you use the Application Client Resource Configuration Tool
(ACRCT). If you do not use the ACRCT the field cannot be encrypted.
v Example:
<resources.jdbc:JDBCProvider xmi:id="JDBCProvider_1" name="jdbcProvider:name"
description="jdbcProvider:description" implementationClassName="jdbcProvider:
ImplementationClass">
<classpath>jdbcProvider:classPath</classpath>
<factories xmi:type="resources.jdbc:WAS40DataSource" xmi:id="WAS40DataSource_1"
name="jdbcFactory:name" jndiName="jdbcFactory:jndiName"
description="jdbcFactory:description" databaseName="jdbcFactory:databasename">
<propertySet xmi:id="J2EEResourcePropertySet_13">
<resourceProperties xmi:id="J2EEResourceProperty_13" name="jdbcFactory:customName"
value="jdbcFactory:customValue"/>
<resourceProperties xmi:id="J2EEResourceProperty_14" name="user"
value="jdbcFactory:user"/>
<resourceProperties xmi:id="J2EEResourceProperty_15" name="password"
value="{xor}NTs9PBk+PCswLSZlMT4yOg=="/>
</propertySet>
</factories>
<propertySet xmi:id="J2EEResourcePropertySet_14">
<resourceProperties xmi:id="J2EEResourceProperty_16" name="jdbcProvider:customName"
value="jdbcProvider:customeValue"/>
</propertySet>
</resources.jdbc:JDBCProvider>

Data source provider settings for application clients:

Use this page to create a data source under a JDBC provider which provides the specific JDBC driver
implementation class.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file. Right-click Data Source Providers >
and click New. The following fields appear on the General tab:

Name:

Specifies the display name for the data source.

For example you can set this field to Test Data Source.

Data type String

Description:

Specifies a text description for the resource.

Data type String

Class Path:

1080 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
A list of paths or .jar file names which together form the location for the resource provider classes.

Implementation class:

Use this setting to perform database specific functions.

Data type String

Default Dependent on JDBC driver implementation class

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Data source properties for application clients:

Use this page to create or modify the data sources.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Data Source Providers > Data source
provider instance. Right-click Data Sources and click New. The following fields are displayed on the
General tab:

Name:

Specifies the display name of this data source.

Data type String

Description:

Specifies a text description of the data source.

Data type String

JNDI Name:

The application client run time uses this field to retrieve configuration information.

Database Name:

The name of the database to which you want to connect.

User:

Use the user ID with the Password property, for authentication if the calling application does not provide a
user ID and password explicitly.

If you specify a value for the User ID property, then you must also specify a value for the Password
property. The connection factory User ID and Password properties are used if the calling application does
not provide a user ID and password explicitly.

Chapter 8. Developing WebSphere applications 1081

Password:

Use the password with the User ID property, for authentication if the calling application does not provide a
user ID and password explicitly.

If you specify a value for the Password property, then you must also specify a value for the User ID
property.

Re-Enter Password:

Confirms the password.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Configuring new data sources for application clients

During this task, you create new data sources for your application client.
1. Click the data source provider for which you want to create a data source in the tree. Take one of the
following actions as needed:
v Configure a new data source provider.
v Click an existing data source provider.
2. Expand the data source provider to view its Data Sources folder.
3. Click the data source folder. Take one of the following actions as needed:
v Right click the data source folder and click New Factory.
v Click Edit > New on the menu bar.
4. Configure the data source properties in the displayed fields.
5. Click OK when you finish.
6. Click File > Save on the menu bar to save your changes.

Configuring mail providers and sessions for application clients

Use the Application Client Resource Configuration Tool (ACRCT) to edit the configurations of JavaMail
sessions and providers for your application clients to use.
1. Start the ACRCT.
2. Open an EAR file.
3. Locate the JavaMail objects in the tree that displays. For example, if your file contains JavaMail
sessions, expand Resources > application.jar > JavaMail Providers >
java_mail_provider_instance > JavaMail Sessions.
In this example, java_mail_provider_instance is a particular JavaMail provider.

The JavaMail session instances are located in the JavaMail Sessions folder.

Mail provider settings for application clients:

Use this page to implement the JavaMail API and create mail sessions.

1082 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file. Right-click Mail Providers > and click
New. The following fields appear on the General tab:

Name:

The name of the JavaMail resource provider.

Description:

An optional description for the resource provider.

Class Path:

Specifies a list of paths or JAR file names which together form the location for the resource provider
classes.

Protocol:

Specifies the name of the protocol.

Classname:

Specifies the name of the class implementing the protocol. Leave this field blank if you want to use the
default implementation.

Type:

This menu contains the following two values: TRANSPORT or STORE.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Mail session settings for application clients:

Use this page to configure mail session properties.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Mail Providers > mail provider
instance. Right-click Mail Sessions and click New. The following fields appear on the General tab:

Name:

Represents the administrative name of the JavaMail session object.

Description:

Provides an optional description for your administrative records.

JNDI Name:

Chapter 8. Developing WebSphere applications 1083

The application client run time uses this field to retrieve configuration information.

Mail Transport Host:

Specifies the server to connect to when sending mail.

Mail Transport Protocol:

Specifies the transport protocol to use when sending mail.

Mail Transport User:

Specifies the user ID to use when the mail transport host requires authentication.

Mail Transport Password:

Specifies the password to use when the mail transport host requires authentication.

Enable strict Internet address parsing:

Specifies whether the recipient addresses must be parsed strictly in compliance with RFC 822, which is a
specifications document issued by the Internet Architecture Board.

This setting is not generally used for most mail applications. RFC 822 syntax for parsing addresses
effectively enforces a strict definition of a valid e-mail address. If you select this setting, JavaMail will
adhere to RFC 822 syntax and reject recipient addresses that do not parse into valid e-mail addresses (as
defined by the specification). If you do not select this setting, JavaMail will not adhere to RFC 822 syntax
and will accept recipient addresses that do not comply with the specification. By default, this setting is
deselected. You can view the RFC 822 specification at the following URL for the World Wide Web
Consortium (W3C): http://www.w3.org/Protocols/rfc822/.

Re-Enter Password:

Confirms the password.

Mail From:

Specifies the mail originator.

Mail Store Host:

Specifies the mail account host (or ″domain″) name.

Mail Store User:

Specifies the user ID of the mail account.

Mail Store Password:

Specifies the password of the mail account.

Re-Enter Password:

Confirms the password.

Mail Store Protocol:

1084 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies the protocol to be used when receiving mail.

Mail Debug:

When true, JavaMail interaction with mail servers, along with these mail session properties are printed to
the stdout file.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Example: Configuring JavaMail provider and JavaMail session settings for application clients: The
purpose of this article is to help you configure JavaMail provider and JavaMail session settings.
v Required fields:
– JavaMail Provider Properties page: name, and at least one protocol provider
– JavaMail Session Properties page: name, jndiName, mail transport protocol, mail store protocol
v Special cases:
– The password is encrypted when using the ACRCT tool. Without the tool, you cannot encrypt this
field.
v Example:
<resources.mail:MailProvider xmi:id="MailProvider_1" name="Default Mail Provider"
description="IBM JavaMail Implementation">
<classpath>mailProvider:classpath</classpath>
<factories xmi:type="resources.mail:MailSession" xmi:id="MailSession_1"
name="mailSession:name" jndiName="mailSession:jndiName"
description="mailSession:description" mailTransportHost="mailSession:mailTransportHost"
mailTransportUser="mailSession:mailTransportUser"
mailTransportPassword="{xor}Mj42Mww6LCw2MDFlMT4yOg=="
mailFrom="mailSession:mailFrom" mailStoreHost="mailSession:mailStoreHost"
mailStoreUser="mailSession:mailStoreUser"
mailStorePassword="{xor}Mj42Mww6LCw2MDFlMT4yOg==" debug="true"
mailTransportProtocol="ProtocolProvider_1" mailStoreProvider="ProtocolProvider_1">
<propertySet xmi:id="J2EEResourcePropertySet_1">
<resourceProperties xmi:id="J2EEResourceProperty_1"
name="mailSession:customName" value="mailSession:customValue"/>
</propertySet>
</factories>
<propertySet xmi:id="J2EEResourcePropertySet_2">
<resourceProperties xmi:id="J2EEResourceProperty_2" name="mailProvider:customName"
value="mailProvider:customValue"/>
</propertySet>
<protocolProviders xmi:id="ProtocolProvider_1" protocol="smtp"
classname="smtp:className"/>
<protocolProviders xmi:id="ProtocolProvider_2" protocol="pop3"
classname="pop3:className"/>
<protocolProviders xmi:id="ProtocolProvider_3" protocol="imap"
classname="imap:className"/>
</resources.mail:MailProvider>

Configuring new mail sessions for application clients

During this task, you configure new mail sessions for your application client. The mail sessions are
associated with the pre-configured default mail provider supplied by the product.
1. Start the Application Client Resource Configuration Tool (ACRCT) and open the EAR file. The EAR file
contents are displayed in a tree view.

Chapter 8. Developing WebSphere applications 1085

2. Select the JAR file in which you want to configure the new JavaMail session.
3. Expand the JAR file to view its contents.
4. Click JavaMail Providers > MailProvider > JavaMail Sessions. Complete one of the following
actions:
v Right click the JavaMail Sessions folder and select New Factory.
v Click Edit > New on the menu bar.
5. Configure the JavaMail session properties in the displayed fields.
6. Click OK.
7. Click File > Save on the menu bar to save your changes.

URLs for application clients

A Uniform Resource Locator (URL) is an identifier that points to an electronically accessible resource, such
as a directory file on a machine in a network, or a document stored in a database.

URLs appear in the format scheme:scheme_information.

You can represent a scheme as http, ftp, file, or another term that identifies the type of resource and
the mechanism by which you can access the resource.

In a World Wide Web browser location or address box, a URL for a file available using HyperText Transfer
Protocol (HTTP) starts with http:. An example is http://www.ibm.com. Files available using File Transfer
Protocol (FTP) start with ftp:. Files available locally start with file:.

The scheme_information commonly identifies the Internet machine making a resource available, the path
to that resource, and the resource name. The scheme_information for HTTP, FTP and File generally starts
with two slashes (//), then provides the Internet address separated from the resource path name with one
slash (/). For example,

http://www-4.ibm.com/software/webservers/appserv/library.html.

For HTTP and FTP, the path name ends in a slash when the URL points to a directory. In such cases, the
server generally returns the default index for the directory.

URL providers for the Application Client Resource Configuration Tool

A URL provider implements the function for a particular URL protocol, such as Hyper Text Transfer
Protocol (HTTP). This provider, comprised of a pair of classes, extends the java.net.URLStreamHandler
and java.net.URLConnection classes.

Configuring new URL providers for application clients

During this task, you create URL providers and URLs for your client application. In a separate
administrative task, you must install the Java code for the required URL provider on the client machine on
which the client application resides.
1. Start the Application Client Resource Configuration Tool (ACRCT).
2. Open the EAR file for which you want to configure the new URL provider. The EAR file contents
display in a tree view.
3. Select the JAR file in which you want to configure the new URL provider from the tree.
4. Expand the JAR file to view the contents.
5. Click the folder called URL Providers. Complete one of the following actions:
v Right click the folder and select New Provider.
v Click Edit > New on the menu bar.
6. Configure the URL provider properties in the resulting property dialog.
7. Click OK.

1086 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
8. Click File > Save on the menu bar to save your changes.

Configuring URL providers and sessions using the Application Client Resource Configuration
Tool:

Use the Application Client Resource Configuration Tool (ACRCT) to edit the configurations of URL
providers and URLs to be used by your application clients.
1. Start the ACRCT.
2. Open an EAR file.
3. Locate the URL objects in the tree that displays. For example, if your file contains URL providers and
URLs, expand Resources -> application.jar -> URL Providers -> url_provider_instance
where url_provider_instance is a particular URL provider.
4. If you expand the tree further, you will also see the URLs folders containing the URL instances for
each URL provider instance.

URL settings for application clients:

Use this page to implement the function for a particular URL protocol, such as Hyper Text Transfer
Protocol (HTTP).

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > URL Providers > URL provider
instance. Right-click URLs and click New. The following fields appear on the General tab.

This provider, comprised of classes, extends the java.net.URLStreamHandler and java.net.URLConnection

classes.

Name:

The administrative name for the URL.

Description:

This is an optional description of the URL for your administrative records.

JNDI Name:

The application client run time uses this field to retrieve configuration information.

URL:

A Uniform Resource Locator (URL) name that points to an Internet or intranet resource. For example:
http://www.ibm.com.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

URL provider settings for application clients:

Chapter 8. Developing WebSphere applications 1087

Use this page create new URL providers.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file. Right click URL Providers, and click
New. The following fields appear on the General tab.

A URL provider implements the function for a particular URL protocol, such as Hyper Text Transfer
Protocol (HTTP). This provider, comprised of classes, extends the java.net.URLStreamHandler and
java.net.URLConnection classes.

Name:

Administrative name for the URL.

Description:

Optional description of the URL, for your administrative records.

Class Path:

A list of paths or JAR file names which together form the location for the resource provider classes.

Protocol:

Protocol supported by this stream handler. For example, nntp, smtp, ftp, and so on.

To use the default protocol, leave this field blank.

Stream handler class:

Fully qualified name of a User-defined Java class that extends the java.net.URLStreamHandler for a
particular URL protocol, such as FTP.

To use the default stream handler, leave this field blank.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Example: Configuring URL and URL provider settings for application clients: The purpose of this
article is to help you to configure URL and URL provider settings.
v Required fields:
– URL Properties page: name, jndiName, url
– URL Provider Properties page: name
v Example:
<resources.url:URLProvider xmi:id="URLProvider_1" name="urlProvider:name"
description="urlProvider:description"
streamHandlerClassName="urlProvider:streamHandlerClass"
protocol="urlProvider:protocol">
<classpath>urlProvider:classpath</classpath>
<factories xmi:type="resources.url:URL" xmi:id="URL_1" name="urlFactory:name"
jndiName="urlFactory:jndiName" description="urlFactory:description"
spec="urlFactory:url">

1088 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
<propertySet xmi:id="J2EEResourcePropertySet_18">
<resourceProperties xmi:id="J2EEResourceProperty_20" name="urlFactory:customName"
value="urlFactory:customValue"/>
</propertySet>
</factories>
<propertySet xmi:id="J2EEResourcePropertySet_19">
<resourceProperties xmi:id="J2EEResourceProperty_21" name="urlProvider:customName"
value="urlProvider:customValue"/>
</propertySet>
</resources.url:URLProvider>

Configuring new URLs with the Application Client Resource Configuration Tool
During this task, you create URLs for your client application.
1. Click the URL provider for which you want to create a URL in the tree. Do one of the following:
v Configure a new URL provider.
v Click an existing URL provider.
2. Expand the URL provider to view the URLs folder.
3. Click the URL folder. Complete one of the following actions:
v Right click the folder and click New Factory.
v Click Edit -> New on the menu bar.
4. Configure the URL properties in the displayed fields.
5. Click OK when you finish.
6. Click File > Save in the menu bar to save your changes.

WebSphere asynchronous messaging using the Java Message Service API for the
Application Client Resource Configuration Tool
WebSphere Application Server supports asynchronous messaging as a method of communication based
on the Java Message Service (JMS) programming interface. The JMS interface provides a common way
for Java programs (clients and J2EE applications) to create, send, receive, and read asynchronous
requests as JMS messages.

This topic provides an overview of asynchronous messaging using JMS support provided by the
WebSphere Application Server.

The base support for asynchronous messaging using the JMS API provides the common set of JMS
interfaces and associated semantics that define how a JMS client can access the facilities of a JMS
provider. This support enables WebSphere product J2EE applications, as JMS clients, to exchange
messages asynchronously with other JMS clients, by using JMS destinations (queues or topics). A J2EE
application can use JMS queue destinations for point-to-point messaging and JMS topic destinations for
Publisher and Subscriber messaging. A J2EE application can explicitly poll for messages on a destination,
and then retrieve messages for processing by business logic beans (enterprise beans).

With the base JMS and XA support, the J2EE application uses standard JMS calls to process messages,
including any responses or outbound messaging. An enterprise bean can handle responses acting as a
sender bean, or within the enterprise bean that receives the incoming messages. Optionally, this process
can use two-phase commit within the scope of a transaction. This level of function for asynchronous
messaging is called bean-managed messaging, and gives an enterprise bean complete control over the
messaging infrastructure, for example, connection and session pool management. The common container
has no role in bean-managed messaging.

WebSphere Application Server also supports automatic asynchronous messaging using message-driven
beans (a type of enterprise bean defined in the EJB 2.0 specification) and JMS listeners (part of the JMS
application server facilities). Messages are automatically retrieved from JMS destinations, optionally within
a transaction, then sent to the message-driven bean in a J2EE application, without the application having
to explicitly poll JMS destinations.

Chapter 8. Developing WebSphere applications 1089

Java Message Service (JMS) providers for clients
This topic describes the different ways that client applications can use JMS providers with WebSphere
Application Server. A JMS provider enables use of the Java Message Service (JMS) and other message
resources in WebSphere Application Server.

IBM WebSphere Application Server supports asynchronous messaging through the use of a JMS provider
and its related messaging system. JMS providers must conform to the JMS specification version 1.1. To
use message-driven beans the JMS provider must support the optional Application Server Facility (ASF)
function defined within that specification, or support an inbound resource adapter as defined in the JCA
specification version 1.5.

The service integration technologies of IBM WebSphere Application Server can act as a messaging
system when you have configured a service integration bus that is accessed through the default
messaging provider. This support is installed as part of WebSphere Application Server, administered
through the administrative console, and is fully integrated with the WebSphere Application Server runtime.

WebSphere Application Server also includes support for the following JMS providers:
WebSphere MQ
Provided for use with supported versions of WebSphere MQ.
Generic
Provided for use with any 3rd party messaging system which supports ASF.

For backwards compatibility with earlier releases, WebSphere Application Server also includes support for
the V5 default messaging provider which enables you to configure resources for use with the WebSphere
Application Server version 5 Embedded Messaging system. The V5 default messaging provider can also
be used with a service integration bus.

WebSphere applications can use messaging resources provided by any of these JMS providers. However
the choice of provider is most often dictated by requirements to use or integrate with an existing
messaging system. For example, you may already have a messaging infrastructure based on WebSphere
MQ. In this case you may either connect directly using the included support for WebSphere MQ as a JMS
provider, or configure a service integration bus with links to a WebSphere MQ network and then access
the bus through the default messaging provider.

Configuring Java messaging client resources

In a separate administrative task, install the Java Message Service (JMS) client on the client machine
where the application client resides. The messaging product vendor must provide an implementation of the
JMS client. For more information, see your messaging product documentation.

During this task, you create new JMS provider configurations for your application client. The application
client can use a messaging service through the Java Message Service APIs. A JMS provider provides two
kinds of J2EE factories. One is a JMS connection factory, and the other is a JMS destination factory.
1. Start the Application Client Resource Configuration Tool (ACRCT).
2. Open the EAR file for which you want to configure the new JMS provider. The EAR file contents are in
the displayed tree view.
3. Select the JAR file in which you want to configure the new JMS provider from the tree.
4. Expand the JAR file to view its contents.
5. Right-click Messaging Providers and select New.
6. Configure the JMS provider properties in the resulting property dialog.
7. Click OK.
8. Click File > Save.

1090 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring new JMS providers with the Application Client Resource Configuration Tool:

During this task, you create new Java Message Service (JMS) provider configurations for the Application
Client. The Application Client makes use of a messaging service through the JMS interfaces. A JMS
provider provides two kinds of J2EE resources. One is a JMS connection factory, and the other is a JMS
destination.

In a separate administrative task, you must install the JMS client on the client machine where your
particular application client resides. The messaging product vendor must provide an implementation of the
JMS client. For more information, see your messaging product documentation.
1. Start the Application Client Resource Configuration Tool and open the EAR file for which you want to
configure the new JMS provider. The EAR file contents are displayed in a tree view.
2. From the tree, select the JAR file in which you want to configure the new JMS provider.
3. Expand the JAR file to view its contents.
4. Right-click Messaging Providers. Complete one of the following actions:
v Right click the folder and select New.
v On the menu bar, click Edit > New.
5. In the resulting property dialog, configure the JMS provider properties.
6. Click OK when finished.
7. Click File -> Save on the menu bar to save your changes.

JMS provider settings for application clients:

Use this page to configure properties of the Java Message Service (JMS) provider, if you want to use a
JMS provider other than the default messaging provider or the WebSphere MQ as a JMS provider.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file. Right click Messaging Providers, and
click New. The following fields appear on the General tab.

Name:

The name by which the JMS provider is known for administrative purposes.

Data type String

Description:

A description of the JMS provider, for administrative purposes.

Data type String

Class Path:

A list of paths or .jar file names which together form the location for the resource provider classes.

Context factory class:

The Java class name of the initial context factory for the JMS provider.

For example, for an LDAP service provider the value has the form: com.sun.jndi.ldap.LdapCtxFactory.

Data type String

Chapter 8. Developing WebSphere applications 1091

Provider URL:

The JMS provider URL for external JNDI lookups.

For example, an LDAP URL for a JMS provider has the form: ldap://hostname.company.com/contextName.

Data type String

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Default Provider connection factory settings:

Use this panel to view or change the configuration properties of the selected JMS connection factory for
use with the internal product Java Message Service (JMS) provider that is installed with WebSphere
Application Server. These configuration properties control how connections are created between the JMS
provider and the service integration bus that it uses

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Default
Provider. Right-click Connection Factories and click New. The following fields appear on the General
tab.

Settings that have a default value display the appropriate value. Any settings that have fixed values have a
drop down menu.

Name:

The name of the connection factory.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

JNDI Name:

The JNDI name that is used to match this Resource Adapter connection factory definition to the
deployment descriptor. This entry is a resource-ref name.

Data type String

User Name:

1092 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The User Name used with the Password property for connecting to an application.

If you specify a value for the User Name property, you must also specify a value for the Password
property.

The connection factory User ID and Password properties are used if the calling application does not
provide a userid and password explicitly. If a user name and password are specified, then an
authentication alias is created for the factory where the password is encrypted.

Data type String

Password:

The password used to authenticate connection to an application.

If you specify a value for the User Name property, you must also specify a value for the Password
property.

Data type String

Re-Enter Password:

Confirms the password.

Bus Name:

The name of the bus to which the connection factory connects.

Data type String

Client Identifier:

The name of the client. Required for durable topic subscriptions.

Data type String

Nonpersistent Messaging Reliability:

The reliability applied to nonpersistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to
As bus destination. The reliability is then defined by the Reliability property of the bus destination to which
the JMS destination is assigned.

Default ReliablePersistent

Chapter 8. Developing WebSphere applications 1093

Range
None There is no message reliability for nonpersistent
messages. If a nonpersistent message cannot be
delivered, it is discarded.
Best effort nonpersistent
Messages are never written to disk, and are
thrown away if memory cache overruns.
Express nonpersistent
Messages are written asynchronously to
persistent storage if memory cache overruns, but
are not kept over server restarts.
Reliable nonpersistent
Messages can be lost if a messaging engine
fails, and can be lost under normal operating
conditions.
Reliable persistent
Messages can be lost if a messaging engine
fails, but are not lost under normal operating
conditions.
Assured persistent
Highest degree of reliability where assured
message delivery is supported.
As Bus destination
Use the delivery option configured for the bus
destination.

Persistent Message Reliability:

The reliability applied to persistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to
As bus destination. The reliability is then defined by the Reliability property of the bus destination to
which the JMS destination is assigned.

Default ReliablePersistent

1094 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range
None There is no message reliability for nonpersistent
messages. If a nonpersistent message cannot be
delivered, it is discarded.
Best effort nonpersistent
Messages are never written to disk, and are
thrown away if memory cache overruns.
Express nonpersistent
Messages are written asynchronously to
persistent storage if memory cache overruns, but
are not kept over server restarts.
Reliable nonpersistent
Messages can be lost if a messaging engine
fails, and can be lost under normal operating
conditions.
Reliable persistent
Messages can be lost if a messaging engine
fails, but are not lost under normal operating
conditions.
Assured persistent
Highest degree of reliability where assured
message delivery is supported.
As Bus destination
Use the delivery option configured for the bus
destination.

Durable Subscription Home:

The name of the durable subscription home.

Data type String

Share durable subscriptions:

Controls whether or not durable subscriptions are shared across connections with members of a server
cluster.

Normally, only one session at a time can have a TopicSubscriber for a particular durable subscription. This
property enables you to override this behavior, to enable a durable subscription to have multiple
simultaneous consumers.

Data type Selection list

Default In cluster
Range
In cluster
Allows sharing of durable subscriptions when
connections are made from within a server
cluster.
Always shared
Durable subscriptions can be shared across
connections.
Never shared
Durable subscriptions are never shared across
connections.

Chapter 8. Developing WebSphere applications 1095

Read Ahead:

Controls the read-ahead optimization during message delivery.

Default Default
Range Default, AlwaysOn and AlwaysOff

Related concepts
“Resource Adapters for the client” on page 1073

Target:

The name of the Workload Manager target group containing the messaging engine.

Data type String

Target Type:

The type of Workload Manager target group that contains the messaging engine.

Default BusMember
Range BusMember, Custom, ME

Target Significance:

The priority of significance for the target specified.

Default Preferred
Range Preferred, Required

Target Inbound Transport Chain:

The name of the protocol that resolves to a group of messaging engines.

Data type String

Provider Endpoints:

The list of comma separated endpoints used to connect to a bootstrap server.

Type a comma-separated list of endpoint triplets with the syntax: host:port:protocol.

Example merlin:7276:BootstrapBasicMessaging,Gandalf:5557:BootstrapSecureMessaging

where

BootstrapBasicMessaging corresponds to the remote protocol InboundBasicMessaging

(JFAP-TCP/IP).
Default v If the host name is not specified, then the default localhost is used as a default
value.
v If the port number is not specified, then 7276 is used as a default value.
v If the chain name is not specified, a predefined chain, such as
BootstrapBasicMessaging, is used as a default value.

1096 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Connection Proximity:

The proximity that the messaging engine should have to the requester.

Default Bus
Range Bus, Host, Cluster, Server

Temporary Queue Name Prefix:

The prefix to apply to the names of temporary queues. This name is a maximum of 12 characters.

Data type String

Temporary Topic Name Prefix:

The prefix to apply to the names of temporary topics. This name is a maximum of 12 characters.

Data type String

Default Provider queue connection factory settings:

Use this panel to view or change the configuration properties of the selected JMS queue connection
factory for use with the internal product Java Message Service (JMS) provider that is installed with
WebSphere Application Server. These configuration properties control how connections are created
between the JMS provider and the service integration bus that it uses

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Default
Provider. Right-click Queue Connection Factories and click New. The following fields appear on the
General tab.

Settings that have a default value display the appropriate value. Any settings that have fixed values have a
drop down menu.

Name:

The name of the queue connection factory.

Data type String

Description:

A description of this queue connection factory for administrative purposes within IBM WebSphere
Application Server.

Data type String

JNDI Name:

The JNDI name that is used to match this queue connection factory definition to the deployment
descriptor. This entry is a resource-ref name.

Data type String

Chapter 8. Developing WebSphere applications 1097

User Name:

The User Name used, with the Password property, for authentication if the calling application does not
provide a userid and password explicitly. If this field is used, then the Properties field UserName is ignored.

If you specify a value for the User Name property, you must also specify a value for the Password
property.

The connection factory User Name and Password properties are used if the calling application does not
provide a userid and password explicitly. If a user name and password are specified, then an
authentication alias is created for the factory where the password is encrypted.

Data type String

Password:

The password used to create an encrypted. If you complete this field, then the Password field in the
Properties box is ignored.

If you specify a value for the User Name property, you must also specify a value for the Password
property.

Data type String

Re-Enter Password:

Confirms the password.

Bus Name:

The name of the bus to which the queue connection factory connects.

Data type String

Client Identifier:

The client identifier. Required for durable topic subscriptions.

Data type String

Nonpersistent Messaging Reliability:

The reliability applied to nonpersistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to
As bus destination. The reliability is then defined by the Reliability property of the bus destination to which
the JMS destination is assigned.

Default ReliablePersistent

1098 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range
None There is no message reliability for nonpersistent
messages. If a nonpersistent message cannot be
delivered, it is discarded.
Best effort nonpersistent
Messages are never written to disk, and are
thrown away if memory cache overruns.
Express nonpersistent
Messages are written asynchronously to
persistent storage if memory cache overruns, but
are not kept over server restarts.
Reliable nonpersistent
Messages can be lost if a messaging engine
fails, and can be lost under normal operating
conditions.
Reliable persistent
Messages can be lost if a messaging engine
fails, but are not lost under normal operating
conditions.
Assured persistent
Highest degree of reliability where assured
message delivery is supported.
As Bus destination
Use the delivery option configured for the bus
destination.

Persistent Message Reliability:

The reliability applied to persistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to
As bus destination. The reliability is then defined by the Reliability property of the bus destination to
which the JMS destination is assigned.

Default ReliablePersistent

Chapter 8. Developing WebSphere applications 1099

Range
None There is no message reliability for nonpersistent
messages. If a nonpersistent message cannot be
delivered, it is discarded.
Best effort nonpersistent
Messages are never written to disk, and are
thrown away if memory cache overruns.
Express nonpersistent
Messages are written asynchronously to
persistent storage if memory cache overruns, but
are not kept over server restarts.
Reliable nonpersistent
Messages can be lost if a messaging engine
fails, and can be lost under normal operating
conditions.
Reliable persistent
Messages can be lost if a messaging engine
fails, but are not lost under normal operating
conditions.
Assured persistent
Highest degree of reliability where assured
message delivery is supported.
As Bus destination
Use the delivery option configured for the bus
destination.

Read Ahead:

Controls the read-ahead optimization during message delivery.

Default Default
Range Default, AlwaysOn and AlwaysOff

Target:

The name of the Workload Manager target group containing the messaging engine.

Data type String

Target Type:

The type of Workload Manager target group that contains the messaging engine.

Default BusMember
Range BusMember, Custom, Destination, ME

Target Significance:

The priority of significance for the target specified.

Default Preferred
Range Preferred, Required

1100 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Target Inbound Transport Chain:

The name of the protocol that resolves to a group of messaging engines.

Data type String

Provider Endpoints:

The list of comma separated endpoints used to connect to a bootstrap server.

Type a comma-separated list of endpoint triplets with the syntax: host:port:protocol.

Example localhost:7777:BootstrapBasicMessaging

where

BootstrapBasicMessaging corresponds to the remote

protocol InboundBasicMessaging (JFAP-TCP/IP).
Default v If the host name is not specified, then the default
localhost is used as a default value.
v If the port number is not specified, then 7276 is used as
a default value.
v If the chain name is not specified, a predefined chain,
such as BootstrapBasicMessaging, is used as a default
value.

Connection Proximity:

The proximity that the messaging engine should have to the requester.

Default Bus, Cluster, Server

Range Bus, Host

Temporary Queue Name Prefix:

The prefix to apply to the names of temporary queues. This name is a maximum of 12 characters.

Data type String

Default Provider topic connection factory settings:

Use this panel to view or change the configuration properties of the selected JMS topic connection factory
for use with the internal product Java Message Service (JMS) provider that is installed with WebSphere
Application Server. These configuration properties control how connections are created between the JMS
provider and the service integration bus that it uses.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Default
Provider. Right-click Topic Connection Factories and click New. The following fields appear on the
General tab.

Settings that have a default value display that appropriate value. Any settings that have fixed values have
a drop down menu.

Chapter 8. Developing WebSphere applications 1101

Name:

The name of the topic connection factory.

Data type String

Description:

A description of this topic connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

JNDI Name:

The JNDI name that is used to match this topic connection factory definition to the deployment descriptor.
This entry is a resource-ref name.

Data type String

User Name:

The User Name used, with the Password property, for authentication if the calling application does not
provide a userid and password explicitly. If this field is used, then the Properties field UserName is ignored.

If you specify a value for the User Name property, you must also specify a value for the Password
property.

The connection factory User Name and Password properties are used if the calling application does not
provide a userid and password explicitly. If a user name and password are specified, then an
authentication alias is created for the factory where the password is encrypted.

Data type String

Password:

The password used to create an encrypted. If you complete this field, then the Password field in the
Properties box is ignored.

If you specify a value for the User Name property, you must also specify a value for the Password
property.

Data type String

Re-Enter Password:

Confirms the password.

Bus Name:

The name of the bus to which the topic connection factory connects.

Data type String

1102 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Client Identifier:

The name of the client. This field is required for durable topic subscriptions.

Data type String

Nonpersistent Messaging Reliability:

The reliability applied to nonpersistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to
As bus destination. The reliability is then defined by the Reliability property of the bus destination to which
the JMS destination is assigned.

Default ReliablePersistent
Range
None There is no message reliability for nonpersistent
messages. If a nonpersistent message cannot be
delivered, it is discarded.
Best effort nonpersistent
Messages are never written to disk, and are
thrown away if memory cache overruns.
Express nonpersistent
Messages are written asynchronously to
persistent storage if memory cache overruns, but
are not kept over server restarts.
Reliable nonpersistent
Messages can be lost if a messaging engine
fails, and can be lost under normal operating
conditions.
Reliable persistent
Messages can be lost if a messaging engine
fails, but are not lost under normal operating
conditions.
Assured persistent
Highest degree of reliability where assured
message delivery is supported.
As Bus destination
Use the delivery option configured for the bus
destination.

Persistent Message Reliability:

The reliability applied to persistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to
As bus destination. The reliability is then defined by the Reliability property of the bus destination to
which the JMS destination is assigned.

Default ReliablePersistent

Chapter 8. Developing WebSphere applications 1103

Range
None There is no message reliability for nonpersistent
messages. If a nonpersistent message cannot be
delivered, it is discarded.
Best effort nonpersistent
Messages are never written to disk, and are
thrown away if memory cache overruns.
Express nonpersistent
Messages are written asynchronously to
persistent storage if memory cache overruns, but
are not kept over server restarts.
Reliable nonpersistent
Messages can be lost if a messaging engine
fails, and can be lost under normal operating
conditions.
Reliable persistent
Messages can be lost if a messaging engine
fails, but are not lost under normal operating
conditions.
Assured persistent
Highest degree of reliability where assured
message delivery is supported.
As Bus destination
Use the delivery option configured for the bus
destination.

Durable Subscription Home:

The name of the durable subscription home.

Data type String

Share durable subscriptions:

Controls whether or not durable subscriptions are shared across connections with members of a server
cluster.

Normally, only one session at a time can have a TopicSubscriber for a particular durable subscription. This
property enables you to override this behavior, to enable a durable subscription to have multiple
simultaneous consumers.

Data type Selection list

Default In cluster
Range
In cluster
Allows sharing of durable subscriptions when
connections are made from within a server
cluster.
Always shared
Durable subscriptions can be shared across
connections.
Never shared
Durable subscriptions are never shared across
connections.

1104 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Read Ahead:

Controls the read-ahead optimization during message delivery.

Default Default
Range Default, AlwaysOn and AlwaysOff

Target:

The name of the Workload Manager target group containing the messaging engine.

Data type String

Target Type:

The type of Workload Manager target group that contains the messaging engine.

Default BusMember
Range BusMember, Custom, ME

Target Significance:

The priority of significance for the target specified.

Default Preferred
Range Preferred, Required

Target Inbound Transport Chain:

The name of the protocol that resolves to a group of messaging engines.

Data type String

Provider Endpoints:

The list of comma separated endpoints used to connect to a bootstrap server.

Type a comma-separated list of endpoint triplets with the syntax: host:port:protocol.

Example localhost:7777:BootstrapBasicMessaging

where

BootstrapBasicMessaging corresponds to the remote

protocol InboundBasicMessaging (JFAP-TCP/IP).
Default v If the host name is not specified, then the default
localhost is used as a default value.
v If the port number is not specified, then 7276 is used as
a default value.
v If the chain name is not specified, a predefined chain,
such as BootstrapBasicMessaging, is used as a default
value.

Chapter 8. Developing WebSphere applications 1105

Connection Proximity:

The proximity that the messaging engine should have to the requester.

Default Bus
Range Bus, Host, Cluster, Server

Temporary Topic Name Prefix:

The prefix to apply to the names of temporary topics. This name is a maximum of 12 characters.

Data type String

Default Provider queue destination settings:

Use this panel to view or change the configuration properties of the selected JMS queue destination for
use with the internal product Java Message Service (JMS) provider that is installed with WebSphere
Application Server.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Default
Provider. Right-click Queue Destinations. Click New. The following fields appear on the General tab.

Name:

The name of the queue destination factory. You must complete this field.

Data type String

Description:

A description of this queue destination for administrative purposes within WebSphere Application Server.

Data type String

JNDI Name:

The JNDI name used to match this definition to a deployment descriptor resource-env-ref name.

Data type String

Queue Name:

The name of the queue.

Data type String

Delivery Mode:

The delivery mode for messages sent to this destination.

Data type String

Range Application, Persistent or NonPersistent

1106 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Default Application

Time to Live:

The default length of time from its dispatch time that a message sent to this destination should be retained
by the system, where 0 indicates that time to live value does not expire. Value from the producer is used if
the Time to Live field is not completed.

Data type Integer

Units Milliseconds

Priority:

The priority for messages sent to this destination. The value from the producer is used if not completed.

Data type Integer

Range 0 to 9 with 0 as the lowest priority and 9 as the highest
priority

Read Ahead:

Used to control read-ahead optimization during message delivery.

Data type String

Range AsConnection, AlwaysOn and AlwaysOff
Default AsConnection

Default Provider topic destination settings:

Use this panel to view or change the configuration properties of the selected JMS topic destination for use
with the internal product Java Message Service (JMS) provider that is installed with WebSphere
Application Server.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Default
Provider. Right-click Topic Destinations, and click New. The following fields appear on the General tab.

Name:

The name of the topic destination entry.

Data type String

Description:

A description of the entry.

Data type String

JNDI Name:

The JNDI name used to match this definition to a deployment descriptor resource-env-ref name.

Chapter 8. Developing WebSphere applications 1107

Data type String

Topic Space:

The name of the topic space. This field is required.

Data type String

Default DEFAULT_TOPIC_SPACE

Topic Name:

The name of the topic. This field is required.

Data type String

Delivery Mode:

The default mode for messages sent to this destination.

Data type String

Range Application, Persistent or NonPersistent
Default Application

Time to Live:

The default length of time from its dispatch time that a message sent to this destination should be retained
by the system, where 0 indicates that time to live value does not expire. Value from the producer is used if
not completed.

Data type Long

Units Milliseconds

Priority:

The priority for messages sent to this destination. Value from producer is used if not completed.

Data type Integer

Range 0 to 9 with 0 as the lowest priority and 9 as the highest
priority

Read Ahead:

Used to control read-ahead optimization during message delivery.

Data type String

Range AsConnection, AlwaysOn and AlwaysOff
Default AsConnection

Version 5 Default Provider queue connection factory settings for application clients:

1108 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Use this panel to browse or change the configuration properties of the selected JMS queue connection
factory for point-to-point messaging for use by WebSphere Application Server version 5 applications.
These configuration properties control how connections are created between the JMS provider and the
default messaging system that it uses.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Provider > Version 5
Default Provider. Right-click Queue Connection Factories and click New. The following fields appear on
the General tab.

A queue connection factory is used to create JMS connections to queue destinations. The queue
connection factory is created by the internal WebSphere Application Server product JMS provider. A
Version 5 Default Provider queue connection factory has the following properties:

Name:

The name by which this queue connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the JMS connection factories across the
WebSphere administrative domain.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

JNDI Name:

The application client run time uses this field to retrieve configuration information.

User ID:

The User ID used, with the Password property, for authentication if the calling application does not
provide a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

The connection factory User ID and Password properties are used if the calling application does not
provide a User ID and password explicitly, for example, if the calling application uses the method
createQueueConnection(). The JMS client flows the userid and password to the JMS server.

Data type String

Password:

The password used, with the User ID property, for authentication if the calling application does not provide
a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

Re-Enter Password:

Chapter 8. Developing WebSphere applications 1109

Confirms the password.

Node:

The WebSphere node name of the administrative node where the JMS server runs for this connection
factory. Connections created by this factory connect to that JMS server.

Data type String

Application Server:

Enter the name of the application server. This name is not the host name of the machine, but the name of
the configured application server.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Version 5 Default Provider topic connection factory settings for application clients:

Use this panel to view or change the configuration properties of the selected topic connection factory for
use with the internal product Java Message Service (JMS) provider. These configuration properties control
how connections are created between the JMS provider and the messaging system that it uses.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Version 5
Default Provider. Right click Topic Connection Factories and click New. The following fields appear on
the General tab.

A Version 5 Default Provider topic connection factory has the following properties.

Name:

The name by which this queue connection factory is known for administrative purposes within WebSphere
Application Server. The name must be unique within the JMS connection factories across the WebSphere
Application Server administrative domain.

Data type String

Description:

A description of this topic connection factory for administrative purposes within WebSphere Application
Server.

Data type String

JNDI Name:

The application client run time uses this field to retrieve configuration information.

1110 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
User ID:

The user ID used, with the Password property, for authentication if the calling application does not provide
a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

The connection factory User ID and Password properties are used if the calling application does not
provide a userid and password explicitly, for example, if the calling application uses the method
createTopicConnection(). The JMS client flows the userid and password to the JMS server.

Data type String

Password:

The password used, with the User ID property, for authentication if the calling application does not provide
a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

Data type String

Re-Enter Password:

Confirms the password.

Node:

The WebSphere Application Server node name of the administrative node where the JMS server runs for
this connection factory. Connections created by this factory connect to that JMS server.

Data type Enum

Range Pull-down list of nodes in the WebSphere Application
Server administrative domain.

Application Server:

Enter the name of the application server. This name is not the host name of the machine, but the name of
the configured application server.

Port:

Which of the two ports that connections use to connect to the JMS Server. The QUEUED port is for
full-function JMS publish/subscribe support, the DIRECT port is for nonpersistent, nontransactional,
nondurable subscriptions only.

Note: Message-driven beans cannot use the direct listener port for publish or subscribe support.
Therefore, any topic connection factory configured with the Port set to Direct cannot be used with
message-driven beans.

Data type Enum

Default QUEUED

Chapter 8. Developing WebSphere applications 1111

Range QUEUED
The listener port used for full-function JMS
compliant, publish or subscribe support.
DIRECT
The listener port used for direct TCP/IP
connection (nontransactional, nonpersistent, and
nondurable subscriptions only) for publish or
subscribe support.

The TCP/IP port numbers for these ports are defined on

the product internal JMS server.

Client ID:

The JMS client identifier used for connections to the MQSeries queue manager.

Data type String

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Version 5 Default Provider queue destination settings for application clients:

Use this panel to view or change the configuration properties of the selected queue destination for use
with product Java Message Service (JMS) provider.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Version 5
Default Provider. Right click Queue Destinations and click New. The following fields are displayed on
the General tab.

A queue destination is used to configure the properties of a JMS queue. A Version 5 Default Provider
queue destination has the following properties.

Name:

The name by which the queue is known for administrative purposes within WebSphere Application Server.

Data type String

Description:

A description of the queue, for administrative purposes.

Data type String

JNDI Name:

The application client run time uses this field to retrieve configuration information.

1112 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Persistence:

Whether all messages sent to the destination are persistent, nonpersistent, or have their persistence
defined by the application.

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
Messages on the destination have their
persistence defined by the application that put
them onto the queue.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Persistent
Messages on the destination are persistent.
Nonpersistent
Messages on the destination are not persistent.

Priority:

Whether the message priority for this destination is defined by the application or the Specified priority
property.

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
The priority of messages on this destination is
defined by the application that put them onto the
destination.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Specified
The priority of messages on this destination is
defined by the Specified priority property. If you
select this option, you must define a priority on
the Specified priority property.

Specified Priority:

If the Priority property is set to Specified, type here the message priority for this queue, in the range 0
(lowest) through 9 (highest).

If the Priority property is set to Specified, messages sent to this queue have the priority value specified
by this property.

Data type Integer

Units Message priority level
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Chapter 8. Developing WebSphere applications 1113

Whether the expiry timeout for this queue is defined by the application or the Specified expiry property, or
whether messages on the queue expire (have an unlimited expiry timeout).

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
The expiry timeout for messages in this queue is
defined by the application that put them onto the
queue.
Specified
The expiry timeout for messages in this queue is
defined by the Specified expiry property.If you
select this option, you must define a time out on
the Specified expiry property.
Unlimited
Messages in this queue have no expiry timeout,
and those messages never expire.

Specified Expiry:

If the Expiry timeout property is set to Specified, specify the number of milliseconds (greater than 0)
after which messages on this queue expire.

Data type Integer

Units Milliseconds
Range Greater than or equal to 0
v 0 indicates that messages never timeout.
v Other values are an integer number of milliseconds.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Version 5 Default Provider topic destination settings for application clients:

Use this panel to view or change the configuration properties of the selected topic destination for use with
the internal product Java Message Service (JMS) provider.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > Version 5
Default Provider. Right click Topic Destinations and click New. The following fields appear on the
General tab.

A topic destination is used to configure the properties of a JMS topic for the associated JMS provider. A
Version 5 Default Provider topic has the following properties.

Name:

The name by which the topic is known for administrative purposes.

Data type String

1114 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Description:

A description of the topic, for administrative purposes within WebSphere Application Server.

Data type String

JNDI Name:

The application client run-time environment uses this field to retrieve configuration information.

Topic Name: The name of the topic as defined to the JMS provider.

Data type String

Persistence:

Whether all messages sent to the destination are persistent, nonpersistent, or have their persistence
defined by the application.

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
Messages on the destination have their
persistence defined by the application that put
them onto the queue.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Persistent
Messages on the destination are persistent.
Nonpersistent
Messages on the destination are not persistent.

Priority:

Whether the message priority for this destination is defined by the application or the Specified priority
property.

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
The priority of messages on this destination is
defined by the application that put them onto the
destination.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Specified
The priority of messages on this destination is
defined by the Specified priority property.If you
select this option, you must define a priority on
the Specified priority property.

Specified Priority:

Chapter 8. Developing WebSphere applications 1115

If the Priority property is set to Specified, specify the message priority for this queue, in the range 0
(lowest) through 9 (highest).

If the Priority property is set to Specified, messages sent to this queue have the priority value specified
by this property.

Data type Integer

Units Message priority level
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Whether the expiry timeout for this queue is defined by the application or the Specified expiry property, or
messages on the queue never expire (have an unlimited expiry timeout).

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
The expiry timeout for messages on this queue is
defined by the application that put them onto the
queue.
Specified
The expiry timeout for messages on this queue is
defined by the Specified expiry property. If you
select this option, you must define a timeout on
the Specified expiry property.
Unlimited
Messages on this queue have no expiry timeout,
so those messages never expire.

Specified Expiry:

If the Expiry timeout property is set to Specified, type here the number of milliseconds (greater than 0)
after which messages on this queue expire.

Data type Integer

Units Milliseconds
Range Greater than or equal to 0
v 0 indicates that messages never time out.
v Other values are an integer number of milliseconds.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

WebSphere MQ Provider queue connection factory settings for application clients:

Use this panel to view or change the configuration properties of the selected queue connection factory for
use with the MQSeries product Java Message Service (JMS) provider. These configuration properties
control how connections are created between the JMS provider and WebSphere MQ.

1116 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > WebSphere
MQ Provider. Right click Queue Connection Factories, and click New. The following fields are displayed
on the General tab.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ for JMS resources. For more information about configuring WebSphere MQ for
JMS resources, see the WebSphere MQ Using Java book, located in the WebSphere MQ Family
library.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.

A queue connection factory for the JMS provider has the following properties.

Name:

The name by which this queue connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the JMS connection factories across the
WebSphere administrative domain.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

JNDI Name:

The application client run time uses this field to retrieve configuration information.

User ID:

The user ID used, with the Password property, for authentication if the calling application does not provide
a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

The connection factory User ID and Password properties are used if the calling application does not
provide a userid and password explicitly; for example, if the calling application uses the method
createQueueConnection(). The JMS client flows the userid and password to the JMS server.

Data type String

Password:

The password used, with the User ID property, for authentication if the calling application does not provide
a userid and password explicitly.

Chapter 8. Developing WebSphere applications 1117

If you specify a value for the User ID property, you must also specify a value for the Password property.

Data type String

Default Null

Re-Enter Password:

Confirms the password.

Queue Manager:

The name of the MQSeries queue manager for this connection factory.

Connections created by this factory connect to that queue manager.

Data type String

Host:

The name of the host on which the WebSphere MQ queue manager runs for client connection only.

Data type String

Default Null
Range A valid TCP/IP host name

Port:

The TCP/IP port number used for connection to the WebSphere MQ queue manager, for client connection
only.

This port must be configured on the WebSphere MQ queue manager.

Data type Integer

Default Null
Range A valid TCP/IP port number, configured on the WebSphere MQ queue
manager.

Channel:

The name of the channel used for connection to the WebSphere MQ queue manager, for client connection
only.

Data type String

Default Null
Range 1 through 20 ASCII characters

Transport type:

Specifies whether the WebSphere MQ client connection or JNDI bindings are used for connection to the
WebSphere MQ queue manager. The external JMS provider controls the communication protocols
between JMS clients and JMS servers. Tune the transport type when you are using non-ASF
nonpersistent, nondurable, nontransactional messaging or when you want to satisfy security issues and
the client is local to the queue manager node.

1118 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Enum
Units Not applicable
Default BINDINGS
Range BINDINGS
JNDI bindings are used to connect to the queue manager.
BINDINGS is a shared memory protocol and can only be used when
the queue manager is on the same node as the JMS client and
poses security risks that should be addressed through the use of
EJB roles.
CLIENT
WebSphere MQ client connection is used to connect to the queue
manager. CLIENT is a typical TCP-based protocol.
DIRECT
For WebSphere MQ Event Broker using DIRECT mode. DIRECT is a
lightweight sockets protocol used in nontransactional, nondurable
and nonpersistent Publish/Subscribe messaging. DIRECT only works
for clients and message-driven beans using the non-ASF protocol.
QUEUED
QUEUED is a standard TCP protocol.
Recommended Queue connection factory transport type
BINDINGS is faster by 30% or more, but it lacks security. When you
have security concerns, BINDINGS is more desirable than CLIENT.
Topic connection factory transport type
DIRECT is the fastest type and should be used where possible. Use
BINDINGS when you want to satisfy additional security tasks and the
queue manager is local to the JMS client. QUEUED is the fallback
for all other cases. WebSphere MQ 5.3 before CSD2 with the
DIRECT setting can lose messages when used with message-driven
beans and under load. This loss also happens with client-side
applications unless the broker maxClientQueueSize is set to 0. You
can set this to 0 with the command (shown here on 2 lines for
publication):
#wempschangeproperties WAS_nodeName_server1 -e default -o
DynamicSubscriptionEngine -n
maxClientQueueSize -v 0 -x executionGroupUUID

where executionGroupUUID can be found by starting the broker and

looking in the Event Log/Applications for event 2201. This value is
usually ffffffff-0000-0000-000000000000.

Client ID:

The JMS client identifier used for connections to the MQSeries queue manager.

Data type String

CCSID:

The coded character set identifier for use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

Data type String

For more information about supported CCSIDs, and about converting between message data from one
coded character set to another, see the WebSphere MQ System Administration and the WebSphere MQ
Application Programming Reference books. These references are available from the WebSphere MQ
Chapter 8. Developing WebSphere applications 1119
messaging multiplatform and platform-specific books Web pages; for example, at http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications Center, or
from the WebSphere MQ collection kit, SK2T-0730.

Message Retention:

Select this check box to specify that unwanted messages are to be left on the queue. Otherwise,
unwanted messages are handled according to their disposition options.

Data type Enum

Units Not applicable
Default Cleared
Range Selected
Unwanted messages are left on the queue.
Cleared
Unwanted messages are handled according to their disposition
options.

Temporary model:

The name of the model definition used to create temporary connection factories if a connection factory
does not already exist.

Data type String

Range 1 through 48 ASCII characters

Temporary queue prefix:

The prefix used for dynamic queue naming.

Data type String

Fail if quiesce:

Specifies whether applications return from a method call if the queue manager has entered a controlled
failure.

Data type Check box

Default Selected

Local Server Address:

Specifies the local server address.

Data type String

Polling Interval:

Specifies the interval, in milliseconds, between scans of all receivers during asynchronous message
delivery

Data type Integer

Units Milliseconds
Default 5000

1120 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Rescan interval:

Specifies the interval in milliseconds between which a topic is scanned to look for messages that have
been added to a topic out of order.

This interval controls the scanning for messages that have been added to a topic out of order with respect
to a WebSphere MQ browse cursor.

Data type Integer

Units Milliseconds
Default 5000

SSL cipher suite:

Specifies the cipher suite to use for SSL connection to WebSphere MQ.

Set this property to a valid cipher suite provided by your JSSE provider. The value must match the
CipherSpec specified on the SVRCONN channel as the Channel property.

You must set this property, if you set the SSL Peer Name property.

SSL certificate store:

Specifies a list of zero or more Certificate Revocation List (CRL) servers used to check for SSL certificate
revocation. If you specify a value for this property, you must use WebSphere MQ JVM at Java 2 version
1.4.

The value is a space-delimited list of entries of the form:

ldap://hostname:[port]

A single slash (/) follows this value. If port is omitted, the default LDAP port of 389 is assumed. At
connect-time, the SSL certificate presented by the server is checked against the specified CRL servers.
For more information about CRL security, see the section “Working with Certificate Revocation Lists” in the
WebSphere MQ Security book; for example at:
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas012w.htm#IDX2254.

SSL peer name:

For SSL, a distinguished name skeleton that must match the name provided by the WebSphere MQ queue
manager. The distinguished name is used to check the identifying certificate presented by the server at
connection time.

If this property is not set, such certificate checking is performed.

The SSL peer name property is ignored if SSL Cipher Suite property is not specified.

This property is a list of attribute name and value pairs separated by commas or semicolons. For example:
CN=QMGR.*, OU=IBM, OU=WEBSPHERE

The example given checks the identifying certificate presented by the server at connect-time. For the
connection to succeed, the certificate must have a Common Name beginning QMGR., and must have at
least two Organizational Unit names, the first of which is IBM and the second WEBSPHERE. Checking is
not case-sensitive.

Chapter 8. Developing WebSphere applications 1121

For more details about distinguished names and their use with WebSphere MQ, see the section
“Distinguished Names” in the WebSphere MQ Security book.

Connection pool:

Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Data type Check box

Default Selected

WebSphere MQ Provider topic connection factory settings for application clients:

Use this panel to view or change the configuration properties of the selected topic connection factory for
use with the WebSphere MQ product Java Message Service (JMS) provider. These configuration
properties control how connections are created between the JMS provider and WebSphere MQ.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > WebSphere
MQ Provider. Right-click Topic Connection Factories and click New.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ product JMS resources. For more information about configuring WebSphere MQ
product JMS resources, see the WebSphere MQ Using Java book.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.

A topic connection factory for the WebSphere MQ product JMS provider has the following properties.

Name:

The name by which this topic connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the JMS provider.

Data type String

Description:

A description of this topic connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

JNDI Name:

1122 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The Java Naming and Directory Interface (JNDI) name that is used to bind the topic connection factory
into the application server name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Units En_US ASCII characters
Range 1 through 45 ASCII characters

User ID:

The user ID used, with the Password property, for authentication if the calling application does not provide
a userid and password explicitly.

If you specify a value for the User property, you must also specify a value for the Password property.

The connection factory User and Password properties are used if the calling application does not provide
a userid and password explicitly, for example, if the calling application uses the method
createTopicConnection(). The JMS client flows the userid and password to the JMS server.

Data type String

Password:

The password used, with the User ID property, for authentication if the calling application does not provide
a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

Data type String

Re-Enter Password:

Confirms the password.

Queue Manager:

The name of the WebSphere MQ queue manager for this connection factory. Connections created by this
factory connect to that queue manager.

Data type String

Host:

The name of the host on which the WebSphere MQ queue manager runs for client connections only.

Data type String

Range A valid TCP/IP host name

Chapter 8. Developing WebSphere applications 1123

Port:

The TCP/IP port number used for connection to the WebSphere MQ queue manager, for client connection
only.

This port must be configured on the WebSphere MQ queue manager.

Data type Integer

Range A valid TCP/IP port number, configured on the WebSphere
MQ queue manager.

Channel:

The name of the channel used for client connections to the WebSphere MQ queue manager for client
connection only.

Data type String

Range 1 through 20 ASCII characters

Transport Type:

Whether WebSphere MQ client connection or JNDI bindings are used for connection to the WebSphere
MQ queue manager.

Data type Enum

Default BINDINGS
Range CLIENT
WebSphere MQ client connection is used to
connect to the WebSphere MQ queue manager.
BINDINGS
JNDI bindings are used to connect to the
WebSphere MQ queue manager.

Client ID:

The JMS client identifier used for connections to the WebSphere MQ queue manager.

Data type String

CCSID:

The coded character set identifier to be used with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

Data type String

Broker Control Queue:

The name of the broker control queue to which all command messages (except publications and requests
to delete publications) are sent.

Data type String

Units En_US ASCII characters

1124 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range 1 through 48 ASCII characters

Broker Queue Manager:

The name of the WebSphere MQ queue manager that provides the Publisher and Subscriber message
broker.

Data type String

Units En_US ASCII characters
Range 1 through 48 ASCII characters

Broker Publish Queue:

The name of the broker input queue that receives all publication messages for the default stream.

The name of the broker’s input queue (stream queue) that receives all publication messages for the
default stream. Applications can also send requests to delete publications on the default stream to this
queue.

Data type String

Units En_US ASCII characters
Range 1 through 48 ASCII characters

Broker Subscribe Queue:

The name of the broker queue from which nondurable subscription messages are retrieved.

The name of the broker queue from which nondurable subscription messages are retrieved. The
subscriber specifies the name of the queue when it registers a subscription.

Data type String

Units En_US ASCII characters
Range 1 through 48 ASCII characters

Broker CCSubQ:

The name of the broker queue from which nondurable subscription messages are retrieved for a
ConnectionConsumer request. This property applies only for use of the Web container.

Data type String

Units En_US ASCII characters
Range 1 through 48 ASCII characters

Broker Version:

Specifies whether the message broker is provided by the WebSphere MQ MA0C SupportPac or newer
versions of WebSphere family message broker products.

Data type Enum

Default Advanced

Chapter 8. Developing WebSphere applications 1125

Range Advanced
The message broker is provided by newer
versions of WebSphere family message broker
products (MQ Integrator and MQ Publish and
Subscribe).
Basic The message broker is provided by the
WebSphere MQ MA0C SupportPac (WebSphere
MQ - Publish and Subscribe).

Cleanup level:

Specifies the level of clean up provided by the publish or subscribe cleanup utility.

Data type Enum

Default SAFE
Range
ASPROP
NONE
STRONG

Cleanup interval:

Specifies the interval, in milliseconds, between background executions of the publish/subscribe cleanup
utility.

Data type Integer

Units Milliseconds
Default 6000

Message selection:

Specifies where broker message selection is performed.

Data type Enum

Default BROKER
Range
BROKER
Message selection is done at the broker location.
Message CLIENT
Message selection is done at the client location.

Publish acknowledge interval:

The interval, in number of messages, between publish requests that require acknowledgement from the
broker.

Data type Integer

Default 25

Sparse subscriptions:

Enables sparse subscriptions.

1126 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Check box
Default Cleared

Status refresh interval:

The interval, in milliseconds, between transactions to refresh publish or subscribe status.

Data type Integer

Default 6000

Subscription store:

Specifies where WebSphere MQ stores data relating to active JMS subscriptions.

Data type Enum

Default MIGRATE
Range
MIGRATE
QUEUE
BROKER

Multicast:

Specifies whether this connection factory uses multicast transport.

Data type Enum

Default NOT USED
Range
NOT USED
This connection factory does not use multicast
transport.
ENABLED
This connection factory always uses multicast
transport.
ENABLED_IF_AVAILABLE
This connection factory uses multicast transport.
ENABLED_RELIABLE
This connection factory uses reliable multicast
transport.
ENABLED_RELIABLE_IF_AVAILABLE
This connection factory uses reliable multicast
transport if available.

Direct authentication:

Specifies whether to use direct broker authorization.

Data type Enum

Default NONE

Chapter 8. Developing WebSphere applications 1127

Range
NONE Direct broker authorization is not used.
PASSWORD
Direct broker authorization is authenticated with a
password.
CERTIFICATE
Direct broker authorization is authenticated with a
certificates.

Proxy Host Name:

Specifies the host name of a proxy to be used for communication with WebSphere MQ.

Data type String

Proxy Port:

Specifies the port number of a proxy to be used for communication with WebSphere MQ.

Data type Integer

Default 0

Fail if quiesce:

Specifies whether applications return from a method call if the queue manager has entered a controlled
failure.

Data type Check box

Default Selected

Local Server Address:

Specifies the local server address.

Data type String

Polling Interval:

Specifies the interval, in milliseconds, between scans of all receivers during asynchronous message
delivery.

Data type Integer

Units Milliseconds
Default 5000

Rescan interval:

Specifies the interval in milliseconds between which a topic is scanned to look for messages that have
been added to a topic out of order.

This interval controls the scanning for messages that have been added to a topic out of order with respect
to a WebSphere MQ browse cursor.

1128 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Integer
Units Milliseconds
Default 5000

SSL cipher suite:

Specifies the cipher suite to use for SSL connection to WebSphere MQ.

Set this property to a valid cipher suite provided by your JSSE provider. The value must match the
CipherSpec specified on the SVRCONN channel as the Channel property.

You must set this property, if you set the SSL Peer Name property.

SSL certificate store:

Specifies a list of zero or more Certificate Revocation List (CRL) servers used to check for SSL certificate
revocation. If you specify a value for this property, you must use WebSphere MQ JVM at Java 2 version
1.4.

The value is a space-delimited list of entries of the form:

ldap://hostname:[port]

A single slash (/) follows this value. If port is omitted, the default LDAP port of 389 is assumed. At
connect-time, the SSL certificate presented by the server is checked against the specified CRL servers.
For more information about CRL security, see the section “Working with Certificate Revocation Lists” in the
WebSphere MQ Security book; for example at:
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas012w.htm#IDX2254.

SSL peer name:

For SSL, a distinguished name skeleton that must match the name provided by the WebSphere MQ queue
manager. The distinguished name is used to check the identifying certificate presented by the server at
connection time.

If this property is not set, such certificate checking is performed.

The SSL peer name property is ignored if SSL Cipher Suite property is not specified.

This property is a list of attribute name and value pairs separated by commas or semicolons. For example:
CN=QMGR.*, OU=IBM, OU=WEBSPHERE

The example given checks the identifying certificate presented by the server at connect-time. For the
connection to succeed, the certificate must have a Common Name beginning QMGR., and must have at
least two Organizational Unit names, the first of which is IBM and the second WEBSPHERE. Checking is
not case-sensitive.

For more details about distinguished names and their use with WebSphere MQ, see the section
“Distinguished Names” in the WebSphere MQ Security book.

Connection pool:

Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

Chapter 8. Developing WebSphere applications 1129

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Data type Check box

Default Selected

Related tasks
“Configuring new JMS providers with the Application Client Resource Configuration Tool” on page 1091

WebSphere MQ Provider queue destination settings for application clients:

Use this panel to view or change the configuration properties of the selected queue destination for use
with the WebSphere MQ product Java Message Service (JMS) provider.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > WebSphere
MQ Provider. Right-click Queue Destinations and click New. The following fields are displayed on the
General tab.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ product for JMS resources. For more information about configuring WebSphere
MQ product for JMS resources, see the WebSphere MQ Using Java book.
v In WebSphere MQ, names can have a maximum of 48 characters.

A queue for use with the WebSphere MQ product JMS provider has the following properties.

Name:

The name by which the queue is known for administrative purposes within IBM WebSphere Application
Server.

Data type String

Description:

A description of the queue, for administrative purposes.

Data type String

JNDI Name:

The application client run-time environment uses this field to retrieve configuration information.

Persistence:

Whether all messages sent to the destination are persistent, nonpersistent or have their persistence
defined by the application.

Data type Enum

1130 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Default APPLICATION_DEFINED
Range Application defined
Messages on the destination have their
persistence defined by the application that put
them onto the queue.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Persistent
Messages on the destination are persistent.
Nonpersistent
Messages on the destination are not persistent.

Priority:

Whether the message priority for this destination is defined by the application or the Specified priority
property.

Data type Enum

Units Not applicable
Default APPLICATION_DEFINED
Range Application defined
The priority of messages on this destination is
defined by the application that put them onto the
destination.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Specified
The priority of messages on this destination is
defined by the Specified priority property. If you
select this option, you must define a priority on
the Specified priority property.

Specified Priority:

If the Priority property is set to Specified, specify the message priority for this queue, in the range 0
(lowest) through 9 (highest).

Data type Integer

Units Message priority level
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Whether the expiry timeout value for this queue is defined by the application or the by Specified expiry
property or whether messages on the queue never expire (have an unlimited expiry time out).

Data type Enum

Units Not applicable
Default APPLICATION_DEFINED

Chapter 8. Developing WebSphere applications 1131

Range Application defined
The expiry timeout for messages on this queue is
defined by the application that put them onto the
queue.
Specified
The expiry timeout for messages on this queue is
defined by the Specified expiry property. If you
select this option, you must define a timeout on
the Specified expiry property.
Unlimited
Messages on this queue have no expiry timeout
and those messages never expire.

Specified Expiry:

If the Expiry timeout property is set to Specified, type here the number of milliseconds (greater than 0)
after which messages on this queue expire.

Data type Integer

Units Milliseconds
Range Greater than or equal to 0
v 0 indicates that messages never time out
v Other values are an integer number of milliseconds

Base Queue Name:

The name of the queue to which messages are sent, on the queue manager specified by the Base queue
manager name property.

Data type String

Base Queue Manager Name:

The name of the WebSphere MQ queue manager to which messages are sent.

This queue manager provides the queue specified by the Base queue name property.

Data type String

Units En_US ASCII characters
Range A valid WebSphere MQ Queue Manager name, as 1
through 48 ASCII characters

CCSID:

The coded character set identifier to use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSID identifier supported by WebSphere
MQ queue manager.

Data type String

Integer encoding:

If native encoding is not enabled, select whether integer encoding is normal or reversed.

1132 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Enum
Default NORMAL
Range NORMAL
Normal integer encoding is used.
REVERSED
Reversed integer encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Decimal encoding:

Indicates that if native encoding is not enabled to select whether decimal encoding is normal or reversed.

Data type Enum

Default NORMAL
Range NORMAL
Normal decimal encoding is used.
REVERSED
Reversed decimal encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Floating point encoding:

Indicates that if native encoding is not enabled to select the type of floating point encoding.

Data type Enum

Default IEEENORMAL
Range IEEENORMAL
IEEE normal floating point encoding is used.
IEEEREVERSED
IEEE reversed floating point encoding is used.
S390 S390 floating point encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Native encoding:

Indicates that the queue destination use native encoding (appropriate encoding values for the Java
platform) when you select this check box.

Data type Enum

Default Cleared
Range Cleared
Native encoding is not used, so specify the
following properties for integer, decimal and
floating point encoding.
Selected
Native encoding is used (to provide appropriate
encoding values for the Java platform).

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Chapter 8. Developing WebSphere applications 1133

Target client:

Whether the receiving application is JMS-compliant or is a traditional WebSphere MQ application.

Data type Enum

Default WebSphere MQ
Range WebSphere MQ
The target is a traditional WebSphere MQ
application that does not support JMS.
JMS The target application supports JMS.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

WebSphere MQ Provider topic destination settings for application clients:

Use this panel to view or change the configuration properties of the selected topic destination for use with
the WebSphere MQ product Java Message Service (JMS) provider.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > WebSphere
MQ Provider. Right click Topic Destinations, and click New. The following fields are displayed on the
General tab.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ product JMS resources. For more information about configuring WebSphere MQ
product JMS resources, see the WebSphere MQ Using Java book.
v In WebSphere MQ, names can have a maximum of 48 characters.

A topic destination is used to configure the properties of a JMS topic for the associated JMS provider. A
topic for use with the WebSphere MQ product JMS provider has the following properties.

Name:

The name by which the topic is known for administrative purposes.

Data type String

Description:

A description of the topic for administrative purposes within IBM WebSphere Application Server.

JNDI Name:

The application client run time uses this field to retrieve configuration information.

Persistence:

1134 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies whether all messages sent to the destination are persistent, nonpersistent, or have their
persistence defined by the application.

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
Messages on the destination have their
persistence defined by the application that put
them in the queue.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Persistent
Messages on the destination are persistent.
Nonpersistent
Messages on the destination are not persistent.

Priority:

Specifies whether the message priority for this destination is defined by the application or the Specified
priority property.

Data type Enum

Default APPLICATION_DEFINED
Range Application defined
The priority of messages on this destination is
defined by the application that put them in the
destination.
Queue defined
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
Specified
The priority of messages on this destination is
defined by the Specified priority property. If you
select this option, you must define a priority for
the Specified priority property.

Specified Priority:

If the Priority property is set to Specified, type the message priority for this queue, in the range 0 (lowest)
through 9 (highest).

If the Priority property is set to Specified, messages sent to this queue have the priority value specified
by this property.

Data type Integer

Units Message priority level
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Whether the expiry timeout for this queue is defined by the application or by the Specified expiry property
or by messages on the queue never expire (have an unlimited expiry timeout).

Chapter 8. Developing WebSphere applications 1135

Data type Enum
Default APPLICATION_DEFINED
Range Application defined
The expiry timeout for messages on this queue is
defined by the application that put them in the
queue.
Specified
The expiry timeout for messages in this queue is
defined by the Specified expiry property. If you
select this option, you must define a timeout
value for the Specified expiry property.
Unlimited
Messages on this queue have no expiry timeout,
and these messages never expire.

Specified Expiry:

If the Expiry timeout property is set to Specified, type the number of milliseconds (greater than 0) after
which messages on this queue expire.

Data type Integer

Units Milliseconds
Range Greater than or equal to 0
v 0 indicates that messages never time out.
v Other values are an integer number of milliseconds.

Base Topic Name:

The name of the topic to which messages are sent.

Data type String

CCSID:

The coded character set identifier to use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSID identifiers that WebSphere MQ
supports.

Data type String

Integer encoding:

Indicates whether integer encoding is normal or reversed when native encoding is not enabled.

Data type Enum

Default NORMAL
Range NORMAL
Normal integer encoding is used.
REVERSED
Reversed integer encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

1136 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Decimal encoding:

If native encoding is not enabled, select whether decimal encoding is normal or reversed.

Data type Enum

Default NORMAL
Range NORMAL
Normal decimal encoding is used.
REVERSED
Reversed decimal encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Floating point encoding:

Indicates the type of floating point encoding when native encoding is not enabled.

Data type Enum

Default IEEENORMAL
Range IEEENORMAL
IEEE normal floating point encoding is used.
IEEEREVERSED
IEEE reversed floating point encoding is used.
S390 S/390 floating point encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Native encoding:

Indicates that the queue destination uses native encoding (appropriate encoding values for the Java
platform) when you select this check box.

Data type Enum

Default Cleared
Range Cleared
Native encoding is not used, so specify the
previous properties for integer, decimal and
floating point encoding.
Selected
Native encoding is used (to provide appropriate
encoding values for the Java platform).

For more information about encoding properties, see the

WebSphere MQ Using Java document.

BrokerDurSubQueue:

The name of the broker queue from which durable subscription messages are retrieved.

The subscriber specifies the name of the queue when it registers a subscription.

Data type String

Units En_US ASCII characters
Range 1 through 48 ASCII characters

Chapter 8. Developing WebSphere applications 1137

BrokerCCDurSubQueue:

The name of the broker queue from which durable subscription messages are retrieved for a
ConnectionConsumer. This property applies only for use of the Web container.

Data type String

Units En_US ASCII characters
Range 1 through 48 ASCII characters

Target Client:

Specifies whether the receiving application is JMS compliant or is a traditional WebSphere MQ application.

Data type Enum

Default WebSphere MQ
Range WebSphere MQ
The target is a traditional WebSphere MQ
application that does not support JMS.
JMS The target is a JMS compliant application.

Multicast:

Specifies whether this connection factory uses multicast transport.

Data type Enum

Default AS_CF
Range
AS_CF This connection factory uses multicast transport.
DISABLED
This connection factory does not use multicast
transport.
NOT_RELIABLE
This connection factory always uses multicast
transport.
RELIABLE
This connection factory uses multicast transport
when the topic destination is not reliable.
ENABLED
This connection factory uses reliable multicast
transport.

Generic JMS connection factory settings for application clients:

Use this panel to view or change the configuration properties of the selected Java Message Service (JMS)
connection factory for use with the associated JMS provider. These configuration properties control how
connections are created between the JMS provider and the messaging system that it uses.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers >
new_JMS_Provider_instance. Right-click Connection Factories, and click New. The following fields are
displayed on the General tab.

1138 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
A Java Message Service (JMS) connection factory creates connections to JMS destinations. The JMS
connection factory is created by the associated JMS provider. A JMS connection factory for a generic JMS
provider (other than the internal default messaging provider or WebSphere MQ as a JMS provider) has the
following properties:

Name:

The name by which this JMS connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the associated JMS provider.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

JNDI Name:

The application client run time uses this field to retrieve configuration information.

User ID:

Indicates the user ID used with the Password property, for authentication if the calling application does
not provide a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

The connection factory User ID and Password properties are used if the calling application does not
provide a userid and password explicitly; for example, if the calling application uses the method
createQueueConnection(). The JMS client flows the userid and password to the JMS server.

Data type String

Password:

The password used with the User ID property for authentication if the calling application does not provide
a userid and password explicitly.

If you specify a value for the User ID property, you must also specify a value for the Password property.

Data type String

Default Null

Re-Enter Password:

Confirms the password entered in the Password field.

External JNDI Name:

The JNDI name that is used to bind the queue into the application server name space.

Chapter 8. Developing WebSphere applications 1139

As a convention, use the fully qualified JNDI name, for example, jms/Name, where Name is the logical
name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI API by the
platform.

Data type String

Connection Type:

Whether this JMS destination is a queue (for point-to-point) or topic (for publication or subscription).

Select one of the following options:

Queue
A JMS queue destination for point-to-point messaging.
Topic A JMS topic destination for publish subscribe messaging.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Generic JMS destination settings for application clients:

Use this panel to view or change the configuration properties of the selected JMS destination for use with
the associated JMS provider.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Messaging Providers > new JMS
Provider instance. Right-click Destinations, and click New. The following fields are displayed on the
General tab.

A JMS destination is used to configure the properties of a JMS destination for the associated generic JMS
provider. Connections to the JMS destination are created by the associated JMS connection factory. A
JMS destination for use with a generic JMS provider (not the default messaging provider or WebSphere
MQ as a JMS provider) has the following properties.

Name:

The name by which the queue is known for administrative purposes within WebSphere Application Server.

Data type String

Description:

A description of the queue, for administrative purposes.

JNDI Name:

The JNDI name of the actual (physical) name of the JMS destination bound into JNDI.

1140 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
External JNDI Name:

The JNDI name that is used to bind the queue into the application server name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Destination Type:

Whether this JMS destination is a queue (for point-to-point) or topic (for publishing or subscribing).

Select one of the following options:

Queue
A JMS queue destination for point-to-point messaging.
Topic A JMS topic destination for pub/sub messaging.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Example: Configuring JMS provider, JMS connection factory and JMS destination settings for
application clients: The purpose of this article is to help you to configure JMS Provider, JMS
Connection Factory and JMS Destination settings.
v Required fields include:
– JMS Provider Properties page: name, and at least one protocol provider
– JMS Connection Factory Properties page: name, jndiName, destination type
– JMS Destination Properties page: name, jndiName, destination type
v Special cases:
– The destination type must be QUEUE, or TOPIC.
v Example:
<resources.jms:JMSProvider xmi:id="JMSProvider_3" name="genericJMSProvider:name"
description="genericJMSProvider:description"
externalInitialContextFactory="genericJMSProvider:contextFactoryClass"
externalProviderURL="genericJMSProvider:providerUrl">
<classpath>genericJMSProvider:classpath</classpath>
<factories xmi:type="resources.jms:GenericJMSDestination"
xmi:id="GenericJMSDestination_1" name="jmsDestination:name"
jndiName="jmsDestination:jndiName" description="jmsDestination:description"
externalJNDIName="jmsDestination:externalJndiName" type="QUEUE">
<propertySet xmi:id="J2EEResourcePropertySet_15">
<resourceProperties xmi:id="J2EEResourceProperty_17" name="jmsDestination:customName"
value="jmsDestination:customValue"/>
</propertySet>
</factories>
<factories xmi:type="resources.jms:GenericJMSConnectionFactory"
xmi:id="GenericJMSConnectionFactory_1" name="jmsCF:name" jndiName="jmsCF:jndiName"
description="jmsCF:description" userID="jmsCF:user" password="{xor}NTIsHBllMT4yOg=="

Chapter 8. Developing WebSphere applications 1141

externalJNDIName="jmsCF:externalJndiName" type="QUEUE">
<propertySet xmi:id="J2EEResourcePropertySet_16">
<resourceProperties xmi:id="J2EEResourceProperty_18" name="jmsCF:customName"
value="jmsCF:customValue"/>
</propertySet>
</factories>
<propertySet xmi:id="J2EEResourcePropertySet_17">
<resourceProperties xmi:id="J2EEResourceProperty_19"
name="genericJMSProvider:customName" value="genericJMSProvider:customValue"/>
</propertySet>
</resources.jms:JMSProvider>

Configuring new JMS connection factories for application clients

Use this task to create a new Java Message Service (JMS) connection factory configuration for your
application client.
1. Click the JMS provider for which you want to create a connection factory in the tree. Complete one of
the following actions:
v Configure a new JMS provider.
v Click an existing JMS provider.
2. Expand the JMS provider to view its JMS Connection Factories folder.
3. Click the connection factory folder, and complete one of the following actions:
v Right-click the folder and selectNew Factory.
v Click Edit > New on the menu bar.
4. Configure the JMS connection factory properties in the displayed fields.
5. Click OK when you finish.
6. Click File > Save on the menu bar to save your changes.

Configuring new Java Message Service destinations for application clients

Use this task to create a new Java Message Service (JMS) destination configuration for your application
client.
1. Click the JMS provider in the tree for which you want to create a destination. Complete one of the
following actions:
v Configure a new JMS provider.
v Click an existing JMS provider.
2. Expand the JMS provider to view its JMS Destinations folder.
3. Click the provider folder, and complete one of the following actions:
v Right-click the folder and select New.
v Click Edit > New on the menu bar.
4. Configure the JMS destination properties in the displayed fields.
5. Click OK when you finish.
6. Click File > Save on the menu bar to save your changes.

Example: Configuring MQ Queue and Topic connection factories and destination

factories for application clients
The purpose of this article is to help you configure MQ Queue connection factory, MQ Topic connection
factory, MQ Queue destination factory, and MQ Topic destination factory settings.
v Required fields:
– MQ Queue Connection Factory Properties page: name, jndiName and transport type
– MQ Topic Connection Factory Properties page: name, jndiName and broker Version
– MQ Queue Factory Properties page: name, jndiName, persistence, priority, expiry, baseQueueName
and targetClient
– MQ Topic Factory Properties page: name, jndiName, persistence, priority, expiry, baseQueueName
and targetClient
v Special cases:
– The transport type must be CLIENT, or BINDINGS.

1142 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 – The Broker Version must be MA0C, or MQSI.
– The port must be a numerical value between -2417483648 and 2417483647.
– The CCSID must be a numerical value between -2417483648 and 2417483647.
– The persistence value must be APPLICATION_DEFINED, QUEUE_DEFINED, PERSISTENT or, NONPERSISTENT.
– The priority must be APPLICATION_DEFINED, QUEUE_DEFINED, or SPECIFIED.
– The expiry must be APPLICATION_DEFINED, UNLIMITED, or SPECIFIED.
– The integer encoding must be Normal, or Reversed.
– The decimal encoding must be Normal, or Reversed.
– The floating encoding must be IEEENormal, IEEEReversed or S390.
– The target client must be JMS or MQ.
– On the MQ Queue Connection Factory Properties page, only set the queueManager, host, and port
values. These are required fields if the transport type is CLIENT.
– On the MQ Topic Connection Factory Properties page, only set the queueManager, host, and port
(required) fields if the transport type is CLIENT.
– On the MQ Topic Factory Properties, and the MQ Queue Factory Properties pages, only set the
Integer encoding, decimal encoding, and floating point encoding (required) fields if you do not set the
nativeEncoding value.
– On the MQ Topic Factory Properties and the MQ Queue Factory Properties pages, the specified
priority entry field must be an integer between 0 and 9 if priority is set to SPECIFIED .
– On the MQ Topic Factory Properties and the MQ Queue Factory Properties pages, the specified
expiry entry field must be a value greater than 0 if the expiry value is set to SPECIFIED.
v Example:
<resources.jms:JMSProvider xmi:id="JMSProvider_1" name="MQ JMS Provider"
description="mqJMSProvider:description"
externalInitialContextFactory="mqJMSProvider:contextFactoryClass"
externalProviderURL="mqJMSProvider:providerUrl">
<classpath>mqJMSProvider:classpath</classpath>
<factories xmi:type="resources.jms.mqseries:MQQueueConnectionFactory"
xmi:id="MQQueueConnectionFactory_1" name="mqQCF:name" jndiName="mqQCF:jndiName"
description="mqQCF:description" userID="mqQCF:user" password="{xor}Mi4OHBllMT4yOg=="
queueManager="mqQCF:queueManager" host="mqQCF:host" port="1" channel="mqQCF:channel"
transportType="CLIENT" clientID="mqQCF:clientId" CCSID="2">
<propertySet xmi:id="J2EEResourcePropertySet_3">
<resourceProperties xmi:id="J2EEResourceProperty_3" name="mqQCF:customName"
value="mqQCF:customValue"/>
</propertySet>
</factories>
<factories xmi:type="resources.jms.mqseries:MQTopicConnectionFactory"
xmi:id="MQTopicConnectionFactory_1" name="mqTCF:name" jndiName="mqTCF:jndiName"
description="mqTCF:description" userID="mqTCF:user"
password="{xor}Mi4LHBllNTE7NhE+Mjo=" host="mqTCF:host" port="1"
transportType="CLIENT" channel="mqTCF:channel" queueManager="mqTCF:queueManager"
brokerControlQueue="mqTCF:brokerControlQueue"
brokerQueueManager="mqTCF:brokerQueueManager" brokerPubQueue="mqTCF:brokerPubQueue"
brokerSubQueue="mqTCF:brokerSubQueue" brokerCCSubQ="mqTCF:brokerCCSubQ"
brokerVersion="MA0C" clientID="mqTCF:clientId" CCSID="2">
<propertySet xmi:id="J2EEResourcePropertySet_4">
<resourceProperties xmi:id="J2EEResourceProperty_4" name="mqTCF:customName"
value="mqTCF:customValue"/>
</propertySet>
</factories>
<factories xmi:type="resources.jms.mqseries:MQQueue" xmi:id="MQQueue_1" name="mqQ:name"
jndiName="mqQ:jndiName" description="mqQ:description" persistence="APPLICATION_DEFINED"
priority="SPECIFIED" specifiedPriority="1" expiry="SPECIFIED" specifiedExpiry="1"
baseQueueName="mqQ:baseQueueName" baseQueueManagerName="mqQ:baseQueueManagerName"
CCSID="1" integerEncoding="Normal" decimalEncoding="Normal"
floatingPointEncoding="IEEENormal" targetClient="JMS">
<propertySet xmi:id="J2EEResourcePropertySet_5">
<resourceProperties xmi:id="J2EEResourceProperty_5" name="mqQ:customName"
value="mqQ:customValue"/>
</propertySet>
</factories>

Chapter 8. Developing WebSphere applications 1143

<factories xmi:type="resources.jms.mqseries:MQTopic" xmi:id="MQTopic_1"
name="mqT:name" jndiName="mqT:jndiName" description="mqT:description"
persistence="APPLICATION_DEFINED" priority="SPECIFIED" specifiedPriority="1"
expiry="SPECIFIED" specifiedExpiry="2" baseTopicName="mqT:baseTopicName" CCSID="3"
integerEncoding="Normal" decimalEncoding="Normal" floatingPointEncoding="IEEENormal"
targetClient="JMS" brokerDurSubQueue="mqT:brokerDurSubQueue"
brokerCCDurSubQueue="mqT:brokerCCDurSubQueue">
<propertySet xmi:id="J2EEResourcePropertySet_6">
<resourceProperties xmi:id="J2EEResourceProperty_6" name="mqT:customName"
value="mqT:customValue"/>
</propertySet>
</factories>
<propertySet xmi:id="J2EEResourcePropertySet_7">
<resourceProperties xmi:id="J2EEResourceProperty_7" name="mqJMSProvider:customName"
value="mqJMSProvider:customValue"/>
</propertySet>
</resources.jms:JMSProvider>

Example: Configuring WAS Queue and Topic connection factories and destination
factories for application clients
The purpose of this article is to help you configure Queue connection factory, Topic connection factory,
Queue destination factory, and Topic destination factory settings.
v Required fields include:
– Java Message Service (JMS) Provider Properties page: name
– WebSphere Application Server Queue Connection Factory Properties page: name, jndiName and
node
– WebSphere Application Server Topic Connection Factory Properties page: name, jndiName, node
and port
– WebSphere Application Server Queue Factory Properties page: name, jndiName, node, persistence,
priority and expiry
– WebSphere Application Server Topic Factory Properties page: name, jndiName, topic name,
persistence, priority and expiry
v Special cases:
– The port value must be QUEUED or DIRECT.
– The CCSID must be a numerical value between -2417483648 and 2417483647.
– The persistence value must be APPLICATION_DEFINED, PERSISTENT, or NONPERSISTENT.
– The priority value must be APPLICATION_DEFINED, or SPECIFIED.
– The expiry value must be APPLICATION_DEFINED, UNLIMITED, or SPECIFIED.
– On the WAS Topic Factory Properties, and the WAS Queue Factory Properties pages, the specified
priority entry field must be an integer between 0 and 9, if the priority value is set to SPECIFIED .
– On the WAS Topic Factory Properties, and the WAS Queue Factory Properties pages, the specified
expiry entry field must be a value greater than 0 if expiry is set to SPECIFIED.
v Example:
<resources.jms:JMSProvider xmi:id="JMSProvider_2" name="WebSphere JMS Provider"
description="wasJMSProvider:description"
externalInitialContextFactory="wasJMSProvider:contextfactoryclass"
externalProviderURL="wasJMSProvider:providerURL">
<classpath>wasJMSProvider:classpath</classpath>
<factories xmi:type="resources.jms.internalmessaging:WASQueueConnectionFactory"
xmi:id="WASQueueConnectionFactory_1" name="wasQCF:name" jndiName="wasQCF:jndiName"
description="wasQCF:description" userID="wasQCF:user" password="{xor}KD4sDhwZZSosOi0="
node="wasQCF:Node">
<propertySet xmi:id="J2EEResourcePropertySet_8">
<resourceProperties xmi:id="J2EEResourceProperty_8" name="wasQCF:customName"
value="wasQCF:customValue"/>
</propertySet>
</factories>
<factories xmi:type="resources.jms.internalmessaging:WASTopicConnectionFactory"
xmi:id="WASTopicConnectionFactory_1" name="wasTCF:name" jndiName="wasTCF:jndiName"
description="wasTCF:description" userID="wasTCF:user" password="{xor}KD4sCxwZZTE+Mjo="
node="wasTCF:node" port="QUEUED" clientID="wasTCF:clientId">
<propertySet xmi:id="J2EEResourcePropertySet_9">

1144 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
<resourceProperties xmi:id="J2EEResourceProperty_9" name="wasTCF:customName"
value="wasTCF:customValue"/>
</propertySet>
</factories>
<factories xmi:type="resources.jms.internalmessaging:WASQueue" xmi:id="WASQueue_1"
name="wasQ:name" jndiName="wasQ:jndiName" description="wasQ:description"
node="wasQ:node" persistence="APPLICATION_DEFINED" priority="SPECIFIED"
specifiedPriority="1" expiry="SPECIFIED" specifiedExpiry="1">
<propertySet xmi:id="J2EEResourcePropertySet_10">
<resourceProperties xmi:id="J2EEResourceProperty_10" name="wasQ:customName"
value="wasQ:customValue"/>
</propertySet>
</factories>
<factories xmi:type="resources.jms.internalmessaging:WASTopic" xmi:id="WASTopic_1"
name="wasT:name" jndiName="wasT:jndiName" description="wasT:description"
topic="wasT:topicName" persistence="APPLICATION_DEFINED" priority="SPECIFIED"
specifiedPriority="1" expiry="SPECIFIED" specifiedExpiry="1">
<propertySet xmi:id="J2EEResourcePropertySet_11">
<resourceProperties xmi:id="J2EEResourceProperty_11" name="wasT:customName"
value="wasT:customValue"/>
</propertySet>
</factories>
<propertySet xmi:id="J2EEResourcePropertySet_12">
<resourceProperties xmi:id="J2EEResourceProperty_12" name="wasJMSProvider:customName"
value="wasJMSProvider:customValue"/>
</propertySet>
</resources.jms:JMSProvider>

Configuring new resource environment providers for application clients

During this task, you create new resource environment provider configurations for your application client.

To configure a new resource environment provider, perform the following steps:

1. Start the Application Configuration Resource Tool and open the EAR file for which you want to
configure the new Java Message Service (JMS) provider. The EAR file contents display in a tree view.
2. Select from the tree the JAR file in which you want to configure the new JMS provider.
3. Expand the JAR file to view its contents.
4. Click the Resource Environment Providers folder. Take one of the following actions:
v Right-click the provider folder, and click New Provider.
v Click Edit > New on the menu bar.
5. Configure the JMS provider properties in the displayed fields.
6. Click OK when you finish.
7. Click File > Save on the menu bar to save your changes.

Resource environment provider settings for application clients:

Use this page to specify resource environment entry properties.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected Java Archive (JAR) file. Right-click Resource
Environment Providers, and click New. The following fields are displayed on the General tab:

Name:

Specifies the administrative name for the resource environment provider.

Description:

Specifies a description of the resource environment provider for your administrative records.

Chapter 8. Developing WebSphere applications 1145

Class Path:

Specifies the path to the JAR file that contains the implementation classes for the resource environment
provider.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Configuring new resource environment entries for application clients

During this task, you create new resource environment entries for your client application.
1. Start the Application Client Resource Configuration Tool (ACRCT).
2. Open the EAR file for which you want to configure the new resource environment entry. The EAR file
contents are in the displayed tree view.
3. Click the desired resource environment provider, and complete the following action to configure new
providers:
v Configure a new resource environment provider.
4. Expand the resource environment provider to view the Resource Environment Entries folder.
5. Click the resource environment entries folder, and complete one of the following actions:
v Right-click the folder and select New.
v Click Edit > New on the menu bar.
6. Configure the resource environment entry properties in the displayed fields.
7. Click OK.
8. Click File > Save on the menu bar to save your changes.

Resource environment entry settings for application clients:

Use this page to specify resource environment entry properties.

To view this Application Client Resource Configuration Tool (ACRCT) page, click File > Open. After you
browse for an EAR file, click Open. Expand the selected JAR file > Resource Environment Providers >
resource environment instance. Right-click Resource environment entry, and click New. The following
fields appear on the General tab:

Name:

Specifies the administrative name for the resource environment entry.

Description:

Specifies a description of the URL for your administrative records.

JNDI Name:

Specifies the Java Naming and Directory Interface (JNDI) name for the resource, including any naming
subcontexts.

1146 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Use this name to link to the binding information of the platform. The binding associates the resources
defined in the deployment descriptor of the module to the actual (or physical) resources bound into JNDI
by the platform.

Custom Properties:

Specifies name-value pairs for setting additional properties on the object that is created at run time for this
resource.

You must enter a name that is a public property on the object and a value that can be converted from a
string to the type required by the set method of the property. The acceptable properties and values depend
on the object that is created. Refer to the object documentation for a list of valid properties and values.

Creating locally defined objects for message destination references and message
destinations
After developing an application client, deploy this application on client machines. Deployment consists of
pulling together the various artifacts that the application client requires.

The Application Client Resource Configuration Tool (ACRCT) defines resources for the application client.
These configurations are stored in the application client .ear file. The application client run time uses
these configurations for resolving and creating an instance of the resources for the application client.

Note: This task only applies to J2EE application clients. Only perform this task if you configured your
J2EE application client to use resource references.

When a local object definition is created using the ACRCT, the JNDI name of the local object definition
points to the reference for which the local object definition applies. The object might be a resource-ref,
resource-env-ref or message-destination-ref. If the message-destination-ref has a
message-destination-link, then point the local object definition to the message-destination. Local object
definitions either point to the message-destination-ref (if the message-destination-ref has no link) or to
the message-destination (if the message-destination-ref has a link). Any local object definitions pointing to
message-destination-refs that have a link are ignored.
1. Start an assembly tool such as Application Server Toolkit (AST) or Rational Web Developer, and open
an EAR file. See ″Starting an assembly tool″ in the information center for additional information.
2. Create a locally defined object.
3. Point the object to the appropriate message destination.
4. Save the EAR file.

Managing application clients

Perform the following tasks after deploying application clients. This task only applies to J2EE application
clients.
1. Update data source and data source provider configurations.
2. Update URLs and URL provider configurations.
3. Update mail session configurations.
4. Update JMS provider, connection factories, and destination configurations.
5. Update MQ JMS provider, MQ connection factories and MQ destination configurations.
6. Update Resource Environment Entry and Resource Environment Provider configurations.
7. (Optional) Remove application client resources.

Updating data source and data source provider configurations with the Application Client Resource
Configuration Tool:

Chapter 8. Developing WebSphere applications 1147

During this task, you update the configuration of an existing data source or data source provider. Perform
this task when your database configuration changes.
1. Start the Application Client Resource Configuration Tool (ACRCT), and open the Enterprise Archive
(EAR) file containing the data source or data source provider. The EAR file contents display in a tree
view.
2. Select Java Archive (JAR) file from the navigation tree containing the data source or data source
provider to update.
3. Expand the JAR file to view its contents until you locate the particular data source or data source
provider to update. Take one of the following actions:
v Right-click the data source object and click Properties.
v Click Edit > Properties on the menu bar.
4. Update the properties in the displayed fields. For detailed field help, see:
v Data source provider properties
v Data source properties
5. Click OK when you finish.
6. Click File > Save on the menu bar to save your changes.

Updating URLs and URL provider configurations for application clients:

1. Start the tool and open the Enterprise Archive (EAR) file containing the URL or URL provider. The EAR
file contents are displayed in a tree view.
2. Select from the tree the Java Archive (JAR) file containing the URL or URL provider to update.
3. Expand the JAR file to view its contents.
4. Keep expanding the JAR file contents until you locate the particular URL or URL provider to update.
Take one of the following actions:
a. Right-click the URL object and click Properties.
b. Click Edit > Properties on the menu bar.
5. Update the properties in the displayed fields.
6. Click OK when you finish.
7. Click File > Save on the menu bar to save your changes.

Updating mail session configurations for application clients:

During this task, you update the configuration of an existing JavaMail session. You cannot update the
name of the default JavaMail provider, and you cannot delete the default JavaMail provider from the
navigation tree.
1. Start the tool and open the Enterprise Archive (EAR) file containing the JavaMail session. The EAR file
contents are displayed in the navigation tree view.
2. Select the Java Archive (JAR) file containing the JavaMail session to update from the navigation tree.
3. Expand the JAR file to view its contents.
4. Keep expanding the JAR file contents until you locate the particular JavaMail session to update. Take
one of the following actions:
a. Right-click the object and click Properties
b. Click Edit > Properties from the menu bar.
5. Update the properties in the displayed fields.
6. Click OK when you finish.
7. Select File > Save from the menu bar to save your changes.

Updating Java Message Service provider, connection factories, and destination configurations for
application clients:

1148 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
During this task, you update the configuration of an existing Java Message Service (JMS) provider,
connection factory or destination.
1. Start the tool and open the Enterprise Archive (EAR) file containing the Java Message Service (JMS)
provider, connection factory, or destination. The EAR file contents display in a tree view.
2. Select the Java Archive (JAR) file containing the JMS provider, connection factory, or destination to
update from the navigation tree.
3. Expand the JAR file to view its contents until you locate the particular JMS provider, connection
factory, or destination to update. When you find it, do one of the following actions:
v Right-click the provider, and click Properties.
v Click Edit > Properties on the menu bar.
4. Update the properties in the displayed fields. For detailed field help, see:
v JMS provider properties
v WebSphere Application Server Queue connection factory properties
v WebSphere Application Server Topic connection factory properties
v WebSphere Application Server Queue destination properties
v WebSphere Application Server Topic destination properties
5. Click OK.
6. Click File > Save to save your changes.

Updating WebSphere MQ as a Java Message Service provider, and its JMS resource
configurations, for application clients:

Use this task to update an existing configuration of WebSphere MQ as a Java Message Service (JMS)
provider, and to update the configuration of WebSphere MQ connection factories or WebSphere MQ
destinations.
1. Start the Application Client Resource Configuration Tool (ACRCT).
2. Open the Enterprise Archive (EAR) file containing the WebSphere MQ JMS provider, WebSphere MQ
connection factory, or WebSphere MQ destination. The EAR file contents are displayed in the
navigation tree view.
3. Select the Java Archive (JAR) file containing the JMS provider, connection factory, or destination to
update.
4. Expand the JAR file to view its contents until you locate the particular JMS provider, connection
factory, or destination that you want to update. Complete one of the following actions:
v Right-click the appropriate object and click Properties.
v Click Edit > Properties on the menu bar.
5. Update the properties in the displayed fields. For detailed field help, see:
v JMS provider properties
v MQ Queue connection factory properties
v MQ Topic connection factory properties
v MQ Queue destination properties
v MQ Topic destination properties
6. Click OK.
7. Click File > Save to save your changes.

Updating resource environment entry and resource environment provider configurations for
application clients:

During this task, you update the configuration of an existing resource environment entry or resource
environment provider.
1. Start the tool and open the Enterprise Archive (EAR) file containing the resource environment entry or
resource environment provider. The EAR file contents display in a navigation tree view.

Chapter 8. Developing WebSphere applications 1149

2. Select from the tree the Java Archive (JAR) file containing the resource environment entry or resource
environment provider to update.
3. Expand the JAR file to view its contents until you locate the resource environment entry or resource
environment provider to update. Take one of the following actions:
v Right-click the resource environment object, and click Properties.
v Click Edit > Properties on the menu bar.
4. Update the properties in the displayed fields. For detailed field help, see:
v Resource environment provider properties
v Resource environment entry properties
5. Click OK when you finish.
6. Click File > Save on the menu bar to save your changes.

Example: Configuring Resource Environment settings: The purpose of this topic is to help you configure
Resource Environment settings.
v Required fields:
– Resource Environment Provider page: Name
– Resource Environment Entry page: Name, JNDI Name
v Example:
<resources.env:ResourceEnvironmentProvider xmi:id="ResourceEnvironmentProvider_1"
name="resourceEnvProvider:name" description="resourceEnvProvider:description">
<classpath>resourceEnvProvider:classpath</classpath>
<factories xmi:type="resources.env:ResourceEnvEntry" xmi:id="ResourceEnvEntry_1"
name="resourceEnvEntry:name" jndiName="resourceEnvEntry:jndiName"
description="resourceEnvEntry:description">
<propertySet xmi:id="J2EEResourcePropertySet_20">
<resourceProperties xmi:id="J2EEResourceProperty_22"
name="resourceEnvEntry:customName" value="resourceEnvEntry:customValue"/>
</propertySet>
</factories>
<propertySet xmi:id="J2EEResourcePropertySet_21">
<resourceProperties xmi:id="J2EEResourceProperty_23"
name="resourceEnvProvider:customName" value="resourceEnvProvider:customValue"/>
</propertySet>
</resources.env:ResourceEnvironmentProvider>

Example: Configuring resource environment custom settings for application clients: The purpose of this
topic is to help you configure resource environment custom settings.
v The custom page applies to every resource type. You can specify as many custom names and values
as you need.
v Example:
<propertySet xmi:id="J2EEResourcePropertySet_20">
<resourceProperties xmi:id="J2EEResourceProperty_22"
name="resourceEnvEntry:customName" value="resourceEnvEntry:customValue"/>
</propertySet>

Removing application client resources:

The option to delete an item does not offer a confirmation dialog. As a safeguard, consider saving your
work right before you begin this task. If you change your mind after removing an item, you can close the
EAR file without saving your changes, canceling your deletion. Remember to close the EAR file
immediately after the deletion, or you also lose any unsaved work that you performed since the deletion.

This task only applies to J2EE application clients.

1. Start the Application Client Resource Configuration Tool (ACRCT) and open the Enterprise Archive
(EAR) file from which you want to remove an object. The EAR file contents display in the navigation
tree view. If you already have an EAR file open and have made some changes, click File > Save to
save your work before preceding to delete an object.

1150 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Locate the object that you want to remove in the tree.
3. Right-click the object, and click Delete.
4. Click File > Save.

Web services

Implementing Web services applications

This topic introduces you to using Web services that are based on the Web Services for Java 2 Platform,
Enterprise Edition (J2EE) specification. WebSphere Application Server supports Web services that are
developed and implemented based on Web Services for J2EE. Use Web services when operating across
a variety of platforms, including the J2EE 1.4 and non-J2EE platforms.

Using Web services makes most sense if your application clients are non-J2EE applications, unless you
have J2EE applications spread across the Web. It is recommended that you use J2EE technologies if all
your clients are J2EE applications because performance can decrease when you use a Web service in a
J2EE exclusive environment.

Decide if a Web service implementation benefits your business process.

Implementing Web services applications is an easy way to integrate application systems together within or
outside your company’s infrastructure that otherwise function as a standalone systems. For example, your
customer information database is a standalone application, but you want your accounting application to be
able to access the customer data. You can create a web service for the customer database and then
enable the accounting application as Web service client. Now, the accounting application can access the
customer information. By implementing a Web service, these two applications can share information in an
efficient manner.

Because Web services are easily applied to existing applications and information technology assets, new
solutions can be deployed quickly and recomposed to address new opportunities. As Web services
become more popular, the pool of services grows, promoting development of more robust models of
just-in-time application and business integration over the Internet.

Use Web services applications with WebSphere Application Server by following the steps provided:
1. Plan to use Web services. Review the Universal Description, Discovery, and Integration (UDDI) and
Web services enablement of the service integration bus (SIBWS) concepts to learn how these
components can make your Web services plan more robust.
2. (Optional) Migrate existing Web services.
If you have used Web services based on Apache SOAP and now want to develop and implement
Web services based on the Web Services for J2EE specification, you need to migrate client
applications developed with all versions of 4.0, and versions of 5.0 prior to 5.0.2.
3. Deploying Web services
This topic is a good starting point in learning about how to develop a J2EE Web service.
4. Configure Web services deployment descriptors
You need to configure the deployment descriptors so that WebSphere Application Server can process
the incoming Web services requests.
5. Assemble Web services.
This topic presents what you need to assemble a Web service and in what order you should
assemble the parts, for example an enterprise archive (EAR) file.
6. Deploy Web services.
This topic presents the steps necessary to deploy the EAR file that has been configured and enabled
for Web services.

Chapter 8. Developing WebSphere applications 1151

 7. Configure Web service client bindings. This topic explains how to edit bindings for a Web service after
these bindings are deployed on a server. When one Web service communicates with another Web
service, you must configure the client bindings to access the downstream Web service.
8. Publish the WSDL file. Refer to ″Publishing the WSDL file″ in the information center or in the
Administering applications and their environment PDF.
After installing a Web services application, and optionally modifying the endpoint information, you
might need WSDL files containing the updated endpoint information. This topic presents the steps
necessary to publish the WSDL files so that this information is available.
9. Develop Web services clients.
This topic explains how to develop a Web services client based on the Web Services for J2EE
specification.
10. Secure Web services.
This topic presents the methods used to integrate message-level security into a WebSphere
Application Server environment.
11. Tune Web services.
This topic includes information to help you use the Performance Monitoring Infrastructure (PMI) to
measure the time required to process Web services requests.
12. Troubleshoot Web services.
You can use this topic to learn more about troubleshooting different processes used to develop,
implement and use Web services, including command-line tools, Java compiling errors, client runtime
errors and exceptions, serialization and deserialization errors, and authentication challenges and
authorization failures with Web services security.

The following example illustrates how a business might use Web services.

The owner of a flower shop wants to start receiving orders from customers through the Web. This owner
starts the process by finding wholesale flower suppliers, pricing the product, and completing contracts for
future flower orders.

Using Web services, the flower shop owner can find wholesale flower suppliers. One way to find new
suppliers is to use a Universal Description, Discovery and Integration (UDDI) registry to search for
potential suppliers. When the suppliers are chosen, the registry sends back information on how to contact
the flower distributors that meet the flower shop owner’s criteria.

The flower shop owner can request price lists from each of the suppliers by obtaining a Web Services
Description Language (WSDL) file for each potential supplier. The WSDL can be downloaded from the
supplier’s Web page, received through e-mail, or retrieved from the supplier’s UDDI registry entry.

The WSDL describes the procedure call. When using WebSphere Application Server, the procedure call is
a Java API for XML-based remote procedure call (JAX-RPC), which retrieves price lists. The WSDL file
also specifies the Universal Resource Locator (URL) where the request is sent.

The flower shop owner now has to compare the prices received back from each supplier, decide which
suppliers to do business with, and make arrangements for future orders to fill. The flower shop can now
sell merchandise through the Web by using Web services to communicate with suppliers for the best
prices and complete the ordering processes. The merchandise price lists need publishing to the Web site
and a mechanism is needed for customers to order flowers.

The Web services clients of the flower supplier are deployed on the flower shop server. When a customer
makes a transaction to purchase flowers through the Web, the order is sent to the supplier through
JAX-RPC. The supplier responds by sending a confirmation with the order number and shipping date. The
suppliers maintain the inventory and the flower shop owner handles billing and customer order
management.

1152 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Similarly, the flower shop catalog can be composed automatically from the catalogs of all the suppliers. If
the supplier ships directly to the customer, the order tracking inquiries can pass directly to the supplier’s
order tracking system. The supplier can also use Web services to send invoices for orders and by the
flower shop to pay the supplier’s invoices. Processes that previously required forms to fill manually, and
fax or mail, can now be done automatically, saving labor costs for both the flower shop and the supplier.

Using Web services is beneficial because a much larger inventory is made available to the flower shop.
No merchandise maintenance overhead exists, but the flower shop can offer their customers products that
they otherwise might not have. Selling flowers through the Web increases capital for the flower shop
without overhead of another store or money invested into additional product.

For a more detailed scenario, see ″Web services scenario: Overview″ in the information center which tells
the story of a fictional online garden supply retailer named Plants by WebSphere and how they
incorporated the Web services concept.

Web services
Web services are self-contained, modular applications that you can describe, publish, locate, and invoke
over a network.

WebSphere Application Server supports Web services that are developed and implemented based on the
Web Services for Java 2 Platform, Enterprise Edition (J2EE) specification.

A typical Web services scenario is a business application requesting a service from another existing
application. The request is processed through a given Web address using SOAP messages over a HTTP,
Java Message Service (JMS) transport or invoked directly as Enterprise JavaBeans (EJB). The service
receives the request, processes it, and returns a response. Examples of a simple Web service include
weather reports or getting stock quotes. The method call is synchronous, that is, it waits until the result is
available. Transaction Web services, supporting quotes, business-to-business (B2B) or business-to-client
(B2C) operations include airline reservations and purchase orders.

Web services can include the actual service or the client that accesses the service.

Web services are Web applications that help you be more flexible in your business processes by
integrating with applications that otherwise do not communicate. The inner-library loan program at your
local library is a good example of the Web services concept and its evolution. The Web service concept
existed even before the term; the concept became widely accepted with the creation of the Internet. Before
the Internet was created, you visited your library, searched the collections and checked out your books. If
you did not find the book that you wanted, the librarian did a search for you by computer or phone and
located the book at a nearby library. The librarian ordered the book for you and you picked it up after it
was delivered to your local library. By incorporating Web services applications, you can streamline your
library visit.

Now, you can search the local library collection and other local libraries at the same time. When other
libraries provide your library with a Web service to search their collection (the service might have been
provided through UDDI), your results yield their resources. Another Web service application might enable
you to check the book out and get it sent to your home. Using Web services applications saves time and
provides a convenience for you, as well as freeing the librarian to do other business tasks.

Web services reflect the service-oriented architecture (SOA) approach to programming. This approach is
based on the idea of building applications by discovering and implementing network-available services, or
by invoking the available applications to accomplish a task. Web services deliver interoperability, for
example, Web services applications provide components created in different programming languages to
work together as if they were created using the same language. Web services rely on existing transport
technologies, such as HTTP, and standard data encoding techniques, such as Extensible Markup
Language (XML), for invoking the implementation.

Chapter 8. Developing WebSphere applications 1153

The key components of Web services include:
v Web Services Description Language (WSDL)
WSDL is the XML-based file that describes the Web service. The Web service request uses this file to
bind to the service.
v SOAP
SOAP is the XML-based protocol that the Web service request uses to invoke the service.
v Universal Description, Discovery and Integration Protocol (UDDI)
UDDI is the registry that hosts the service broker. UDDI is similar to the Yellow Pages in a phone book.

For a more detailed scenario, see ″Web services scenario: Overview″ in the information center, which tells
the story of a fictional online garden supply retailer named Plants by WebSphere, and how this retailer
incorporated the Web services concept.

Web Services for J2EE specification

The Web services for Java 2 Platform, Enterprise Edition (J2EE) specification defines the programming
model and run-time architecture for implementing Web services based on the Java language. Another
name for the Web Services for J2EE specification is the Java Specification Requirements (JSR) 109. The
specification includes open standards for developing and implementing Web services.

Version 6.0 uses Web Services for J2EE 1.1 as the standard for developing and implementing Web
services. Web Services for J2EE 1.1 is one of the Web service APIs available in J2EE 1.4.

The Web Services for J2EE specification focuses on Extensible Markup Language (XML) remote
procedure call (RPC) and the Java language, including representing XML-based interface definitions in the
Java language; Java language definitions in XML-based definition languages, such as SOAP, and
assembling.

The J2EE technology can be integrated with Web services in a variety of ways. J2EE components, for
example, JavaBeans and enterprise beans, can be exposed as Web services. These services can be
accessed by clients written in Java code or by existing Web service clients that are not written in Java
code. J2EE components can also act as Web service clients.

The Web Services for J2EE specification is the preferred platform for Web-based programming because it
provides open standards allowing different types of languages, operating systems and software to
communicate seamlessly through the Internet.

For a Java application to act as Web service client, a mapping between the Web Services Description
Language (WSDL) file and the Java application must exist. The mapping is defined by the Java API for
XML-based RPC (JAX-RPC) specification.

You can use a Java component to implement a Web service by specifying the component interface and
binding information in the WSDL file and designing the application server infrastructure to accept the
service request.

This entire process encompassed is based on the Web Services for J2EE specification.

The specification brings with it the webservices.xml deployment descriptor specifically for Web services.
You are responsible for providing various elements to the deployment descriptor, including:
v Port name
v Port service implementation
v Port service endpoint interface
v Port WSDL definition
v Port QName
v JAX-RPC mapping

1154 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Handlers (optional)
v Servlet mapping (optional)

The Enterprise JavaBeans (EJB) 2.1 specification also states that for a Web service developed from a
session bean, the EJB deployment descriptor, ejb-jar.xml, must contain the service-endpoint element.
The service-endpoint value must be the same as that stated in the webservices.xml deployment descriptor.
To learn more about the EJB 2.1 specification see Enterprise beans: Resources for learning.

To review the entire Web Services for J2EE specification, see Web services: Resources for learning.

JAX-RPC
The Java API for XML-based RPC (JAX-RPC) specification enables you to develop SOAP-based
interoperable and portable Web services and Web service clients. JAX-RPC 1.1 provides core APIs for
developing and deploying Web services on a Java platform and is a required part of the J2EE 1.4
platform. The J2EE 1.4 platform allows you to develop portable Web services. Web services can also be
developed and deployed on J2EE 1.3 containers.

WebSphere Application Server implements JAX-RPC 1.1 standards.

The JAX-RPC standard covers the programming model and bindings for using Web Services Description
Language (WSDL) for Web services in the Java language. JAX-RPC simplifies development of Web
services by shielding you from the underlying complexity of SOAP communication.

On the surface, JAX-RPC looks like another instantiation of remote method invocation (RMI). Essentially,
JAX-RPC allows clients to access a Web service as if the Web service was a local object mapped into the
client’s address space even though the Web service provider is located in another part of the world. The
JAX-RPC is done by using the XML-based protocol SOAP, which typically rides on top of HTTP.

JAX-RPC defines the mappings between the WSDL port types and the Java interfaces, as well as
between Java language and Extensible Markup Language (XML) schema types.

A JAX-RPC Web service can be created from a JavaBean or a enterprise bean implementation. You can
specify the remote procedures by defining remote methods in a Java interface. You only need to code one
or more classes that implement the methods. The remaining classes and other artifacts are generated by
the Web service vendor’s tools. The following is an example of a Web service interface:
package com.ibm.mybank.ejb;
import java.rmi.RemoteException;
import com.ibm.mybank.exception.InsufficientFundsException;
/**
* Remote interface for Enterprise Bean: Transfer
*/
public interface Transfer_SEI extends java.rmi.Remote {
public void transferFunds(int fromAcctId, int toAcctId, float amount)
throws java.rmi.RemoteException;

The interface definition in JAX-RPC must follow specific rules; most of these rules are from RMI with some
additions for JAX-RPC. The following are the rules for defining a JAX-RPC interface:
v The interface must extend java.rmi.Remote just like RMI.
v Methods must throw java.rmi.RemoteException.
v Method parameters cannot be remote references.
v Method parameter must be one of the parameters supported by the JAX-RPC specification. The
following list are examples of method parameters that are supported. For a complete list of method
parameters see the JAX-RPC specification.
– Primitive types: boolean, byte, double, float, short, int and long

Chapter 8. Developing WebSphere applications 1155

 – Object wrappers of primitive types: java.lang.Boolean, java.lang.Byte, java.lang.Double,
java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short
– java.lang.String
– java.lang.BigDecimal
– java.lang.BigInteger
– java.lang.Calendar
– java.lang.Date
v Methods can take value objects which consist of a composite of the types previously listed, in addition
to aggregate value objects.

A client creates a stub and invokes methods on it. The stub acts like a proxy for the Web service. From
the client code perspective, it seems like a local method invocation. However, each method invocation gets
marshaled to the remote server. Marshaling includes encoding the method invocation in XML as
prescribed by the SOAP protocol.

The following are key classes and interfaces needed to write Web services and Web service clients:
v Service interface: A factory for stubs or dynamic invocation and proxy objects used to invoke methods
v ServiceFactory class: A factory for Services.
v loadService
The loadService method is provided in WebSphere Application Server Version 6.0 to generate the
service locator which is required by a JAX-RPC implementation. If you recall, in previous versions there
was no specific way to acquire a generated service locator. For managed clients you used a JNDI
method to get the service locator and for non-managed clients, you were required to instantiate IBM’s
specific service locator ServiceLocator service=new ServiceLocator(...); which does not offer
portability. The loadService parameters include:
– wsdlDocumentLocation: A URL for the WSDL document location for the service or null.
– serviceName: A qualified name for the service
– properties: A set of implementation-specific properties to help locate the generated service
implementation class.
v isUserInRole
The isUserInRole method returns a boolean indicating whether the authenticated user for the current
method invocation on the endpoint instance is included in the specified logical role.
– role: The role parameter is a String specifying the name of the role.
v Service
v Call interface: Used for dynamic invocation
v Stub interface: Base interface for stubs

If you are using a stub to access the Web service provider, most of the JAX-RPC API details are hidden
from you. The client creates a ServiceFactory (java.xml.rpc.ServiceFactory). The client instantiates a
Service (java.xml.rpc.Service) from the ServiceFactory. The service is a factory object that creates the
port. The port is the remote service endpoint interface to the Web service. In the case of DII, the Service
object is used to create Call objects, which you can configure to call methods on the Web service’s port.

To learn more about JAX-RPC see Web services: Resources for learning.

SOAP
Simple Object Access Protocol (SOAP) is a specification for the exchange of structured information in a
decentralized, distributed environment. As such, it represents the main way of communication between the
three key actors in a service oriented architecture (SOA): service provider, service requestor and service
broker. The main goal of its design is to be simple and extensible. A SOAP message is used to request a
Web service.

1156 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WebSphere Application Server follows the standards outlined in SOAP 1.1.

SOAP was submitted to the World Wide Web Consortium (W3C) as the basis of the Extensible Markup
Language (XML) Protocol Working Group by several companies, including IBM and Lotus. This protocol
consists of three parts:
v An envelope that defines a framework for describing message content and processing instructions.
v A set of encoding rules for expressing instances of application-defined data types.
v A convention for representing remote procedure calls and responses.

SOAP is a protocol-independent transport and can be used in combination with a variety of protocols. In
Web services that are developed and implemented with WebSphere Application Server, SOAP is used in
combination with HTTP, HTTP extension framework, and Java Message Service (JMS). SOAP is also
operating-system independent and not tied to any programming language or component technology.

As long as the client can issue XML messages, it does not matter what technology is used to implement
the client. Similarly, the service can be implemented in any language, as long as the service can process
SOAP messages. Also, both server and client sides can reside on any suitable platform.

For more information about SOAP, see Web services: Resources for learning.

SOAP with Attachments API for Java

SOAP with Attachments API for Java (SAAJ) is used for SOAP messaging that works behind the scenes in
the Java API for XML-based RPC (JAX-RPC) implementation.

Web services uses SOAP messages to represent remote procedure calls between the client and the
server. In normal JAX-RPC flows, the SOAP message is deserialized into a series of Java value type
business objects that represent the parameters and return values. In addition, JAX-RPC provides APIs that
support applications and handlers to manipulate the SOAP message directly. The SOAP message is
manipulated using the SAAJ data model. The primary interface in the SAAJ model is
javax.xml.soap.SOAPElement.

WebSphere Application Server uses SAAJ Version 1.2. The main benefit of SAAJ Version 1.2 is that the
model extends the Document Object Model (DOM) model. The DOM model is used by applications that
manipulate XML. Using this model applications are able to process an SAAJ model that uses pre-existing
DOM code. It is also easier to convert pre-existing DOM objects to SAAJ objects.

Messages created using SAAJ follow SOAP standards. A SOAP message is represented in the SAAJ
model as a javax.xml.soap.SOAPMessage object. The XML content of the message is represented by a
javax.xml.soap.SOAPPart object. Each SOAP part has a SOAP envelope. This envelope is represented by
the SAAJ javax.xml.SOAPEnvelope object. The SOAP specification defines various elements that reside in
the SOAP envelope; SAAJ defines objects for the various elements in the SOAP envelope.

The SOAP message can also contain non-XML data that is called attachments. These attachments are
represented by SAAJ AttachmentPart objects that are accessible from the SOAPMessage object.

A number of reasons exist as to why handlers and applications use the generic SOAPElement API instead
of a tightly bound mapping:
v The Web service might be a conduit to another Web service. In this case, the SOAP message is only
forwarded.
v The Web service might manipulate the message using a different data model, for example a Service
Data Object (SDO). It is easier to convert the message from a SAAJ Document Object Model (DOM) to
a different data model.
v A handler, for example, a digital signature validation handler, might want to manipulate the message
generically.

Chapter 8. Developing WebSphere applications 1157

To review the entire SAAJ API, see Web services: Resources for learning.

Web Services-Interoperability Basic Profile

The Web Services-Interoperability (WS-I) Basic Profile is a set of non-proprietary Web services
specifications that promote interoperability.

WebSphere Application Server conforms to the WS-I Basic Profile 1.1.

The WS-I Basic Profile is governed by a consortium of industry-leading corporations, including IBM, under
direction of the WS-I Organization. The profile consists of a set of principles that relate to bringing about
open standards for Web services technology. All organizations that are interested in promoting
interoperability among Web services are encouraged to become members of the Web Services
Interoperability Organization.

Several technology components are used in the composition and implementation of Web services,
including messaging, description, discovery, and security. Each of these components are supported by
specifications and standards, including SOAP 1.1, Extensible Markup Language (XML) 1.0, HTTP 1.1,
Web Services Description Language (WSDL) 1.1, and Universal Description, Discovery and Integration
(UDDI). The WS-I Basic Profile specifies how these technology components are used together to achieve
interoperability, and mandates specific use of each of the technologies when appropriate. You can read
more about the WS-I Basic Profile at the WS-I Organization Web site. A link to this Web site is listed in
Web services: Resources for learning.

Each of the technology components have requirements that you can read about in more detail at the WS-I
Organization Web site. For example, support for Universal Transformation Format (UTF)-16 encoding is
required by WS-I Basic Profile. UTF-16 is a kind of Unicode encoding scheme using 16-bit values to store
Universal Character Set (UCS) characters. UTF-8 is the most common encoding that is used on the
Internet; UTF-16 encoding is typically used for Java and Windows product applications; and UTF-32 is
used by various Linux and Unix systems. Unlike UTF-8, UTF-16 has issues with big-endian and
little-endian, and often involves Byte Order Mark (BOM) to indicate the endian. BOM is mandatory for
UTF-16 encoding and it can be used in UTF-8.

See how to modify your encoding from UTF-8 to UTF-16 if you need to change from UTF-8 to UTF-16.

The following table summarizes some of the properties of each UTF:

Bytes Encoding form

EF BB BF UTF-8
FF FE UTF-16, little-endian
FE FF UTF-16, big-endian
00 00 FE FF UTF-32, big-endian
FF FE 00 00 UTF-32, little-endian

BOM is written prior to the XML text, and it indicates to the parser how the XML is encoded. The XML
declaration contains the encoding, for example: <?xml version=xxx encoding=″utf-xxx″?>. BOM is used
with the encoding to determine how to interpret the XML. Here is an example of a SOAP message and
how BOM and UTF encoding are used:
POST http://www.whitemesa.net/soap12/add-test-rpc HTTP/1.1
Content-Type: application/soap+xml; charset=utf-16; action=""
SOAPAction:
Host: localhost: 8080
Content-Length: 562

OxFF0xFE<?xml version="1.0" encoding="utf-16"?>

<soap:Envelope xmlns:soap="http://www.w3.org/2002/12/soap-envelope"

1158 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 xmlns:soapenc="http://www.w3.org/2002/12/soap-encoding
xmlns:tns="http://whitemesa.net/wsdl/soap12-test"
xmlns:types="http://whitemesa.net/wsdl/soap12-test/encodedTypes"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<q1:echoString xmlns:q1="http://soapinterop.org/">
<inputString soap:encodingStyle="http://example.org/unknownEncoding"
xsi:type="xsd:string">
Hello SOAP 1.2
</inputString>
</q1:echoString>
</soap:Body>
</soap:Envelope>

In the example code, 0xFF0xFE represents the byte codes, while the <?xml> declaration is the textual
representation.

To learn more about the WS-Basic profile, including scenarios, UTF and BOM, see Web services:
Resources for learning.

RMI-IIOP using JAX-RPC

Java API for XML-based Remote Procedure Call (JAX-RPC) is the Java standard API for invoking Web
services through remote procedure calls. A transport is used by a programming language to communicate
over the Internet. You can use protocols with the transport such as SOAP and Remote Method Invocation
(RMI). You can use Remote Method Invocation over Internet Inter-ORB Protocol (RMI-IIOP) with JAX-RPC
to support non-SOAP bindings.

Using RMI-IIOP with JAX-RPC, enables WebSphere Java clients to invoke enterprise beans using a
WSDL file and the JAX-RPC programming model instead of using the standard J2EE programming model.
When a enterprise JavaBeans implementation is used to invoke a Web service, multiprotocol JAX-RPC
permits the Web service invocation path to be optimized for WebSphere Java clients. Learn more about
this by reviewing ″Using WSDL EJB bindings to invoke an EJB from a Web services client ″ in the
information center.

Benefits of using the RMI/IIOP protocol instead of a SOAP- based protocol are:
v XML processing is not required to send and receive messages; Java serialization is used instead.
v The client JAX-RPC call can participate in a user transaction, which is not the case when SOAP is
used.

WS-I Attachments Profile

The Web Services-Interoperability (WS-I) Attachments Profile is a set of non-proprietary Web services
specifications that promote interoperability. This profile compliments the WS-I Basic Profile 1.1 to add
support for interoperable SOAP messages with attachments-based Web services.

WebSphere Application Server conforms to the WS-I Attachments Profile 1.0.

Attachments are typically used to send binary data, for example, data that is mapped in Java code to
java.awt.Image and javax.activation.DataHandler. The raw data can be sent in the SOAP message,
however, this approach is inefficient because an XML parser has to scan the data as it parses the
message.

The WS-I Attachments Profile provides a solution to the limitations that are presented by Web Services
Description Language (WSDL) 1.1. Because WSDL 1.1 attachments are not part of the XML schema type
space, they can be message parts only. As message parts, the attachments cannot be arrays or properties
of Java beans. The profile defines the wsi:swaRef XML schema type.Use the wsi:swaRef XML schema
type to overcome the limitations of WSDL 1.1 attachments.

Chapter 8. Developing WebSphere applications 1159

The wsi:swaRef type is an extension of the xsd:anyURI type, where its value contains the content-ID of
the attachment.

Web services: Resources for learning

This topic provides relevant supplemental information about the following Web services-related topics:
v Web services overview
v Developing Web services:
Includes developing Web services based on the Java 2 Platform, Enterprise Edition (J2EE) and Java
API for XML-based remote procedure call (JAX-RPC) specifications.
v Universal Description Discovery and Integration (UDDI)
Includes an overview about UDDI and information about the UDDI Java API.
v The Web Services Invocation Framework (WSIF)
Includes a look into the Apache Software Foundation and its maintenance of WSIF.
v Web Services-Interoperability (WS-I) Basic Profile
Includes an overview about the WS-I Basic Profile.
v SOAP
Includes an overview about SOAP, information about the SOAP syntax and processing rules.
v Security
Includes a roadmap to security, the WS-Security specification, best practices, a profile of the OASIS
Security Assertion Markup Language (SAML) and more.
v Samples
Includes the Samples Gallery for WebSphere Application Server and Samples Central for UDDI and
WSIF.

The information resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy
of the information.

These links are provided for convenience. Often, the information is not specific to an IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

Web services overview

v WebSphere Version 5.1.1 Web Services Handbook
This IBM Redbook describes the new concept of Web services from various perspectives. It presents
the major building blocks on which Web services rely. Well-defined standards and new concepts are
presented and discussed.
v Web services (r)evolution, Part 1
This article focuses on the benefits and challenges of building Web services applications. Web services
might be an evolutionary step in designing distributed applications, however, the technology is not
without problems. Outlined are the difficulties developers face in creating a truly workable distributed
system of Web services. This article also outlines author Graham Glass’s plan for building peer-to-peer
Web applications.

Developing Web services

v Java Web Services: SOAP with Attachments API for Java (SAAJ)
This document describes the SOAP with Attachments API for Java (SAAJ) and how this API provides a
standard way to send XML documents over the Internet from the Java platform.
v JSR 109: Implementing Enterprise Web services
This document describes the Java 2 Platform, Enterprise Edition (J2EE) specification.
v JAX-RPC: Core Web services API in the Java platform
This document reviews the JAX-RPC specification which enables Java technology developers to
develop SOAP-based interoperable and portable Web services.

1160 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v A developer introduction to the JAX-RPC specification, Part 1: Learn the ins and outs of the JAX-RPC
type-mapping system. The JAX-RPC specification is an important step forward in the quest for Web
services interoperability. This DeveloperWorks WebSphere article explains the mapping between WSDL
and XML types and Java types. It explains how the JAX-RPC standard defines this feature and some of
the important points on designing an interoperable type system.
v A developer introduction to JAX-RPC, Part 2: Mine the JAX-RPC specification to improve Web service
interoperability. This DeveloperWorks WebSphere article explains how you can achieve the next level of
Web service interoperability using the JAX-RPC standard client and server side interface definitions and
message processing model. It includes information on developing JAX-RPC handlers and handler
chains.
v Getting Started with JAX-RPC. This article explains some of the basic JAX-RPC programming concepts.
It describes the JAX-RPC client and server programming models and provides some simple examples
for illustration. The article is intended to give developers a good grasp of how to use the JAX-RPC
specification to develop or use Web services.
v Web Services Description Language
This article is a detailed overview of Web Services Description Language (WSDL), which includes
programming specifications.

UDDI
v Universal Description, Discovery and Integration
This article is a detailed overview of Universal Description, Discovery, and Integration (UDDI).
v A new approach to UDDI and WSDL: Introduction to the new OASIS UDDI WSDL Technical Note
This article is about using WSDL with UDDI. Although it is based on the UDDI Registry in WebSphere
Application Server Version 5, it remains a useful description of the recommended approach for use of
WSDL with UDDI.
v UDDI Version 3 Features List
This article is an introduction to the new features in UDDI Version 3.

WSIF
v The Apache Software Foundation. The Apache Software Foundation provides support for the Apache
community of open-source software projects. Of particular interest is the Apache Web services project.
The WSIF source code is donated by IBM to the Apache Software Foundation, and is maintained here
as an Apache project.

WS-I Basic Profile

v Web Services Interoperability Organization This Web site offers resources and guidelines for Web
services interoperability. You can also view the latest specification documents for WS-I Basic Profile
from the documentation link on the home page.
v UTF and BOM Frequently Asked Questions. This Web site offers general information about UTF-8,
UTF-16, UTF-32, along with Byte Order Mark (BOM) in a question and answer format.

SOAP
v SOAP
This article is a detailed overview of SOAP, which includes programming specifications.
v SOAP Security Extensions: Digital Signature
This document specifies the syntax and processing rules of a SOAP header entry to carry digital
signature information within a SOAP 1.1 Envelope

Security
v Security in a Web Services World: A Proposed Architecture and Roadmap
This document describes a proposed model for addressing security within a Web service environment. It
defines a comprehensive Web Services Security model that supports, integrates, and unifies several

Chapter 8. Developing WebSphere applications 1161

 popular security models, mechanisms, and technologies, including both symmetric and public key
technologies. Enable a variety of systems to securely interoperate in a platform and language-neutral
manner. It also describes a set of specifications and scenarios that show how these specifications can
be used together.
v Web Services Security (WS-Security)
The Web Services security specifications describe enhancements to SOAP messaging to provide the
quality of protection through message integrity, message confidentiality, and single message
authentication. Use these mechanisms to accommodate a wide variety of security models and
encryption technologies. Web Services security also provides a general-purpose mechanism for
associating security tokens with messages. Additionally, Web Services Security describes how to
encode binary security tokens. Specifically, the specification describes how to encode X.509 certificates
and Kerberos tickets, as well as how to include opaque encrypted keys. It also includes extensibility
mechanisms that can be used to further describe the characteristics of the credentials that are included
with a message.
v SOAP Security Extensions: Digital Signature
This document specifies the syntax and processing rules of a SOAP header entry to carry digital
signature information within a SOAP 1.1 envelope
v Web Services Security Addendum
This document describes clarifications, enhancements, best practices, and errata of the Web Services
Security specification.
v WS-Security Profile of the OASIS Security Assertion Markup Language (SAML) Working Draft 04, 10
September 2002
This document proposes a set of standards for SOAP extensions used to increase message
confidentiality.
v Web Services Security: SOAP Message Security Working Draft 12, Monday 21 April 2003
This document describes the support for multiple token formats, trust domains, signature formats, and
encyrption technologies.
v JSR 55:Certification Path API
This document provides a short description of the certification path API.
v XML-Signature Syntax and Processing
This document specifies XML digital signature processing rules and syntax. XML signatures provide
integrity, message authentication, or signer authentication services for data of any type, whether located
within the XML that includes the signature or elsewhere.
v Canonical XML Version 1.0
This specification describes a method for generating a physical representation, the canonical form, of an
XML document that accounts for the permissible changes.
v Exclusive XML Canonicalization Version 1.0
Canonical XML [XML-C14N] specifies a standard serialization of XML that, when applied to a
subdocument, includes the subdocument ancestor context including all of the namespace declarations
and attributes in the ″xml:″namespace.
v XML Encryption Syntax and Processing
This document specifies a process for encrypting data and representing the result in XML.
v Decryption Transform for XML Signature
This document specifies an XML Signature decryption transform that enables XML Signature
applications to distinguish between those XML encryption structures that are encrypted before signing,
and must not be decrypted, and those that are encrypted after signing, and must be decrypted, for the
signature to validate.
v WS-Security
This document specifies resources for the April 2002 Web Services Security Specification. The following
addenda and drafts are available:
– http://schemas.xmlsoap.org/ws/2002/07/secext/
– http://schemas.xmlsoap.org/ws/2002/07/utility/
– OASIS draft 12 for secext

1162 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 – OASIS draft 12 for utility
v Specification: Web Services Security (WS-Security) Version 1.0 05 April 2002
v XML Encryption Syntax and Processing W3C Recommendation 10 December 2002
v XML-Signature Syntax and Processing W3C Recommendation 12 February 2002
v Web Services Security Addendum
v Web Services Security Core Specification Working Draft 01, 20 September 2002
v Web Services Security: SOAP Message Security Working Draft 13, Thursday, 01 May 2003
v Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile,
RFC3280, April 2002
v OASIS Web Services Security Technical Committee

Samples
v Samples Gallery
v Samples Central. Samples and associated documentation for the following Web services components
are available through the Samples Central page of the DeveloperWorks WebSphere Web site:
– The IBM WebSphere UDDI Registry.
– The Web Services Invocation Framework (WSIF).

Deploying Web services

This task explains how to deploy a Web service into WebSphere Application Server.

To deploy Web services that are based on the Web Services for Java 2 Platform, Enterprise Edition
(J2EE) specification, you need an enterprise application, also known as an enterprise archive (EAR) file
that is configured and enabled for Web services.

If you have a Web service that was deployed on a previous version of WebSphere Application Server, you
might want to run the wsdeploy command so that you can benefit from performance features that have
been added to this release.

This task is one of the steps in developing and implementing Web services.

You can use either the administrative console or the wsadmin scripting tool to deploy an EAR file. If you
are installing an application containing Web services by using the wsadmin command, specify the
-deployws option. If you are installing an application containing Web services by using the administrative
console, select Deploy WebServices in the Install New Application wizard. For more information about
installing applications using the administrative console see Installing a new application.

If the Web services application is previously deployed with the wsdeploy command, it is not necessary to
specify Web services deployment during installation.

The following actions deploy the EAR file with the wsadmin command:
1. Start install_root\bin\wsadmin from a command prompt. If you are using Linux or Unix platforms,
start install_root/bin/wsadmin.sh.
2. Enter the $AdminApp install EARfile ″-usedefaultbindings -deployws″ command at the wsadmin
prompt.

You have a Web service installed into the Application Server.

Protect your Web services applications by adding security to the applications.

wsdeploy command
This topic explains how to use the wsdeploy command-line tool with Web services that are based on the
Web Services for Java 2 Platform, Enterprise Edition (J2EE) specification. The wsdeploy command adds
WebSphere product-specific deployment classes to a Web services-compatible enterprise application
enterprise archive (EAR) file or an application client Java archive (JAR) file. These classes include:

Chapter 8. Developing WebSphere applications 1163

v Stubs
v Serializers and deserializers
v Implementations of service interfaces

This deployment step must be performed at least once, and can be performed more often. Deployment
can be performed separately using the wsdeploy command, assembly tools, or when the application is
installed. When using the wsadmin command for installation, specify the -deployws option.

The wsdeploy command operates as noted in the following list:

v Each module in the enterprise application or JAR file is examined
v If the module contains Web services implementations, indicated by the presence of the webservices.xml
deployment descriptor, the associated Web Services Description Language (WSDL) files are located
and the WSDL2Java command is run with the role deploy-server option.
v If the module contains Web services clients, indicated by the presence of the client deployment
descriptor, the associated WSDL files are located and the WSDL2Java command is run with the role
deploy-client option.
v The files generated by the WSDL2Java command are compiled and repackaged.

See WSDL2Java command for more information about the files that are generated for deployment.

When the generated files are compiled, they can reference application-specific classes outside the EAR or
JAR file, if the EAR or JAR file is not self-contained. In this case, use either the -jardir or -cp option to
specify additional JAR or zip files to be added to CLASSPATH variable when the generated files are
compiled.

wsdeploy command syntax

The command syntax is noted in the following example:

wsdeploy Input_filename Output_filename [options]

Required options:
v Input_filename
Specifies the path to the EAR or JAR file to deploy.
v Output_filename
Specifies the path of the deployed EAR or JAR file. If output_filename already exists, it is silently
overwritten. The output_filename can be the same as theinput_filename.

Other options:
v -jardir directory
Specifies a directory that contains JAR or zip files. All JAR and zip files in this directory are added to
the CLASSPATH used to compile the generated files. This option can be specified zero or more times.
v -cp entries
Specifies entries to add to the CLASSPATH when the generated classes are compiled. Multiple entries
are separated the same as they are in the CLASSPATH environment variable, with a semicolon on
Windows platforms and a colon for Linux and Unix platforms.
v -codegen
Specifies to generate but not compile deployment code. This option implicitly specifies the -keep option.
v -debug
Includes debugging information when compiling, that is, use javac -g to compile.
v -help
Displays a help message and exit.
v -ignoreerrors
Do not stop deployment if validation or compilation errors are encountered.
v -keep

1164 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Do not delete working directories containing generated classes. A message is displayed indicating the
name of the working directory that is retained.
v -novalidate
Do not validate the Web services deployment descriptors in the input file.
v -trace
Displays processing information, including the names of the generated files.

Example The following example illustrates how the options are used with the wsdeploy command:
wsdeploy x.ear x_deployed.ear -trace -keep
Processing web service module x_client.jar.
Keeping directory: f:\temp\Base53383.tmp for module: x_client.jar.
Parsing XML file:f:\temp\Base53383.tmp\WarDeploy.wsdl
Generating f:\temp\Base53383.tmp\generatedSource\com\test\WarDeploy.java
Generating f:\temp\Base53383.tmp\generatedSource\com\test\WarDeployLocator.java
Generating f:\temp\Base53383.tmp\generatedSource\com\test\HelloWsBindingStub.java
Compiling f:\temp\Base53383.tmp\generatedSource\com\test\WarDeploy.java.
Compiling f:\temp\Base53383.tmp\generatedSource\com\test\WarDeployLocator.java.
Compiling f:\temp\Base53383.tmp\generatedSource\com\test\HelloWsBindingStub.java.
Done processing module x_client.jar.

Messages
v Flag -fis not valid.
Option f was not recognized as a valid option.
v Flag -c is ambiguous.
Options can be abbreviated, but the abbreviation must be unique. In this case, the wsdeploy command
cannot determine which option was intended.
v Flag -c is missing parameter -p.
A required parameter for an option is omitted.
v Missing p parameter.
A required option is omitted.

Configuring Web service client bindings

When a Web service application is deployed into WebSphere Application Server, an instance is created for
each application or module. The instance contains deployment information for the Web module or
enterprise JavaBean (EJB) module, including client bindings.

Deploy the Web service into WebSphere Application Server.

To complete this task, you need to know the topology of the URL endpoint address of the Web services
servers and which Web service the client depends upon. You can view the deployment descriptors in the
administrative console to find topology information. See the article ″View Web services server deployment
descriptors″ in the information center for more information.

The client bindings define the Web Services Description Language (WSDL) file name and preferred ports.
The relative path of a Web service in a module is specified within a compatible WSDL file that contains the
actual URL to be used for requests. The address is only needed if the original WSDL file did not contain a
URL, or when a different address is needed. For a service endpoint with multiple ports, you need to define
an alternative WSDL file name.

The following steps describe how to edit bindings for a Web service after these bindings are deployed on
a server. When one Web service communicates with another Web service, you must configure the client
bindings to access the downstream Web service.

You can also configure client bindings with wsadmin.

Chapter 8. Developing WebSphere applications 1165

To configure client bindings through the administrative console:
1. Open the administrative console.
2. Click Applications > Enterprise Applications > application_instance > Web modules >
module_instance > Web services client bindings.
For EJB modules, click Applications >Enterprise Applications > application_instance > EJB
modules > module_instance > Web services client bindings.
3. Find the Web service you want to update.
The Web services are listed in the Web Service field.
4. Select the WSDL file name from the drop down box in the WSDL file name field.
5. Click Edit in the Preferred port mappings field to configure the default port to use.
a. Specify the port type and the preferred ports in the Port type and Preferred ports fields.
Configuring the preferred port enables you to select an optimal port implementation use non-SOAP
protocols. See RMI-IIOP Web services using JAX-RPC for more information about using
non-SOAP protocols.
b. Click Apply and OK.
6. Click Edit in the Port information field to configure the request timeout, the overridden endpoint, and
the overridden binding namespace for a port.
Configuring the request timeout accommodates complex topologies that can have multiple cascaded
Web services that involve multiple hops or long-running services.
Timeout values can be configured based on observed behavior of the overall system as integration
proceeds. For example, a Web service client might time out because of changing network conditions or
the performance of an external Web service. When you have applications containing Web services
clients that timeout, you can change the request time out values for the clients.
a. Click Apply and OK.

Your Web service client bindings are configured.

Now you can finish any other configurations, start or restart the application, and verify the expected
behavior of the Web service.

Web services client bindings

The client bindings define the Web Service Description Language (WSDL) file name, preferred ports and
other port information. Use this page to specify the client bindings and the port mappings for the Web
services in a module.

A Web service can specify the relative path within the module of a compatible WSDL file containing the
actual URL to be used for requests. The relative path only needs to be specified if the original WSDL file
does not contain a URL or when a different URL is needed. For a service endpoint with multiple ports
defined, a preferred mapping specifies the default port to use for a port type.

To view this page, click Applications >Enterprise Applications > application_instance > Web modules >
module_instance>Web services client bindings.

For EJB modules, click Applications >Enterprise Applications > application_instance > EJB modules >
module_instance>Web services client bindings.

Web service:

Identifies the name of this Web service. A module can contain one or more Web services.

EJB:

Identifies the name of the EJB for the EJB modules.

1166 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WSDL file name:

Specifies the WSDL file name, which is relative to the module. Locate the WSDL file name in the drop
down menu.

Preferred port mappings:

Specifies and manages the preferred port type mapping for a Web service when a particular port type is
requested.

Click Edit to edit the preferred port mapping information on the Preferred port mappings panel.

Port information:

Specifies additional configuration information for the ports of this Web service.

Click Edit to edit the port information on the Port information panel. You can set a request timeout,
override an endpoint and override a binding namespace for each client port.

Preferred port mappings:

Use this page to view and manage a preferred portType mapping for a Web service.

When you have multiple ports that reference the same portType (service endpoint interface), a preferred
port specifies the port to use when the Service.getPort(Class SEI) method is called with only the service
endpoint interface.

To view this administrative console page, click Applications >Enterprise Application >
application_instance > Web modules > module_instance>Web services client bindings > Edit>
preferred_port_instance.

For EJB modules, click Applications >Enterprise Application > application_instance > EJB modules >
module_instance>Web services client bindings > Edit> preferred_port_instance.

portType:

Specifies the portType.

The preferred port and the portType values are both of the type java.xml.namespace.QName.

Preferred port:

Specifies the preferred port to be associated with a particular portType. The Service.getPort(Class)
method returns the preferred port associated with the specified service endpoint interface class (portType).

The preferred ports available are listed, as well as a value of None, which indicates no preferred port is
selected.

Web services client port information:

Use this page to specify a request timeout, override an endpoint, and override a binding namespace for a
Web services client port.

A Web service can have multiple ports. You can view and configure the port attributes for each defined
Web service port. The Web services are listed on the Web services client bindings panel.

Chapter 8. Developing WebSphere applications 1167

To view this page, click Applications >Enterprise Applications > application_instance > Web modules >
module_instance>Web services client bindings > Edit.

For EJB modules, click Applications >Enterprise Applications > application_instance > EJB modules >
module_instance>Web services client bindings > Edit.

Port:

Identifies the name of a port.

Request timeout:

Specifies the time, in milliseconds, that the Web service client waits for a request to complete on this port.
If a timeout is not specified, the default request timeout for the client to wait is 360 seconds. If the value is
set at 0 (zero), the client’s request does not timeout.

A typical use for this setting is to customize the client’s behavior when it is configured to use a JMS
transport to access a Web service to make it wait longer for an expected completion. Depending upon
network conditions, or the nature of a Web service implementation, it might be necessary to tune the
timeout.

Overridden endpoint:

Specifies the name of an endpoint that is used to override the current endpoint. A client invoking a request
on this port uses this endpoint instead of the endpoint specified in the WSDL file.

If an assembled application contains a Web service client that is statically bound, the client is locked into
using the implementation (service end point) identified in the WSDL file used during development.
Overriding the endpoint is an alternative to configuring the deployed WSDL attribute.

The overridden endpoint URI attribute is specified on a per port basis. It does not require an alternative
WSDL file within the module. The overridden endpoint URI takes precedence over the deployed WSDL
attribute. The client uses this value for the service end point URI or SOAP address, instead of the value in
the static client bindings.

Overridden binding:

Specifies the WSDL file binding namespace URI to use with this port, instead of the namespace in the
WSDL file. This binding does not need to exist in the WSDL file. A client invoking a request on this port
uses this binding instead of the binding specified in the WSDL file. An overridden binding namespace
cannot be specified unless an overridden endpoint is specified.

Configuring the scope of a Web service port

When a Web service application is deployed into WebSphere Application Server, an instance is created for
each application or module. The instance contains deployment information for the Web module or
enterprise bean module, including implementation scope, client bindings and deployment descriptor
information. There are three levels of scope that can be set: application, session and request.

Deploy the Web service into WebSphere Application Server.

Web Services for Java 2 platform Enterprise Edition (J2EE) specifies that Web services implementations
must be stateless. Therefore, to maintain specification compliance, the scope can remain at the application
level because the state relevant to the individual sessions level or the requests level is not supposed to be
maintained in the implementation. If you want to deviate from the specification and want to access a
different JavaBean instance, because you are looking for information that is located in another JavaBean
implementation, the scope settings need to change.

1168 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The setting that you configure for the scope determines how frequently a new instance of a service
implementation class is created for the Web service ports in a module. Use this task to configure the
scope of a Web service port.

You can also configure the scope with the wsadmin tool.

To change the scope setting through the administrative console:

1. Open the administrative console.
2. Click Applications >Enterprise Applications > application_instance > Web Modules >
module_instance>Web Services Implementation Scope. If you are using an EJB module click EJB
Modules instead of Web Modules.
3. Set the scope to application, session or request. The application scope causes the same instance of
the implementation to be used for all requests on the application. The session scope causes the same
instance to be used for all requests in each session. The request scope causes a new instance to be
used for every request. For example, with the scope set to application, every message that comes to
the server accesses the same JavaBean instance because that is the way the scope settings are
configured.
4. Click Apply.
5. Click OK.

The scope for a Web service port is configured.

Now you can finish any other configurations, start or stop the application, and verify the expected behavior
of the Web service.

Web services implementation scope

The scope determines when a new implementation instance is created for Web service ports. For
example, setting the scope to application causes the same instance of the implementation to be used for
each request. Setting the scope to session causes the same instance of the implementation to be used for
each requests of a session. Setting the scope to request causes a new instance to be created for each
request.

Use this page to view and manage the scope of the ports of a Web service application.

To view this administrative console page, click Applications >Enterprise Applications >
application_instance > Web modules > module_instance>Web services implementation scope.

Port:

Specifies a port name for a Web service. A module can contain one or more Web services, each of which
can contain one or more ports.

Web service:

Specifies the name of the Web service. A module can contain one or more Web services.

URI:

Specifies the Uniform Resource Identifier (URI) of the binding file that defines the scope. The URI is
relative to the Web module.

Scope:

Specifies the scope of a port. The valid values for scope are request, session and application.

Chapter 8. Developing WebSphere applications 1169

Web Services Invocation Framework (WSIF): Enabling Web services
The Web Services Invocation Framework (WSIF) provides a Java API for invoking Web services,
independent of the format of the service or the transport protocol through which it is invoked. This
framework includes an EJB provider for EJB invocation using Remote Method Invocation over Internet
Inter-ORB Protocol (RMI-IIOP). However, for EJB(IIOP)-based Web service invocation you should instead
invoke RMI-IIOP Web services using JAX-RPC.

The Web Services Invocation Framework (WSIF) is a WSDL-oriented Java API. You use this API to invoke
Web services dynamically, regardless of the service implementation format (for example enterprise bean
(EJB)) or the service access mechanism (for example Java Message Service (JMS)).

Using WSIF, you can move away from the usual Web services programming model of working directly with
the SOAP APIs, towards a model where you interact with representations of the services. You can
therefore work with the same programming model regardless of how the service is implemented and
accessed.

If you want to know more about the issues that WSIF addresses, see Goals of WSIF.

If you want to know how WSIF addresses these issues, see An overview of WSIF.

To use WSIF, see the following topics in the information center:

v Using WSIF to invoke Web services.
v WSIF system management and administration.
v WSIF API.

For more information about working with WSIF, visit the Web sites listed in Web services: Resources for
Learning.

Goals of WSIF
SOAP bindings for Web services are part of the WSDL specification, therefore when most developers think
of using a Web service, they immediately think of assembling a SOAP message and sending it across the
network to the service endpoint, using a SOAP client API. For example: using Apache SOAP the client
creates and populates a Call object that encapsulates the service endpoint, the identification of the SOAP
operation to invoke, the parameters to send, and so on.

While this process works for SOAP, it is limited in its use as a general model for invoking Web services for
the following reasons:
v Web services are more than just SOAP services.
v Tying client code to a particular protocol implementation is restricting.
v Incorporating new bindings into client code is hard.
v Multiple bindings can be used in flexible ways.
v A freer Web services environment enables intermediaries.

The goals of the Web Services Invocation Framework (WSIF) are therefore:
v To give a binding-independent mechanism for Web service invocation.
v To free client code from the complexities of any particular protocol used to access a Web service.
v To enable dynamic selection between multiple bindings to a Web service.
v To help the development of Web service intermediaries.

WSIF - Web services are more than just SOAP services: You can deploy as a Web service any
application that has a WSDL-based description of its functional aspects and access protocols. If you are
using the Java 2 platform, Enterprise Edition (J2EE) environment, then the application is available over
multiple transports and protocols.

1170 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
For example, you can take a database-stored procedure, expose it as a stateless session bean, then
deploy it into a SOAP router as a SOAP service. At each stage, the fundamental service is the same. All
that changes is the access mechanism: from Java DataBase Connectivity (JDBC) to Remote Method
Invocation over Internet Inter-ORB Protocol (RMI-IIOP) and then to SOAP.

The WSDL specification defines a SOAP binding for Web services, but you can add binding extensions to
the WSDL so that, for example, you can offer an enterprise bean as a Web service using RMI-IIOP as the
access protocol. You can even treat a single Java class as a Web service, with in-thread Java method
invocations as the access protocol. With this broader definition of a Web service, you need a
binding-independent mechanism for service invocation.

WSIF - Tying client code to a particular protocol implementation is restricting:

If your client code is tightly bound to a client library for a particular protocol implementation, it can become
hard to maintain.

For example, if you move from Apache SOAP to Java Message Service (JMS) or enterprise bean, the
process can take a lot of time and effort. To avoid these problems, you need a protocol
implementation-independent mechanism for service invocation.

WSIF - Incorporating new bindings into client code is hard: As is explained in Web services are not
just SOAP services, if you want to make an application that uses a custom protocol work as a Web
service, you can add extensibility elements to WSDL to define the new bindings. But in practice, achieving
this capability is hard. For example you have to design the client APIs to use this protocol. If your
application uses just the abstract interface of the Web service, you have to write tools to generate the
stubs that enable an abstraction layer. These tasks can take a lot of time and effort. What you need is a
service invocation mechanism that allows you to update existing bindings, and to add new bindings.

WSIF - Multiple bindings can be used in flexible ways: Imagine that you have successfully deployed
an application that uses a Web service which offers multiple bindings. For example, imagine that you have
a SOAP binding for the service and a local Java binding that lets you treat the local service
implementation (a Java class) as a Web service.

The local Java binding for the service can only be used if the client is deployed in the same environment
as the service. In this case, it is more efficient to communicate with the service by making direct Java calls
than by using the SOAP binding.

If your clients could switch the actual binding used based on run-time information, they could choose the
most efficient available binding for each situation. To take advantage of Web services that offer multiple
bindings, you need a service invocation mechanism that can switch between the available service bindings
at run-time, without having to generate or recompile a stub.

WSIF - Enabling a freer Web services environment promotes intermediaries:

Web services offer application integrators a loosely-coupled paradigm. In such environments,

intermediaries can be very powerful.

Intermediaries are applications that intercept the messages that flow between a service requester and a
target Web service, and perform some mediating task (for example logging, high-availability or
transformation) before passing on the message. The Web Services Invocation Framework (WSIF) is
designed to make building intermediaries both possible and simple. Using WSIF, intermediaries can add
value to the service invocation without needing transport-specific programming.

Chapter 8. Developing WebSphere applications 1171

An overview of WSIF
The Web Services Invocation Framework (WSIF) provides a Java API for invoking Web services,
independent of the format of the service or the transport protocol through which it is invoked. This
framework addresses all of the issues identified in the goals of WSIF.

WSIF provides the following features:

v An API that provides binding-independent access to any Web service.
v A close relationship with WSDL, so it can invoke any service that you can describe in WSDL.
v A stubless and completely dynamic invocation of a Web service.
v The capability to plug a new or updated implementation of a binding into WSIF at run-time.
v The option to defer the choice of a binding until run-time.

WSIF is designed to work both in an unmanaged environment (stand-alone) and inside a managed
container. You can use the Java Naming and Directory Interface (JNDI) to find the WSIF service, or you
can use the location described in the WSDL.

For more conceptual information about WSIF and WSDL, see the following topics:
v WSIF and WSDL
v WSIF architecture
v Using WSIF with Web services that offer multiple bindings
v WSIF usage scenarios
v Dynamic invocation

WSIF supports Internet Protocol Version 6, and Java API for XML-based Remote Procedure Calls
(JAX-RPC) Version 1.1 for SOAP.

WSIF architecture: The Web Services Invocation Framework (WSIF) architecture is shown in the figure.

1. Load WSDL WSDL WSDL

document document describes
service
interface
2. Create WSIF 3. Use WSIF
service service to get
WSIF operation Service
WSIF WSIF
service
service operation
factory
WSIF
4. Create message 5. Invoke service provider
with operation name
and message

The components of this architecture include:

WSDL document
The Web service WSDL document contains the location of the Web service. The binding
document defines the protocol and format for operations and messages defined by a particular
portType.
WSIF service
The WSIFService interface is responsible for generating an instance of the WSIFOperation
interface to use for a particular invocation of a service operation. For more information, see
″Finding a port factory or service″ in the information center.
WSIF operation
The run-time representation of an operation, called WSIFOperation is responsible for invoking a
service based on a particular binding. For more information, see ″WSIF API reference: Using
ports″ in the information center.
WSIF provider
A WSIF provider is an implementation of a WSDL binding that can run a WSDL operation through

1172 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 a binding-specific protocol. WSIF includes SOAP providers, JMS providers, Java providers and
EJB providers. For more information, see ″Using the WSIF providers″ in the information center.

Using WSIF with Web services that offer multiple bindings:

Using WSIF, a client application can choose dynamically the optimal binding to use for invoking Web
service operations.

For example, a Web service might offer a SOAP binding, and also a local Java binding so that you can
treat the local service implementation (a Java class) as a Web service. If a client application is deployed in
the same environment as the service, then this client can use the local Java binding for the service. This
provides more efficient communication between the client and the service by making direct Java calls
rather than indirect calls using the SOAP binding.

For more information on how to configure a client to dynamically select between multiple bindings, see
″Developing a WSIF service″ in the information center.

WSIF and WSDL: WSDL is the acronym for Web Services Description Language.

In WSDL a service is defined in three distinct sections:

v The portType. This section defines the abstract interface offered by the service. A portType defines a
set of operations. Each operation can be In-Out (request-response), In-Only, Out-Only and Out-In
(Solicit-Response). Each operation defines the input and/or output messages. A message is defined as
a set of parts, and each part has a schema-defined type.
v The binding. This section defines how to map between the abstract portType and a real service format
and protocol. For example the SOAP binding defines the encoding style, the SOAPAction header, the
namespace of the body (the targetURI), and so on.
v The port. This section defines the actual location (endpoint) of the available service. For example, the
HTTP Web address at which a SOAP service is available.

Currently in WSDL, each port has one and only one binding, and each binding has a single portType. But
(more importantly) each service (portType) can have multiple ports, each of which represents an
alternative location and binding for accessing that service.

The Web Services Invocation Framework (WSIF) follows the semantics of WSDL as much as possible:
v The WSIF dynamic invocation API directly exposes run-time equivalents of the model from WSDL. For
example, invocation of an operation involves executing an operation with an input message.
v WSDL has extension points that support the addition of new ports and bindings. This enables WSDL to
describe new systems. The equivalent concept in WSIF is a provider, that enables WSIF to understand
a class of extensions and thereby to support a new service implementation type.

As a metadata-based invocation framework, WSIF follows the design of the metadata. As WSDL is
extended, WSIF is updated to follow.

The implicit and primary type system of WSIF is XML schema. WSIF supports invocation using dynamic
proxies, which in turn support Java type systems, but when you use the WSIFMessage interface it is your
responsibility to populate WSIFMessage objects with data based on the XML schema types as defined in
the WSDL document. You should define your object types by a canonical and fixed mapping from schema
types into the run-time.

For more information on WSDL, see Web services: Resources for learning.

WSIF usage scenarios:

This topic describes two brief scenarios that illustrate the role WSIF plays in the emerging Web services
environment.

Chapter 8. Developing WebSphere applications 1173

Scenario: Redevelopment and redeployment

When you first implement a Web service, you create a simple prototype. When you want to move a
prototype Web service into production, you often need to redevelop and redeploy it.

The Web Services Invocation Framework (WSIF) uses the same API calls irrespective of the underlying
technologies, therefore if you use WSIF:
v You can reimplement and redeploy your services without changing the client code.
v You can use existing reliable and high-performance infrastructures like Remote Method Invocation over
Internet Inter-ORB Protocol (RMI-IIOP) and Java Message Service (JMS) without sacrificing the
location-independence that the Web service model offers.

Scenario: Service Flow composition

A service flow typically invokes a Web service, then passes the response from one Web service to the
next Web service, perhaps performing some transformation in the middle.

There are two key aspects to this flow that WSIF provides:
v A representation of the service invocation based on the metadata in WSDL.
v The ability to build invocations based solely on the portType, which can therefore be used in any
implementation.

For example, imagine that you build a meta-service that uses a number of services to build a process.
Initially, several of those services are simple Java bean prototypes that are written and exposed through
SOAP, but you plan to reimplement some of them as EJB components, and to out-source others.

If you use SOAP, it ties up multiple threads for every onward invocation, because they pass through the
Web server and servlet engine and on to the SOAP router. If you use WSIF to call the beans directly, you
get much better performance compared to SOAP and you do not lose access or location transparency.
Using WSIF, you can replace the Java bean implementations with EJB implementations without changing
the client code. To move some of the Web services from local implementations to external SOAP services,
you just update the WSDL.

Dynamic invocation: For the Web Services Invocation Framework (WSIF), dynamic invocation means
providing the following levels of support when invoking Web services:
1. Support for WSDL extensions and bindings that were not known at build time.
2. Support for Web services that were not known at build time.

WSIF supports (1) through the use of providers.

The providers support (2) by using the WSDL description to access the target service.

Getting started with UDDI Registry

This section covers the basic knowledge you need to get started either as an administrator of a UDDI
Registry or as a user of a UDDI Registry that has already been set up.
v Getting started for UDDI Administrators
v Getting started for UDDI users

Getting started for UDDI Administrators

Use this topic if you are involved in installing (setting up and deploying), customizing, or managing a UDDI
Registry.

1174 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This section contains a list of some of the topics that you will need to refer to as an administrator of a
UDDI Registry:
v ″UDDI Registry Terminology″ in the information center introduces some terms with which you will need
to be familiar in order to administer a UDDI Registry
v Setting up and deploying a new UDDI Registry explains how to install a UDDI Registry node by setting
up the resources that it will use, and deploying the UDDI Registry application.
v ″Managing the UDDI Registry″ in the information center explains how to use the UDDI pages in the
WebSphere Administrative Console, or the UDDI Registry Administrative interface, to administer a UDDI
Registry node. It also covers how to back up and restore your UDDI Registry data.
v ″UDDI node settings″ in the information center explains how to view and set UDDI properties and
policies, and how to manage UDDI publishers, tiers and user entitlements.
v ″UDDI Registry Management Interfaces″ covers details of programmatic interfaces that you can use to
administer a UDDI Registry node (UDDI Registry Administrative (JMX) Interface), to add custom Value
Set data to a UDDI Registry (User Defined Value Set Support), and to export and import UDDI version
2 entities (UDDI Utility Tools).

″UDDI Registry troubleshooting″ in the information center might be useful if you encounter any problems
or unexpected behaviour while using the UDDI Registry, and ″UDDI Registry messages″ explains any
UDDI messages which you might see.

Getting started for UDDI users

Use this topic if you use a UDDI Registry to publish or find UDDI entities either through a user interface or
by writing UDDI client applications.

This section contains a list of some of the topics that you might want to refer to as a user of a UDDI
Registry:

″UDDI Registry Terminology″ in the information center introduces some terms with which you might need
to be familiar with to use a UDDI Registry.

″UDDI Registry user interface″ in the information center tells you how to access the UDDI User Console,
which is a user interface that allows you to find UDDI entities and carry out simple UDDI publish
operations.

See ″Displaying the user interface″ in the information center for the URL for the UDDI User Interface.

UDDI Registry SOAP Service End Points contains details for accessing the UDDI version 3 Inquiry,
Publish, Security, and custody transfer APIs, as well as the UDDI version 1 and version 2 APIs.

UDDI Registry Client Programmingexplains how to write UDDI client application programs. The
recommended client programming interface is the IBM UDDI version 3 Client for Java.

″IBM JAXR Provider for the UDDI Registry″ in the information center is for users who want to use the Java
API for XML Registries to access UDDI.

″User Defined Value Set Support in the UDDI Registry″ explains how to add custom value set data to a
UDDI Registry.

″UDDI Registry troubleshooting″ in the information center might be useful if you encounter any problems
or unexpected behaviour while using the UDDI Registry, and ″UDDI Registry messages″ in the information
center explains any UDDI messages which you might see.

Chapter 8. Developing WebSphere applications 1175

Planning to use Web services
This topic discusses how to plan your use of Web services that are developed and implemented based on
the Web Services for Java 2 Platform, Enterprise Edition (J2EE) specification.

Read the ″Web services scenario: Overview″ in the information center which tells the story of a fictional
online garden supply retailer named Plants by WebSphere and how this retailer incorporated the Web
services concept.

Web services are Web applications that help you be more flexible in your business processes by
integrating with applications that otherwise do not communicate.

Web services reflect the service-oriented architecture approach to programming. This approach is based
on the idea of building applications by discovering and implementing network-available services, or by
invoking the available applications to accomplish a task. Web services deliver interoperability, for example,
Web services applications provide a way for components created in different programming languages to
work together as if they were created using the same language. Web services rely on existing transport
technologies, such as HTTP, and standard data encoding techniques, such as Extensible Markup
Language (XML), for invoking the implementation.

To plan to use Web services:

1. Identify your goals and design Web services to fit your e-business solution. Consider what you want to
accomplish by using Web services. Decide how Web services fit into your current topology,
applications and programming model. Determine how the Web services process requests on the server
and how the clients manage and use the Web service.
2. Design your Web services for reliability, availability, manageability and security. For example, you want
your Web services to process a transaction in a reasonable time at all hours of the day and provide
users with good security characteristics, such as authentication for buyers. Planning to use Web
services to work with WebSphere Application Server helps to meet these requirements.
3. To support Web services, extend WebSphere Application Server to support Web services standards.
For interoperable Web services running on platforms supplied by multiple vendors, standards are
essential.
4. Decide what development and implementation tools to use. You can use a variety of manual
development and implementation tasks. Whether you have an existing Web service to implement or
you want to develop your own from a Java bean or from Enterprise JavaBeans (EJB), you can choose
different tasks respective to your resources. You can also use Rational Application Developer (RAD) to
complete development and implementation tasks.
See Developing Web services for information about developing Web services based on the Java
language through the WebSphere Application Server. To read more about RAD see the information
center for the product.
5. Install WebSphere Application Server.
6. Review Web services Samples.

You have a design plan for implementing Web services applications into your business architecture.

Develop a Web service.

This topic explains how to develop a Web service using the Web Services for J2EE specification.

Service-oriented architecture
A service-oriented architecture (SOA) is a collection of services that communicate with each other, for
example, passing data from one service to another or coordinating an activity between one or more
services.

1176 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Companies want to integrate existing systems to implement Information Technology (IT) support for
business processes that cover the entire business value chain. A variety of designs are used, ranging from
rigid point-to-point electronic data interchange (EDI) to Web auctions. By using the Internet, companies
make their IT systems available to internal departments or external customers, but the interactions are not
flexible and are without standardized architecture.

Because of this increasing demand for technologies that support connecting and sharing resources and
data, a need exists for a flexible, standardized architecture. SOA is a flexible architecture that unifies
business processes by structuring large applications into building blocks, or small modular functional units
or services, for different groups of people to use inside and outside the company. The building blocks can
be one of three roles: service provider, service broker, or service requestor. See Web services approach to
a service-oriented architecture to learn more about these roles.

Requirements for an SOA

To efficiently use an SOA, follow these requirements:

v Interoperability between different systems and programming languages.
The most important basis for a simple integration between applications on different platforms is to
provide a communication protocol. This protocol is available for most systems and programming
languages.
v Clear and unambiguous description language.
To use a service offered by a provider, it is not only necessary to be able to access the provider system,
but the syntax of the service interface must also be clearly defined in a platform-independent fashion.
v Retrieval of the service.
To support a convenient integration at design time or even system run time, a search mechanism is
required to retrieve suitable services. Classify these services as computer-accessible, hierarchical or
taxonomies based on what the services in each category do and how they can be invoked.

Web services approach to a service-oriented architecture

The Web services approach implements a service-oriented architecture (SOA). A major focus of Web
services is to make functional building blocks accessible over standard Internet protocols that are
independent from platforms and programming languages. These services can be new applications or just
wrapped around existing legacy systems to make them network-enabled. A service can rely on another
service to achieve its goals.

Each SOA building block can assume one or more of three roles:
v Service provider
The service provider creates a Web service and possibly publishes its interface and access information
to the service registry. Each provider must decide which services to expose, how to make trade-offs
between security and easy availability, how to price the services, or how to exploit free services for
other value. The provider also has to decide which category to list the service in for a given broker
service and what sort of trading partner agreements are required to use the service.
v Service broker
The service broker, also known as service registry, is responsible for making the Web service interface
and implementation access information available to any potential service requestor. The implementer of
the broker decides the scope of the broker. Public brokers are available through the Internet, while
private brokers are only accessible to a limited audience, for example, users of a company intranet.
Furthermore, some decisions need to be made about the amount of the offered information. Some
brokers specialize in many listings. Others offer high levels of trust in the listed services. Some cover a
broad landscape of services and others focus within an industry. Some brokers catalog other brokers.
Depending on the business model, brokers can attempt to maximize look-up requests, the number of
listings or the accuracy of the listings. The Universal Description, Discovery and Integration (UDDI)
specification defines a way to publish and discover information about Web services.

Chapter 8. Developing WebSphere applications 1177

v Service requester
The service requestor or Web service client locates entries in the broker registry using various find
operations and then binds to the service provider to invoke one of its Web services.

Legacy
system
Client

2 1

Service Service
Internet
requester provider

Service
broker

Characteristics of the SOA

The presented SOA illustrates a loose coupling between the participants, which provides greater flexibility
in the following ways:
v A client is coupled to a service. Therefore, the integration of the server takes place outside the scope of
the client application programs.
v Old and new functional blocks or applications and systems, are encapsulated into components that work
as services.
v Functional components and their interfaces are separate, so that new interfaces can be plugged in more
easily.
v Within complex applications, the control of business processes can be isolated. A business rule engine
can be incorporated to control the workflow of a defined business process. Depending on the state of
the workflow, the engine calls the respective services.
v Services can be incorporated dynamically during run time.
v Bindings are specified using configuration files and can be easily adapted to new needs.

Properties of a service-oriented architecture

The service-oriented architecture offers the following properties:

v Web services are self-contained.
On the client side, no additional software is required. A programming language with Extensible Markup
Language (XML) and HTTP client support is enough to get you started. On the server side, a Web
server and a SOAP server are required. It is possible to enable an existing application for Web services
without writing a single line of code.
v Web services are self-describing.
Neither the client nor the server knows or cares about anything besides the format and content of the
request and response messages (loosely coupled application integration). The definition of the message
format travels with the message; no external metadata repositories or code generation tool are required.
v Web services can be published, located, and invoked across the Internet.

1178 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 This technology uses established lightweight Internet standards such as HTTP and it leverages the
existing infrastructure. Some other standards that are required include, SOAP, Web Services Description
Language (WSDL), and UDDI.
v Web services are language-independent and interoperable.
Client and server can be implemented in different environments. Existing code does not have to change
in order to be Web services enabled.
v Web services are inherently open and standard-based.
XML and HTTP are the major technical foundation for Web services. A large part of the Web service
technology has been built using open-source projects.
v Web services are dynamic.
Dynamic e-business can become reality using Web services because with UDDI and WSDL you can
automate the Web service description and discovery.
v Web services are composable.
Simple Web services can be aggregated to more complex ones, either using workflow techniques or by
calling lower-layer Web services from a Web service implementation. Web services can be chained
together to perform higher-level business functions. This chaining shortens development time and
enables best-of-breed implementations.
v Web services are loosely coupled.
Traditionally, application design has depended on tight interconnections at both ends. Web services
require a simpler level of coordination that supports a more flexible reconfiguration for an integration of
the services.
v Web services provide programmatic access.
The approach provides no graphical user interface; it operates at the code level. Service consumers
need to know the interfaces to Web services, but do not need to know the implementation details of
services.
v Web services provide the ability to wrap existing applications.
Already existing stand-alone applications can easily integrate into the service-oriented architecture by
implementing a Web service as an interface.

Web services business models supported

The properties and benefits of using a service-oriented architecture (SOA) such as Web services is well
suited for binding small modules that perform independent tasks within a highly heterogeneous e-business
model. Web services can be easily wrapped around existing applications in your business model and
plugged into different business processes.

For connecting to a large monolithic system that does not support the implementation of different flexible
business processes, other approaches might be better suited, for example, to satisfy specialized features,
such as performance or security.

The following business models are easily implemented by using an architecture including Web services:
v Business information
Sharing of information with consumers or other businesses. Web services can be used to expand the
reach through such services as news streams, local weather reports, integrated travel planning, and
intelligent agents.
v Business integration
Providing transactional, fee-based services for customers. A global network of suppliers can be easily
created. Web services can be implemented in auctions, e-marketplaces, and reservation systems.
v Business process externalization

Chapter 8. Developing WebSphere applications 1179

 Web services can be used to model value chains by dynamically integrating processes to a new
solution within an organizational unit or even with those of other e-businesses. This modeling can be
achieved by dynamically linking internal applications to new partners and suppliers, to offer their
services to complement internal services.

Setting up and deploying a new UDDI Registry

Start the installation of WebSphere Application Server Version 6 and create the profile for your application
server (for example, server1) to be used to host UDDI.

You have a choice of deploying either a default UDDI node, or a user customized UDDI node.

A default UDDI node would be a suitable option for initial evaluation of UDDI and for development and test
purposes. With a customized UDDI node, you have more control over the database management system
used for the UDDI database, and the properties used to set up the UDDI database. With a user
customized UDDI node, you create the UDDI database and datasource to your own specifications, and
then use the uddiDeploy.jacl script to deploy the UDDI application.

The main difference between default and user customized, in the context of these set up tasks, refers to a
number of vital UDDI properties. For a default set up these vital properties are automatically set to default
values and are not changeable by the user. For a user customizable set up, the user is given an
opportunity to set these vital properties, but once set they can not be changed for this configuration.

Important: Important Note for DB2 users - Starting the WebSphere Application Server in which the UDDI
Registry is deployed

On Unix and Linux platforms, before you start the WebSphere server that is hosting your
UDDI DB2 application, you must run the db2profile script which is found in the home directory
for you db2 userid, for example /home/db2inst1/sqllib/db2profile

Similarly when in an ND configuration and starting the server via the Deployment Manager,
you must ensure the db2profile is run before starting the relevant nodeagent.

The information above is true during initial set up and deployment of UDDI and also every
time you start the application server or node agent. For this reason it is strongly recommended
that you update the user profile for the user that will start the nodeagent and server to also
execute the db2profile.

If running the profile manually type:

. /home/db2inst1/sqllib/db2profile

In the above example, notice that the ’.’ is followed by a single space character.

Deploying into a Network Deployment cell (but not a cluster)

It is important to note that the uddiDeploy.jacl script must be run with the Deployment Manager as the
target.

If you are deploying into a network deployment cell you cannot create a default Cloudscape node using
uddiDeploy.jacl. You may, however, manually create the default Cloudscape database (with a default
profile) by following the instructions in Creating a Cloudscape database and adding the parameter
’DEFAULT’ as the last argument.

1180 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
You will not be able to use the default option on uddiRemove for a UDDI node that is deployed into an
application server which is part of a Network Deployment cell. See ″Removing a UDDI Registry node″ for
more information.

If you have a non default UDDI setup in a base application server, you can issue an addNode
-includeapps command which will add the necessary definitions into the deployment manager.

Deploying into a cluster within a Network Deployment cell

It is important to note that uddiDeploy.jacl and uddiRemove.jacl can not be used in a cluster environment.

It is assumed a single database will be used for all members of the cluster.

You can follow the same guidelines for a non cluster set up in general for the resources such as the JDBC
provider and datasource as described in this Information Center, but they may need updating on individual
cluster members to correctly access the shared database for example.

The options that are available are:

v Deploy UDDI into a standalone server , as described in this Information Center (using uddiDeploy), and
then create a cluster using that server as a template for the other members.
v If using an cluster that already exists, you can use the admin console or wsadmin for example (and not
uddiDeploy.jacl), to deploy the uddi.ear across the cluster members, but follow the additional advice in
the main instructions.

Changing from a base application server to a Network Deployment cell.

It is possible to move from a base application server to a network deployment cell using the standard
addNode command. During the move, any applications may be lost unless you use the -includeapps
option. This applies to all applications and not just UDDI applications. See the addNode command for
details. This applies to a default or a user customized UDDI node.

Moving from a default UDDI node to a user customized UDDI node.

After testing the UDDI deployment in a default UDDI node, you can move to a user customized node by
recreating the database using the instructions in Setting up a customized UDDI node, but you must be
aware that any data saved in the default node (both policies, properties and user data) will be lost in the
move.

Moving between Cloudscape, DB2 and Oracle databases.

If you decide to move between one type of database to another, the datasource of the old database will
still have a JNDI name of datasources/uddids. You must either rename this JNDI name to something
different, or delete the datasource before you define the new database, create the new datasource and
initialize the database.

You now have the choice of a default UDDI node, or a user customized UDDI node.

Setting up a customized UDDI node

You can set up a customized UDDI node by completing the following steps:
1. Create a database schema to hold the UDDI registry by executing one of the following:
v Creating a DB2 database
v Creating an Oracle database
v Creating a Cloudscape database

Chapter 8. Developing WebSphere applications 1181

 Note: You must not run the final step to set the default node indicator in the database.
2. Create a J2C Authentication Data Entry (not required for Cloudscape):
a. Expand Global Security and JAAS Configuration (on the right), then click on J2C
Authentication Data
b. Select New to create a new J2C authentication data entry
c. Fill in the details as follows:
Alias a suitable (short) name, such as ″UDDIAlias″
Userid
the database userid, which is used to read and write to the UDDI registry database.
Password
The password associated with the userid specified above.
Description
a suitable description to describe the chosen userid.
Click ’Apply’ and then Save the changes to the master configuration
3. Create a JDBC Provider (if a suitable one does not already exist):
v For DB2, select the options DB2 Legacy CLI-based Type 2 JDBC Driver and Connection Pool
datasource.
v For Oracle, select the options Oracle JDBC Driver and Connection Pool datasource.
v For Cloudscape, select the Cloudscape JDBC Driver and Connection Pool datasource.
For details on how to create a JDBC provider, see Creating and configuring a JDBC provider using the
administrative console.
4. Create a datasource for the UDDI Registry by following these steps:
a. Expand Resource and JDBC Providers
b. Select the desired ’scope’ of the JDBC provider you selected or created earlier. For example,
select:
Server: yourservername
This displays the JDBC providers at the server level.
c. Select the JDBC provider created earlier.
d. Under Additional Properties, select Data Sources (not the Data Sources Version 4 option)
e. Select ’New’ to create a new datasource
f. Fill in the details for the datasource as follows:
Name a suitable name, such as UDDI Datasource
JNDI name
set to datasources/uddids - this value is obligatory.

Note: You must not have any other datasources using this JNDI name. If you have another
datasource using this JNDI name, then you must either remove it or change its JNDI
name. For example, if you have previously created a default UDDI node using
Cloudscape, you should use the uddiRemove.jacl script with the default option to
remove the datasource and the UDDI application instance, before continuing.
Description
a suitable description
Category
set to uddi
Data store helper class name
filled in for you as:

1182 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v for DB2 - com.ibm.websphere.rsadapter.DB2DataStoreHelper
v for Oracle 9i - com.ibm.websphere.rsadapter.OracleDataStoreHelper
v for Oracle 10g - com.ibm.websphere.rsadapter.Oracle10gDataStoreHelper
v for Cloudscape - com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper
Relational Database Management System data source properties
v for DB2 - Database name - for example:
UDDI30
v for Oracle - URL - for example:
jdbc:oracle:oci8:@<Oracle database name>
v for Cloudscape - Database name - for example:
${USER_INSTALL_ROOT}/databases/com.ibm.uddi/UDDI30
Component-managed authentication alias
v for DB2, select the alias that you created in step 3 from the pulldown. It will have the
node name appended in front of it, for example MyNode/UDDIAlias.
v for Oracle, select the alias that you created in step 3 from the pulldown. It will have the
node name appended in front of it, for example MyNode/UDDIAlias.
v for Cloudscape leave this set to (none).
Container-managed authentication alias
Set to DefaultPrincipalMapping
Mapping-configuration alias
Set to (none)
g. Use this Data Source in container-managed persistence (CMP), and ensure it is unchecked.
5. Test the connection to your UDDI database by clicking on the ″Test Connection″ button for the
datasource. You will see a message similar to ″Test Connection for datasource UDDI Datasource on
server server1 at node MyNode was successful″. If you do not see this message investigate the
problem with the help of the error message.
6. Deploy the UDDI Registry into the server by running the uddiDeploy.jacl command from a command
prompt as shown.
This file is located in
WAS_HOME/bin
The syntax of the command is:
wsadmin [-conntype none] -f uddiDeploy.jacl <node> <server>
where:
-conntype none
is optional, and is only needed if the application server is not running.
<node>
the name of the WebSphere node on which the target server runs. Note that the node name is
case sensitive.
<server>
is the name of the target server on which you wish to deploy the UDDI Registry, such as
server1. Note the server name entered is case sensitive.
You are recommended to deploy the UDDI application using the uddiDeploy.jacl, but note that you can
also use the administrative console to deploy the application in the normal way. If you use the
administrative console you must ensure that the Classloader Mode for the application is set to
PARENT_LAST, and that the WAR class loader Policy is set to Application. The uddiDeploy.jacl
command in a command prompt will do this for you.

Chapter 8. Developing WebSphere applications 1183

 For example, to deploy UDDI on node ’MyNode’ and server ’server1’ on a Windows system you might
enter the following (assuming that server1 is already started):
wsadmin -f uddiDeploy.jacl MyNode server1
You should now start the UDDI application, or start the application server if it is not already running.

As you have chosen a user customized UDDI node, you will need to set up the properties for the UDDI
node using UDDI administration, and initialize the node before it is ready to accept UDDI requests (see
″Configuring the UDDI Registry Application″ in the information center for details).

Setting up a default UDDI node

There are two ways to setup a default UDDI node:
v Either by executing the uddiDeploy.jacl script and specifying the default option. This creates a running
default UDDI node within a Cloudscape database, or
v Executing an additional step after you have created your database.

Run one of the following

1. Optional: For a default Cloudscape UDDI node:
For a default Cloudscape configuration Network Deployment read the section ’Installing into a Network
Deployment Cell’ first.
Deploy the UDDI Registry by running the uddiDeploy.jacl script from a command prompt as shown.
This file is located in
WAS_HOME/bin
The syntax of the command is (shown here on 2 lines for publication):
wsadmin [-conntype none] -wsadmin_classpath WAS_HOME/cloudscape/lib -f
uddiDeploy.jacl <node> <server> default
where:
-conntype none
is optional, and is only needed if the application server is not running.
WAS_HOME
is the directory name of the WebSphere Application Server install location
<node>
is the name of the WebSphere node on which the target server runs. Note that the node name
is case sensitive.
<server>
is the name of the target server on which you wish to deploy the UDDI Registry, such as
server1. Note the server name entered is case sensitive.
default
using the ’default’ option causes the command to create a UDDI node, with default policies
within a Cloudscape database and datasource. This is a special case only for Cloudscape and
creates everything required to run a UDDI node, in a standalone application server.
For example, to create a UDDI node called ’MyNode’ on server ’server1’ on a Windows system, you
might enter the following (this assumes server1 is started). The command is shown on 2 lines for
publication.
wsadmin -wsadmin_classpath C:\Progra~1\IBM\WebSphere\AppServer\cloudscape\lib
-f uddiDeploy.jacl MyNode server1 default
If the server is not started the command is (shown here on 2 lines for publication):
wsadmin -conntype none -wsadmin_classpath C:\Progra~1\IBM\WebSphere\AppServer\cloudscape\lib
-f uddiDeploy.jacl MyNode server1 default
(Note that these should be entered as one command on a single line)

1184 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 You should now start the UDDI application, or start the application server if it is not already running.
2. Optional: For a default DB2, default Cloudscape or default Oracle UDDI node:
DB2, Cloudscape or Oracle may be used for a single application server installation or a Network
Deployment installation.
a. Initially you need to define some resources and run some scripts to set up the database. Go to
Creating the DB2 database, Creating the Cloudscape databaseor Creating the Oracle database to
create and load the database, ensuring you have run the final step to set the default node indicator
in the database, and return to this point. You must create a JDBC Provider if a suitable one does
not already exist or select one, and a Datasource to reference the UDDI database.
v For DB2, select the ’DB2 Legacy CLI-based Type 2 JDBC Driver’ option and Connection Pool
datasource option.
v When using Oracle ensure you select ’Oracle JDBC Driver’ and the Connection Pool datasource
option.
v For Cloudscape, select the supplied Cloudscape JDBC Driver
v Refer to Creating and configuring a JDBC provider using the administrative console for details
on how to create a JDBC Provider.
b. Create a J2C Authentication Data Entry for DB2 or Oracle access (not required for Cloudscape)
using the WebSphere Application Server administrative console by following these steps:
1) Expand ’Global Security’ and ’JAAS Configuration’ and click on ’J2C Authentication Data
Entries’
2) Select ’New’ to create a new J2C authentication data entry
3) Fill in the details as follows:
Alias a suitable (short) name, such as UDDIAlias
Userid
your DB2 userid, such as db2admin, or your Oracle userid, such as SYSTEM.
Password
The password associated with your userid.
Description
a suitable description
Click ’Apply’ and then Save the changes to the master configuration
c. Create a datasource for the UDDI Registry by following these steps:
1) Expand ’Resource’ and ’JDBC Providers’
2) Select the desired ’scope’ of the JDBC provider created earlier. For example, select:
Server: yourservername
to show the JDBC providers at the server level.
3) Select your DB2 or Oracle JDBC provider as selected or created earlier
4) Under ’Additional Properties’, select ’Data Sources’ (not the Data Sources Version 4 option)
5) Select ’New’ to create a new datasource
6) Fill in the details for the datasource as follows:
Name a suitable name, such as UDDI Datasource
JNDI name
set to datasources/uddids - this value is obligatory.

Note: Note that you must not have any other datasources using this JNDI name. If you
have another datasource using this JNDI name, then you must either remove it
or change its JNDI name. For example, if you have previously created a default

Chapter 8. Developing WebSphere applications 1185

 UDDI node using Cloudscape, you should use the uddiRemove.jacl script with
the default option to remove the datasource and the UDDI application instance
before continuing.
Description
a suitable description
Category
set to uddi
Data store helper class name
filled in for you as:
v for DB2 - com.ibm.websphere.rsadapter.DB2DataStoreHelper
v for Oracle 9i - com.ibm.websphere.rsadapter.OracleDataStoreHelper
v for Oracle 10g - com.ibm.websphere.rsadapter.Oracle10gDataStoreHelper
v for Cloudscape - com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper
Relational Database Management System data source properties
v for DB2 - Database name - for example:
UDDI30
v for Oracle - URL - for example:
jdbc:oracle:oci8:@<Oracle database name>
v for Cloudscape - Database name - for example:
${USER_INSTALL_ROOT}/databases/com.ibm.uddi/UDDI30
Component-managed authentication alias
v for DB2, select the alias that you created in step 3 from the pulldown. It will have the
node name appended in front of it, for example MyNode/UDDIAlias.
v for Oracle, select the alias that you created in step 3 from the pulldown. It will have
the node name appended in front of it, for example MyNode/UDDIAlias.
v for Cloudscape leave this set to (none).
Container-managed authentication alias
select the alias that you created earlier from the pulldown. It will have the node name
appended in front of it, for example MyNode/UDDIAlias.
Mapping-configuration alias
set to DefaultPrincipleMapping from the pulldown (this might already be filled in).
Leave all other fields unchanged.
Click ’Apply’ and Save the changes to the master configuration.
d. Test the connection to your UDDI database by clicking on the ″Test Connection″ button for the
datasource. You will see a message similar to ″Test Connection for datasource UDDI Datasource
on server server1 at node MyNode was successful″. If you do not see this message investigate the
problem with the help of the error message.
e. Deploy the UDDI Registry into the server by running the uddiDeploy.jacl script from a command
prompt as shown.
This file is located in
WAS_HOME/bin
The syntax of the command is:
wsadmin [-conntype none] -f uddiDeploy.jacl <node> <server>
where:
-conntype none
is optional, and is only needed if the application server is not running.

1186 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 <node>
the name of the WebSphere node on which the target server runs. Note that the node
name is case sensitive.
<server>
is the name of the target server on which you wish to deploy the UDDI Registry, such as
server1. Note the server name entered is case sensitive.
You are recommended to deploy the UDDI application using the uddiDeploy.jacl, but note that you
can also use the administrative console to deploy the application in the normal way. If you use the
administrative console you must ensure that the Classloader Mode for the application is set to
PARENT_LAST, and that the WAR class loader Policy is set to Application. The uddiDeploy.jacl
command in a command prompt will do this for you.
For example, to deploy UDDI on node ’MyNode’ and server ’server1’ on a Windows system you
might enter the following (assuming that server1 is already started):
wsadmin -f uddiDeploy.jacl MyNode server1
You should now start the UDDI application, or start the application server if it is not already
running.

As you have chosen to use a default UDDI node, it will be initialized when the UDDI application is started
for the first time.

Creating a DB2 database

Perform this task if you want to use DB2 as the database store for your UDDI Registry data. You only
need do this once for each UDDI Registry, as part of Setting up and deploying a UDDI Registry.

Before you begin

The steps below use a number of variables for which you need to enter appropriate values. You should
decide the values that you will use before you start. The variables used, and suggested values are:
<DataBaseName>
is the name of the UDDI Registry database. A recommended value is UDDI30, and this name is
assumed throughout the UDDI documentation. If you use some other name, then you should
substitute that name whenever you see ’UDDI30’ in other sections of the documentation.
<DB2UserID>
is a DB2 userid with administrative privileges.
<DB2Password>
is the password for the DB2 userid.
<BufferPoolName>
is the name of a buffer pool to be used by the UDDI Registry database. A suggested name is
uddibp, but any name can be used, as the buffer pool is created as part of this task.
<TableSpaceName>
is the name of a table space. A suggested value is uddits, but any name can be used.
<TempTableSpaceName>
is the name of a temporary table space. A suggested value is udditstemp, but any name can be
used, as the temporary table space is created as part of this task.

To create the DB2 database follow the steps shown below:

1. Run the following commands to setup the DB2 environment variables from the DB2 Command Line
Processor (that is, at a prompt which requires db2 to be entered before each command):
a. Not required for DB2 Vesion 8 and onwards: db2set DB2_INDEX_2BYTEVARLEN=YES
b. db2set DB2CODEPAGE=1208
2. Create the DB2 database by entering the following command from the DB2 Command Line Processor:

Chapter 8. Developing WebSphere applications 1187

 a. db2 create database <DataBaseName> using codeset UTF-8 territory en where
<DataBaseName> is the name of the database being created.
3. Configure the DB2 database by entering the following commands from the DB2 Command Line
Processor:
a. db2 connect to <DataBaseName> user <DB2UserID> using <DB2Password>
b. db2 update db cfg for <DataBaseName> using applheapsz 2048
c. db2 update db cfg for <DataBaseName> using logfilsiz 8192
d. db2 connect reset
e. db2 terminate
4. Create additional database structures by entering the following commands from the DB2 Command
Line Processor:
a. db2 connect to <DataBaseName> user <DB2UserID> using <DB2Password>
b. db2 create bufferpool <BufferPoolName> size 250 pagesize 32K
c. db2 connect reset
d. db2 terminate
e. db2 force application all
f. db2 terminate
g. db2stop
h. db2start
5. Create further database structures by entering the following commands from the DB2 Command Line
Processor:
a. db2 connect to <DataBaseName> user <DB2UserID> using <DB2Password>
b. db2 create regular tablespace uddits pagesize 32K managed by system using
(’<TableSpaceName>’) extentsize 64 prefetchsize 32 bufferpool <BufferPoolName>
c. db2 create system temporary tablespace <TempTableSpacename> pagesize 32K managed by
system using (’<TempTableSpacename>’) extentsize 32 overhead 14.06 prefetchsize 32
transferrate 0.33 bufferpool <BufferPoolName>
6. Enter the following commands exactly as shown (noting in particular one step uses -vf rather than -tvf)
into a DB2 Command Window to define the database structures needed to store the UDDI data
(before running these commands change dirstory to WAS_HOME/UDDIReg/databaseScripts):
a. db2 -tvf uddi30crt_10_prereq_db2.sql
b. db2 -tvf uddi30crt_20_tables_generic.sql
c. db2 -tvf uddi30crt_25_tables_db2udb.sql
d. db2 -tvf uddi30crt_30_constraints_generic.sql
e. db2 -tvf uddi30crt_35_constraints_db2udb.sql
f. db2 -tvf uddi30crt_40_views_generic.sql
g. db2 -tvf uddi30crt_45_views_db2udb.sql
h. db2 -vf uddi30crt_50_triggers_db2udb.sql
i. db2 -tvf uddi30crt_60_insert_initial_static_data.sql
7. This last step should only be run if you want your database to be used as a default UDDI node.
a. Enter the following command from the DB2 Command Line Window: db2 -tvf
uddi30crt_70_insert_default_database_indicator.sql

Continue with setting up and deploying your UDDI Registry node.

Creating an Oracle database

Perform this task if you want to use Oracle as the database store for your UDDI Registry data. You need
only do this once for each UDDI registry, as part of Setting up and deploying a UDDI Registry.

1188 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Note: Only Version 9i1 and Oracle 10g2

Before you begin

Note that this task will create two new schemas, ibmudi30 and ibmuds30. You will be unable to complete
this task if you already have existing schemas of those names.

The steps below use a number of variables for which you need to enter appropriate values. You should
decide the values that you will use before you start. The variables used, and suggested values are:
<OracleUserID>
is the Oracle userid to be used to create the database.
<OraclePassword>
is the password for the Oracle userid.
1. Run the following commands:
a. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_10_prereq_oracle.sql
b. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_20_tables_generic.sql
c. Complete one of the two following actions depending on your level of Oracle:
v For Version 10g and later:
sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_25_tables_oracle.sql
v For Oracle 9i:
sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_25_tables_oracle_pre10g.sql
d. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_30_contraints_generic.sql
e. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_35_constraints_oracle.sql
f. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_40_views_generic.sql
g. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_45_views_oracle.sql
h. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_50_triggers_oracle.sql
i. sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_60_insert_initial_static_data.sql
2. This last command should only be run if you want the database to be used as a default UDDI node.
sqlplus <OracleUserID>/<OraclePassword> @ uddi30crt_70_insert_default_database_indicator.sql

Continue with setting up and deploying your UDDI Registry node.

Creating a Cloudscape database

Perform this task if you want to use Cloudscape as the database store for your UDDI Registry, and you do
not want to use the default option on uddiDeploy.jacl (see ’Setting up a default UDDI node’). The most
likely reasons for not using the default option on uddiDeploy.jacl are that you want to set up a customized

1.
Restrictions:
discoveryURL (Business) maximum 4000 bytes, UDDI specification 4096 characters; accessPoint (bindingTemplate)
maximum 4000 bytes), UDDI Specification 4096 characters; instacneParms (tModelInstanceInfo) maximum 4000 bytes,
UDDI specification 8192 characters; overviewURL (tModelInstanceInfo) maximum 4000 bytes, UDDI specification 4096
characters; Digital Signature maximum 4000 bytes.

2.
Restrictions:
discoveryURL (business) maximum 4000 bytes, UDDI specification 4096 characters.

Chapter 8. Developing WebSphere applications 1189

UDDI node, or that you are deploying UDDI into a Network Deployment cell. You need only perform this
task once for each UDDI Registry, as part of the Setting up and deploying a UDDI Registry.

The commands below use a number of arguments for which you need to enter appropriate values. You
should decide the values that you will use before you start. The arguments used, and suggested values,
are:
arg1 is the path of the SQL files, which on a standard install will be
WAS_HOME/UDDIReg/databasescripts
arg2 is the path to the location where you want to install the Cloudscape database, such as
WAS_HOME/databases/com.ibm.uddi
arg3 is the name of the Cloudscape database. A recommended value is UDDI30, and this name is
assumed throughout the UDDI documentation. If you use some other name, you should substitute
that name whenever you see ’UDDI30’ in other sections of the UDDI documentation.
arg4 is an optional argument, and must either be omitted or be the string ’DEFAULT’. DEFAULT should
only be specified if you want your database to be used as a default UDDI node. Note that this
argument is case sensitive.

Run the following java -jar command to create a UDDI Cloudscape database using
UDDICloudscapeCreate.jar, which is created in WAS_HOME/Lib directory.
1. On Solaris and HP-UX platforms:
java -Djava.ext.dirs=WAS_HOME/cloudscape/lib:WAS_HOME/java/lib/ext -jar
UDDICloudscapeCreate.jar arg1 arg2 arg3 arg4
2. On all other platforms:
java -cp WAS_HOME/cloudscape/lib/db2j.jar -jar UDDICloudscapeCreate.jar arg1 arg2 arg3 arg4

Continue with setting up and deploying your UDDI Registry node.

Using a remote database for the UDDI Registry

It is possible for the UDDI Registry database to be hosted on a separate system (remote system) from the
system on which the UDDI Registry application is deployed.

This is achieved using standard database capabilities of the database product used for the UDDI Registry
database. You should refer to documentation for the database product if you are not familiar with these
capabilities. Some considerations specific to each database product are:

Remote DB2

Create a DB2 UDDI database on the remote system, and use the DB2 Client to create an alias to
reference it. Use the alias name as the Database name in the UDDI datasource.

Remote Oracle

Create the Oracle tables used for an Oracle UDDI database on the remote system, and use the URL
property of the UDDI datasource to reference the remote Oracle instance.

Networked Cloudscape

Create a Cloudscape UDDI database on the remote system, and use the Cloudscape Network Server
using Universal data source properties (Database name, Server name and Port number) of the UDDI
datasource to reference the remote Cloudscape database.

1190 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
UDDI Registry Installation Verification Program (IVP)
This topic describes a simple test that you can carry out as an Installation Verification Program (IVP) to
verify that you have deployed a UDDI Registry successfully. You should perform this task after you have
followed the instructions in Setting up and Deploying a new UDDI Registry.

Open a browser window and enter the URL to access the UDDI Registry User Interface. Under the ’Quick
Find’ heading on the Find tab, select the ’Business’ radio button and enter ’%’ in the box. Click the ’Find’
button, and you should see the business displayed in the detail frame which will be this UDDI node’s
business entity. You can click on the listed business in order to see its detail.

If you see a business listed in the detail frame, your UDDI Registry has been deployed successfully.

As a further IVP, you can publish and find more UDDI entities by using the UDDI Registry User Interface,
or you can compile and run one or more of the UDDI Registry Samples.

Publishing WSDL files

To publish a Web Services Description Language (WSDL) file you need an enterprise application, also
known as an enterprise archive (EAR) file, that contains a Web services-enabled module and has been
deployed into WebSphere Application Server. See Deploying Web services based on Web Services for
Java 2 platform, Enterprise Edition (J2EE).

The purpose of publishing the WSDL file is to provide clients with a description of the Web service,
including the URL identifying the location of the service.

After installing a Web services application, and optionally modifying the endpoint information, you might
need WSDL files containing the updated endpoint information. You can obtain the updated WSDL files by
publishing them to the file system. If you are a client developer or a system administrator, you can use
WSDL files to enable clients to connect to a Web service.

Before you publish a WSDL file, you can configure Web services to specify endpoint information in the
form of URL fragments to enable full URL specification of WSDL ports. Refer to the tasks describing
configuring endpoint URL information.

The WSDL files for each Web services-enabled module are published to the file system location you
specify. You can provide these WSDL files to clients that want to invoke your Web services.

You can specify endpoint information for HTTP ports, Java Message Service (JMS) ports or directly access
enterprise JavaBeans (EJBs) that are acting as Web services.

To publish a WSDL file:

1. Configure the URL endpoint information. Do one of the following depending on what kind of bindings
you are using:
v Configure the URL endpoint information for HTTP bindings.
v Configure the URL endpoint information for JMS bindings.
v Configure the URL endpoint information to directly access enterprise beans.
2. Externalize or publish the WSDL file out of the application. You can complete this task in one of three
ways:
v Publish a WSDL file with the administrative console
v Publish a WSDL file through a URL.
v Publish a WSDL file with the wsadmin command tool.

Apply security to the Web service.

Chapter 8. Developing WebSphere applications 1191

WSDL
Web Services Description Language (WSDL) is an Extensible Markup Language (XML)-based description
language. This language was submitted to the World-Wide Web Consortium (W3C) as the industry
standard for describing Web services. The power of WSDL is derived from two main architectural
principles: the ability to describe a set of business operations and the ability to separate the description
into two basic units. These units are a description of the operations and the details of how the operation
and the information associated with it are packaged.

A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract
definition of endpoints and messages is separated from their concrete network deployment or data format
bindings. This separation supports the reuse of abstract definitions: messages, which are abstract
descriptions of exchanged data, and port types, which are abstract collections of operations. The concrete
protocol and data format specifications for a particular port type constitutes a reusable binding. A port is
defined by associating a network address with a reusable binding, and a collection of ports define a
service. Therefore, a WSDL document is composed of several elements. See WSDL architecture for more
information and examples of the WSDL elements.

When creating Web services for WebSphere Application Server, you must first have an implementation
bean that includes a service endpoint interface. Then, you use the Java2WSDL command-line tool to
create a WSDL file that defines the Web services. To learn more about how the WSDL file is used in the
development process, see Developing Web services.

WSDL architecture
Web Services Description Language (WSDL) files are written in Extensible Markup Language (XML). To
learn more about XML, see Web services: Resources for learning.

The following is the structure of the information in a WSDL file:

Port type Operation signatures

Web service
Messages Parameter definitions
interface
definition
Types Complex type definitions

Bindings Transport protocol and payload format

Service Service definition element

Web service
implementation
Ports Supported interface bindings

A WSDL file contains the following parts:

v Web service interface definition
This is part contains the elements, as well as the namespaces.
v Web service implementation
This part contains the definition of the service and ports.

A WSDL file describes a Web service with the following elements:

1192 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
portType

The description of the operations and associated messages. The portType element defines abstract
operations.
<portType name="EightBall">
<operation name="getAnswer">
<input message="ebs:IngetAnswerRequest"/>
<output message="ebs:OutgetAnswerResponse"/>
</operation>
</portType>

message

The description of input and output parameters and return values.

<message name="IngetAnswerRequest">
<part name="meth1_inType" type="ebs:questionType"/>
</message>
<message name="OutgetAnswerResponse">
<part name="meth1_outType" type="ebs:answerType"/>
</message>

types

The schema for describing XML types used in the messages.

<types>
<xsd:schema targetNamespace="...">
<xsd:complexType name="questionType">
<xsd:element name="question" type="string"/>
</xsd:complexType>
<xsd:complexType name="answerType">
...
</types>

binding

The bindings describe the protocol that is used to access a portType, as well as the data formats for the
messages that are defined by a particular portType element.
<binding name="EightBallBinding" type="ebs:EightBall">
<soap:binding style="rpc" transport="schemas.xmlsoap.org/soap/http">
<operation name="ebs:getAnswer">
<soap:operation soapAction="urn:EightBall"/>
<input>
<soap:body namespace="urn:EightBall" ... />
...

The services and ports define the location of the Web service.

Service

The service contains the Web service name and a list of ports.

Ports

The ports contain the location of the Web service and the binding used for service access.
<service name="EightBall">
<port binding="ebs:EightBallBinding" name="EightBallPort">
<soap:address location="localhost:8080/axis/EightBall"/>
</port>
</service>

Chapter 8. Developing WebSphere applications 1193

Multipart WSDL best practices
WebSphere Application Server supports deployment of Web services using a multipart Web Services
Description Language (WSDL) file. In multipart WSDL files, an implementation WSDL file contains the
wsdl:service. This implementation WSDL flie imports an interface WSDL file, which contains the other
WSDL constructs. This supports multiple Web services using the same WSDL interface definition.

The <wsdl:import> element indicates a reference to another WSDL file. If the <wsdl:import> element
location attribute does not contain a URL, that is, it contains only a file name, and does not begin with
http://, https:// or file://, the imported file must be located in the same directory and must not
contain a relative path component. For example, if META-INF/wsdl/A_Impl.wsdl is in your module and
contains the <wsdl:import=″A.wsdl″ namespace=″...″/> import statement, the A.wsdl file must also be
located in the module META-INF/wsdl directory.

It is recommended that you place all WSDL files in either the META-INF/wsdl directory, if you are using
Enterprise JavaBeans (EJB), or the WEB-INF/wsdl directory, if you are using JavaBeans components, even
if relative imports are located within the WSDL files. Otherwise, implications exist with the WSDL
publication when you use a path like <location=″../interfaces/A_Interface.wsdl″namespace=″...″/>.
Using a path like this example fails because the presence of the relative path, regardless of whether the
file is located at that path or not. If the location is a Web address, it must be readable at both deployment
and server startup.

WSDL publication

You can publish the files located in the META-INF/wsdl or the WEB-INF/wsdl directory through either a URL
address or file, including WSDL or XSD files. For example, if the file referenced in the <wsdl-file> element
of the webservices.xml deployment descriptor is located in the META-INF/wsdl or the WEB-INF/wsdl
directory, it is publishable. If the files imported by the <wsdl-file> are located in the wsdl/ directory or its
subdirectory, they are publishable.

If the WSDL file referenced by the <wsdl-file> element is located in a directory other than wsdl, or its
subdirectories, the file and its imported files, either WSDL or XSD files, which are in the same directory,
are copied to the wsdl directory without modification when the application is installed. These types of files
can also be published.

If the <wsdl-file> imports a file located in a different directory (a directory that is not -INF/wsdl or a
subdirectory), the file is not copied to the wsdl directory and not available for publishing.

Configuring endpoint URL information for JMS bindings

WebSphere Application Server supports the use of the Java Message Service (JMS) API to transport Web
services requests, as an alternative to using HTTP.

Review the topic Using the Java Message Service to transport Web services requests.

Configuring a service endpoint is necessary to connect Web service clients to any Web services among
the components being assembled or to any external Web services. You can configure the endpoint URL
information for JMS during application installation

In this task, enter the JMS endpoint URL prefix to use for each Web service-enabled enterprise JavaBean
(EJB) Java archive (JAR) file that belong to the application. The JMS endpoint URLs are included in the
Web Service Description Language (WSDL) files published for clients to use.

You can specify HTTP URL prefixes for Web services that are accessed through HTTP by using the
Provide HTTP endpoint URL information panel in the administrative console. These prefixes are used to
form complete endpoint addresses that are included in WSDL files when published.

1194 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
You can specify JMS URL prefixes by using the Provide JMS and EJB endpoint URL information panel in
the administrative console during or after application installation.

To configure JMS URL prefixes:

1. Open the administrative console.
2. Click Applications > Enterprise Applications > application_instance > Provide JMS and EJB
endpoint URL information.
3. Locate the list of Web services modules that are accessible through JMS transport.
4. Type the JMS URL fragment in the URL fragment field. Enter a URL fragment that is a prefix to the
initial URL part that is obtained by examining the deployment information of the Web service. See the
usage scenario following this task for more information.
The value that you enter is used to define the location attribute of the port soap:address element within
the WSDL file that is published using the application_name_ExtendedWSDLFiles.zip or the
application_name_WSDLFiles.zip file on the Publish WSDL zip files panel.

You have a Web service that is accessible through the JMS transport and configured with JMS bindings.

Suppose an application called StockQuoteService contains an EJB JAR file that is named StockQuoteEJB,
which contains one or more Web services that are accessible through the JMS transport. In Using the
Java Message Service to transport Web services requests you defined a queue with the Java Naming and
Directory Interface (JNDI) name of jms/StockQuote_Q, and a connection factory with the JNDI name of
jms/StockQuote_CF, for your application. In this example, you specify the following string as the JMS URL
prefix within the Provide JMS and EJB endpoint URL information panel:
jms:/queue?destination=jms/StockQuote_Q&connectionFactory=jms/StockQuote_CF

The WSDL publisher uses this partial URL string to produce the actual JMS URL for each port component
that is defined in the module. The targetService=<port_name> string is added to the end of the JMS URL,
for example:
jms:/queue?destination=jms/StockQuote_Q&connectionFactory=jms/
StockQuote_CF&targetService=getQuote

The published WSDL file is used by clients to invoke the Web service.

Publish WSDL files.

Provide JMS and EJB endpoint URL information

Use this page to specify endpoint URL fragments for Web services accessed through SOAP and Java
Message Service (JMS) or directly as enterprise JavaBean (EJBs). Fragments are used to form complete
endpoint addresses included in published Web Services Description Language (WSDL) files.

To view this administrative console page, click Applications >Enterprise Applications >
application_instance > Provide JMS and EJB endpoint URL information.

You can specify a fragment of the endpoint URL to be used in each Web service module. In a published
WSDL file, the URL defining the target endpoint address is found in the location attribute of the port’s
soap:address element.

If you are using Web services modules that are configured to use JMS or configured to access EJBs
directly, these modules are listed on this panel.

URL fragment for JMS:

Specifies a URL fragment for Web services accessed through a JMS transport. You can enter a value that
is used to define the soap:address of a Web service. When WSDL files are published, a URL is formed
using this fragment and is contained in the WSDL files.

Chapter 8. Developing WebSphere applications 1195

The URL fragment that is entered as a value is a prefix to which the targetService=property is appended
to form a complete JMS URL endpoint. The default value is obtained by examining the installed service’s
deployment information, for example, jms:/queue?destination=jms/MyQueue&connectionFactory=jms/MyCF.

This information is obtained from the Web service’s configured JMS endpoint, which is a Message Driven
Bean (MDB) defined by the endpointEnabler command-line tool. You can modify the URL fragment, for
example, by adding properties. The URL fragment is combined with the targetService property to form the
complete URL, for example,
jms:/queue?destination=jms/MyQueue&connectionFactory=jms/MyCF&priority=5&targetService=GetQuote.

URL fragment for EJB:

Specifies a URL fragment for Web services accessed through an EJB binding. You can enter a value used
to define the location attribute of the port’s generic:address element of a Web service. This port address
is contained in the WSDL zip file when the zip file is published using the
application_name_ExtendedWSDLFiles.zip field on the Publish WSDL zip file panel.

The URL fragment value entered is a suffix, which is appended to the initial part of the URL obtained by
examining the Web service’s deployment information. For example, the following URL fragment can be
obtained from the EJB’s deployment information:
wsejb:/com.acme.sample.MyStockQuoteHome?jndiName=ejb/MyStockQuoteHome.

In this case, you can enter the following information in the URL fragment field,
jndiProviderURL=corbaloc:iiop:myhost.mycompany.com:2809, which results in this endpoint URL,
wsejb:/com.acme.sample.MyStockQuoteHome?jndiName=ejb/MyStockQuoteHome&jndiProviderURL=

corbaloc:iiop:myhost.mycompany.com:2809.

Configuring Web services applications with the wsadmin tool

You can use the wsadmin scripting tool to complete the several tasks for a Web services application.

Develop a Web services application.

The WebSphere Application Server wsadmin tool provides the ability to run scripts. You can use the
wsadmin tool to manage a WebSphere Application Server installation, as well as configuration, application
deployment, and server run-time operations. The WebSphere Application Server only supports the Jacl
and Jython scripting languages.

To use the wsadmin tool to configure a Web services application or publish a Web Services Description
Language (WSDL) file:
1. Launch a scripting command.
2. Follow the steps in one of the following topics, depending on what task you want to complete:
v Configure Web service client bindings.
v Configure Web service client preferred port mappings .
v Configure Web service client port information .
v Configure the scope of a Web service port .

You have configured Web services applications with the wsadmin tool.

WSIF system management and administration

The Web Services Invocation Framework (WSIF) is provided as a stand-alone JAR file named wsif.jar.
The JAR file contains the core WSIF classes, and the Java, EJB, SOAP over HTTP and SOAP over JMS
providers. Additional providers are packaged as separate JAR files.

1196 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
When you install WebSphere Application Server, the wsif.jar file is put on the WebSphere or Java Virtual
Machine (JVM) class path.

WSIF requires no further configuration. WSIF is a thin abstraction layer between application code and the
relevant invocation infrastructure.

For specific information on other aspects of managing your WSIF system, see the following topics:
v Maintaining the WSIF properties file
v Enabling security for WSIF
v Trace and logging for WSIF
v Troubleshooting the Web Services Invocation Framework
v WSIF (Web Services Invocation Framework) messages
v WSIF - Known restrictions.

Maintaining the WSIF properties file

The Web Services Invocation Framework (WSIF) properties are stored in the wsif.jar file, in a properties
file named wsif.properties.

The wsif.jar file is located in the install_root/lib directory, where install_root is the root directory for
your installation of IBM WebSphere Application Server.

You must keep the “as shipped” wsif.properties file on the class path, so that WSIF can find it and the
client administrator can use it to configure WSIF. However if you make any changes to the file, you do not
replace the original copy in the wsif.jar file. Instead, you save the modified version in the
install_root/lib/properties directory.

Here is a copy of the initial contents of the wsif.properties file. All the possible properties are listed and
described.
# Two properties are used to override which WSIFProvider is selected when there
# exists multiple providers supporting the same namespace URI. These properties are:
#
# wsif.provider.default.CLASSNAME=N
# wsif.provider.uri.M.CLASSNAME=URI
#
# CLASSNAME is the WSIFProvider class name
# N is the number of following default wsif.provider.uri.M.CLASSNAME properties
# M is a number from 1 to N to uniquely identify each wsif.provider.uri.M.CLASSNAME
# property key.
# For example the following two properties would override the default SOAP provider
# to be the Apache SOAP provider:
#
# wsif.provider.default.org.apache.wsif.providers.soap.ApacheSOAP.WSIFDynamicProvider_ApacheSOAP=1
# wsif.provider.uri.1.org.apache.wsif.providers.soap.ApacheSOAP.WSIFDynamicProvider_ApacheSOAP=\
# http://schemas.xmlsoap.org/wsdl/soap/
#

# maximum number of milliseconds to wait for a response to a synchronous request.

# Default value if not defined is to wait forever.
wsif.syncrequest.timeout=10000

# maximum number of seconds to wait for a response to an async request.

# if not defined on invalid defaults to no timeout
wsif.asyncrequest.timeout=60

To enable your legacy Web services to continue to work with WSIF, you might need to change the default
WSIF SOAP provider back to the former Apache SOAP provider.

Chapter 8. Developing WebSphere applications 1197

Enabling security for WSIF
The Web Services Invocation Framework (WSIF) interacts with a security manager in the following ways:
v WSIF runs in the Java 2 platform, Enterprise Edition (J2EE) security context without modification.
v When WSIF is run under a J2EE container, port implementations can use the security context to pass
on security tokens or credentials as necessary.
v WSIF implementations can automatically convert J2EE security context into appropriate context for
onward services.

For WSIF to interact effectively with the WebSphere Application Server security manager, enable the
following permission in the was.policy file: FilePermission to load the WSDL. This permission is required
when a WSDL file is referred to using the file:// protocol.

Troubleshooting the Web Services Invocation Framework

For information on resolving WebSphere-level problems, see the Troubleshooting and support PDF.

To identify and resolve Web Services Invocation Framework (WSIF)-related problems, you can use the
standard WebSphere Application Server trace and logging facilities. If you encounter a problem that you
think might be related to WSIF, you can check for error messages in the WebSphere Application Server
administrative console, and in the application server stdout.log file. You can also enable the application
server debug trace to provide a detailed exception dump.

A list of the WSIF run-time system messages, with details of what each message means, is provided in
Message reference for WSIF.

A list of the main known restrictions that apply when using WSIF is provided in WSIF - Known restrictions.

Here is a checklist of major WSIF activities, with advice on common problems associated with each
activity:
Create service
Handcrafted WSDL can cause numerous problems. To help ensure that your WSDL is valid, use a
tool such as Rational Application Developer to create your service.
Define transport mechanism
For the Java Message Service (JMS), check that you have set up the Java Naming and Directory
Interface (JNDI) correctly, and created the necessary connection factories and queues.
For SOAP, make sure that the deployment descriptor file dds.xml is correct - preferably by creating
it using Rational Application Developer or similar tooling.
Create client - Java code
Follow the correct format for creating a WSIF service, port, operation and message. For examples
of correct code, see the Address Book Sample.
Compile code (client and service)
Check that the build path against code is correct, and that it contains the correct levels of JAR
files.
Create a valid EAR file for your service in preparation for deployment to a Web server.
Deploy service
When you install and deploy the service EAR file, check carefully any messages given when the
service is deployed.
Server setup and start
Make sure that the WebSphere Application Server server.policy file (in the /properties
directory) has the correct security settings. For more information, see Enabling security for WSIF.
WSIF setup
Check that the wsif.properties file is correctly set up. For more information, see Maintaining the
WSIF properties file.

1198 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Run client
Either check that you have defined the class path correctly to include references to your client
classes, WSIF JAR files and any other necessary JAR files, or (preferably) run your client using
the WebSphere Application Server launchClient tool.

Here is a list of common errors, and information on their probable causes:

v “No class definition” errors received when running client code.
This problem usually indicates an error in the class path setup. Check that the relevant JAR files are
included.
v “Cannot find WSDL” error.
Some likely causes are:
– The application server is not running.
– The server location and port number in the WSDL are not correct.
– The WSDL is badly formed (check the error messages in the application server stdout.log file).
– The application server has not been restarted since the service was installed.
You might also try the following checks:
– Can you load the WSDL into your Web browser from the location specified in the error message?
– Can you load the corresponding WSDL binding files into your Web browser?
v Your Web service EAR file does not install correctly onto the application server.
It is likely that the EAR file is badly formed. Verify the installation by completing the following steps:
– For an EJB binding, run the WebSphere Application Server tool \bin\dumpnamespace. This tool lists
the current contents of the JNDI directory.
– For a SOAP over HTTP binding, open the http://pathToServer/WebServiceName/admin/list.jsp
page (if you have the SOAP administration pages installed). This page lists all currently installed
Web services.
– For a SOAP over JMS binding, complete the following checks:
- Check that the queue manager is running.
- Check that the necessary queues are defined.
- Check the JNDI setup.
- Use the “display context” option in the jmsadmin tool to list the current JNDI definitions.
- Check that the Remote Procedure Call (RPC) router is running.
v There is a permissions problem or security error.
Check that the WebSphere Application Server server.policy file (in the /properties directory) has the
correct security settings. For more information, see Enabling security for WSIF.
v Using WSIF with multiple clients causes a SOAP parsing error.
Before you deploy a Web service to WebSphere Application Server, you must decide on the scope of
the Web service. The deployment descriptor file dds.xml for the Web service includes the following line:
<isd:provider type="java" scope="Application" ......
You can set the Scope attribute to Application or Session. The default setting is Application, and this
value is correct if each request to the Web service does not require objects to be maintained for longer
than a single instance. If Scope is set to Application the objects are not available to another request
during the execution of the single instance, and they are released on completion. If your Web service
needs objects to be maintained for multiple requests, and to be unique within each request, you must
set the scope to Session. If Scope is set to Session, the objects are not available to another request
during the life of the session, and they are released on completion of the session. If scope is set to
Application instead of Session, you might get the following SOAP error:
SOAPException: SOAP-ENV:ClientParsing error, response was:
FWK005 parse may not be called while parsing.;
nested exception is:

[SOAPException: faultCode=SOAP-ENV:Client; msg=Parsing error, response was:

Chapter 8. Developing WebSphere applications 1199

FWK005 parse may not be called while parsing.;
targetException=org.xml.sax.SAXException:
FWK005 parse may not be called while parsing.]
v Using the same names for JMS messaging queues and queue connection factories that run on
application servers on different machines can cause JNDI lookup errors. You should not use the
same names for messaging queues and queue connection factories that run on application servers on
different machines, because WSIF always looks first for JMS destinations locally, and only uses the full
JNDI reference if it cannot find the destination locally. For example, if you run a Web service on a
remote machine, and have an application server running locally that uses the same names for the
messaging queues and queue connection factories, then WSIF will find and use the local queues even
if the remote JNDI destination is provided in full in the WSDL service definition.
v The current WSIF default SOAP provider (the IBM Web Service SOAP provider) does not fully
interoperate with services that are running on the former (Apache SOAP) provider. This restriction
is due to the fact that the IBM Web Service SOAP provider is designed to interoperate fully with a
JAX-RPC compliant Web service, and Apache SOAP cannot provide such a service. To enable
interoperation, modify either your Web service or the WSIF default SOAP provider as described in WSIF
SOAP provider: working with legacy applications.

Trace and logging for WSIF:

If you want to enable trace for the Web Services Invocation Framework (WSIF) API within WebSphere
Application Server, and have trace, stdout and stderr for the application server written to a well-known
location, see ″Enabling trace″ and ″Setting up component trace (CTRACE)″ in the Troubleshooting and
support PDF.

WSIF offers trace points at the opening and closing of ports, the invocation of services, and the responses
from services.

To trace the WSIF API, you need to specify the following trace string:
wsif=all=enabled

WSIF also includes a SimpleLog utility through which you can run trace when using WSIF outside of
WebSphere Application Server. To enable this utility, complete the following steps:
1. Create a file named commons-logging.properties with the following contents:
org.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
org.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
2. Create a file named simplelog.properties with the following contents:
org.apache.commons.logging.simplelog.defaultlog=trace
org.apache.commons.logging.simplelog.showShortLogname=true
org.apache.commons.logging.simplelog.showdatetime=true
3. Put both these files, and the commons-logging.jar file, on the class path.

The SimpleLog uitility writes trace to the System.err file.

WSIF (Web Services Invocation Framework) messages:

This topic contains a list of the WSIF run-time system messages, with details of what each message
means.

WebSphere system messages are logged from a variety of sources, including application server
components and applications. Messages logged by application server components and associated IBM
products start with a unique message identifier that indicates the component or application that issued the
message.

1200 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
For more information about the message identifier format, see the topic Message reference.
WSIF0001E: An extension registry was not found for the element type “{0}”
Explanation: Parameters: {0} element type. No extension registry was found for the element type
specified.
User Response: Add the appropriate extension registry to the port factory in your code.
WSIF0002E: A failure occurred in loading WSDL from “{0}”
Explanation: Parameters: {0} location of the WSDL file. The WSDL file could not be found at the
location specified or did not parse correctly
User Response: Check that the location of the WSDL file is correct. Check that any network
connections required are available. Check that the WSDL file contains valid WSDL.
WSIF0003W: An error occurred finding pluggable providers: {0}
Explanation: Parameters: {0} specific details about the error. There was a problem locating a
WSIF pluggable provider using the J2SE 1.3 JAR file extensions to support service providers
architecture. The WSIF trace file will contain the full exception details.
User Response: Verify that a META-INF/services/org.apache.wsif.spi.WSIFProvider file exists in a
provider jar, that each class referenced in the META-INF file exists in the class path, and that each
class implements org.apache.wsif.spi.WSIFProvider. The class in error will be ignored and WSIF
will continue locating other pluggable providers.
WSIF0004E: WSDL contains an operation type “{0}” which is not supported for “{1}”
Explanation: Parameters: {0} name of the operation type specified. {1} name of the portType for
the operation. An operation type which is not supported has been specified in the WSDL.
User Response: Remove any operations of the unsupported type from the WSDL. If the operation
is required then make sure all messages have been correctly specified for the operation.
WSIF0005E: An error occurred when invoking the method “{1}” . (“{0}” )
Explanation: Parameters: {0} name of communication type. For example EJB or Apache SOAP.
{1} name of the method that failed. An error was encountered when invoking a method on the Web
service using the communication shown in brackets.
User Response: Check that the method exists on the Web service and that the correct parts have
been added to the operation as described in the WSDL. Network problems might be a cause if the
method is remote and so check any required connections.
WSIF0006W: Multiple WSIFProvider found supporting the same namespace URI “{0}” . Found (“{1}”
) Explanation: Parameters: {0} the namespace URI. {1} a list of the WSIFProvider found.. There
are multiple org.apache.wsif.spi.WSIFProvider classes in the service provider path that support the
same namespace URI.
User Response: A following WSIF0007I message will be issued notifying which WSIPFProvider
will be used. Which WSIFProvider is chosen is based on settings in the wsif.properties file, or if
not defined in the properties, the last WSIFProvider found will be used. See the wsif.properties file
for more details on how to define which provider should be used to support a namespace URI.
WSIF0007I: Using WSIFProvider “{0}” for namespaceURI “{1}”
Explanation: Parameters: {0} the classname of the WSIFProvider being used. {1} the
namespaceURI the provider will be used to support.. Either a previous WSIF0006W message has
been issued or the SetDynamicWSIFProvider method has been used to override the provider used
to support a namespaceURI.
User Response: None. See also WSIF0006W.
WSIF0008W: WSIFDefaultCorrelationService removing correlator due to timeout. ID:“{0}”
Explanation: Parameters: {0} the ID of the correlator being removed from the correlation service.
A stored correlator is being removed from the correlation service due to its timeout expiring.
User Response: Determine why no response has been received for the asynchronous request
within the timeout period. The wsif.asyncrequest.timeout property of the wsif.properties file defines
the length of the timeout period.

Chapter 8. Developing WebSphere applications 1201

WSIF0009I: Using correlation service - “{0}”
Explanation: Parameters: {0} the name of the correlation service being used. This identifies the
name of the correlation service that will be used to process asynchronous requests.
User Response: None. If a correlation service other than the default WSIF supplied one is
required, ensure that it is correctly registered in the JNDI java:comp/wsif/WSIFCorrelationService
namespace.
WSIF0010E: Exception thrown while processing asynchronous response - “{0}”
Explanation: Parameters: {0} the error message string of the exception. While processing the
response from an executeRequestResponseAsync call an exception was thrown.
User Response: Use the exception error message string to determine the cause of the error. The
WSIF trace will have more details on the error including the exception stack trace.
WSIF0011I: Preferred port “{0}” was not available
Explanation: Parameters: {0} the user’s preferred port. The preferred port set by the user on
org.apache.wsif.WSIFService is not available
User Response: None unless this message appears for long periods of time in which case the
user might want to pick a different port as their preferred port.

WSIF - Known restrictions:

This topic lists the main known restrictions that apply when using WSIF.
Threading
WSIF is not thread-safe.
External Standards
WSIF supports:
v SOAP Version 1.1 (not 1.2 or later).
v WSDL Version 1.1 (not 1.2 or later).
WSIF does not provide WS-I compliance, and it does not support the Java API for XML-based
Remote Procedure Calls (JAX-RPC) Version 1.1 (or later).
Full schema parsing
WSIF does not support full schema parsing. For example, WSDL references in complex types in
the schema are not handled, and attributes are not handled.
SOAP WSIF does not support:
v SOAP headers that are passed as <parts>.
v Unreferenced attachments in SOAP responses.
v Document Encoded style SOAP messages.

Note: This is not primarily a WSIF restriction. Although you can specify Document Encoded
style in WSDL, it is not generally considered to be a valid option and is not supported by
the Web Services Interoperability Organization (WS-I).
SOAP provider interoperability
The current WSIF default SOAP provider (the IBM Web Service SOAP provider) does not fully
interoperate with services that are running on the former (Apache SOAP) provider. This restriction
is due to the fact that the IBM Web Service SOAP provider is designed to interoperate fully with a
JAX-RPC compliant Web service, and Apache SOAP cannot provide such a service. For
information on how to overcome this restriction, see WSIF SOAP provider: working with legacy
applications
Type mappings
The current WSIF default SOAP provider (the IBM Web Service SOAP provider) conforms to the
JAX-RPC type mapping rules that were finalized after the former (Apache SOAP) provider was
created. The majority of types are mapped the same way by both providers. The exceptions are:

1202 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 xsd:date, xsd:dateTime, xsd:hexBinary and xsd:QName. Both client and service need to use the
same mapping rules if any of these four types are used. Below is a table detailing the mapping
rules for these four types:

XML Data Type Apache SOAP Java Mapping JAX-RPC Java Mapping
xsd:date java.util.Date Not supported
xsd:dateTime Not supported java.util.Calendar
xsd:hexBinary Hexadecimal string byte [ ]
xsd:QName org.apache.soap.util.xml.QName javax.xml.namespace.QName

Arrays and complex types

WSIF does not support general complex types, it only handles complex types that map to Java
Beans. To use schema complex types, you must write your own custom serializers. The specific
complex type and array support for WSIF outbound invocation of Web services is as follows:
v WSIF supports Java classes generated by WebSphere Studio Application Developer -
Integration Edition (WSAD-IE) message generators (the normal case when WSDL files are
downloaded from somewhere else). The WSAD-IE-based generation happens automatically
when you use the BPEL editor, or the generation actions available on the Enterprise Services
context menu, or the Business Integration toolbar.
v WSIF does not support Java beans generated by other tools, including the base WSAD tool.
v For WSAD-IE generated Java beans, attributes defined in the WSDL do not work. That is to say
that these attributes, although they appear in the Java beans generated to represent the
complex type, do not appear in the SOAP request created by WSIF.
v WSIF does not support arrays when they are a field of a Java bean. That is to say, WSIF only
supports an array that is passed in as a named <part>. If an array is wrappered inside a Java
bean, the array is not serialized in the same way.
Object Serialization
WSIF does not support serialization of objects across different releases.
Asynchronous invocation
WSIF supports synchronous invocation for all providers. For the JMS and the SOAP over JMS
providers, WSIF also supports asynchronous invocation. You should call the supportsAsync()
method before trying to execute an asynchronous operation.
The EJB provider
The target service of the WSIF EJB provider must be a remote-home interface, it cannot be an
EJB local-home interface. In addition, the EJB stub classes must be available on the client class
path.
Running outside WebSphere Application Server
WSIF is not supported for use outside WebSphere Application Server.

Using the UDDI Registry

Welcome to the IBM WebSphere UDDI Registry.

Use the table of contents (on the left and below) to view the various topics for a specific product or
technology. Select the topic you are interested in to either open documentation locally or find information
about how to locate documentation.
v An Overview of the IBM Version 3 UDDI Registry
v Terminology
v Getting started with UDDI Registry
v Migrating to Version 3 of the UDDI Registry
v Setting up and deploying a new UDDI Registry

Chapter 8. Developing WebSphere applications 1203

v Removing and reinstalling a UDDI Registry
v Configuring the UDDI Registry Application
v Managing the UDDI Registry
v UDDI Registry Client Programming
v UDDI Registry Security
v The UDDI Registry user interface
v UDDI Registry Management Interfaces
v IBM JAXR Provider for the UDDI Registry
v UDDI Registry troubleshooting
v UDDI Registry Messages
v UDDI Registry Samples

An overview of the IBM Version 3 UDDI Registry

The Universal Description, Discovery and Integration (UDDI) specifications define a way to publish and
discover information about Web services. The term ’Web service’ describes specific business functionality
exposed by a company, usually through an Internet connection, to allow another company, or its
subsidiaries, or software program to use the service.

The UDDI specifications define a standard for the visibility, reusability and manageability essential for a
Service Oriented Architecture (SOA) registry service.

IBM WebSphere UDDI Registry

The IBM WebSphere UDDI Registry is a directory for Web services that is implemented using the UDDI
specifications. It is a component of WebSphere Application Server Version 6.

A critical component of IBM’s on-demand Service Oriented Architecture, IBM WebSphere UDDI Registry
solves the problem of discovery of technical components for an enterprise and its partners by:
v Providing control, flexibility and confidentiality so that an enterprise can protect its e-business
investments
v Increasing efficiency by making it easier to identify technical assets
v Leveraging existing infrastructures

For example, the IBM WebSphere UDDI Registry could be used in the following way within a larger
enterprise:

A company has a legacy application that provides telephone numbers and Human Resources (HR)
information about employees. This is turned into a Web service and published to the registry. A developer
in the same company needs to write an application for a procurement function that also needs to provide
HR information to the supplier. The application should allow the supplier to have access to the employee
account codes once the employee provides his name or serial number. Before Web services, the
developer had there choices:
1. Would not have known about the similar application
2. Knew about it but could not reuse due to technical barriers
3. Knew about it and reused only after significant time and negotiation

With UDDI, the developer can search for the ″web service″ and reuse the existing technical component in
their new application for the supplier in a matter of minutes. The developer saves time and gets the
application up and running sooner than they would have otherwise, thereby increasing efficiency and
saving the company time and money. The IBM WebSphere UDDI Registry was the first version 2
standard-compliant UDDI registry for private enterprise work. The IBM WebSphere UDDI Registry in
WebSphere Application Server Version 6.0:
v Supports the UDDI Version 3.0 specifications and also supports the Version 2.0 standard API.
v Leverages the proven, reliable WebSphere Application Server technology

1204 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Uses a relational database, such as DB2, for its persistent store

What’s new in UDDI Version 3

The main aspects of UDDI Version 3 specification that are provided within WebSphere Application Server
Version 6 are as follows: (There are also some additional capabilities provided by the IBM WebSphere
UDDI Registry in WebSphere Application Server Version 6.0 which are described in a section below).

Improved recognition of the importance of Private UDDI Registries

These are registries that are installed, owned, managed and controlled by a department, company,
consortium and so on.

Publisher-assigned keys

This allows the publisher of a UDDI entity to specify its key, rather than having a unique key assigned by
the registry. As well as allowing more human-friendly, URI-based keys, this also makes it easier to manage
multiple registries.

UDDI Information Model improvements

The UDDI data structures have been extended in a number of ways which improve the ability of UDDI to
represent businesses and services via metadata.

Security Enhancements

The introduction of digital signatures provides additional security. Each of the main UDDI entities can be
digitally signed, thus improving the integrity and trustworthiness of UDDI data.

Ownership transfer APIs

These allow the ownership of a UDDI entity to be transferred from one publisher to another.

UDDI Policy

Allows the behavior of a UDDI Registry (or a node within a multi-node registry) to be defined by setting
policy, thus recognizing the various different environments in which a UDDI Registry will be used.

HTTP GET support for UDDI entities

The HTTP GET service is extended beyond the scope for discovery URLs that is a part of the UDDI
Version 2 specification. The service allows HTTP GET to be used to access XML representations of each
of the UDDI data structures.

Additional Capabilities provided by the UDDI Registry

The Version 3 UDDI Registry provided in WebSphere Application Server Version 6.0 provides the following
capabilities in addition to support for the UDDI Version 3 specification:

Version 2 UDDI Inquiry and Publish SOAP API compatibility

Backward compatibility is maintained for the Version 1 and Version 2 SOAP Inquiry and Publish APIs.

UDDI Admin Console extension

Chapter 8. Developing WebSphere applications 1205

The WebSphere Application Server Version 6 Administrative Console includes a section which will allow
administrators to manage UDDI-specific aspects of their WebSphere environment. This includes the ability
to set defaults for initialization of the UDDI node (such as its node ID), and to set the UDDI Version 3
Policy values.

UDDI Registry Administrative Interface

A JMX administrative interface allows administrators to programmatically manage UDDI-specific aspects of

the WebSphere environment.

Multi-database support

The UDDI data is persisted to a registry database. In WebSphere Application Server Version 6 the
databases that are supported are DB2, Cloudscape, and Oracle. Support is provided for remote
databases.

User-defined Value Set support

This allows users to create their own categorization schemes or value sets, in addition to the standard
schemes, such as NAICS, that are provided with the product.

UDDI Utility Tools

UDDI Utility Tools allows importing and exporting of entities using the UDDI Version 2 API.

UDDI user interface

The UDDI user console supports the Inquiry and Publish APIs providing a similar level of support for the
Version 3 APIs as was offered for UDDI Version 2 in WebSphere Application Server Version 5.

UDDI Version 3 Client

The IBM Java Client for UDDI Version 3 is a Java client for UDDI which handles the construction of raw
SOAP requests for the client application. It is a JAX-RPC client and uses Version 3 datatypes generated
from the UDDI Version 3 WSDL and schema. These datatypes are serialized/deserialized to the XML
which constitutes the raw UDDI requests.

UDDI Version 2 Clients

The following clients for UDDI Version 2 requests are provided:

v UDDI4J - a Java class library for issuing UDDI requests. This was provided in WebSphere Application
Server Version 5 for both UDDI Version 1 requests (uddi4j.jar) and Version 2 requests (uddi4jv2.jar).
These class libraries continue to be supported but are now both deprecated.
v JAXR - the Java API for XML Registries is a Java client API for accessing UDDI and ebXML registries.
WebSphere Application Server 6.0 provides a JAXR Provider for accessing the IBM WebSphere UDDI
Registry. It conforms to the JAXR 1.0 specification.
v EJB - an EJB interface for issuing UDDI version 2 requests. This continues to be supported but is now
deprecated.

UDDI Registry terminology

Throughout the UDDI documentation in this Information Center the directory location of the WebSphere
Application Server is referred to as WAS_HOME. The default locations are:

Windows

1206 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WAS_HOME
C:\Program Files\IBM\WebSphere\AppServer\

Linux/Solaris/HP Platforms
WAS_HOME
/opt/IBM/WebSphere/AppServer/

AIX Platform
WAS_HOME
/usr/IBM/WebSphere/AppServer/

z/OS Platform
WAS_HOME
/WebSphere/V6R0M0/AppServer/

UDDI Definitions
bindingTemplate
Technical information about a service entry point and construction specifications.
businessEntity
Information about the party who publishes information about a family of services.
businessService
Descriptive information about a particular service.
Customized UDDI node
This is a UDDI node that is initialized with customized settings for the UDDI properties and UDDI
policies, in particular with non-default values for those properties that are read-only after
initialization. A customized UDDI node is recommended for anything other than simple testing
purposes (for which a default UDDI node is sufficient). You can set up a customized UDDI node by
following the instructions in Setting up a customized UDDI node. When a customized UDDI node
is first started, you have to set values for certain properties and to initialize the node (using the
Administrative Console or UDDI Administrative Interface), before the node is ready to accept UDDI
requests. The properties that need to be set control characteristics of the UDDI node that cannot
be changed after initialization. An advantage of using a customized UDDI node is that it allows you
to set these properties to values that are suitable for your environment and usage of UDDI. After a
customized UDDI node has been initialized, it differs from a default UDDI node only in that it uses
customized UDDI property and policy values.
Default UDDI node
This is a UDDI node which has been initialized with default settings for the UDDI properties and
UDDI policies, including the properties that are read-only after initialization. A default UDDI node is
intended for test purposes and as a simple way to become familiar with the behavior of the UDDI
Registry. You can set up a default UDDI node in two ways. The first is to specify the ’default’
option when you run uddiDeploy.jacl, in which case the UDDI database will be a Cloudscape
database. The second is to run the supplied SQL script insert_default_database_indicator against
the UDDI database, in which case the UDDI database can be Cloudscape, DB2 or Oracle. After a
default UDDI node has been initialized, it differs from a customized UDDI node only in that it uses
default UDDI property and policy values.
Policy profile
A set of UDDI policies. The default policy profile is the profile created when the default UDDI node
is created. In this instance, the nodeID and root key generator are set to read only and are
unchangeable after installation.
publisherAssertion
Information about a relationship between two parties, asserted by one or both.

Chapter 8. Developing WebSphere applications 1207

tModel
Short for technical model.
A tModel is a data structure representing a reusable concept, such as a Web service type, a
protocol used by Web services, or a category system.
tModel keys within a service description are a technical ″fingerprint″ that you can use to trace the
compatibility origins of a given service. They provide a common point of reference that allows you
to identify compatible services.
tModels are used to establish the existence of a variety of concepts and to point to their technical
definitions. tModels that represent value sets such as category, identifier, and relationship systems
are used to provide additional data to the UDDI core entities to facilitate discovery along a number
of dimensions. This additional data is captured in keyedReferences that reside in category Bags,
identifierBags, or publisherAssertions. The tModelKey attributes in these keyedReferences refer to
the value set that relates to the concept or namespace being represented. The keyValues contain
the actual values from that value set. In some cases keyNames are significant, such as for
describing relationships and when using the general keywords value set. In all other cases,
however, keyNames are used to provide a human readable version of what is in the keyValue.
UDDI Application
The IBM WebSphere UDDI Registry J2EE application.
UDDI entitlement
An entitlement that a UDDI user or publisher has within a UDDI registry, such as the capability to
publish keyGenerators, or the tier to which the publisher is assigned (in other words, the number
of entities that the publisher is entitled to published). Each UDDI publisher will have a set of
settings for the various UDDI entitlements. A UDDI entitlement is sometimes referred to as a ’user
entitlement’, or as the UDDI publisher’s set of ’user entitlements’.
UDDI Node
A set of Web Services supporting at least one of the UDDI API sets, which supports interaction
with UDDI data through the UDDI APIs. There is no direct mapping between a UDDI node and a
WebSphere Application Server (WAS) node. A UDDI node consists of an instance of the UDDI
application running in an application server (or a cluster of UDDI application instances running in a
cluster of application servers) together with an instance of the UDDI database containing UDDI
data.
UDDI node initialization
The process of node initialization sets up values in the UDDI database, and establishes the
″personality″ of the UDDI node. A UDDI node cannot accept UDDI API requests until it has been
initialized.
UDDI node state
Describes the current state of the UDDI node, as opposed to the state of the UDDI application
(which is either stopped or started). The state of a UDDI node can be one of not initialized,
initialization pending, initialization in progress, activated or deactivated.
UDDI NodeId
A unique identifier of a UDDI node.
UDDI Policy
A UDDI policy is a statement of required and expected behavior of a UDDI Registry, specified via
policy values for the various policies defined in the UDDI Version Specification.
UDDI property
A value for a property which controls the personality or behavior of a UDDI node.
UDDI publisher
A WebSphere user who is entitled to publish UDDI entities to a specified UDDI Registry. A UDDI
publisher is sometimes referred to as a ’UDDI user’, or simply as a ’publisher’ when used in a
UDDI context.

1208 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
UDDI Registry
A UDDI Registry comprises one or more UDDI nodes. The IBM WebSphere UDDI Registry in
WebSphere Application Server Version 6.0 only supports single-node UDDI registries.
UDDI Tier
Determines the number of UDDI entities of each type (business, services per business, bindings
per service, tModel, publisher assertion) that a UDDI publisher is entitled to publish. Each UDDI
publisher will be assigned (either by default or explicitly by a UDDI administrator) to a particular
tier, and will not be able to publish more entities than are allowed for that tier. There are some
predefined tiers supplied with the UDDI Registry, and a UDDI administrator can create additional
tiers. A UDDI tier is often referred to simply as a ’tier’ when used in a UDDI context.
Version 2 UDDI Registry
A shorthand term used to refer to an IBM WebSphere UDDI Registry implementation which
supports Version 2 of the UDDI specification (and also Version 1). A Version 2 UDDI Registry is
included in WebSphere Application Server Network Deployment Version 5.x.
Version 3 UDDI Registry
A shorthand term used to refer to an IBM WebSphere UDDI Registry implementation which
supports Version 3 of the UDDI specification (and also Versions 1 and 2). A Version 3 UDDI
Registry is included in WebSphere Application Server Version 6.0. It should be noted that the term
’Version 3 UDDI Registry’ does not indicate a registry which only supports UDDI version 3
requests.

The following table shows how the various versions of the IBM UDDI Registry relate to the relevant OASIS
specification and WebSphere Application Server level:

IBM UDDI Registry Version OASIS UDDI specification levels Supported on WebSphere Application
supported Server version
1.1 v UDDI Version 1 4.0.2
v UDDI Version 2
1.1.1 v UDDI Version 1 4.0.3 and later
v UDDI Version 2
2.0.x v UDDI Version 1 5.0.x
v UDDI Version 2
2.1.x v UDDI Version 1 5.1.x
v UDDI Version 2
3.0.2 v UDDI Version 1 6.0
v UDDI Version 2.0.4 (APIs), Version
2.0.3 (data structures)
v UDDI Version 3.0.2

UDDI Registry Security

The IBM UDDI V3 Registry is designed to exploit the advantages of WebSphere security, and it supports
the UDDI v1,v2 security features and UDDI V3 Security API.

For production use, it is recommended that the IBM UDDI V3 Registry is configured to use WebSphere
security and avoid use of UDDI V1,V2 security features and the V3 Security API.

But, for solutions with a strong preference for UDDI security, the IBM UDDI V3 Registry can be configured
to enable its use, both when WAS security is enabled and when it is disabled.

Chapter 8. Developing WebSphere applications 1209

Configuring UDDI to use WAS security

To exploit WebSphere security features WebSphere Application Server (WAS) security must be enabled.
When security is enabled, the default settings in UDDI v3 Application and Web deployment descriptors
result in the following features:

Authentication

UDDI exploits WAS security Role Mapping by mapping users of UDDI Publish services to the special
AllAuthenticatedUsers role to ensure that only valid WebSphere registered users can access these
services. This is the default setting for:
v V1,2 SOAP Publish service (SOAP_Publish _User)
v EJB Publish service (EJB_Publish_Role)
v V3 GUI Publish service (GUI_Publish_User)
v V3 Publish service (V3SOAP_Publish_User_Role)
v V3 Custody Transfer service (V3SOAP_CustodyTransfer_User_Role)
v V3 Security service (V3SOAP_Security_User_Role)

The following services are mapped to the special role Everyone and are not protected:
v V1,2 SOAP Inquiry service (SOAP_Inquiry_User)
v EJB Inquiry service (EJB_Inquiry_Role)
v V3 GUI Inquiry service (GUI_Inquiry_User)
v V3 SOAP Inquiry service (V3SOAP_Inquiry_User_Role)

This restriction can be managed using WebSphere Administrative Console features:Applications >
Enterprise Applications> UDDI V3 Registry > Additional Properties > Map security roles to
users/groups.

Further information is also available in: Configuring UDDI Security Roles.

Data Confidentiality

UDDI also exploits the advantages of the WAS security feature enforcing service data confidentiality (
’security constraint‘,’user-data-constraint‘, ’transport-guarantee‘ = ’CONFIDENTIAL‘ requiring the use of
HTTPS) for the following services:
v V1,2 SOAP Publish service (SOAP_Publish _User)
v EJB Publish service (EJB_Publish_Role)
v V3 GUI Publish service (GUI_Publish_User)
v V3 Publish service (V3SOAP_Publish_User_Role)
v V3 Custody Transfer service (V3SOAP_CustodyTransfer_User_Role)
v V3 Security service (V3SOAP_Security_User_Role)

By default the following services are do not enforce data confidentiality (’security constraint‘,
’user-data-constraint‘, ’transport-guarantee‘ = ’NONE‘ not requiring the use of HTTPS, HTTP is OK):
v V1,2 SOAP Inquiry service (SOAP_Inquiry_User )
v EJB Inquiry service (EJB_Inquiry_Role)
v V3 GUI Inquiry service (GUI_Inquiry_User)
v V3 SOAP Inquiry service (V3SOAP_Inquiry_User_Role)

For information on how to manage the data confidentiality restriction, please refer to ’Configuring SOAP
API and GUI services‘ section on user data constraint transport guarantee.

1210 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Configuring UDDI to use UDDI security

It is possible to exploit UDDI security features when WebSphere Application Server (WAS) security is
enabled or disabled. Depending on the WAS security enabled/disabled setting, different configuration is
required and different behavior achieved. While useful for test, it is not anticipated that WAS security is
disabled for production configurations.

UDDI security with WAS Security enabled

When WAS security is enabled, to use the UDDI v1//2 (publish) security features
(get_AuthToken,discard_AuthToken) or the UDDI v3 security API (get_AuthToken, discard_AuthToken) it is
necessary to do the following:
v v set the WAS security Role Mappings to Everyone for:
– V1,2 SOAP Publish service (SOAP_Publish _User)
– V3 Publish service (V3SOAP_Publish_User_Role)
– V3 Custody Transfer service (V3SOAP_CustodyTransfer_User_Role)
– V3 Security service (V3SOAP_Security_User_Role)
As identified above this can be managed using the WebSphere Administrative Console: Applications >
Enterprise Applications> UDDI V3 Registry > Additional Properties > Map security roles to
users/groups
v v ensure that UDDI Policy is set to require the use of AuthTokens for the Publish and CustodyTransfer
API services ( it is implicit for V1/2 Publish).
This can be managed using the WebSphere Administrative Console: UDDI>UDDI
Nodes>uddinodename>Policy Groups>APIs>‘authorization for publish‘, ’authorization for
custody transfer‘

With this configuration, no Security Role authentication restriction is imposed, but the credentials
associated with the authToken are authenticated by WebSphere. Further information is also available in:
Configuring UDDI Security Roles.

Note, that when WAS security is enabled, WAS data confidentiality management is independent of UDDI
security and is managed as described above.

UDDI security with WAS Security disabled

With WAS Security disabled, neither WAS Security Roles nor data confidentiality constraints apply. This
mode may be useful for test UDDI Registry configurations.

In this mode, UDDI V1/2 security features are active, and UDDI V1/2 authTokens should be used on UDDI
V1/2 publish requests. Publisher requesting an authToken or using an authToken do have to be a
registered WAS users.

With respect to UDDI V3, the use of the UDDI V3 Security API, and the use of authTokens with V3 Publish
and Custody Transfer APIs is optional. If required, the following configuration steps are necessary:
v use the WebSphere Administrative Console to identify that use of authInfo is required: UDDI>UDDI
Nodes>uddinodename >General Properties> check ’Use authInfo credentials if provided‘
v ensure that UDDI Policy is set to require the use of AuthTokens for the Publish and CustodyTransfer
using the WebSphere Administrative Console: UDDI>UDDI Nodes>uddinodename>Policy
Groups>APIs>check ‘authorization for publish‘ and ’authorization for custody transfer

Chapter 8. Developing WebSphere applications 1211

Additional security considerations

The UDDI Registry also supports use of XML Digital Signatures to sign UDDI entities. This is described in
Use of digital signatures with the UDDI Registry.

Additional Policy considerations

A number of the UDDI property and policy settings also determine the behavior of a UDDI Registry with
respect to security:
v Default user name -used when WAS Security is disabled and no authToken data is supplied (see
WebSphere Administrative Console > UDDI>UDDI Nodes>uddiNodeName >General Properties>
Default user).
v Authorization for Inquiry, Authorization for Publish, Authorization for Custody Transfer – as described
above, checked to require use of authTokens when not ’overridden‘ by WAS Security Role
AllAuthenticatedUsers (see WebSphere Administrative Console> UDDI>UDDI Nodes>uddiNodeName
> Policy Groups>APIs>‘authorization for Inquiry‘, ‘authorization for publish‘ and ’authorization
for custody transfer‘ ).
v Use authInfo credential if provided – as described above, applicable when WAS security is disabled
(UDDI>UDDI Nodes>uddinodename >General Properties> ’Use authInfo credentials if provided‘).
v Authentication token expiry period – to determine the length of idle time allowed before an authToken
becomes invalid (see WebSphere Administrative Console > UDDI>UDDI Nodes>uddiNodeName
>General Properties> Authentication token expiry period).
v Key space requests require digital signature – determines whether all tModel:keyGenerator requests for
key space must be signed. To understand key space refer to the Entity Keys Section, to manage this
setting (see WebSphere Administrative Console > UDDI>UDDI Nodes>uddiNodeName > General
Properties> Key space requests require digital signature).

In addition to Security specific policies and properties, awareness of some Keying Policy and User Policies
also influences publish behavior:
v Keying Policy – Registry key generation. If this is set, publishers may request key space and if
successful publish with publisher assigned keys (see WebSphere Administrative Console > UDDI>UDDI
Nodes>uddiNodeName >Policy Groups> UDDI Keying).
v Automatically register UDDI publishers – UDDI requires publisher entitlements to be set, before allowing
any publish request. This option automatically registers Users with default entitlements (see WebSphere
Administrative Console > UDDI>UDDI Nodes>uddiNodeName >General Properties> Automatically
register UDDI Publishers).
v UDDI Publishers – if the ’Automatically register UDDI publishers‘ option is not selected, then Users (and
their entitlements) can be registered (see WebSphere Administrative Console > UDDI>UDDI
Nodes>Additional properties> UDDI Publishers).See also the topics on Create UDDI Publishers and
UDDI Publisher settings.
v UDDI tier limits – UDDI V3 publish tier limits management (enforcing publisher tier limit) can be
activated ( see WebSphere Administrative Console > UDDI>UDDI Nodes> uddiNodeName>General
Properties>Use TierLimits). Also refer to the ’Use tier limits’ UDDI property.
v If the above option is checked, then it relevant to configure Tiers (see WebSphere Administrative
Console > UDDI>UDDI Nodes> uddiNodeName>Addition Properties>Tiers) also to set any
registered UDDI Publishers Tier entitlement (see WebSphere Administrative Console> UDDI>UDDI
Nodes> uddiNodeName>Addition Properties>UDDI Publishers).

UDDI Registry user interface

This topic describes the UDDI user interface (also referred to as the UDDI User Console), which you can
use to explore the IBM WebSphere UDDI Registry.

For information about how to display the UDDI user console, see Displaying the user interface.

1212 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If you will be using the UDDI console, you must configure the application server into which you have
installed the UDDI Registry for UTF-8 encoding support: To do this, refer to ″Configuring application
servers for UTF-8 encoding″ elsewhere in this Information Center.
v The user console provides a graphical user interface to the majority of the UDDI Version 3 API. It is not
intended to support the full API set: there is some focus on inquiry operations, as the main purpose of
the UDDI user console is to allow users to issue inquiry requests and to familiarize themselves with
general UDDI concepts. This section documents those areas for which support through the user console
is not provided, together with other known restrictions to the user console.
– General
- Help is provided in the form of explanatory text on the screens.
- Maximum rows cannot be specified on finds. The single maximum rows value for the registry can
be set through the Maximum inquiry result set size general property on the WebSphere
Administrative console.
– Find business
- The business identifier feature is not supported.
– Find technical model (tModel)
- The business identifier feature is not supported.
– Add business
- You must supply the business contact as a name and role (no other information is supported).
– Add technical model (tModel)
- You can enter the overview URL, but only with one description in English.
– Business Relationships
- There is no support for Business Relationships
v Note: The UDDI Version 3 specification states that when a tModel is deleted, it should not be physically
deleted. This allows the tModel to be reinstated. One effect of this is that, if you delete a tModel using
the UDDI user console, the tModel is still visible through the Show Owned Entities display.

The UDDI user console is split into three distinct areas. At the top of the screen are buttons that activate
various functions in the areas below this bar. These buttons are:
Home Returns you to the IBM WebSphere UDDI Registry welcome page
Find Activates the Find tab on the frame below to the left
Publish
Similarly activates the Publish tab on the frame below to the left

Below the WebSphere UDDI Registry banner the screen is split into two parts. On the left are the two tabs
mentioned above, the Find and Publish tabs.

Find tab

The Find tab is in two parts. At the top, a Quick Find service is provided. There are three radio buttons to
enable a choice of ’service’, ’business’ and ’technical model’ finds. Below these radio buttons is a text
entry box for entering the name to search for and, beneath this, a ’Find’ link to start the search. Comments
are provided to show the user the wildcard character. The results of clicking the ’Find’ link are shown in
the detail frame to the right.

Beneath the Quick Find is a section for Advanced Find functions which enables the user to choose which
entity they want to perform an advanced search on. There are three links: Find services, Find
businesses and Find technical models. Clicking one of these links displays the corresponding advanced
search form in the frame to the right, where the user can specify search criteria. To initiate a Find, the user
must first enter a search path (the % wildcard may be used) and then click the Add Name link to enter the
search. Then click the ’Find Services’ (or ’Find Businesses/Find technical models) link below to initiate the
Find operation. The Locator section has a link (marked in blue with the words ″Show category tree″)
which displays the tree from which the user can select categories (or taxonomies). This is shown in the
left-hand frame. In the advanced search form there are two links to start the search (mid-way down and at
the bottom).

Chapter 8. Developing WebSphere applications 1213

The results of the search are displayed in the same detail frame.

Publish tab

The Publish link on the top banner activates the Publish tab in the navigation frame to the left. The Publish
tab is split into three distinct sections.
1. Quick Publish Function
The top part is a Quick Publish section to allow the user to publish a business or technical model by
name only. There are two radio buttons to enable a choice of ’business’ or ’technical model’. Below
these radio buttons is a text entry box for entering the name to assign to the selected entity and,
beneath this, a blue Publish link to publish the entity. The results of clicking the Publish link are
shown in the detail frame to the right.
2. Advanced Publish Functions
To publish an entity with more detail, such as with multiple names, descriptions and categories, use the
Advanced Publish section below this. The comments below each link (’Add a business’ and ’Add a
technical model’) describe individual functions. Clicking one of these links displays the corresponding
advanced publish form in the detail frame where the user may enter details about the entity they want
to publish. Similarly the Locator section allows taxonomies to be shown in the left frame from which
the user can select categories.
Following entry of the relevant details on the Advanced Publish section, the user must click the
Publish Business bar in order for the business to be published to the UDDI Registry.
3. Registered Information
Below the Advanced Publish section is a Registered Information section which has a link to Show
Owned Entities in order to show the businesses, services and technical models registered to the
individual user. Clicking the Show Owned Entities link displays the Show Owned Entities page in the
detail frame at the right. The Show Owned Entities page is organized in two sections: Registered
Businesses and Registered Technical Models. Each section shows the number of registered items.
Edit and Delete Businesses
Users can Edit or Delete businesses owned by them by clicking the appropriate links in the Actions
column.
After an Edit or Delete function has been completed, the user must click the Update Business bar to
publish the service to the UDDI Registry.
To delete a Business select the Show Owner Entities link and click the Delete link shown next to the
business.
Adding a Service to a Business
Services are added to a business by clicking the Add a Service link in the Services column of the
Registered Businesses section.
Click the Add Service button to publish the service to the UDDI Registry.
Technical Models
Technical Models owned by the user are shown in the bottom Registered Technical Models section.
As for businesses, users can Edit or Delete technical models owned by them by clicking the
appropriate links in the Actions column.

Note: Users should take note that deletion of Technical Models (tModels) does not cause them to be
physically deleted, but hidden. This is in accordance with the UDDI Registry Version 3.0
specifications. After deletion Technical Models are shown under the ″Shown Owned Entities″
link on the publish page but not via the Find links on the Find page. ALL other entities are
deleted from the UDDI Registry in the normal way.

Example of publishing a Business, Service and tModel with the User Console

For the example, here, we will assume a business called Modern Cars that sells used cars
1. Add the Business

1214 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Click the Publish tab in the left hand navigation frame. Then click ’Add a business’ in the Advanced
Publish in the left pane. This takes you to a ’Publish Business’ pane on the right. Start by adding your
Business Name in the text field labelled (Modern Cars in this example) and select a language and then
click on the blue Add name to the right. This adds the business name. Below the Business Name is
the descriptions field - free text can be added to describe the business. Enter a description and click
the blue Add description link to add the description. You can add multiple descriptions in a variety of
languages as required.
Categorizations can be used to describe the business according to which categories it falls into. This
example uses a Used car dealership. As an example, view the NAICS taxonomy by clicking ’Show
category tree’ and then expanding NAICS 2002 in the left hand panel. Expand the Retail Trade [44]
entry by clicking the (+) plus sign next to it. You may need to drag the division between the left and
right panes to be able to see all the category names. Similarly expand Motor Vehicle and Parts
Dealers [441] then automobile Dealers [4411] and finally Used Car Dealers [441120]. Select ’Used Car
Dealers [441120] and the ’Type’, ’Key Name’, ’Key Value’ fields under categorizations will be filled in
with the relevant values. Click the blue ’Add categorization’ link to add the categorization details.
Once all the fields are filled in, click the Publish Business button at the bottom of the form or at the
top. A page is displayed showing the business details and the business is published to the UDDI
Registry.
2. Add a Service
From the Publish tab, there is a Show owned entities link shows the businesses in the UDDI Registry
owned by the current user. In our Modern Cars example, to add the description of a service provided
by the business click the Add service link and a Publish Service form is shown. At the top of the form
in the Service Name field you can add a name, then select it’s language and click the Add name link.
You can also add a description (free text), one or more bindings (to add link points to the Service), and
Categorizations (to add references to taxonomies to the service. After completion the required areas,
clicking the ’Publish Service’ button will Publish the service to the UDDI Registry with the current form
contents.
3. Adding a new technical model
Clicking the Add a technical model link in the left frame opens up the Publish Technical Model form
on the right. A tModel can only have one name so there is no blue Add link next to the Technical Model
Name field. Beneath this are the descriptions (a free text area to describe the technical model),
overview documents (which gives a URL pointing to an overview document) and Categorizations
(taxonomies describing the technical model). For each of these fields there is a blue Add link which
must be clicked to add the relevant data. At the bottom of the form is a Publish Technical Model link
which creates the technical model in the UDDI Registry.

UDDI Registry Management Interfaces

This topic explains interfaces and tools you can use to programmatically manage UDDI nodes.

UDDI Registry Administrative (JMX) Interface

UDDI Registry Administrative (JMX) Interface provides a Java API that allows you to manage runtime
configuration settings to control UDDI Registry runtime behavior, such as setting the maximum number of
results that UDDI users can receive for inquiry requests, or creating publish limits for UDDI publishers.
Sample client code is provided for you to build on.

User Defined Value Set Support in the UDDI Registry

User Defined Value Set Support in the UDDI Registry explains the tooling provided to manage your own
categorization value sets, including loading value set data into a UDDI Registry node.

Chapter 8. Developing WebSphere applications 1215

UDDI Utility Tools

UDDI Utility Tools explains the tooling and Java API for promoting version 2 entities from one UDDI
registry to another while retaining entity keys. This is particularly useful for publishing canonical tModels
with a predefined key.

UDDI Registry Administrative (JMX) Interface:

Each WebSphere UDDI Registry application registers an MBean with an MBean identifier of
’UddiNode‘.

This MBean may be used by client applications to inspect and manage the runtime configuration of a
UDDI application. This includes managing the activation state of and information about a UDDI node,
updating properties and policies, setting publish tier limits, registration of UDDI publishers, and controlling
value set support.

You can read and invoke the UddiNode attributes and operations using standard JMX interfaces. A client
utility class UddiNodeProxy.java provides a ready-made application to connect to a UddiNode MBean and
perform all the available operations. Example classes are also provided to drive UddiNodeProxy and
demonstrate how to use the various UDDI management data types.

UddiNodeProxy Usage

The following jars required for compilation can be found in WAS_HOME/lib/:

v admin.jar
v management.jar
v uddiadmin.jar
v wsexception.jar

The UddiNodeProxy class provides a utility method to programmatically interrogate the UddiNode MBean
and output all the available attributes, operations and notifications to System.out. For each operation, the
return type, operation name and parameter types are output as well as the impact property which indicates
how the operation changes the state of the UddiNode MBean (and the UDDI node). As for all MBeans, the
value for the impact property can be one of:
ACTION:
state of MBean will be changed
INFO: of the MBean remains unchanged and will return information
ACTION_INFO:
state of the MBean will change and return some information
UNKNOWN:
the impact of invoking the operation is not known
1. Invoke outputMBeanInterface:uddiNode.outputMBeanInterface();
Expected output:
java.lang.String getNodeID() [INFO]
(getter for attribute nodeID)
java.lang.String getNodeState() [INFO]
(getter for attribute nodeState)
java.lang.String getNodeDescription() [INFO]
(getter for attribute nodeDescription)
java.lang.String getNodeApplicationName() [INFO]
(getter for attribute nodeApplicationName)
void activateNode() [ACTION]
(activates UDDI node)
void deactivateNode() [ACTION]
(deactivates UDDI node)

1216 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
void initNode() [ACTION]
(initializes Uddi node)
com.ibm.uddi.v3.management.Property getProperty(java.lang.String propertyId) [INFO]
(returns UDDI Property)
com.ibm.uddi.v3.management.PolicyGroup getPolicyGroup(java.lang.String policyGroup
Id) [INFO]
(returns UDDI PolicyGroup)
com.ibm.uddi.v3.management.Policy getPolicy(java.lang.String policyId) [INFO]
(returns UDDI Policy)
void updatePolicy(com.ibm.uddi.v3.management.Policy policy) [ACTION]
(updates UDDI Policy)
void updateProperty(com.ibm.uddi.v3.management.ConfigurationProperty property) [ACTION]
(updates UDDI Property)
void updateProperties(java.util.List properties) [ACTION]
(updates collection of UDDI properties)
void updatePolicies(java.util.List policies) [ACTION]
(updates collection of UDDI policies)
java.util.List getProperties() [INFO]
(returns the collection of UDDI properties)
java.util.List getPolicyGroups() [INFO]
(returns collection of policy groups (note that the policies are not populated))
java.util.List getValueSets() [INFO]
(returns collection of value set status objects)
com.ibm.uddi.v3.management.ValueSetStatus getValueSetDetail(java.lang.String
tModelKey) [INFO]
(returns status for a value set)
com.ibm.uddi.v3.management.ValueSetProperty getValueSetProperty(java.lang.String
tModelKey,java.lang.String valueSetPropertyId) [INFO]
(returns a property of a value set)
void updateValueSet(com.ibm.uddi.v3.management.ValueSetStatus valueSet) [ACTION]
(updates value set status)
void updateValueSets(java.util.List valueSets) [ACTION]
(updates multiple value sets)
void loadValueSet(java.lang.String filePath,java.lang.String tModelKey) [ACTION]
(loads values for a value set from a UDDI Registry V3/V2 taxonomy data file.)
void loadValueSet(com.ibm.uddi.v3.management.ValueSetData valueSetData) [ACTION]
(loads values for a value set with the given tModel key.)
void changeValueSetTModelKey(java.lang.String oldTModelKey,java.lang.String
newTModelKey) [ACTION]
(replaces all occurrences of values belonging to original tModelKey to new tModelKey.)
void unloadValueSet(java.lang.String tModelKey) [ACTION]
(unloads values for a value set with the given tModel key.)
java.lang.Boolean isExistingValueSet(java.lang.String tModelKey) [INFO]
(Determine if Value Set data exists for the given tModel key.)
java.util.List getTierInfos() [INFO]
(returns the collection of UDDI tier descriptions.)
java.util.List getLimitInfos() [INFO]
(returns the collection of UDDI limit descriptions.)
java.util.List getEntitlementInfos() [INFO]
(returns the collection of UDDI entitlements.)
com.ibm.uddi.v3.management.Tier getTierDetail(java.lang.String tierId) [INFO]
(returns UDDI Tier detail, specifying limits to the number of entities that
can be published.)
com.ibm.uddi.v3.management.Tier createTier(com.ibm.uddi.v3.management.Tier tier) [ACTION]
(creates a UDDI Tier, specifying limits to the number of entities that can be
published. Returns the new tier ID.)
com.ibm.uddi.v3.management.Tier updateTier(com.ibm.uddi.v3.management.Tier tier) [ACTION]
(updates UDDI Tier details. Returns the updated Tier.)
void deleteTier(java.lang.String tierId) [ACTION]
(deletes the UDDI Tier, if it not in use.)
void setDefaultTier(java.lang.String tierId) [ACTION]
(Specifies the tier that auto registered UDDI publishers are assigned to.)
java.lang.Integer getUserCount(java.lang.String tierId) [INFO]
(returns the number of UDDI publisher within the specied tier.)
com.ibm.uddi.v3.management.TierInfo getUserTier(java.lang.String userId) [INFO]
(returns UDDI Tier information, specifying the tier this user belongs to.)
com.ibm.uddi.v3.management.UddiUser getUddiUser(java.lang.String userId) [INFO]

Chapter 8. Developing WebSphere applications 1217

 (returns UDDI user details, including tier and entitlements details.)
java.util.List getUserInfos() [INFO]
(returns the collection of UDDI user names and the tier they belong to.)
void createUddiUser(com.ibm.uddi.v3.management.UddiUser user) [ACTION]
(creates a new UDDI user.)
void createUddiUsers(java.util.List users) [ACTION]
(creates the collection of new UDDI users.)
void updateUddiUser(com.ibm.uddi.v3.management.UddiUser user) [ACTION]
(updates UDDI user details.)
void deleteUddiUser(java.lang.String userId) [ACTION]
(deletes UDDI publisher.)
void assignTier(java.util.List userIds,java.lang.String tierId) [ACTION]
(sets the tier for a List of users.)
notificationInfo: description=default UDDI event,descriptorType=notification,
severity=(6),name=uddi.node.event
notificationInfo: description=null,descriptorType=notification,severity=(6),
name=jmx.attribute.changed

See ManageNodeInfoSample class for sample code that demonstrates the attributes and operations
described in this section.

Managing UDDI Node States and Attributes

UDDI nodes can be in one of several states, depending on the way the UDDI application was installed (as
a default configuration or one where the administrator controls when initialization occurs). The UddiNode
MBean provides four read only attributes: nodeID, nodeState, nodeDescription and nodeApplicationName.
In addition the following MBean operations change UDDI node state: activateNode, deactivateNode and
initNode.

nodeID

The node ID is the unique identifier for a UDDI node. If the UDDI application is installed as a default
configuration the node ID is automatically generated. If the UDDI application is set up manually, the node
ID is set by the administrator. It must be a valid UDDI key.
String nodeID = uddiNode.getNode();

System.out.println("node ID: " + nodeId);

nodeState

The nodeState attribute can have one of the following values:

nodeState value English text associated with state

node.state.uninitialized Not initialized
node.state.initialized Initialized
node.state.initPending Initialization pending
node.state.initInProgress Initialization in progress
node.state.activated Activated
node.state.deactivated Deactivated
node.state.unknown Unknown

After installing a UDDI application using the default configuration, the UDDI node will be in activated state,
that is, ready to receive and process UDDI API requests. The node ID and root key generator and some
other properties are generated and cannot be changed. For a manually installed UDDI application where
you want to specify the UDDI node ID and root key generator values, starting the UDDI application will put
the UDDI node into initPending state. In this state, you can update all writable values up until the point you

1218 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
invoke the initNode operation. The initNode operation loads bas e tModels and value set data and writes
all the configuration data to the UDDI node‘s database. During initialization the state is initInProgress.
When initialization completes, the state changes momentarily to initialized and settles at activated. At this
point the state can only be switched between activated and deactivated using deactivateNode and
activateNode MBean operations.

Each node state value is in fact a message key which can be looked up in the messages.properties
resource bundle. The attribute value can be retrieved using the getNodeState method of UddiNodeProxy:
1. Invoke getNodeState:
String nodeStateKey = uddiNode.getNodeState();
2. Look up translated text from ResourceBundle and output:
String messages = "com.ibm.uddi.v3.management.messages";

ResourceBundle bundle = ResourceBundle.getBundle(messages,

Locale.ENGLISH);

String nodeStateText = bundle.getString(nodeStateKey);

System.out.println("node state: " + nodeStateText);

nodeDescription

You can get the administrator assigned description for the UDDI node using the getNodeDescription
method of UddiNodeProxy:
1. Invoke getNodeDescription and output:
String nodeDescription = uddiNode.getNodeDescription();
System.out.println("node description: " + nodeDescription);

nodeApplicationName

The nodeApplicationName attribute is useful for discovering where the UDDI application that corresponds
to the UDDI node is installed. The value will be a concatenation of the cell, node and server names,
separated by colons. Retrieve the application location using the getApplicationId method of
UddiNodeProxy:
1. Invoke getApplicationId and output:
String nodeApplicationId = uddiNode.getApplicationId();

System.out.println("node application location: " +

nodeApplicationId);

activateNode

Changes the state of the UDDI node to activated, if the UDDI node was previously deactivated.
1. . Invoke activateNode:
uddiNode.activateNode();

deactivateNode

Changes the state of the UDDI node to deactivated, if the UDDI node was previously activated.
1. Invoke deactivateNode:
uddiNode.deactivateNode();

initNode

Causes UDDI node initialization, and when this completes the state of the UDDI node is ’activated‘.

Chapter 8. Developing WebSphere applications 1219

1. Invoke initNode:
uddiNode.initNode();

Managing Configuration Properties

UDDI node runtime behavior is affected by the setting of several configuration properties. The UddiNode
MBean provides operations to inspect and update their values, as follows: getProperties, getProperty,
updateProperty and updateProperties.

See ManagePropertiesSample class for sample code that demonstrates the operations described in this
section.

get Properties

Returns collection of all configuration properties as ConfigurationProperty objects.

1. Invoke getProperties:
List properties = uddiNode.getProperties();
2. Cast each collection member to ConfigurationProperty:
if (properties != null) {
for (Iterator iter = properties.iterator(); iter.hasNext();) {
ConfigurationProperty property =
(ConfigurationProperty) iter.next();
System.out.println(property);
}
}

Once you have the ConfigurationProperty objects you can inspect attributes like the ID, value, type,
whether the property is read only, required for initialization, and get name and description message keys.
For example, invoking the toString method returns results similar to:
ConfigurationProperty
id: operatorNodeIDValue
nameKey: property.name.operatorNodeIDValue
descriptionKey: property.desc.operatorNodeIDValue
type: java.lang.String
value: uddi:capnscarlet:capnscarlet:server1:default
unitsKey:
readOnly: true
required: true
usingMessageKeys: false
validValues: none

The nameKey and descriptionKey values can be used to look up the translated name and description for a
given locale, using the messages.properties resource in uddiadmin.jar.

getProperty

Returns ConfigurationProperty object with the specified ID. Available property IDs are specified in
PropertyConstants together with descriptions of the purpose of the corresponding properties.
1. Invoke getProperty:
ConfigurationProperty property =
uddiNode.getProperty(PropertyConstants.DATABASE_MAX_RESULT_COUNT);
2. To retrieve the value of the property you could use the getValue method which returns an Object, but
in this case, the property is of type integer, so it‘s easier to retrieve the value using the convenience
method getIntegerValue:
int maxResults = property.getIntegerValue();

updateProperty

1220 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Updates the value of the ConfigurationProperty object with the specified ID. Available property IDs are
specified in PropertyConstants together with descriptions of the purpose of the corresponding properties.
Although you can invoke the setter methods in a ConfigurationProperty object, the only value that is
updated in the UDDI node is the value. So to update a property, the steps are typically:
1. Create a ConfigurationProperty object and set its ID:
ConfigurationProperty defaultLanguage = new ConfigurationProperty();
defaultLanguage.setId(PropertyConstants.DEFAULT_LANGUAGE);
2. Set the value:
defaultLanguage.setStringValue("ja");
3. Invoke updateProperty:
uddiNode.updateProperty(defaultLanguage);

updateProperties

Updates several ConfigurationProperty objects in a single request. Set up the ConfigurationProperty

objects as for the updateProperty operation.
1. Add updated properties to a List:
List updatedProperties = new ArrayList();

updatedProperties.add(updatedProperty1);
updatedProperties.add(updatedProperty2);
2. Invoke updateProperties:
uddiNode.updateProperties(updatedProperties);

Managing Policies

Policies affecting behavior of the UDDI API are managed using the following UddiNode operations:
getPolicyGroups, getPolicyGroup, getPolicy, updatePolicy and updatePolicies.

See ManagePoliciesSample class for sample code that demonstrates the attributes and operations
described in this section.

getPolicyGroups

Returns collection of all policy groups as PolicyGroup objects.

1. Invoke getPolicyGroups:
List policyGroups = uddiNode.getPolicyGroups();
2. Cast each collection member to PolicyGroup:
if (policyGroups != null) {
for (Iterator iter = policyGroups.iterator(); iter.hasNext();) {
PolicyGroup policyGroup = (PolicyGroup) iter.next();
System.out.println(policyGroup);
}
}

Each policy group has an ID, name and description key (which can be looked up in the
messages.properties resource in uddiadmin.jar). While the PolicyGroup class does have a getPolicies
method it is important to note that PolicyGroup objects returned by the getPolicyGroups operation do not
contain any Policy objects. This is so clients can determine the known policy groups (and their IDs) without
retrieving the entire set of policies in one request. To retrieve the policies within a policy group, you would
use the getPolicyGroup operation.

getPolicyGroup

Returns the PolicyGroup object with the supplied ID.

Chapter 8. Developing WebSphere applications 1221
1. Convert policy group ID to a String:
String groupId = Integer.toString(PolicyConstants.REG_APIS_GROUP);
2. Invoke getPolicyGroup:
PolicyGroup policyGroup = uddiNode.getPolicyGroup(groupId);

getPolicy

Returns the Policy object for the specified ID. Like a ConfigurationProperty, a Policy object has an ID,
name and description keys, type, value and indicators specifying if the policy is read only or required for
node initialization.
1. Convert policy ID to a String:
String policyId = Integer.toString(
PolicyConstants.REG_AUTHORIZATION_FOR_INQUIRY_API);
2. Invoke getPolicy:
Policy policy = uddiNode.getPolicy(policyId);

updatePolicy

Updates the value of the Policy object with the specified ID. Available policy IDs are specified in
PolicyConstants together with descriptions of the purpose of the corresponding policies. Although you can
invoke the setter methods in a Policy object, the only value that is updated in the UDDI node is the value.
So to update a policy, the steps are typically:
1. Create a Policy object and set its ID:
Policy updatedPolicy = new Policy();
String policyId =
Integer.toString(PolicyConstants.REG_SUPPORTS_UUID_KEYS);
updatedPolicy.setId(policyId);
2. Set the value:
updatedPolicy.setBooleanValue(true);
3. Invoke updatePolicy:
uddiNode.updatePolicy(updatedPolicy);

updatePolicies

Updates several Policy objects in a single request. Set up the Policy objects as for the updatePolicy
operation.
1. Add updated policies to a List:
List updatedPolicies = new ArrayList();

updatedPolicies.add(updatedPolicy1);
updatedPolicies.add(updatedPolicy2);
2. Invoke updatePolicies:
uddiNode.updatePolicies(updatedPolicies);

Managing Tiers

Tiers control how many of each type of UDDI entities a publisher can save in the UDDI registry. A tier has
an ID, an administrator defined name and description, and a set of limits, one for each type of entity. Tiers
are managed using the following UddiNode operations: createTier, getTierDetail, getTierInfos,
getLimitInfos, setDefaultTier, updateTier, deleteTier and getUserCount.

See ManageTiersSample class for sample code that demonstrates the attributes and operations described
in this section.

1222 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
createTier

Creates a new tier, with specified publish limits for each UDDI entity.
1. Set tier name and description in a TierInfo object.
String tierName = "Tier 100";
String tierDescription = "A tier with all limits set to 100.";

TierInfo tierInfo = new TierInfo(null, tierName, tierDescription);

2. Define Limit objects for each UDDI entity:
List limits = new ArrayList();

Limit businessLimit = new Limit();

businessLimit.setIntegerValue(100);

businessLimit.setId(LimitConstants.BUSINESS_LIMIT);

Limit serviceLimit = new Limit();

serviceLimit.setIntegerValue(100);
serviceLimit.setId(LimitConstants.SERVICE_LIMIT);

Limit bindingLimit = new Limit();

bindingLimit.setIntegerValue(100);
bindingLimit.setId(LimitConstants.BINDING_LIMIT);

Limit tModelLimit = new Limit();

tModelLimit.setIntegerValue(100);
tModelLimit.setId(LimitConstants.TMODEL_LIMIT);

Limit assertionLimit = new Limit();

assertionLimit.setIntegerValue(100);

assertionLimit.setId(LimitConstants.ASSERTION_LIMIT);
limits.add(businessLimit);
limits.add(serviceLimit);
limits.add(bindingLimit);
limits.add(tModelLimit);
limits.add(assertionLimit);
3. Create Tier object:
Tier tier = new Tier(tierInfo, limits);
4. Invoke create Tier and retrieve created tier:
Tier createdTier = uddiNode.createTier(tier);
5. Inspect generated tier ID of created tier:
tierId = createdTier.getId();
System.out.println("created tier has ID: " + tierId);

getTierDetail

Returns the Tier object for the given tier ID. The Tier class has getter methods for the tier ID, tier name
and description (as set by the administrator), and the collection of Limit objects which specify how many of
each UDDI entity type may be published by UDDI publishers allocated to the tier. The isDefault method
indicates whether the tier is the default tier, that is, the tier that is allocated to UDDI publishers when auto
registration is enabled.
1. Invoke getTierDetail:
Tier tier = uddiNode.getTierDetail("2");

updateTier

Updates tier contents with the supplied Tier object.

Chapter 8. Developing WebSphere applications 1223

1. Update an existing Tier object (which may have been newly instantiated, or returned by the
getTierDetail or createTier operations). This example retains the tier name and description, and all the
limit values except the limit being updated:
modifiedTier.setName(tier.getName());
modifiedTier.setDescription(tier.getDescription());

Limit tModelLimit = new Limit();

tModelLimit.setId(LimitConstants.TMODEL_LIMIT);
tModelLimit.setIntegerValue(50);

List updatedLimits = new ArrayList();

updatedLimits.add(tModelLimit);

modifiedTier.setLimits(updatedLimits);
2. Invoke updateTier:
uddiNode.updateTier(modifiedTier);

getTierInfos

Returns collection of lightweight tier descriptor objects (TierInfo) which contain the tier ID, and tier name
and description values, and whether the tier is the default tier.
1. Invoke getTierInfos:
List tierInfos = uddiNode.getTierInfos();
2. Output content of each TierInfo:
if (tierInfos != null) {

for (Iterator iter = tierInfos.iterator(); iter.hasNext();) {

TierInfo tierInfo = (TierInfo) iter.next();
System.out.println(tierInfo);
}
}

setDefaultTier

Specifies the tier with the given tier ID is the default tier. The default tier is the tier that is allocated to
UDDI publishers when auto registration is enabled. Typically this would be set to a tier with low publish
limits to prevent casual users publishing too many entities.
1. Invoke setDefaultTier:
uddiNode.setDefaultTier("4");

deleteTier

Removes the tier with the given tier ID. Tiers can only be removed if they have no UDDI publishers
assigned to them, and the tier is not the default tier.
1. Invoke deleteTier:
uddiNode.deleteTier("4");

getUserCount

Returns the number of UDDI publishers assigned to tier specified by the tier ID.
1. Invoke getUserCount:
Integer userCount = uddiNode.getUserCount("4");
System.out.println("users in tier 4: " + userCount.intValue());

getLimitInfos

1224 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Returns collection of Limit objects representing the limit values for each type of UDDI entity. Limits are
used in Tier objects.
1. Invoke getLimitInfos:
List limits = uddiNode.getLimitInfos();
2. Output the ID and limit value for each Limit object:
for (Iterator iter = limits.iterator(); iter.hasNext();) {
Limit limit = (Limit) iter.next();

System.out.println("limit ID: "

+ limit.getId()
+ ", limit value: "
+ limit.getIntegerValue());
}

Managing UDDI Publishers

UDDI publishers are managed using the UddiNode MBean operations createUddiUser, createUddiUsers,
updateUddiUser, deleteUddiUser, getUddiUser, getUserInfos, getEntitlementInfos, assignTier, getUserTier.
An example is provided for each, making use of the UddiNodeProxy client class.

See ManagePublishersSample class for sample code that demonstrates the attributes and operations
described in this section.

createUddiUser

Registers a single UDDI publisher, in a specified tier, with specified entitlements. The UddiUser class
represents the UDDI publisher, and this is constructed using a user name (ID), a TierInfo object which
specifies the tier ID to allocate the UDDI publisher to, and a collection of Entitlement objects which specify
what the UDDI publisher is permitted to do.

Tip: to allocate the UDDI publisher default entitlements, set the entitlements parameter to null.
1. Create the UddiUser object:
UddiUser user = new UddiUser("user1", new TierInfo("3"), null);
2. Invoke createUddiUser:
uddiNode.createUddiUser(user);

createUddiUsers

Registers multiple UDDI publishers. This example shows how to register 7 UDDI publishers in one call,
with default entitlements.
1. Create TierInfo objects for tiers that publishers will be allocated to:
TierInfo tier1 = new TierInfo("1");
TierInfo tier4 = new TierInfo("4");
2. Create UddiUser objects for each UDDI publisher, specifying tier to allocate to:
UddiUser publisher1 = new UddiUser("Publisher1", tier4, null);
UddiUser publisher2 = new UddiUser("Publisher2", tier4, null);
UddiUser publisher3 = new UddiUser("Publisher3", tier4, null);
UddiUser publisher4 = new UddiUser("Publisher4", tier1, null);
UddiUser publisher5 = new UddiUser("Publisher5", tier1, null);
UddiUser cts1 = new UddiUser("cts1", tier4, null);
UddiUser cts2 = new UddiUser("cts2", tier4, null);
3. Add the UddiUser objects to a List:
List uddiUsers = new ArrayList();

uddiUsers.add(publisher1);
uddiUsers.add(publisher2);

Chapter 8. Developing WebSphere applications 1225

 uddiUsers.add(publisher3);
uddiUsers.add(publisher4);
uddiUsers.add(publisher5);
uddiUsers.add(cts1);
uddiUsers.add(cts2);
4. Invoke createUddiUsers:
uddiNode.createUddiUsers(uddiUsers);

updateUddiUser

Updates a UDDI publisher with the details in the supplied UddiUser object. This is typically used to change
the tier of one UDDI publisher or update their entitlements. Tip: only supply the entitlements you want to
update – the remainder of available entitlements will retain their existing value.
1. Create Entitlement objects with appropriate permission. (the entitlement IDs are found in
EntitlementConstants:
Entitlement publishUuiDKeyGenerator =
new Entitlement(PUBLISH_UUID_KEY_GENERATOR, true);
Entitlement publishWithUuidKey =
new Entitlement(PUBLISH_WITH_UUID_KEY, true);
2. Add Entitlement objects to a List:
List entitlements = new ArrayList();
entitlements.add(publishUuiDKeyGenerator);
entitlements.add(publishWithUuidKey);
3. Update a UddiUser object with the updated entitlements:
user.setEntitlements(entitlements);
4. Invoke updateUddiUser:
uddiNode.updateUddiUser(user);

getUddiUser

Retrieves details about a UDDI publisher in the form of a UddiUser object. This specifies the UDDI
publisher ID, information about the tier they are assigned to and the entitlements they possess.
1. Invoke getUddiUser:
UddiUser user1 = uddiNode.getUddiUser("user1");
2. Output the contents of UddiUser:
System.out.println("retrieved user: " + user1);

getUserInfos

Returns a collection of UserInfo objects. Each UserInfo represents a UDDI publisher known to the UDDI
node, and the name of the tier they are allocated to. To get details about a specific UDDI publisher,
including the tier ID, and entitlements, use the getUddiUser operation.
1. Invoke getUserInfos:
List registeredUsers = uddiNode.getUserInfos();
2. Output the UserInfo objects:
System.out.println("retrieved registered users: ");
System.out.println(registeredUsers);

getEntitlementInfos

Returns a collection of Entitlement objects. Each entitlement is a property that controls whether permission
is granted to a UDDI publisher to perform a specified action.
1. Invoke getEntitlementInfos:
List entitlementInfos = uddiNode.getEntitlementInfos();

1226 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Specify where to find message resources:
String messages = "com.ibm.uddi.v3.management.messages";
ResourceBundle bundle = ResourceBundle.getBundle(
messages, Locale.ENGLISH);
3. Iterate through the Entitlement objects, displaying the ID, name and description:
for (Iterator iter = entitlementInfos.iterator(); iter.hasNext();) {
Entitlement entitlement = (Entitlement) iter.next();

StringBuffer entitlementOutput = new StringBuffer();

String entitlementId = entitlement.getId();

String entitlementName =
bundle.getString(entitlement.getNameKey());
String entitlementDescription =
bundle.getString(entitlement.getDescriptionKey());

entitlementOutput.append("Entitlement id: ");

entitlementOutput.append(entitlementId);
entitlementOutput.append("\n name: ");
entitlementOutput.append(entitlementName);
entitlementOutput.append("\n description: ");
entitlementOutput.append(entitlementDescription);

System.out.println(entitlementOutput.toString());
}

deleteUddiUser

Removes the UDDI publisher with the specified user name (ID) from the UDDI registry.
1. Invoke deleteUddiUser:
uddiNode.deleteUddiUser("user1");

assignTier

Assigns UDDI publishers with supplied IDs to the specified tier. This is useful when you want to restrict
several UDDI publishers, perhaps by assigning them all to a tier that doesn‘t allow publishing of any
entities.
1. Create list of publisher IDs:
List uddiUserIds = new ArrayList();

uddiUserIds.add("Publisher1");
uddiUserIds.add("Publisher2");
uddiUserIds.add("Publisher3");
uddiUserIds.add("Publisher4");
uddiUserIds.add("Publisher5");
uddiUserIds.add("cts1");
uddiUserIds.add("cts2");
2. Invoke assignTier:
uddiNode.assignTier(uddiUserIds, "0");

getUserTier

Returns information about the tier a UDDI publisher is assigned to. The returned TierInfo has getters
methods for retrieving the tier ID, tier name, tier description, and whether the tier is the default tier.
1. Invoke getUserTier:
TierInfo tierInfo = getUserTier("Publisher3");
2. Output the contents of the TierInfo object:
System.out.println(tierInfo);

Chapter 8. Developing WebSphere applications 1227

Managing Value Sets

Value sets are represented in a UDDI registry as value set tModels, with a UDDI types keyedReference
with value ’categorization‘. Such value sets are backed with a set of valid values and for user defined
value sets, this data is loaded into the UDDI registry using UddiNode MBean operations (although it is
more convenient to use the User defined value set tool for this purpose). Each value set can be controlled
by policy as being supported or not supported. When a value set is supported by policy, it can be
referenced within UDDI publish requests. The UddiNode operations available to manage value sets and
their data are: getValueSets, getValueSetDetail, getValueSetProperty, updateValueSet, updateValueSets,
loadValueSet, changeValueSetTModelKey, unloadValueSet and isExistingValueSet.

See ManageValueSetsSample class for sample code that demonstrates the attributes and operations
described in this section.

getValueSets

Returns collection of ValueSetStatus objects.

1. Invoke getValueSets:
List valueSets = uddiNode.getValueSets();
2. Cast each element to ValueSetStatus and output contents:
for (Iterator iter = valueSets.iterator(); iter.hasNext();) {

ValueSetStatus valueSetStatus = (ValueSetStatus) iter.next();

System.out.println(valueSetStatus);
}

getValueSetDetail

Returns ValueSetStatus object for the given value set tModel key.
1. Invoke getValueSetDetail:
uddiNode.getValueSetDetail(
"uddi:uddi.org:ubr:categorization:naics:2002");
2. Retrieve and display details:
String name = valueSetStatus.getName();
String displayName = valueSetStatus.getDisplayName();
boolean supported = valueSetStatus.isSupported();

System.out.println("name: " + name);

System.out.println("display name: " + displayName);
System.out.println("supported: " + supported);
3. Display value set properties:
List properties = valueSetStatus.getProperties();

for (Iterator iter = properties.iterator(); iter.hasNext();) {

ValueSetProperty property = (ValueSetProperty) iter.next();

System.out.println(property);
}

getValueSetProperty

Returns a property of a value set as a ValueSetProperty object. This is mainly for use by the WebSphere
administrative console to render properties of a value set as a row in a table. For example, one such
property is the keyedReference which indicates whether the value set is checked.
1. Invoke getValueSetProperty:

1228 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 uddiNode.getValueSetProperty(
"uddi:uddi.org:ubr:categorization:naics:2002",
ValueSetPropertyConstants.VS_CHECKED);
2. Read and display boolean value of the property:
boolean checked = valueSetProperty.getBooleanValue();

System.out.println("checked: " + checked);

updateValueSet

Updates value set status. Only the supported attribute can be updated (all other setter methods are used
by the UDDI application).
1. Create a ValueSetStatus object specifying the tModel key and the updated supported value:
ValueSetStatus updatedStatus = new ValueSetStatus();
updatedStatus.setTModelKey(
"uddi:uddi.org:ubr:categorization:naics:2002");
updatedStatus.setSupported(true);
2. Invoke updateValueSet:
uddiNode.updateValueSet(updatedStatus);

updateValueSets

Updates value set status for multiple value sets. As for the updateValueSet operation, only the supported
attribute is updated.
1. Populate List with updated ValueSetStatus objects:
List valueSets = new ArrayList();

ValueSetStatus valueSetStatus = new ValueSetStatus();

valueSetStatus.setTModelKey(
"uddi:uddi.org:ubr:categorization:naics:2002");
valueSetStatus.setSupported(false);
valueSets.add(valueSetStatus);

valueSetStatus = new ValueSetStatus();

valueSetStatus.setTModelKey(
"uddi:uddi.org:ubr:categorizationgroup:wgs84");
valueSetStatus.setSupported(false);
valueSets.add(valueSetStatus);

valueSetStatus = new ValueSetStatus();

valueSetStatus.setTModelKey(
"uddi:uddi.org:ubr:identifier:iso6523:icd");
valueSetStatus.setSupported(false);
valueSets.add(valueSetStatus);
2. Invoke updateValueSets:
uddiNode.updateValueSets(valueSets);

loadValueSet

Loads values for a value set from a UDDI Registry V3/V2 taxonomy data file on the local file system. Note:
there is also a loadValueSet operation that takes a ValueSetData object but this is only for use by the user
defined value set tool.
1. Invoke loadValueSet:
uddiNode.loadValueSet(
"C:/valuesets/myvalueset.txt",
"uddi:cell:node:server:myValueSet");

changeValueSetTModelKey

Chapter 8. Developing WebSphere applications 1229

Any value set values that were allocated to one value set tModel are allocated to the new value set
tModel.
1. Invoke changeValueSetTModelKey with old and new tModel keys:
uddiNode.changeValueSetTModelKey(
"uddi:cell:node:server:myValueSet",
"uddi:cell:node:server:myNewValueSet");

unloadValueSet

Unloads values for a value set with the given tModel key.
1. Invoke unloadValueSet:
uddiNode.unloadValueSet("uddi:myValueSet");

isExistingValueSet

Determines if value set data exists for the given tModel key.
1. Invoke isExistingValueSet and display result:
boolean exists = uddiNode.isExistingValueSet(
"uddi:uddi.org:ubr:categorization:naics:2002");
System.out.println("NAICS 2002 is a value set: " + exists);

User-defined value set support in the UDDI registry:

In UDDI Version 2 this was called ’Custom Taxonomy Support’.

Data is worthless if it is lost within a mass of other data and cannot be distinguished or discovered. If a
client of UDDI cannot effectively find information within a registry, the purpose of UDDI is considerably
compromised. Providing the structure and modeling tools to address this problem is at the heart of UDDI’s
design. The verification of data within UDDI is core to its mission of description, discovery and integration.
It achieves this by several means.

It allows users to define multiple value sets that can be used in UDDI. In such a way, multiple classification
schemes can be overlaid on a single UDDI entity. This capability allows organizations to extend the set of
such systems UDDI registries support. One is not tied to a single system, but can rather employ several
different classification systems simultaneously.

While default value sets are shipped with the product, the UDDI Version 3 Private Registry provides tools
enabling ’custom’ value sets to be added, potentially enabling UDDI entities to be more specifically
categorized when published and further enhancing the capability of client to find specific data.

These value sets can be either checked or unchecked, and this is indicated via a keyedReference in the
categoryBag of the tModel that represents a value set (a ″categorization tModel″). These keyedReferences
have the tModel key for uddi-org:types and are added to the categoryBag to further describe the behavior
of the categorization tModel, as follows:
checked
Marking a tModel with this classification asserts that it represents a categorization, identifier, or
namespace tModel that has a validation service to check that category values are present in a
specified value set.
unchecked
Marking a tModel with this classification asserts that it represents a categorization, identifier, or
namespace tModel that does not have a validation service.

The procedure defined below describes how to add additional user-defined value sets, and display their
allowed values in the UDDI user console value set tree display. Rational Application Developer has a Web

1230 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Services Explorer user interface that also allows addition and display of custom checked value sets. The
publisher of a value set categorization tModel may specify a ’display name’ for use in UDDI user console
implementations.

Procedure for adding a user defined value set

To add a user defined value set to the IBM WebSphere UDDI Registry requires you to perform three tasks:
v publish a categorization tModel
v load the user defined value set data
v set the value set to supported status using the Administration console.

Only when all are complete will the checked value set be referenced. Value set data must be provided for
validating checked value sets.

Value set data may also be used by user consoles for unchecked value sets, but it is not a requirement
and is usually only used for presentation of deprecated value sets, such as unspc-org:unspc and
back-level compatibility.

If the value set is checked, any publish requests that have a categoryBag containing keyedReferences
with the new categorization tModel will be validated. If there is value set data corresponding to the
categorization tModel in the registry database, only valid values will be accepted. If there is no value set
data in the database all values will be rejected, and the publish request will fail. If the categorization
tModel is unchecked, all values will be allowed, regardless of whether there is a corresponding value set
present in the UDDI Registry database. The value set tModel is not available for use until the administrator
enables support for it using the Administration console, or the JMX interface.

Suggested approach

To introduce a new value set:

1. Publish the categorization tModel with a keyedReference of type ’uddi-org:categorization:types’ with a
key value of categorization, a keyedReference of type ’uddi-org:categorization:types’ with a Key
Name of ’Checked value set’ and a Key Value of ’checked’, or a Key Name of ’Unchecked value
set’ and a Key Value of ’unchecked’ and a keyedReference of type ’uddi-
org:categorization:general_keywords’ supplying the value set display name (as described below).
2. Load user defined value set data into the UDDI Registry database using the
UDDIUserDefinedValueSet utility (described below).
3. Use the Administration Console to set the status of the value set to supported (as described in Value
set settings). This can also be achieved directly using the JMX interface.

Note: The SOAP and EJB interfaces will be able to make use of categorization tModels as soon as they
are published. However, the UDDI Registry user console will require a restart of the UDDI
application because it currently gathers its list of categorizations for use in the value set tree display
when the application starts.

Publishing a Checked Categorization tModel

This section describes how to publish a checked categorization tModel with the ’Checked value set’ Key
Name for use by a user defined value set.

Publish a tModel to the IBM WebSphere UDDI Registry with a categoryBag containing keyedReferences
as follows:

Note tModelKey KeyName KeyValue

Chapter 8. Developing WebSphere applications 1231

 1 uddi:uddi-org:categorization:types categorization categorization

In the UDDI Registry user

interface this tModelKey can be
chosen by selecting the category
type of UDDI Types
2 uddi:uddi-org:categorization:types Checked value set checked

In the UDDI Registry user

interface this tModelKey can be
chosen by selecting the category
type of UDDI Types
3 uddi:uddi- urn:x-ibm:uddi:customTaxonomy: <User Defined Value Set
org:categorization:general_ displayName displayName>
keywords

In the UDDI Registry user

interface this tModelKey can be
chosen by selecting the category
type of
categorization:general_keywords

1. Indicates this tModel is a categorization tModel (required).

2. Indicates use of the tModel will be checked against a list of valid data (required). (Omitting this
keyedReference, or explicitly specifying a value of ’unchecked’ will indicate this categorization is
unchecked).
3. Indicates special use of the general keywords value set, with a proprietary urn as the keyName value,
defines a name for the user defined value set that is intended for use in user console implementations
where the full tModel name might be too long. The value can be 1-255 characters (inclusive) long.

The displayName is intended to provide a way to label a value set such that, when the UDDI user console
displays it in a value set tree or in a pull-down list of available value sets, the meaning is clear to the user
without being restricted to 8 characters and without needing to be the same as the published tModelName,
which could be as long as 255 characters. An example is shown below:

display name

Taxonomies
test1
udditype
unspsc Locator
Natural Foods
Food Categories: Show category tree
Fruit
Apples [101] Type Key name
Oranges [102] Natural Foods
Pears [103]
Pomegranates [104] test1
Vegetables [20] udditype
geo unspec
naics Natural Foods
other Search Modifiersgeo
unspsc7 naics
Search behavior other
unspsc7

The urn:x-ibm:customTaxonomy:displayName should be unique if only to avoid confusion when displayed

in user interfaces but this is not validated.

1232 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To publish a new categorization tModel using SOAP, the message would be:
<save_tModel generic="3.0" xmlns="urn:uddi-org:api_v3">
<authInfo></authInfo>>
<tModel tModelKey="">
<name>Natural Foods tModel</name>
<categoryBag>
<keyedReference tModelKey="uddi:uddi.org:categorization:types" keyName=
"categorization" keyValue="categorization"/>
<keyedReference tModelKey="uddi:uddi.org:categorization:types" keyName=
"Checked value set" keyValue="checked"/>
<keyedReference tModelKey="uddi:uddi.org:categorization:general_keywords"
keyName="urn:x-ibm:uddi:customTaxonomy:displayName"
keyValue="Natural Foods"/>
</categoryBag>
</tModel>
</save_tModel>

Note: to specify an unchecked categorization substitute the key name ’Checked value set’ with
’Unchecked value set’ and ’checked’ Key Value with ’unchecked’ or, more simply, omit the
keyedReference completely.

Loading User Defined Value Set Data

User Defined Value Set Data File Format

Value set data is identified by a unique code value, an optional description and a parent code that
specifies its relationship with other code values. Value set data must adhere to this format:

Column name Maximum length Description of use

Code 765 Unique value within the value set used for validation
description 765 Typically used by UDDI user consoles and optionally in the
keyedReference as the keyName value
parentcode 765 Indicates which existing code is the logical parent of this one,
and is used in tree displays

Typically columns are delimited in the value set data file by ’#’ characters as in this example:
00#Food#00
10#Fruit#00
101#Apples#10
102#Oranges#10
103#Pears#10
1031#Anjou#103
1032#Conference#103
1033#Bosc#103
104#Pomegranates#10
20#Vegetables#00
201#Carrots#20
202#Potatoes#20
203#Peas#20
204#Sprouts#20

In the example, ’Food’ is the description for the root node with child nodes of ’Fruit’ and ’Vegetables’ (both
of these have parentcode values the same as the code value for ’Food’).

The value set data in the example file could then be rendered in a tree like this:
Food
Fruit
Apples
Oranges

Chapter 8. Developing WebSphere applications 1233

 Pears
Anjou
Conference
Bosc
Pomegranates
Vegetables
Carrots
Potatoes
Peas
Sprouts

The file must be saved in UTF-8 format.

Custom Taxonomy files used in UDDI Version 2 are also supported by the utility.

UDDIUserDefinedValueSet

A utility is provided to load value set data into the IBM WebSphere UDDI Registry, assign existing value
set data to another tModel and unload existing value set data. This utility uses the UDDI Registry’s JMX
interface and therefore requires a number of connection parameters.
Usage: UDDIUserDefinedValueSet[.sh|.bat] ’{’function’}’ [options]

function:
-load <path> <key> Load value set data from specified file
-newKey <oldKey> <newKey> Move value set to a new tModel
-unload <key> Unload existing value set

options:
-properties <path> Specify location of configuration file
-host <host name> Application Server or Deployment Manager host
-port <port> SOAP Lister port number
-node <node name> Node running a UDDI server
-server <server name> Server with UDDI deployed
-columnDelimiter <delim> Character delimiter to denote field end
-stringDelimiter <delim> Character delimiter to denote strings

Connector security parameters

-userName <name>
-password <password>
-trustStore <path>
-trustStorePassword <password>
-keyStore <name>
-keyStorePassword <password>

Note: Ensure that the command window from which the UDDIUserDefinedValueSet is run is using a
suitable codepage and font for displaying the characters contained in the value set name. Use of an
incorrect codepage/font may result in unclear messages on a successful load, and create difficulty
using the -unload and -newKey options.

The UDDIUserDefinedValueSet .bat (for Windows) or UDDIUserDefinedValueSet.sh (for Unix platforms) is

located in the WAS_HOME/bin directory.

If no connection parameters are supplied a connection is sought on the local host using firstly the
Deployment Managers default SOAP port number, and, if there is no Deployment Manager running, the
default Application Server SOAP port number.

Command arguments are case insensitive.

Usage examples

1234 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Load a value set data for a tModel on the local UDDI Registry using the ’%’ sign as a column marker in
the valuesetdata.txt file:
UDDIUserDefinedValueSet.xxx -load valuesetdata.txt
uddi:a708b8a7-35b5-451c-aafc-718ae071fcfe -columnDelimiter %

where .xxx is .bat for Windows or .sh for Unix platforms.

Move value set data from one checked tModel to another on a UDDI Registry in a Network Deployment:
UDDIUserDefinedValueSet.xxx –newKey uddi:a708b8a7-35b5-451c-aafc-718ae071fcfe
uddi:b819c9b8-46c6-562d-bb0d-829bf1820d0f –host depmanagerhost.ibm.com –port
8879 –node uddinode –server uddiserver -override

where .xxx is .bat for Windows or .sh for Unix platforms.

Unload a value set from a tModel from a server with security turned on supplying the connection and
security parameters in myproperties.properties file, but supplying the server and password arguments on
the command line (which augment or override those contained in the properties file):
UDDIUserDefinedValueSet.xxx –unload uddi:b819c9b8-46c6-562d-bb0d-829bf1820d0f
–server uddiserver –properties myproperties.properties
–password myrealpassword

where .xxx is .bat for Windows or .sh for Unix platforms.

The configuration file, if specified by the optional -properties parameter, determines a number of optional
parameters. These parameters can be specified on the command line and, if so, override the values in the
properties file. These parameters are largely JMX connection parameters and security parameters.

The string.delimiter is typically used where a description value contains the same character as the column
delimiter character. For example, if the column.delimiter was set to ’,’ (a comma), and there was a value
set description value of ’Fruits, citrus’, you could include this in the value set data file by setting the
string.delimiter to ″ (double quote) and enclosing the description in quotes: ’Fruits, citrus’. Note that the
quote character is escaped with a backslash (’\’) to indicate the literal character is to be used.

If an attempt is made to load a value set to a tModel that has existing value set data, a warning message
is given. To override this error provide the -override argument. This argument is also required if moving
value set data to a new tModel using -newKey where the tModel is checked, and also unloaded value set
data for a checked tModel.

Command line arguments and Property and example data Comments

example data
-columnDelimiter # column.delimiter=# Column delimiter used in value set
data files
-stringDelimiter \″ string.delimiter=\″ Field delimiter (must be different to
the column.delimiter value
-host ibm.com host=ibm.com Host name of the system running
Deployment Manager or Application
Server
-port 8880 port=8880 SOAP port number of Deployment
Manager or Application Server
-node ibmNode node=ibmNode Name of the Node running the
server with the UDDI Registry
-server server1 server=server1 Server running the UDDI Registry
-userName ibmuser security.username=ibmuser User name. Required if WebSphere
security is turned on

Chapter 8. Developing WebSphere applications 1235

-password mypassword security.password=mypassword Password
-trustStore /TrustStoreLocation security.truststore=/TrustStoreLocation Truststore file location
-keyStore ibmkeystore security.keystore=ibmkeystore Keystore name
-trustStorepassword trustpass security.truststore.password=trustpass Truststore password
-keyStorePassword keypass security.keystore.password=keypass Keystore password

Set the value set to supported

Use the Administration console to set the value set to supported by:
v Click UDDI Nodes > <node> and Value Sets (under Additional Properties on the right of the screen)
v Select the Value Set (by checking the box next to it)
v Click Enable Support above the list of Value Sets

Validation and Error Handling

The UDDI Registry user console performs validation while a save tModel request is being built, that is,
before the publish occurs. For example, if the user tries to add two customTaxonomy:displayName
keyedReferences the following message is displayed:
Advice: Only one ’urn:x-ibm:uddi:customTaxonomy:displayName’ key name is allowed
for the ’Other’ taxonomy.

If a keyedReference containing a keyName value that starts with ’urn:x-ibm:uddi:customTaxonomy:’ is

followed by anything other than ’displayName’, the following message is displayed:
Advice: Only key name values of ’urn:x-ibm:uddi:customTaxonomy:displayName’
are supported.

For requests where the save_tModel message may have multiple tModels, if any one of the tModels is a
categorization tModel and it fails validation, the request fails with a UDDIInvalidValueException (plus
additional information explaining the likely cause), and none of the tModels is published. For example:
E_invalidValue (20200) A value that was passed in a keyValue attribute did not
pass validation.
This applies to checked categorizations, identifiers and other validated code lists.
The error text will clearly indicate the key and value combination that failed validation.
Invalid ’customTaxonomy:dbKey’ keyValue [naics] in keyedReference.
KeyValue already in use by tModelKey[UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2]

UDDI Utility Tools:

The UDDI Utility Tools is a suite of functions that can be used to migrate/move/copy UDDI Version 2
entities, including child entities and their respective Version 2 entity keys, into a Version 3 UDDI Registry.

Note: The UDDI Version 3 publish API supports publisher assigned keys (the Version 2 API did not) and
promotion of entities between Version 3 registries can be achieved using normal API functions.
UDDI Utility Tools supplied in this release is functionally equivalent to the version supplied in
WebSphere Application Server 5.1. However, it is important to know that all UDDI Utility Tools
functions in this release are performed using the UDDI Version 2 API. You can export from Version
2 and 3 registries and import into the Version 3 registry, using Version 2 API types. Entities from a
Version 3 registry are exported as Version 2 entities and, as such, elements such as digital
signatures will not be present. See section Saving Version 3 entities with a supplied key for an
example on how to use the Version 3 API to assign your own keys to Version 3 entities.

Other uses of the tool include:

v Search and select entities from a source UDDI Registry by specifying keys or search criteria

1236 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Publishing canonical tModels in a UDDI Registry, including child entities
v Persist UDDI (Version 2) entities in an intermediate XML representation that can be used to customize
and copy those entities to multiple target UDDI Registries
v Update existing entities in a target UDDI Registry, including child entities
v Delete selected entities from a target UDDI Registry

UDDI Utility Tools can be used by running the UDDIUtilityTools.jar file. This file is located in the
WAS_HOME/UDDIReg/scripts directory. Alternatively, all of the functions of UDDI Utility Tools can be
invoked through the supplied public Java API.

There are five main functions in UDDI Utility Tools:

Export
Given an entity type and key, or a list of entity types and keys, UDDI Utility Tools gets the UDDI
entities from the specified registry and writes them to the UDDI Entity Definition File. The entity
type for each key can be one of business, service, bindingTemplate or tModel. The Entity
Definition File contains XML that exactly describes each of the specified entities, according to the
UDDI Utility Tools schema (which includes the UDDI Version 2 schema). The UDDI Entity
Definition File separates entities by type, and automatically detects and records tModels
referenced by the specified entities. You can use the ’referenced tModels’ section of the file to
ensure a target registry includes any referenced tModels before you try to import new entities to
that registry.
Import
Given a list of UDDI entities (which can be supplied using the UDDI Entity Definition File
generated by the export function, possibly with additional editing, or programmatically in a
container object), the import function detects if the entities already exist in the target registry and,
if they do not, creates a minimal entity (″stub″) with the specified key. The entities are then
published updating the stubs with the supplied data and overwriting, or ignoring, existing entities
as specified by the user. Note that the original key is maintained throughout.
Promote
Combines the export and import steps such that the specified entities are extracted (by key) from
the source registry and then imported into the target registry in a single logical step. The
generation of a UDDI Entity Definition File is optional for this function.
Delete Deletes the specified entities from the target UDDI Registry. The entities to delete are specified as
an entity type, or a list of entity types, and keys, in the same way as for the export function.
Find Matching Entities
Takes as input search criteria in the form of UDDI Inquiry API objects for each of the various entity
types. The set of entities that match the search criteria are used to generate a list of entity keys,
and this in turn can be used as input to the export, promote and delete functions.

Note: This function is available only through the programmatic API.

The relationship between the functions, their input and output, and the source and target UDDI
Registries is shown in this conceptual overview diagram:

Chapter 8. Developing WebSphere applications 1237

Setting up the configuration file

Configuration data for UDDI Utility Tools resides in a configuration properties file, which describes the
runtime environment, UDDI and database locations and access information, logging information, security
configuration, entity definition file location, and other flags to control whether referenced entities are to be
imported and/or overwritten.

UDDI Utility Tools is distributed with a sample configuration properties file (UDDIUtilityTools.properties) and
this is searched for by default in the current directory if no properties path is specified. By default, this file
is located in the WAS_HOME/UDDIReg/scripts directory.

The most important property to set is the classpath, and this should include the current directory (.) and
the UDDIUtilityTools.jar itself, plus all the dependent jars, most of which are located in the WebSphere
AppServer lib directory. The classpath must include the database driver jar (for example db2java.zip). The
other properties are well commented in the example properties file.

Below is an example properties file as distributed:

##############################################
# Runtime environment #
# (if invoking via java -jar...) #
# "X Y" required around paths with spaces #
##############################################
classpath=.;c:/Progra~1/WebSphere/utilitytools/UDDIUtilityTools.jar;
C:/WebSphere/AppServer/lib/soap.jar;C:/WebSphere/AppServer/java/jre/lib/ext/mail.jar;
C:/WebSphere/AppServer/java/jre/lib/ext/ibmjsse.jar;
C:/WebSphere/AppServer/java/jre/lib/ext/activation.jar;
C:/promoter/uddi4jv2.jar;C:/WebSphere/AppServer/lib/xerces.jar;
C:/WebSphere/AppServer/lib/j2ee.jar;"C:/Program Files/SQLLIB/java12/db2java.zip"

(ALL the above is on ONE line - shown here as broken for clarity)

##############################################
# SOAP entry points for source UDDI #
##############################################
fromInquiryURL=http://localhost:9080/uddisoap/inquiryapi
fromGetURL=http://localhost:9080/uddisoap/get

##############################################

1238 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 # SOAP entry points for target UDDI #
##############################################
toInquiryURL=http://localhost:9080/uddisoap/inquiryapi
toPublishURL=http://localhost:9080/uddisoap/publishapi

##############################################
# UDDI Registry user information #
# #
# Note: this must match the user information #
# that was used to publish the entities on #
# the target UDDI registry. #
##############################################
userID=UNAUTHENTICATED
password=NONE

##############################################
# Configuration for destination UDDI DB #
##############################################
dbDriver=COM.ibm.db2.jdbc.app.DB2Driver
dbUrl=jdbc:db2:uddi30
dbUser=db2admin (Your dbUser id)
dbPasswd=db2admin (Your dbPassword)

##############################################
# Security provider configuration #
##############################################
# Indicates whether security is required on the target registry
secure.connection=true

# The location of the truststore if security is required

trustStore.fileName=c:/websphere/appserver/etc/DummyClientTrustFile.jks

# The password for the trust store

trustStore.password=WebAS

##############################################
# Trace and message logging configuration #
##############################################
# detail level of message output (all functions)
verbose=true

# detail level of trace output.

# 1: severe
# 2: normal
# 3: detail
traceLevel=3

# path to message log file (relative or absolute)

messageLogFileName=logs/messages.log

# path to trace log file (relative or absolute)

traceLogFileName=logs/trace.log

##############################################
# Miscellaneous Options #
##############################################
# indicates if existing entities are overwritten (import/promote)
overwrite=false

# indicates if referenced entities will be imported (import/promote)

importReferencedEntities=true

# location of entity definition file, used for (export/import)

UddiEntityDefinitionFile=C:/definitions/entities01.xml

# namespace prefix to use in definition file (export)

namespacePrefix=promote

Chapter 8. Developing WebSphere applications 1239

Prerequisites

UDDI Utility Tools must have the following jar files available. Their locations should be specified in the
classpath property in the UDDI Utility Tools properties file:
UDDIUtilityTools.jar
This is the tools jar itself. It MUST appear on the classpath.
uddi4jv2.jar
This is the UDDI4J classes and can be found in <WAS_HOME>/lib.
j2ee.jar
This contains some required J2EE classes.
soap.jar
This is the Apache SOAP implementation.
xerces.jar
This is the xerces XML parser.
DbDriver
This is the default driver needed to allow UUT to connect to your target database. For example,
for DB2, it would be $DB2_HOME/DB2java.zip, for Oracle, it would be
$ORACLE_HOME/jdbc/lib/ojdbc14.jar and for Cloudscape you need two jars. These are
WAS_HOME/cloudscape/lib/otherJars/db2jcc.jar and
WAS_HOME/cloudscape/lib/db2jcc_license_c.jar. The respective dbURL’s and Drivers are: for
DB2 jdbc:db2:databasename and COM.ibm.db2.jdbc.app.DB2Driver, for Oracle thin client
jdbc:oracle:thin:@host:1521:databasename (the number specified is the default port number and
this may change depending on your Oracle setup) and Oracle.jdbc.driver.OracleDriver, for
Cloudscape jdbc:db2j:net://host:1527/databasename (databasename includes the path) and
com.ibm.db2.jcc.DB2Driver. Note that if your destination database is Cloudscape you will need to
make it network enabled so that it can handle multiple connections. See Configuring Cloudscape
Version 5.1.38 for details on how to do this. For information on how to set up Cloudscape for
multiple connections, see:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=
/com.ibm.websphere.base.doc/info/ae/ae/ tdat_cloudscape_setup.html

Apache SOAP, and therefore UDDI Utility Tools, has a requirement of having activation.jar and mail.jar
java extensions available. These should NOT be placed on the classpath but rather the ext folder of the
JRE that is used to run the tool. If SSL is needed then ibmjsse.jar must also be in the ext folder. If you are
using the JRE as supplied with IBM WebSphere Application Server then these extensions will already be
in place and no further action is necessary.

The Security provider configuration section in the above properties file shows the location of the default
DummyClientTrustFile.jks file. If you are using your own truststore, ensure that the location is placed here.

The UDDI Entity Definition File

You generate this file by the export and promote functions, or you can choose to create it (either by hand,
or by modifying a version of the file output by UDDI Utility Tools specifying the export function). It is the
input to the import function.

Note: The extension to the uddi:tModel type to add a ’deleted’ attribute is not currently used in UDDI
Utility Tools.

The file is validated for well formedness and that it complies with the UDDI Utility Tools schema, shown
here.

1240 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema id="uddiPromote" attributeFormDefault="unqualified"
elementFormDefault="qualified"
targetNamespace="http://www.ibm.com/xmlns/prod/WebSphere/UDDIUtilityTools"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:uddi="urn:uddi-org:api_v2" xmlns=
"http://www.ibm.com/xmlns/prod/WebSphere/UDDIUtilityTools"
xmlns:promote="http://www.ibm.com/xmlns/prod/WebSphere/UDDIUtilityTools">

<xsd:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd" />

<xsd:import namespace="urn:uddi-org:api_v2" schemaLocation="uddi_v2.xsd" />

<!-- define a type to represent state of a tModel -->

<xsd:simpleType name="tModelDeleted">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="true" />
<xsd:enumeration value="false" />
</xsd:restriction>
</xsd:simpleType>

<!-- extend tModel with additional attribute of type tModelDeleted -->

<!-- This is restricted to values true or false -->
<xsd:complexType name="tModel">
<xsd:complexContent>
<xsd:extension base="uddi:tModel">
<xsd:attribute name="deleted" type="promote:tModelDeleted" use="optional" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>

<!-- Top level element definitions -->

<xsd:element name="uddiEntities" type="promote:uddiEntities" />
<xsd:complexType name="uddiEntities">
<xsd:sequence>
<xsd:element ref="promote:tModels" minOccurs="0" maxOccurs="1" />
<xsd:element ref="promote:businesses" minOccurs="0" maxOccurs="1" />
<xsd:element ref="promote:services" minOccurs="0" maxOccurs="1" />
<xsd:element ref="promote:bindings" minOccurs="0" maxOccurs="1" />
<xsd:element ref="promote:referencedTModels" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>

<xsd:element name="businesses" type="promote:businesses" />

<xsd:complexType name="businesses">
<xsd:sequence>
<xsd:element ref="uddi:businessEntity" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>

<xsd:element name="tModels" type="promote:tModels" />

<xsd:complexType name="tModels">
<xsd:sequence>
<xsd:element ref="uddi:tModel" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>

<xsd:element name="services" type="promote:services" />

<xsd:complexType name="services">
<xsd:sequence>
<xsd:element ref="uddi:businessService" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>

<xsd:element name="bindings" type="promote:bindings" />

<xsd:complexType name="bindings">
<xsd:sequence>

Chapter 8. Developing WebSphere applications 1241

 <xsd:element ref="uddi:bindingTemplate" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>

<xsd:element name="referencedTModels" type="promote:referencedTModels" />

<xsd:complexType name="referencedTModels">
<xsd:sequence>
<xsd:element ref="uddi:tModel" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>

UDDI Entity Definition File example for canonical tModels

The example Entity Definition File following shows the five main sections for tModels, businesses,
services, bindings and referencedTModels:

UDDI Utility Tools can be used to create new UDDI entities in a target UDDI Registry. A typical example of
this is to introduce a new canonical tModel, which has a publicly known tModel key.
<?xml version="1.0" encoding="UTF-8"?>
<promote:uddiEntities xmlns="urn:uddi-org:api_v2" xmlns:promote="
http://www.ibm.com/xmlns/prod/WebSphere/UDDIUtilityTools">

<!-- tModels -->

<promote:tModels>

<tModel tModelKey="uuid:ee3966a8-faa5-416e-9772-128554343571" >

<name>http://schemas.xmlsoap.org/ws/2002/07/policytmodel</name>
<description>WS-PolicyAttachment policy expression</description>
</tModel>

<tModel tModelKey="uuid:ad61de98-4db8-31b2-a299-a2373dc97212" >

<name>uddi-org:wsdl:address</name>
<description xml:lang="en">
This tModel is used to specify the URL fact that the address must be obtained from
the WSDL deployment file.
</description>
<overviewDoc>
<overviewURL>
http://www.oasis-open.org/committees/uddi-spec/doc/tn/
uddi-spec-tc-tn-wsdl-v2.htm#Address
</overviewURL>
</overviewDoc>
</tModel>

</promote:tModels>

<!-- businesses -->

<promote:businesses>
</promote:businesses>

<!-- services -->

<promote:services>
</promote:services>

<!-- bindings -->

<promote:bindings>
</promote:bindings>

<!-- referenced tModels -->

<promote:referencedTModels>
</promote:referencedTModels>

</promote:uddiEntities>

1242 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Starting UDDI Utility Tools at a command prompt

Ensure the correct level of java is appropriate by setting the PATH statement to the level of java supplied
with WebSphere. For example, from the command line, type:

On Windows:
set PATH=WAS_HOME\java\bin;%PATH%

On Unix and Linux platforms:

export PATH=WAS_HOME/java/bin:$PATH

If you are using DB2 on Unix and Linux platforms run the db2profile script before issuing the java
command to start UDDI Utility Tools. This script is located within the DB2 instance home directory under
sqllib and is invoked by typing:
. /$DB2_HOME/db2profile

Note: In the above example, notice that the ’.’ is followed by a single space character.

Note: On Unix and Linux platforms the DB2 user must have a db2profile at $HOME/sqllib/db2profile.

UDDI Utility Tools can be started using:

java - jar UDDIUtilityTools.jar <function> [options]
using a specified properties file that sets up classpath and other parameters, or it can be called
using:
java CommandLineProcessor
where CommandLineProcessor is the class which processes command line arguments for UDDI
Utility Tools, sets up configuration and invokes the appropriate function.

The usage is as follows:

Usage: java -jar UDDIUtilityTools.jar {function} [options]

function:
-promote <entity source> Promote entites between registries
-export <entity source> Extract entities from registry to XML
-delete <entity source> Delete entities from registry
-import Create entities from XML to registry

where <entity source> is one of:

-tmodel|-business|-service|-binding <key> Specify single entity type and key
-keysFile | -f <filename> Specify file containing entity types and keys

options:
-properties <filename> Specify path to configuration file
-overwrite | -o Overwrite an entity if it already exists
-log | -v Output verbose messages
-definitionFile <filename> Specify path to UDDI entity definition file
-importReferenced Import entities referenced by source entities

The following options override property settings in configuration file:

-overwrite
-log
-definitionFile
-importReferenced

Example: java -jar UDDIUtilityTools.jar -promote -keysFile C:/uddikeys.txt

Below are a set of UDDI Utility Tools command line examples:

To export a single business to the EDF file specified in a properties file in the current directory.

Chapter 8. Developing WebSphere applications 1243

java -jar UDDIUtilityTools.jar -export -business 28B8B928-2B2E-4EC9-A647-1E40651E4752

As above but this time using a keys file to specify the entities to be exported
java -jar UDDIUtilityTools.jar -export -keysFile c:/myKeyFiles/keyFile01.txt

As above but also specifying verbose output to appear on the command line.
java -jar UDDIUtilityTools.jar -export -keysFile c:/myKeyFiles/keyFile02.txt -v

To import the contents of the default EDF specified in a UDDIUtilitiyTools.properties file in the current
directory.
java -jar UDDIUtilityTools.jar -import

As above but also specifying that referenced tModels should be imported into the target registry.
java -jar UDDIUtilityTools.jar -import -importReferenced

To import the entities from an EDF at the specified location. Note the use of forward slashes even though
this is an example on a Windows file system.
java -jar UDDIUtilityTools.jar -import -definitionFile c:/myEDFs/entities01.xml

To import the entities from the default EDF including referenced tModels. Overwrite specifies that any
entities excluding referenced tModels that are found in the target registry should be overwritten.
java -jar UDDIUtilityTools.jar -import -overwrite -importReferenced

To promote a single service from a source to a target registry using the properties file at a specified
location.
java -jar UDDIUtilityTools.jar -promote -service 67961D67-330F-4F14-8210-E74A58E710F3
-properties c:/UUT/myUUTProps.properties

To promote a set of entities specified in a keys file.

java -jar UDDIUtilityTools.jar -promote -keysFile c:/myKeyFiles/keyFile03.txt

As above but specifying that existing entities in the target registry get overwritten.
java -jar UDDIUtilityTools.jar -promote -keysFile c:/myKeyFiles/keyFile04.txt -overwrite

To promote a set of entities specified in a keys file including referenced tModels.

java -jar UDDIUtilityTools.jar -promote -keysFile c:/myKeyFiles/keyFile05.txt -importReferenced

To promote a set of entities specified in a keys file but also create an EDF containing the promoted
entities.
java -jar UDDIUtilityTools.jar -promote -keysFile c:/myKeyFiles/keyFile06.txt
-definitionFile c:/myEDFs/entities02.xml

To logically delete a single tModel. Note that it is not possible to physically delete tModels.
java -jar UDDIUtilityTools.jar -delete -tModel UUID:1E2B9D1E-E53D-4D36-9D46-6CCC176C466A

To delete all the entities specified in the keys file. Note that with the exception tModels all other entities will
be physically deleted from the target registry.
java -jar UDDIUtilityTools.jar -delete -keysFile c:/myKeyFiles/keyFile04.txt

A keys file example

Below is an example of the keys that are to be exported, promoted or deleted from the target registry:

1244 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
#
# Keys of entities to be exported, promoted from source registry or deleted from
target registry
#
# Note: keys must be comma separated and on SAME line
# Note: property names are case sensitive. (’tmodels=’ will be ignored)

businesses=97C77097-AC6C-4CA0-A6C4-452F7045C470, 4975E949-581F-4FCA-AD5F-E08280E05F9F
services=BB3864BB-1578-4833-8179-14391F14791F
bindings=
tModels=273F1727-7BFF-4FB5-A1FD-BA5C45BAFD9C

Note: If the importReferenced property is set to true, the list of tModels in the referencedTModels section
is imported to the target registry. Minimal entities are created if the referencedTModel is new. If the
referencedTModel already exists it is never overwritten, regardless of the overwrite property value.
This is so that commonly referenced tModels such as categorization tModels do not keep being
updated unnecessarily.

Should you need to update a referencedTModel, you must manually move the referencedTModel
definition to the tModels section in the entity definition file and set overwrite to true.

Content of the log files

Below shows examples of contents of two of the log files produced by running the tool. Note that some
comments have been added in square brackets and in italic to highlight important points within the log file.
The first is the messages.log which shows successful and unsuccessful operations for export, import and
delete functions:
[29/07/04 17:39:57:531 BST] CWUDU0002I: ***** Starting UDDI Utility Tools ****
****** [timestamp and eyecatcher indicate when tool is run]
[29/07/04 17:39:57:531 BST] CWUDU0009I: Exporting entities...
[29/07/04 17:39:57:531 BST] CWUDU0015I: Exported 14 entities.
[29/07/04 17:39:57:531 BST] CWUDU0029I: Serializing...
[29/07/04 17:39:57:531 BST] CWUDU0030I: Serialized entities.
[29/07/04 17:39:57:531 BST] CWUDU0016I: Importing entities...
[29/07/04 17:39:57:531 BST] CWUDU0124I: Created tModel minimal entity with tModelKey
[uuid:667e2766-4781-4151-b3a0-809f7180a096].
[29/07/04 17:39:57:531 BST] CWUDU0121I: Created business minimal entity with
businessKey [263f5526-8708-4834-9f5d-8f8c878f5d6e].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with
serviceKey [0af2a30a-be70-401f-a027-331a6c332712].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with
serviceKey [61012761-d02c-4c70-ae98-435ffd4398f9].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with
bindingKey [f97af9f9-7cb7-47bd-8b90-b55e4db590df].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with
bindingKey [17e4c017-d273-43ec-af4a-f9b841f94a30].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with
bindingKey [9e2c239e-3b30-40a9-9c25-ce64edce25b9].
[29/07/04 17:39:57:531 BST] CWUDU0121I: Created business minimal entity with
businessKey [49bb6949-4b0e-4e81-88a7-e26bfbe2a7f1].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with
serviceKey [003d2b00-f6c0-4071-8b84-f235a2f28445].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with
bindingKey [df1019df-2d2f-4f32-bf18-4f21274f1835].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with
bindingKey [b229aeb2-f2b1-4115-a06f-536753536f10].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with
serviceKey [84d8e584-2510-4099-9b2a-6023f1602a0a].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with
bindingKey [62a9a762-7fff-4f7a-8463-af0c79af63ee].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with
bindingKey [e08654e0-b212-42c0-bcf3-655e9765f392].
[29/07/04 17:39:57:531 BST] CWUDU0115I: Imported 7 entities and 0 referenced entities.
[this kind of message indicates the operation worked!]

Chapter 8. Developing WebSphere applications 1245

[29/07/04 17:39:57:531 BST] CWUDU0002I: ********** Starting UDDI Utility Tools
**********
[29/07/04 17:39:57:531 BST] CWUDU0023I: Deleting entities...
[29/07/04 17:39:57:531 BST] CWUDU0028I: Deleted 7 entities.

The second log file shows a typical trace log file entry for an export:
[29/07/04 17:39:57:531 BST] ********** Starting UDDI Utility Tools **********
[eyecatcher and timestamp indicate when tool is run]
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.PromoterAPI.setUddiEntities()
[the ’>’ indicates entry to the constructor of this class]
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.export.KeyFileReader()
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.export.KeyFileReader() loaded
tModel keys
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.export.KeyFileReader() loaded
business keys
TransformConfiguration:
nameSpacePrefix=promote
uddiEntityDefinitionFile=c:\temp/MigToolFiles/Results/Promote_api_EDF_1.xml

ExportConfiguration:
fromGetURL=http://yottskry:9080/uddisoap/
fromInquiryURL=http://yottskry:9080/uddisoap/inquiryAPI

ImportConfiguration:
overwrite=true
uddiEntityDefinitionFile=c:\temp/MigToolFiles/Results/Promote_api_EDF_1.xml
importReferencedEntities=true

PublishConfiguration:
toInquiryURL=http://davep:9080/uddisoap/inquiryAPI
toPublishURL=http://yottskry:9080/uddisoap/publishAPI
userID=Publisher1
trustStoreFileName=c:/WebSphere600/AppServer//etc/DummyClientTrustFile.jks
secureConnection=false

DatabaseConfiguration:
dbDriver=COM.ibm.db2.jdbc.app.DB2Driver
dbURL=jdbc:db2:UDDI30
dbUser=db2admin

LoggerConfiguration:
messageStream=null
messageLogFileName=c:\temp/MigToolFiles/logs/message.log
traceLogFileName=c:\temp/MigToolFiles/logs/trace.log
traceLevel=3
verbose=true

[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.PromoterAPI()

[29/07/04 17:39:57:531 BST] ********** Starting UDDI Utility Tools **********
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.PromoterAPI.setUddiEntities()
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.export.KeyFileReader()
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.export.KeyFileReader() loaded
tModel keys [ log entries without a ’>’ or ’<’ are status messages only ]
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.export.KeyFileReader() loaded
business keys
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.export.KeyFileReader() loaded
service keys
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.export.KeyFileReader() loaded
binding keys
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.UddiEntityKeys()
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.UddiEntityKeys() [the ’<’
indicates exit from the constructor]
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.export.KeyFileReader() removed
duplicate, empty and null keys
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.export.KeyFileReader()

1246 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.PromoterAPI.setUddiEntities()
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.PromoterAPI.deleteEntities()
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.publish.EntityDeleter()
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.publish.EntityDeleter()
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.UDDIClient()
[29/07/04 17:39:57:531 BST] com.ibm.uddi.promoter.UDDIClient() client type: 1

Starting UDDI Utility Tools through the API

UDDI Utility Tools provides a public API to functions for exporting, importing, promoting, finding and
deleting UDDI entities. All of these functions can be invoked by using the PromoterAPI class. Usage of this
class to perform these functions is typically to:
1. Create a Configuration object and populate it from a Properties object or from a configuration
properties file.
2. Create a PromoterAPI object passing the Configuration in the constructor.
3. For keys based functions (export, delete and promote), set the keys by supplying a UDDIEntityKeys
object, the location of the keys file, or, for one entity, by specifying an entity type and a key value.
4. Invoke the corresponding method for the function required: exportEntities, promoteEntities(boolean),
importEntities, deleteEntities or extractKeysFromInquiry(FindTModel, FindBusiness, FindService,
FindBinding, FindRelatedBusinesses).

There is some sample code for UDDI Utility Tools, demonstrating usage of the API classes, available from
Samples Central.

The ″low-level″ API classes and methods have been deprecated in this release. Refer to the Javadoc
welcome page for details.

Known limitations with UDDI Utility Tools and workarounds

There are some known limitations with UDDI Utility Tools and a workaround for each. See ″UDDI
troubleshooting tips″ in the information center.

Cloudscape Restriction

The ’export’ function when referencing a source registry with a Cloudscape database is supported.
However, the ’import’, ’promote’ and ’delete’ functions are not supported when referencing a target registry
because of a limitation with the UDDI Registry when working with a Cloudscape database.

Saving Version 3 entities with a supplied key

An example of saving a Version 3 business with a defined key is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<save_business xmlns="urn:uddi-org:api_v3">
<authInfo>a399c4a3-6387-47cd-a1bd-91f7bb91bdd7</authInfo>
<businessEntity businessKey="uddi:mycompany-p1.com:computers">
<name xml:lang="en">WithKey</name>
</businessEntity>
</save_business>
</Body>
</Envelope>

Known limitations with UDDI Utility Tools and workarounds

There are known limitations with the UDDI Utility Tools and a workaround for each:
v PublisherAssertions are not supported and will not be promoted.

Chapter 8. Developing WebSphere applications 1247

 Workaround: After the user has promoted the businesses that are related, he must recreate the
publisherAssertion relationship.
v Referenced businesses in service projections are not added automatically to the EDF in the same
manner as referenced tModels.
Workaround: Add the referenced business that will ’own’ the projected service to the EDF. If the
business is not present in the target registry, it should be placed before the service’s owning business in
the EDF.
v Cycle detection for service projections are not detected in the same manner as for referenced tModels.
Workaround: If a circular reference is present between two or more service projections, break the cycle
by removing one of the projections temporarily, perform the import and update the changed entity to
reestablish the cycle in the target registry.
v tModels that were deleted (in the logical sense) in the source registry are imported and promoted as
undeleted in the target registry. This is because, in the UDDI Version 2 specification, the deleted state
of tModels is not exposed as API calls.
Workaround: After importing the tModel, perform a delete. This is done using the UDDI Utility Tools
delete function, or any other UDDI Registry API access method.
v BindingTemplates referenced by hostingRedirectors are not added automatically to the EDF in the same
manner as referenced tModels.
Workaround: Add the referenced bindingTemplate to the EDF.
v Businesses referenced by an ’owningBusiness’ keyedReference are not automatically added to the EDF.
Workaround: Import the referenced business into the target registry before importing the tModel that
references it.
v The JSSE provider class, when security is enabled, is not configurable. It must be
com.ibm.jsse.IBMJSSEProvider.
v A few combinations of command line arguments are not validated and prevented, for example, it is
possible to specify -import with -keysFile <path to file> in the same command, although the
&#8209;keysFile is ignored.

IBM Java API for XML Registries (JAXR) Provider for UDDI
Overview

The Java API for XML Registries (JAXR) is a Java client API for accessing both UDDI (Version 2 only) and
ebXML registries. It is part of the J2EE 1.4 specification.

The JAXR API comprises the J2EE packages javax.xml.registry and javax.xml.registry.infomodel. J2EE API
documentation can be found at http://java.sun.com/webservices/reference/api/index.html (this is a
download site). More information on JAXR, including the JAXR Version 1.0 specification, can be found at
http://java.sun.com/xml/jaxr/index.jsp.

Note that the preferred UDDI Java client APIs are UDDI4J Version 2 for UDDI Version 2, and the IBM
UDDI Client for Java for UDDI Version 3.

JAXR Provider

The current JAXR specification (Version 1.0) defines a JAXR Provider as an implementation of the JAXR
API. A JAXR Provider may be a JAXR Provider for UDDI, a JAXR Provider for ebXML, or a pluggable
provider which supports both UDDI and ebXML. The IBM JAXR Provider for UDDI is a provider for UDDI
only.

UDDI Versions

A JAXR Provider for UDDI accesses a UDDI Registry using the UDDI Version 2 SOAP APIs only. The IBM
WebSphere UDDI Registry for UDDI Version 3 in WebSphere Application Server Version 6.0 supports the

1248 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
UDDI Version 1, 2 and 3 SOAP APIs, and so the IBM JAXR Provider for UDDI can be used to access this
registry. The IBM JAXR Provider can also be used to access the IBM WebSphere UDDI Registry for UDDI
Version 2 in WebSphere Application Server Version 5.x. Note that to use the UDDI Version 3 SOAP APIs,
JAXR cannot be used. The IBM UDDI Version 3 Client for Java is recommended for this.

Capability Level

The JAXR specification defines two Capability Profiles, Capability Level 0 and Capability Level 1. The
JAXR API documentation categorizes each JAXR method as either Level 0 or Level 1. A JAXR provider for
UDDI has Capability Level 0 and supports all Level 0 methods. A JAXR provider for ebXML has Capability
Level 1 and supports all Level 0 and Level 1 methods. The IBM JAXR Provider for UDDI is a Capability
Level 0 Provider, and supports only Level 0 methods.

JAXR for UDDI - getting started and advanced topics:

Getting started

A simple sample

The following sample program shows how to obtain the ConnectionFactory instance, create a Connection
to the registry and save an Organization in the registry.
import java.net.PasswordAuthentication;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashSet;
import java.util.Properties;
import java.util.Set;

import javax.xml.registry.BulkResponse;
import javax.xml.registry.BusinessLifeCycleManager;
import javax.xml.registry.Connection;
import javax.xml.registry.ConnectionFactory;
import javax.xml.registry.JAXRException;
import javax.xml.registry.RegistryService;
import javax.xml.registry.infomodel.Key;
import javax.xml.registry.infomodel.Organization;

public class JAXRSample

{
public static void main(String[] args) throws JAXRException
{
//Tell the ConnectionFactory to use the IBM JAXR Provider for UDDI
System.setProperty("javax.xml.registry.ConnectionFactoryClass",
"com.ibm.xml.registry.uddi.ConnectionFactoryImpl");
ConnectionFactory connectionFactory = ConnectionFactory.newInstance();

//Set the URLs for the UDDI inquiry and publish APIs.
//These must be the URLs of the UDDI version 2 APIs.
Properties props = new Properties();
props.setProperty("javax.xml.registry.queryManagerURL", "http://localhost:9080/uddisoap/inquiryapi");
props.setProperty("javax.xml.registry.lifeCycleManagerURL", "http://localhost:9080/uddisoap/publishapi");
connectionFactory.setProperties(props);

//Create a Connection to the UDDI registry accessible at the above URLs.

Connection connection = connectionFactory.createConnection();

//Set the user ID and password used to access the UDDI registry.
PasswordAuthentication pa = new PasswordAuthentication("Publisher1", new char[]
{ ’p’, ’a’, ’s’, ’s’, ’w’, ’o’, ’r’, ’d’ });
Set credentials = new HashSet();
credentials.add(pa);
connection.setCredentials(credentials);

//Get the javax.xml.registry.BusinessLifeCycleManager interface, which contains

Chapter 8. Developing WebSphere applications 1249

 //methods corresponding to UDDI publish API calls.
RegistryService registryService = connection.getRegistryService();
BusinessLifeCycleManager lifeCycleManager = registryService.getBusinessLifeCycleManager();

//Create an Organization (UDDI businessEntity) with name "Organization 1".

Organization org = lifeCycleManager.createOrganization("Organization 1");

//Add the Organization to a Collection, ready to be saved in the UDDI registry.

Collection orgs = new ArrayList();
orgs.add(org);

//Save the Organization in the UDDI registry.

BulkResponse bulkResponse = lifeCycleManager.saveOrganizations(orgs);

//Obtain the Organization’s Key (the UDDI businessEntity’s businessKey) from the response.
if (bulkResponse.getExceptions() == null)
{
//1 Organization was saved, so 1 key will be returned in the response collection
Collection responses = bulkResponse.getCollection();
Key organizationKey = (Key)responses.iterator().next();
System.out.println("\nOrganization Key = " + organizationKey.getId());
}
}
}

Classpath

The class libraries of the IBM JAXR Provider for UDDI are contained within the archive jaxruddi.jar, located
in the WAS_HOME/lib directory. When using the JAXR API from within a J2EE application running under
WebSphere Application Server Version 6.0, all required classes will automatically be on the classpath.
When using the JAXR API from outside this environment, the following jars must be on the java classpath:
bootstrap.jar, jaxruddi.jar, j2ee.jar, soap.jar and uddi4jv2.jar, which are all located in the WAS_HOME/lib
directory.

javax.xml.registry.ConnectionFactory

To use the IBM JAXR Provider for UDDI, the name of the ConnectionFactory implementation class must
first be specified by setting the System Property “javax.xml.registry.ConnectionFactoryClass” to
“com.ibm.xml.registry.uddi.ConnectionFactoryImpl”. Failure to specify this will result in the value defaulting
to “com.sun.xml.registry,common.ConnectionFactoryImpl”, which will not be found. This will result in a
JAXRException when the ConnectionFactory.newInstance() method is called. The IBM JAXR Provider for
UDDI does not support lookup of the ConnectionFactory via JNDI.

javax.xml.registry.Connection Properties

Connection specific properties must be specified by setting a java.util.Properties object on the JAXR
ConnectionFactory before obtaining a Connection. The JAXR specification defines the full list of these
properties. The table below lists the three most important properties, and what values they should take in
order to use the IBM JAXR Provider for UDDI to access the IBM WebSphere UDDI Registry. The only
required Connection property is “javax.xml.registry.queryManagerURL”, however it is recommended that
“javax.xml.registry.lifeCycleManagerURL” is also set, and that the default value of
“javax.xml.registry.security.authenticationMethod” is understood. The rest of the Connection properties
defined in the JAXR specification are optional, and their values are not specific to the IBM WebSphere
UDDI Registry. The IBM JAXR Provider for UDDI does not define any additional provider-specific
properties.

Property Description

1250 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
javax.xml.registry.queryManagerURL The URL of the IBM WebSphere UDDI Registry‘s inquiry API for
UDDI Version 2. Typically this will be of the form:
“http://<hostname>:<port>/uddisoap/inquiryapi”. This property is
required.
javax.registry.xml.lifeCycleManagerURL The URL of the IBM WebSphere UDDI Registry‘s publish API for
UDDI v2. Typically this will be of the form:
“http://<hostname>:<port>/uddisoap/publishapi”. If this property is
not specified, it defaults to the value of the
javax.xml.registry.queryManagerURL property, however the IBM
UDDI Registry will typically have different URLs for the inquiry
and publish APIs, and it is recommended to specifiy both
properties.
javax.xml.registry.authenticationMethod The method of authentication to use when authenticating with the
registry. This may take one of two values,
“UDDI_GET_AUTHTOKEN” and “HTTP_BASIC”. The default
value is “UDDI_GET_AUTHTOKEN” if none is specified. See
section Authentication and Security below for more information.

Authentication and security

Authentication

The javax.xml.registry.authenticationMethod Connection property tells the JAXR Provider which method to
use when authenticating with the UDDI registry. The two supported values of this property are
“UDDI_GET_AUTHTOKEN” and “HTTP_BASIC”. The IBM JAXR Provider for UDDI does not support the
“CLIENT_CERTIFICATE” or “MS_PASSPORT” methods of authentication. If this property is not set, the
default authentication method is “UDDI_GET_AUTHTOKEN”.

UDDI_GET_AUTHTOKEN

The JAXR Provider uses the UDDI V2 get_authToken API to authenticate with the registry. The
get_authToken call is made automatically by the JAXR Provider when the Connection credentials are set,
and the UDDI V2 authToken returned by the call is saved by the JAXR Provider for use on subsequent
UDDI publish API calls.

HTTP_BASIC

The JAXR Provider uses HTTP basic authentication to authenticate with the registry. This is supported by
WebSphere when WebSphere Global Security is on. No UDDI V2 get_authToken API call is made, instead
the username and password are sent in the HTTP headers using HTTP basic authentication every time a
UDDI API call is made (both inquiry and publish). If the UDDI Registry does not require HTTP basic
authentication, the credentials are ignored.

USING SSL (Secure Sockets Layer)

SSL can be used to encrypt HTTP traffic between the IBM JAXR Provider for UDDI and the IBM
WebSphere UDDI Registry. To use SSL, the JAXR client program should do the following:
1. When setting the “javax.xml.registry.queryManagerURL” and “javax.xml.registry.lifeCycleManagerURL”
Connection properties, specify a URL with the protocol “https” and the correct port for using SSL to
access the UDDI registry. The IBM WebSphere UDDI Registry‘s default port for https is 9443. Often
only the lifeCycleManager URL (the UDDI Publish API URL) will require SSL.
2. Add a new Security Provider to the java.security.Security object, according to the JSSE (Java Secure
Sockets Extension) implementation being used. If running under the IBM JVM in WAS 6.0, the IBM
JSSE will automatically be on the classpath. Add the IBM Security Provider as follows:
java.security.Security.addProvider(new com.ibm.jsse.JSSEProvider());

Chapter 8. Developing WebSphere applications 1251

3. Set the System property “javax.net.ssl.trustStore” to be the file name of the client trust store file. This is
a java key store (.jks) file and must contain the server certificate of the UDDI registry. Key store files
can be managed using WebSphere‘s ikeyman tool
4. Set the System property “javax.net.ssl.trustStorePassword”. This is the password used to open the
client trust store file.
5. If using an IBM JVM prior to that in WAS 6.0, it may be necessary to set the System property
“java.protocol.handler.pkgs” to “com.ibm.net.ssl.internal.www.protocol”. For more information on SSL
and the ikeyman tool refer to SSL and IKEYMAN in the Information Center.

Internal taxonomies

The IBM JAXR Provider for UDDI supplies the following internal taxonomies:

Taxonomy ClassificationScheme name ClassificationScheme id (UDDI Version 2

(UDDI tModel name) tModelKey)
NAICS 1997 ntis-gov:naics:1997 UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2
NAICS 2002 ntis-gov:naics:2002 UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2
UNSPSC 3.1 unspsc-org:unspsc:3-1 UUID:DB77450D-9FA8-45D4-A7BC-04411D14E384
UNSPSC 7 unspsc-org:unspsc UUID:CD153257-086A-4237-B336-6BDCBDCC6634
ISO3166 2003 ubr-uddi-org:iso-ch:3166-2003 UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88

The tModels corresponding to all of these taxonomies are available in the IBM UDDI Version 3 Registry. If
using the IBM JAXR Provider to access an IBM UDDI Version 2 Registry, only the tModels corresponding
to NAICS 1997, UNSPSC 3.1 and ISO3166 are available.

Custom internal taxonomies

A user may supply their own custom internal taxonomies. To create a new custom internal taxonomy and
make it available to the JAXR provider, follow these steps:
1. Create a text file containing the taxonomy element data. As an example, look at the file geo-data.txt on
the root of jaxruddi.jar. This is the taxonomy data file for the supplied ISO 3166 taxonomy. The first few
lines are:
geo#--#World#--
geo#AE#United Arab Emirates#--
geo#AF#Afghanistan#--
geo#AG#Antigua And Barbuda#--
geo#AI#Anguilla#--
geo#AL#Albania#--
geo#AM#Armenia#--
geo#AN#Netherlands Antilles#--
geo#AO#Angola#--
geo#AQ#Antarctica#--
geo#AR#Argentina#--
geo#AR-A#Salta#AR
geo#AR-B#Buenos Aires#AR
Each line represents one element of the taxonomy, or one Concept in the taxonomy Concept tree.
Each line has the form:
<taxonomy ID>#<element name>#<parent element value>

Token Description
<taxonomy ID> The taxonomy ID is the same for every element of a taxonomy.
<element value> The taxonomy ID is the same for every element of a taxonomy.
<element name> The Concept name (UDDI keyName).

1252 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
<parent element value> This defines the element‘s parent element in the taxonomy tree. For every element
(except the root element) in the data file, there should be another line which defines the
element‘s parent element. The root element is denoted by defining itself as its own
parent. There should be only one root element, and no parentless elements.
# The delimiter character. This does not have to be “#” and can be defined for each
taxonomy in the taxonomyConfig.properties file.

2. Save a ClassificationScheme (UDDI tModel) in the UDDI registry to represent the new internal
taxonomy. This can be done using the
javax.xml.registry.BusinessLifeCycleManager.saveClassificationSchemes() method.
3. Add the new taxonomy to the taxonomyConfig.properties file:
a. Copy the supplied taxonomyConfig.properties file from the root of jaxruddi.jar.
The content of the supplied taxonomyConfig.properties file is:
naics-1997 = UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2, naics-1997-data.txt, #
naics-2002 = UUID:1FF729F2-1948-46CF-B660-31EC107F1663, naics-2002-data.txt, #
unspsc = UUID:DB77450D-9FA8-45D4-A7BC-04411D14E384, unspsc-data.txt, #
unspsc7_data = UUID:CD153257-086A-4237-B336-6BDCBDCC6634, unspsc7-data.txt, #
iso3166-2003 = UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88, iso3166-2003-data.txt,#
This file has one line per supplied internal taxonomy, which is of the form:
<taxonomy ID> = <tModelKey>,<data filename>,<data file delimiter>

Token Description
<taxonomy ID> This is used internally by the JAXR provider to identify each taxonomy. It
does not have to be the same as the taxonomy ID in the corresponding
taxonomy data file.
<tModelKey> The tModelKey of the corresponding UDDI tModel. (The id of the
corresponding JAXR ClassificationScheme).
<data filename> The name of the corresponding taxonomy data file.
<data file delimiter> The delimiter character used in the taxonomy data file. All supplied internal
taxonomies use “#”, but user-supplied internal taxonomies may use different
delimiters.

b. Add a new line for the new taxonomy to the copy of the taxonomyConfig.properties file. Do not
remove any existing taxonomies from the file as this will make them unavailable to the JAXR
provider.
4. Add the copied taxonomyConfig.properties file to the java classpath ahead of jaxruddi.jar.
5. If any JAXR client programs are still running that were started before the new taxonomy was added to
the taxonomyConfig.properties file, a new Connection must be created in order to pick up the new
taxonomy.

Important notes on internal taxonomies

Each internal taxonomy is loaded into memory once per JAXR Connection. The taxonomy‘s
ClassificationScheme is created when the Connection is created. At this time the associated UDDI tModel
is obtained from the registry and used to populate the ClassificationScheme attributes. The taxonomy‘s
Concept object tree is not created until the first time the ClassificationScheme is requested by the user. All
subsequent requests for the same internal taxonomy using the same Connection will return the same
object tree.

Modification of the object tree

Because there is only one ClassificationScheme and Concept object tree per internal taxonomy per
Connection, a user should not attempt to modify programmatically any part of the Concept tree, because
all future requests for this taxonomy using the same Connection will return the modified (and now possibly
Chapter 8. Developing WebSphere applications 1253
invalid) objects. Programmatic modification of the Concept tree will not result in any changes to the
associated taxonomy data file. If a user wishes to make a change to the values in a user-defined internal
taxonomy, they must first make the changes in the taxonomy data file, and then create a new Connection
to pick up the changes in a new Concept tree.

Modification of the Concept tree

Because there is only one Concept object tree per internal taxonomy per Connection, a user should not
attempt to modify programmatically any part of the Concept tree, because all future requests for this
taxonomy using the same Connection will return the modified (and now possibly invalid) objects.
Programmatic modification of the Concept tree will not result in any changes to the associated taxonomy
data file. If a user wishes to make a change to the values in a user-defined internal taxonomy, they must
first make the changes in the taxonomy data file, and then create a new Connection to pick up the
changes in a new Concept tree.

Modification of the ClassificationScheme

Similarly, a user should not attempt to modify programmatically an internal ClassificationScheme, except in
the case where a user wishes to modify and then save a user-defined internal ClassificationScheme. A
new Connection is not required to pick up programmatic changes.

Logging and messages

UDDI4J Logging

The IBM JAXR Provider for UDDI uses UDDI4J Version 2 to communicate with the UDDI Registry. UDDI4J
has its own logging which can be switched on by setting the value of the System property
“org.uddi4j.logEnabled” to “true”. This outputs to the standard error log the XML request and response
bodies of every UDDI request.

Trace

Entry, exit, exception, warning and debug trace is provided using commons-logging. See
http://jakarta.apache.org/commons/logging/ for more information on commons-logging. Trace will only be
created if the JAXR client configures it. Entry, exit and debug trace uses the debug level of logging.
Exception and warning trace uses the info level of logging. Additionally, info level logging is provided
before each UDDI4J request is made.

Standard error log messages

The InternalTaxonomyManager, EnumerationManager and PostalSchemeManager send warning messages

to System.err if error conditions occur that do not warrant an exception, but that the user should be
informed of. Examples of these are if a taxonomy data file contains an invalid line, or if a tModel
corresponding to an internal taxonomy could not be found in the registry.

UDDI Registry Messages

The UDDI Registry issues messages to report events or errors. The messages are in the form CWUDxnnnns
where:
x is a character descriptor identifying which UDDI component is involved
nnnn is the error code
s is one of I (Information), E (Error) or W (Warning)

The prefix CWUDxnnnns: is followed by text that describes the event or error. For some messages, the
first word of the text is one of the form (MSN=SSSS). The SSSS provides a message sequence number
(or MSN), which identifies the unique circumstance in which the message was issued, and is of use where
the same message can be issued in more than one circumstance.

1254 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
To help you diagnose problems and minimize the need to enable trace in any of the above components,
view the messages table. You can view the messages by prefix or component, whichever is easiest for
you to find in the table. All messages are documented with user/system action and explanation.

The text for the UDDI messages is contained in the following files:
v setupuddimessages.jar and UDDICLoudscapeCreate.jar for the CWUDD messages
v jaxruddi.jar for CWUDX messages
v UDDIValueSetTools.jar for CWUDV messages
v UDDIUtilityTools.jar for CWUDU messages
v uddiresourcebundles.jar for the remaining prefixes

which are placed, by the installation process, into the lib subdirectory of the WebSphere application server
into which the UDDI Registry was installed (with the exception of UDDIUtilityTools.jar, which is placed into
UDDIReg/scripts). If you will be running a console or log analyzer from another process; for example, to
analyze the activity log, you must place a copy of the above jar files into a directory that is within the
classpath of that process. Otherwise, the message lookup for the UDDI messages will fail.

UDDI Components Message Prefix Table

Click on individual links for message documentation for the component

CWUDDnnnns UDDI Deploy and Removal
CWUDGnnnns UDDI User Console
CWUDMnnnns UDDI Management Interface
CWUDNnnnns UDDI Node Management
CWUDQnnnns UDDI Migration
CWUDRnnnns UDDI Logging and Tracing
CWUDSnnnns UDDI SOAP Interface
CWUDUnnnns UDDI Utility Tools
CWUDVnnnns UDDI Value Set Tools
CWUDXnnnns JAXR

CWUDDnnnns (Web Services UDDI Deployment and Removal) messages:

CWUDD0001I: Attempting to deploy UDDI Registry application.
Explanation: The UDDI deployment process is starting.
User Response: None..
CWUDD0002W: Failed to discard unsaved changes caught exception Exc. Value is: <Exception
Message>
Explanation: This warning message indicates that changes in the wsadmin session previous to
running the uddiDeploy.jacl script cannot be discarded. The <Exception Message> describes the
error that occurred.
User Response: None.
CWUDD0003I: Application Manager found.
Explanation: An active Application Manager can be used to stop and start UDDI on the
deployment server.
User Response: None.
CWUDD0004I: Application Manager unavailable, application will not be started/stopped.
Explanation: No active Application Manager can be found so there is no need to stop and start
UDDI on the deployment server.
User Response: None.

Chapter 8. Developing WebSphere applications 1255

CWUDD0005I: Application Manager not running, application will not be started/stopped.
Explanation: Application Manager has been found, but it is not running so there is no need to
stop and start UDDI on the deployment server.
User Response: None.
CWUDD0006I: Checking for installed UDDI Registry application of name appname. Value is: <UDDI
Application Name>
Explanation: The deployment script is checking for deployed UDDI applications.
User Response: None.
CWUDD0007I: Stopping application of name appname. Value is: <Application Name>
Explanation: Attempting to stop a deployed UDDI application.
User Response: None.
CWUDD0008W: Stopping application appname caught exception Exc. Application might not have
been running on this server. Values are: <Application Name> <Exception Message>
Explanation: The UDDI application stop request failed.
User Response: Attempt to stop the UDDI application via the Administration Console and rerun
the uddiDeploy.jacl script.
CWUDD0009I: Application appname stopped successfully. Value is: <Application Name>
Explanation: The UDDI application has stopped successfully.
User Response: None.
CWUDD0010I: Removing application appname. Value is: <Application Name>
Explanation: The deployment script is attempting to remove an existing UDDI application.
User Response: None.
CWUDD0011I: Application appname removed successfully. Value is: <Application Name>
Explanation: The UDDI application has been removed from the configuration.
User Response: None.
CWUDD0012I: Attempting to create default UDDI datasource.
Explanation: A default UDDI deployment has been requested and therefore a Cloudscape
datasource will be created.
User Response: None.
CWUDD0013I: Multiple Cloudscape JDBC Providers found. Using first in list.
Explanation: The deployment script has detected a number of suitable Cloudscape JDBC
providers and will use the first.
User Response: None.
CWUDD0014I: UDDI Datasource name successfully created. Value is: <Datasource Name>
Explanation: A Cloudscape datasource has been created for the default UDDI deployment.
User Response: None.
CWUDD0015I: Setting application classloader mode.
Explanation: The UDDI application requires PARENT_LAST class loading.
User Response: None.
CWUDD0016I: Altered classloader mode of application appname from oldmode to newmode. Values
are: <Application Name> <Old Classloader Mode> <New Classloader Mode>
Explanation: The UDDI application class loader has been successfully changed.
User Response: None.
CWUDD0017I: Setting classloader mode for application modules.
Explanation: The UDDI application web modules require PARENT_LAST class loading.
User Response: None.
CWUDD0018I: Altered classloader mode of module modname in application appname from
oldmode to newmode. Values are: <Web Module Name> <Application Name> <Old Classloader

1256 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Mode> <New Classloader Mode>
Explanation: The UDDI Web modules class loader mode has been successfully changed.
User Response: None.
CWUDD0019I: UDDI successfully deployed.
Explanation: UDDI has been successfully deployed.
User Response: None.
CWUDD0020I: Attempting to save new configuration.
Explanation: Attempting to save the configuration after removing any existing UDDI application.
User Response: None.
CWUDD0021I: Changes saved successfully.
Explanation: The configuration changes have been successfully saved.
User Response: None.
CWUDD0022I: Attempting to save new configuration.
Explanation: Attempting to save the configuration after installing the UDDI application ear.
User Response: None.
CWUDD0023W: Changes saved successfully.
Explanation: The configuration changes have been successfully saved.
User Response: None.
CWUDD0024I: Attempting to save new configuration.
Explanation: Attempting to save the configuration after changing the class loader modes.
User Response: None.
CWUDD0025I: Changes saved successfully.
Explanation: The configuration changes have been successfully saved.
User Response: None.
CWUDD1001W: Failed to discard unsaved changes caught exception Exc. Value is: <Exception
Message>
Explanation: This warning message indicates that changes in the wsadmin session previous to
running the uddiDeploy.jacl script cannot be discarded. The <Exception Message> describes the
error that occurred.
User Response: None.
CWUDD1002I: Application Manager found.
Explanation: An active Application Manager can be used to stop and start UDDI on the
deployment server.
User Response: None.
CWUDD1003I: Application Manager unavailable, application will not be started/stopped.
Explanation: No active Application Manager can be found so there is no need to stop and start
UDDI on the deployment server.
User Response: None.
CWUDD1004I: Application Manager not running, application will not be started/stopped.
Explanation: Application Manager has been found, but is not running so there is no need to stop
and start UDDI on the deployment server.
User Response: None.
CWUDD1005I: Stopping application of name appname. Value is: <Application Name>
Explanation: Attempting to stop a deployed UDDI application.
User Response: None.
CWUDD1006W: Stopping application appname caught exception Exc. Application might not have
been running on this server. Values are: <Application Name> <Exception Message>
Explanation: The UDDI application stop request failed.

Chapter 8. Developing WebSphere applications 1257

 User Response: Attempt to stop the UDDI application via the Administration Console and rerun
the uddiDeploy.jacl script.
CWUDD1007I: Application appname stopped successfully. Value is: <Application Name>
Explanation: The UDDI application has stopped executing.
User Response: None.
CWUDD1008I: Removing application appname. Value is: <Application Name>
Explanation: The removal script is attempting to remove the UDDI application.
User Response: None.
CWUDD1009I: Attempting to remove UDDI Registry application.
Explanation: The UDDI removal process is starting.
User Response: None.
CWUDD1010I: Application appname removed successfully. Value is: <Application Name>
Explanation: The UDDI application has been removed from the configuration.
User Response: None.
CWUDD1011I: Attempting to remove the default UDDI datasource.
Explanation: A default UDDI removal has been requested and therefore the Cloudscape
datasource used for UDDI will be removed.
User Response: None.
CWUDD1012I: UDDI Datasource name successfully removed. Value is: <Datasource Name>
Explanation: The UDDI Cloudscape datasource has been removed from the configuration.
User Response: None.
CWUDD1013I: UDDI Datasource name does not exist. No action required. Value is: <Datasource
Name>
Explanation: The default UDDI Cloudscape datasource does not exist in this configuration and
therefore does not need to be removed.
User Response: None.
CWUDD1014I: UDDI Registry application and default UDDI datasource removed successfully.
Explanation: UDDI has been successfully removed from the configuration.
User Response: None.
CWUDD1015I: Attempting to save new configuration.
Explanation: Attempting to save the configuration after removing the UDDI application.
User Response: None.
CWUDD1016I: Changes saved successfully.
Explanation: The configuration changes have been successfully saved.
User Response: None.
CWUDD1017I: UDDI Registry application removed successfully.
Explanation: UDDI has been successfully removed from the configuration.
User Response: None.
CWUDD3001I: Commencing UDDI Cloudscape database creation
Explanation: This is an informational message. It indicates that creation of the UDDI Cloudscape
database is being started.
User Response: None
CWUDD3002I: Path to scripts=’<DBscriptsLocation>’.
Explanation: This is an informational message. It indicates the location (path) of the scripts for
creating the UDDI database, in the <DBscriptsLocation> insert.
User Response: None
CWUDD3003I: Path of database=’<DBlocation>’.
Explanation: This is an informational message. It indicates the location (path) to be used for the
UDDI Cloudscape database, in the <DBlocation> insert.

1258 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 User Response: None
CWUDD3004I: Database name=’<DBname>’.
Explanation: This is an informational message. It indicates the name to be used for the UDDI
Cloudscape database, in the <DBname> insert.
User Response: None
CWUDD3005I: Default profile requested
Explanation: This is an informational message. It indicates that the UDDI Cloudscape database is
to be created as a default UDDI database, using the default UDDI profile.
User Response: None
CWUDD3006I: Default profile not requested
Explanation: This is an informational message. It indicates that the UDDI Cloudscape database is
to be created as a non-default UDDI database.
User Response: None
CWUDD3007I: Attempting to create or connect to UDDI Cloudscape database container
Explanation: This is an informational message. It indicates that an attempt is being made to
create, or connect to, the database container for the UDDI Cloudscape database.
User Response: None
CWUDD3008I: UDDI Cloudscape database container successfully created or connected to
Explanation: This is an informational message. It indicates that the database container for the
UDDI Cloudscape database has been connected to successfully.
User Response: None
CWUDD3009I: UDDI Cloudscape database creation completed normally
Explanation: This is an informational message. It indicates that the UDDI Cloudscape database
has been successfully created.
User Response: None
CWUDD3010I: Attempting to open DDL File List file of name FileName. Value is:
FileName=’<DDLlistFilename>’
Explanation: This is an informational message. It indicates that the DDL File List file, which lists
the DDL Files (database scripts) to be used to create the UDDI Cloudscape database, has been
successfully opened. The name of the DDL File List file is given in the <DDLlistFilename> insert.
User Response: None
CWUDD3011I: Reading the contents of the DDL File List file and verifying
Explanation: This is an informational message. It indicates that the contents of the DDL File List
file are being read and verified.
User Response: None
CWUDD3012I: Comment from file: <DDLfileComment>
Explanation: This is an informational message. It indicates that a comment line has been read
from the DDL File List file, and shows the comment in the <DDLfileComment> insert.
User Response: None
CWUDD3013I: Line from file: <DDLfileLine>
Explanation: This is an informational message. It indicates that a non-comment line has been
read from the DDL File List file, and shows the line in the <DDLfileLine> insert.
User Response: None
CWUDD3014I: Extraneous attributes will be ignored
Explanation: This is an informational message. It indicates that more attributes have been
specified than are required, and that the extraneous attributes will be ignored.
User Response: None

Chapter 8. Developing WebSphere applications 1259

CWUDD3015I: Skipping the Default Profile record because Default Profile was not requested
Explanation: This is an informational message. It indicates that the default UDDI profile was not
requested, and that therefore the record in the DDL File List file for setting up the default profile
will be skipped.
User Response: None
CWUDD3016I: Attempting to populate the database container with schema structures.
Explanation: This is an informational message. It indicates that an attempt is being made to add
schemas to the UDDI Cloudscape database container.
User Response: None
CWUDD3017I: Attempting to load the Cloudscape JDBC driver.
Explanation: This is an informational message. It indicates that an attempt is being made to load
the JDBC driver class for Cloudscape.
User Response: None
CWUDD3018I: Cloudscape JDBC driver successfully loaded
Explanation: This is an informational message. It indicates that the JDBC driver for Cloudscape
has been successfully loaded.
User Response: None
CWUDD3019I: Processing DDL file DDLFile using Term as the terminator. Values are:
DDLFile=<DDLfilename>, Term=<terminator>.
Explanation: This is an informational message. It indicates that the DDLFile whose name is in the
<DDLfilename> insert is being processed, with the character in the <terminator> insert being used
as terminator.
User Response: None
CWUDD3020I: DDL file successfully processed. N statements processed. Value is:
N=<numStatements>.
Explanation: This is an informational message. It indicates that the current DDL file has been
successfully processed, and that the number of statements indicated by the <numStatements>
insert were processed.
User Response: None
CWUDD3021I: End of file reached
Explanation: This is an informational message. It indicates that the end of the current DDL file
has been reached.
User Response: None
CWUDD3022I: Converting SQL string Str to Cloudscape syntax. Value is: Str=<SQLstring>.
Explanation: This is an informational message. It indicates that the SQL string given in the
<SQLstring> insert is being converted into an SQL syntax that is recognized by Cloudscape.
User Response:None
CWUDD3030I: UDDI Cloudscape database successfully completed
Explanation: This is an informational message. It indicates that creation of the UDDI Cloudscape
database has completed successfully.
User Response: None
CWUDD4001E: An Exception Exc occurred during creation of UDDI Cloudscape database. Value is:
Explanation: An exception occurred during the attempt to create the UDDI Cloudscape database.
User Response: The <exception> insert provides information that should help you diagnose the
cause of the problem.
CWUDD4002E: Abnormal exit from creation of UDDI Cloudscape database.
Explanation: The attempt to create the UDDI Cloudscape database is exiting abnormally.
User Response: Examine the preceding messages to determine the reason for the abnormal exit.

1260 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDD4003E: Insufficient arguments supplied
Explanation: Insufficient arguments have been supplied for creating the UDDI Cloudscape
database.
User Response: Retry the request, supplying the correct number of arguments.
CWUDD4004E: Usage is: java -jar <thisjar> <arg1> <arg2> <arg3> <arg4>
where:
v <thisjar> = name of jar file for creating UDDI Cloudscape Database
v <arg1> = path to DDL (SQL) files
v <arg2> = path to location for UDDI Cloudscape database
v <arg3> = name of UDDI Cloudscape Database
v <arg4> = (optional), if specified must be the string DEFAULT
Explanation: This message gives the correct usage syntax for creating the UDDI Cloudscape
Database. It is issued when the incorrect syntax has been used.
User Response: Correct the syntax to match the usage indicated by the message. You might also
need to specify the Cloudscape class library on the classpath, by using the -cp parameter on the
java command. Refer to the Information Center documentation on setting up and deploying UDDI
for more details.
CWUDD4005E: Creation of UDDI Cloudscape database was unsuccessful
Explanation: The attempt to create the UDDI Cloudscape database has been unsuccessful.
User Response: Examine the preceding messages to determine the reason for this failure.
CWUDD4006E: SQL Exception Exc encountered during database container creation. Value is:
Exc=<exception>.
Explanation: An SQL exception occurred when attempting to create the database container for
the UDDI Cloudscape database.
User Response: The <exception> insert should contain information which will help you to
diagnose the problem.
CWUDD4007E: DDL File List file not found
Explanation: The DDL File List file, used to specify the DDL files to be used to create the UDDI
Cloudscape database, could not be found.
User Response: The DDL File List file should be included in the UDDICloudscapeCreate.jar used
to create the UDDI Cloudscape database, so this error indicates a possible corruption of that jar
file. Check that you have a valid version of UDDICloudscapeCreate.jar.
CWUDD4008E: Invalid attribute Attr found in DDL File List file. Value should be true or false. Value
is: Attr=<attribute>.
Explanation: An invalid attribute was found in the DDL File List file. The expected attribute is one
of ’true’ or ’false’. The <attribute> insert indicates the value that was found.
User Response: The DDL File List file is included in the UDDICloudscapeCreate.jar used to
create the UDDI Cloudscape database, so this error indicates a possible corruption of that jar file.
Check that you have a valid version of UDDICloudscapeCreate.jar.
CWUDD4009E: Insufficient attributes found in DDL File List file.
Explanation: Insufficient attributes were found in the DDL File List file.
User Response: The DDL File List file should be included in the UDDICloudscapeCreate.jar used
to create the UDDI Cloudscape database, so this error indicates a possible corruption of that jar
file. Check that you have a valid version of UDDICloudscapeCreate.jar.
CWUDD4010E: SQL exception Exc encountered during database population. Value is:
Exc=<exception>.
Explanation: An SQL exception has occurred while populating the UDDI Cloudscape database.
User Response: The <exception> insert contains the SQL exception which occurred. Use this to
diagnose the problem.

Chapter 8. Developing WebSphere applications 1261

CWUDD4011E: Delete existing UDDI Cloudscape database if it is to be overwritten with a new one.
Explanation: This message is issued when an exception has occurred while populating the UDDI
Cloudscape database. A common cause of this problem is that a UDDI Cloudscape database
already exists.
User Response: You can ignore this message if you want to keep the existing data in your
existing UDDI Cloudscape Database. If you want to overwrite this with a new UDDI Cloudscape
database, then you should delete the existing database, then and rerun the request. Previous
messages will have shown the location and name of the UDDI Cloudscape database.
CWUDD4012E: Exception Exc occurred while trying to find the Cloudscape JDBC Provider. Value
is: Exc=<exception>.
Explanation: An exception occurred while trying to find the Cloudscape JDBC driver class.
User Response: The <exception> insert contains the exception which occurred. Examine this to
diagnose the problem.
CWUDD4013E: Ensure that the Cloudscape libraries are on the classpath
Explanation: This message is issued when an exception has occurred when trying to find the
Cloudscape JDBC driver class. A common cause of this problem is that the classpath has not
been set up to include the path to the Cloudscape class library.
User Response: Ensure that you have specified the Cloudscape class library on the request to
create the Cloudscape UDDI database. Depending on how you issued the request, this might
involve specifying the classpath on the wsadmin command used to invoke uddiDeploy.jacl, or on
the java -jar command used to invoke the UDDICloudscapeCreate.jar file. Refer to the Information
Center documentation on setting up and deploying UDDI for more details.
CWUDD4014E: Exception Exc occurred while processing SQL statement Str. Character positions
within Str shown by StrPos.
Values are:
v Exc=<exception>,
v <SQLstring>,
v StrPos=<charPositions>
Explanation: An exception occurred while processing an SQL statement used to create the UDDI
Cloudscape database. The message shows the SQL exception message in the <exception> insert,
the SQL string which was being processed in the <SQLstring> insert, and a string of character
positions in the <charPositions> insert.
User Response: Examine the exception message to determine the cause of the problem. If the
exception message indicates the position at which the problem occurred, then use the
<charPositions> string to identify that position in the SQLstring.
CWUDD4015E: There were no SQL statements in the DDL file.
Explanation: No SQL statements have been found in the DDL file that is currently being
processed.
User Response: Previous messages will tell you the path to the database scripts (DDL files), and
the DDL file which is currently being processed. Use this information to find the DDL file and check
that it is valid.
CWUDD4016E: Exception Exc occurred while processing DDL file. Value is: Exc=<exception>.
Explanation: An exception occurred while processing the current DDL file.
User Response: Examine the exception message in the <exception> insert to diagnose the
problem.
CWUDD4017E: Location of database scripts not specified.
Explanation: The request issued to create the Cloudscape database has not specified a location
for the database scripts.
User Response: Retry the request, providing a location for the database scripts. If this message
is issued when using the uddiDeploy.jacl script with the default option, then check that you are
using a valid version of uddiDeploy.jacl.

1262 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDD4018E: Location of database not specified.
Explanation: The request issued to create the Cloudscape database has not specified a location
for the UDDI Cloudscape database.
User Response: Retry the request, providing a location for the UDDI Cloudscape database. If this
message is issued when using the uddiDeploy.jacl script with the default option, then check that
you are using a valid version of uddiDeploy.jacl.
CWUDD4019E: Name of database not specified.
Explanation: The request issued to create the Cloudscape database has not specified a name for
the UDDI Cloudscape database.
User Response: Retry the request, providing a name for the UDDI Cloudscape database. If this
message is issued when using the uddiDeploy.jacl script with the default option, then check that
you are using a valid version of uddiDeploy.jacl.
CWUDD4020E: Invalid value specified for Default Profile parameter Parm, value should be
GoodParm. Values are: Parm=<suppliedparm>, GoodParm=<expectedparm>.
Explanation: The request issued to create the Cloudscape database has specified an invalid
value for the default profile parameter. The <suppliedparm> insert indicates the value that was
supplied, and the <expectedparm> indicates the value that was expected.
User Response: Retry the request, specifying a valid value for the default profile parameter, or
omit this parameter altogether if you do not want to create the UDDI Cloudscape database with a
default profile. If this message is issued when using the uddiDeploy.jacl script with the default
option, then check that you are using a valid version of uddiDeploy.jacl.
CWUDD4021E: An error occurred while loading the Cloudscape JDBC driver.
Explanation: An error occurred while attempting to load the Cloudscape JDBC driver class.
User Response:Examine the preceding messages for details of the error.
CWUDD6001E: Incorrect number of arguments passed to script.
Explanation: The wrong number of arguments were passed to the script. Arguments are Node
Name, Server Name, and optionally the default keyword.
User Response:Retry with the correct arguments.
CWUDD6002E: Usage is: <Command format description>.
Explanation: The deployment script has not been called with the correct arguments.
User Response:Retry with the correct arguments.
CWUDD6003E: Failed to determine server ID caught exception Exc. Value is: <Exception
Message>.
Explanation: An Exception occurred whilst trying to determine the Server ID.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6004E: Failed to determine server ID, possibly due to invalid nodename or servername
(check case).
Explanation: The Server ID could not be located for the given node name and server name.
User Response: Check the node name and server name are correct and are in the correct case.
CWUDD6005E: Failed to determine the list of JDBC providers caught exception Exc. Value is:
<Exception Message>.
Explanation: The deployment script was unable to determine the list of JDBC providers.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6006E: Failed to get JDBC provider name from id caught exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to determine the list of JDBC providers for the
server.

Chapter 8. Developing WebSphere applications 1263

 User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6007E: Attempt to create a Cloudscape JDBC provider caught exception Exc. Value is:
<Exception Message>.
Explanation: A Cloudscape JDBC provider is required for the default deployment of UDDI and an
Exception occurred whilst trying to create this JDBC provider.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6008E: Failed to create datasource caught exception Exc. Value is: <Exception Message>.
Explanation: An Exception occurred whilst trying to create the UDDI Cloudscape datasource.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6009E: Failed to create resource property set caught exception Exc. Value is: <Exception
Message>.
Explanation: An Exception occurred whilst trying to J2EEResourcePropertySet.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6010E: Failed to create ’databaseName’ resource property caught exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to create the J2EE Resource Property
’databaseName’.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6011E: Failed to create ’shutdownDatabase’ resource property caught exception Exc. Value
is: <Exception Message>.
Explanation: An Exception occurred whilst trying to create the J2EE Resource Property
’shutdownDatabase’.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6012E: Failed to create ’datasourceName’ resource property caught exception Exc. Value
is: <Exception Message>.
Explanation: An Exception occurred whilst trying to create the J2EE Resource Property
’datasourceName’.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6013E: Failed to create ’description’ resource property caught exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to create the J2EE Resource Property
’description’.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.

1264 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDD6014E: Failed to create ’connectionAttributes’ resource property caught exception Exc.
Value is: <Exception Message>.
Explanation: An Exception occurred whilst trying to create the J2EE Resource Property
’connectionAttributes’.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6015E: Failed to create ’createDatabase’ resource property caught exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to create the J2EE Resource Property
’createDatabase’.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6016E: Attempt to locate the WebSphere Installation Directory failed.
Explanation: The installation directory of WebSphere Application Server could not be determined.
User Response: Verify that WebSphere Application Server has been correctly installed and that
the WAS_INSTALL_ROOT WebSphere environment variable exists in the configuration.
CWUDD6017E: Uninstall of application appname caught exception Exc. Values are: <Application
Name> <Exception Message>.
Explanation: An Exception occurred whilst trying to uninstall an existing UDDI application.
User Response:This message is self-explanatory.
CWUDD6018E: Install of UDDI application caught exception Exc. Value is: <Exception Message>.
Explanation: An Exception occurred whilst trying to install the UDDI application.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6019E: Attempt to find application classloader failed with exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to locate the classloader for the UDDI
application.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6020E: Attempt to read current classloader mode failed with exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to determine the classloader mode of the UDDI
application.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6021E: Attempt to modify classloader mode to newmode failed with exception Exc. Values
are: <Classloader Mode> <Exception Message>.
Explanation: An Exception occurred whilst trying to change the classloader mode of the UDDI
application.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6022E: Attempt to read new classloader mode failed with exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to verify the new classloader mode of the UDDI
application.

Chapter 8. Developing WebSphere applications 1265

 User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6023E: Attempt to read module list from application failed with exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to determine the list of modules held in the
UDDI application.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6024E: Attempt to locate URI attribute on module failed with exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to determine the URI attribute of the application
module.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6025E: Attempt to read current classloader mode from module failed with exception Exc.
Value is: <Exception Message>.
Explanation: An Exception occurred whilst trying to determine the classloader mode of a UDDI
module.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6026E: Attempt to modify module classloader mode to newmode failed with exception Exc.
Values are: <Classloader Mode> <Exception Message>.
Explanation: An Exception occurred whilst trying to change the classloader mode of a UDDI
module.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6027E: Attempt to read new module classloader mode failed with exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to verify the new classloader mode of a UDDI
module.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6028E: Attempt to create default UDDI Registry Cloudscape database failed with exception
Exc. Value is: <Exception Message>.
Explanation: An Exception occurred whilst trying to create the default Cloudscape database.
User Response: Refer to messages displayed during creation to determine cause. If the problem
cannot be resolved, contact the IBM Customer Service Center.
CWUDD6029E: Attempt to locate the Nodes Variable Map failed with exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to locate the configurations Variable Map for the
given node.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.

1266 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDD6030E: Error saving configuration, changes not saved due to exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to save the configuration after creating default
datasource and removing an existing UDDI application.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6031E: Error saving configuration, changes not saved due to exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to save the configuration after installing the
UDDI application.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6032E: Error saving configuration, changes not saved due to exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to save the final configuration.
User Response: Retry the deployment of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD6033E: Incorrect argument passed to script.
Explanation: The wrong argument was passed to the script. Arguments are Node Name, Server
Name, and optionally the default keyword.
User Response: Retry with the correct arguments.
CWUDD6034E: ’default’ keyword is not allowed in a WebSphere Application Server Network
Deployment configuration.
Explanation: A default Cloudscape UDDI Registry is not permitted in a WebSphere Application
Server Network Deployment configuration. Please follow the UDDI Installation instructions on how
to create a non default UDDI Registry database.
User Response: Retry with the correct arguments.
CWUDD7001E: Incorrect number of arguments passed to script.
Explanation: The wrong number of arguments were passed to the script. Arguments are Node
Name, and optionally the default keyword.
User Response: Retry with the correct arguments.
CWUDD7002E: Usage is: <Command format description>.
Explanation: The removal script has not been called with the correct arguments.
User Response: Retry with the correct arguments.
CWUDD7003E: Failed to determine server ID caught exception Exc. Value is: <Exception
Message>.
Explanation: An Exception occurred whilst trying to determine the Server ID.
User Response: Retry the removal of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD7004E: Failed to determine server ID, possibly due to invalid nodename or servername
(check case).
Explanation: The Server ID could not be located for the given node name and server name.
User Response: Check the node name and server name are correct and are in the correct case.
CWUDD7005E: Uninstall of application appname caught exception Exc. Values are: <Application
Name> <Exception Message>.
Explanation: An Exception occurred whilst trying to uninstall the UDDI application.

Chapter 8. Developing WebSphere applications 1267

 User Response: Retry the removal of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD7006E: Failed to remove default UDDI datasource caught exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to remove the UDDI Cloudscape datasource.
User Response: Retry the removal of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD7007E: Error saving configuration, changes not saved due to exception Exc. Value is:
<Exception Message>.
Explanation: An Exception occurred whilst trying to save the final configuration.
User Response: Retry the removal of UDDI. If the error persists, examine the Exception
information on its cause. If the problem cannot be resolved, contact the IBM Customer Service
Center.
CWUDD7008E: Incorrect argument passed to script.
Explanation: The wrong argument was passed to the script. Arguments are Node Name, Server
Name, and optionally the default keyword.
User Response: Retry with the correct arguments.
CWUDD7009E: ’default’ keyword is not allowed in a WebSphere Application Server Network
Deployment configuration.
Explanation: A default Cloudscape UDDI Registry is not permitted in a WebSphere Application
Server Network Deployment configuration. Therefore there is no default Cloudscape UDDI
datasource to remove.
User Response: Retry with the correct arguments.

CWUDMnnnns (Web Services UDDI Management Interface) messages:

CWUDM0001E: Unexpected error in MBean operation: <operation name>
Explanation: An internal error occurred processing the specified UddiNode MBean operation.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0002E: MBean transaction failed. Commit flag was: <true|false>
Explanation: Failed to commit or rollback the current transaction.
User Response:Check database connectivity and UDDI application installation configuration. If the
problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0003E: MBean transaction did not begin.
Explanation: Failed to invoke begin method on the UserTransaction.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0004E: MBean transaction connection failed to release.
Explanation: Failed to release connection after transaction committed or rolled back.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0005E: MBean could not establish control with persistence manager.
Explanation: Message is self-explanatory.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0006E: MBean could not acquire connection for UDDI datasource.
Explanation: Message is self-explanatory.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.

1268 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDM0007E: UddiNode MBean with ObjectName <ObjectName value> could not be recognized.
Explanation: The UddiNode MBean for the UDDI application could not be unregistered from the
MBeanServer.
User Response: Restart the UDDI application or the application server. If the problem cannot be
resolved, contact your IBM Customer Service Center, supplying the ObjectName value reported in
the message (if present).
CWUDM0008W: MBean notification for event <notification identifier> failed.
Explanation: Message is self-explanatory.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0009W: A UddiNode MBean is already registered.
Explanation: There is a UddiNode MBean registered in the same cell, node and server.
User Response: Ensure there is only one UDDI application deployed in the server. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0020E: Unable to retrieve UDDI node ID.
Explanation: A database error occurred.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0021E: Unable to retrieve UDDI node state.
Explanation: A database error occurred.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0022E: Unable to retrieve UDDI node application name.
Explanation: A database error occurred.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0023E: Unable to retrieve UDDI node description.
Explanation: A database error occurred.
User Response: Check database connectivity and UDDI application installation configuration. If
the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0024E: Unable to activate UDDI node.
Explanation: An error occurred trying to activate the UDDI node.
User Response: Check the running state of the UDDI application. Restart the application if
necessary. If the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0025I: Unable to activate a UDDI node that is not initialized.
Explanation: The UDDI node must be initialized (and in deactivated state) before it can be
activated.
User Response: If the UDDI node is ready to be initialized, invoke the initialization operation.
CWUDM0026E: Unable to deactivate UDDI node.
Explanation: An error occurred trying to deactivate the UDDI node.
User Response:Check the running state of the UDDI application. Restart the application if
necessary. If the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0027I: Unable to deactivate UDDI node that is not initialized.
Explanation: The UDDI node must be initialized (and activated) before it can be deactivated.
User Response: If the UDDI node is ready to be initialized, invoke the initialization operation.
CWUDM0028E: Unable to initialize UDDI node.
Explanation: An error occurred during UDDI node initialization.
User Response: Check the UDDI application installation and datasource settings. If the problem
cannot be resolved, contact your IBM Customer Service Center.

Chapter 8. Developing WebSphere applications 1269

CWUDM0029I: Unable to initialize UDDI node because a required property is missing or invalid:
<property name>.
Explanation: A configuration property that is required for UDDI node initialization has not been
populated.
User Response: Supply a value for the required property.
CWUDM0030I: Initialize operation did not occur because the UDDI node is already initialized.
Explanation: A UDDI node can only be initialized once.
User Response: None.
CWUDM0031I: Initialize operation did not occur because the UDDI node is in default configuration
and is already initialized.
Explanation: A UDDI node can only be initialized once.
User Response: None.
CWUDM0032I: The initialize operation is already in progress.
Explanation: A UDDI node can only be initialized once.
User Response: Wait until the current initialization operation completes.
CWUDM0050I: The UDDI publisher with user name <user ID> does not exist.
Explanation: An operation that requires a UDDI publisher ID could not find a publisher with that
ID.
User Response: Check the UDDI publisher is registered with the UDDI node using the
administrative functions available.
CWUDM0051E: Unable to create UDDI publisher with user name <user ID>.
Explanation: An error occurred trying to register the UDDI publisher.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0052I: Unable to create UDDI publisher for user name <user ID> because a UDDI publisher
with that name already exists.
Explanation: The UDDI publisher is already registered.
User Response: None.
CWUDM0053E: Unable to delete UDDI publisher with user name <user ID>.
Explanation: An error occurred trying to register the UDDI publisher.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0054I: Unable to delete UDDI publisher with user name <user ID> because that UDDI
publisher does not exist.
Explanation: The UDDI publisher is not registered so cannot be removed.
User Response: None.
CWUDM0055E: Unable to create a UDDI publisher with user name <user ID> because one or more
entitlement identifiers are invalid.
Explanation: UddiUser objects must contain Entitlement objects with valid entitlement IDs.
User Response: Use valid entitlement IDs for Entitlement objects. Valid IDs can be found in the
EntitlementConstants interface.
CWUDM0056E: Unable to update UDDI publisher with user name <user ID>.
Explanation: An error occurred trying to update the UDDI publisher.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0057E: Unable to update UDDI publisher with user name <user ID> because one or more
entitlement identifiers are invalid.
Explanation: UddiUser objects must contain Entitlement objects with valid entitlement IDs.
User Response: Use valid entitlement IDs for Entitlement objects. Valid IDs can be found in the
EntitlementConstants interface.

1270 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDM0058I: Unable to update the UDDI publisher with user name <user ID> because that UDDI
publisher does not exist.
Explanation: The UDDI publisher is not registered so cannot be updated.
User Response: None.
CWUDM0059E: Unable to retrieve information for UDDI publisher with user name <user ID>.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0060E: Unable to retrieve collection of UDDI publishers.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0061E: Unable to get tier assigned to UDDI publisher with user name <user ID>.
Explanation: This may be because the UDDI publisher with the specified user name does not
exist, or because a database error occurred performing the operation.
User Response: Check the UDDI publisher exists. If it does, check UDDI application configuration
and database connectivity. If the problem cannot be resolved, contact your IBM Customer Service
Center.
CWUDM0062E: Unable to create UDDI publishers with user names: <user IDs>.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0070E: Unable to create tier with ID: <tier ID>.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0071E: Unable to delete tier with ID: <tier ID>.
Explanation: This may because the tier with the specified ID does not exist, or because a
database error occurred performing the operation.
User Response: Check the tier ID. If it does exist, check UDDI application configuration and
database connectivity. If the problem cannot be resolved, contact your IBM Customer Service
Center.
CWUDM0072E: Unable to retrieve information for tier with ID: <tier ID>.
Explanation: This may be because the supplied tier ID is not an integer, or the tier with the ID
does not exist, or because of a database error performing the operation.
User Response: Check the tier ID is an integer and the tier exists. If it does exist, check UDDI
application configuration and database connectivity. If the problem cannot be resolved, contact
your IBM Customer Service Center.
CWUDM0073E: Unable to retrieve collection of tiers.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0074E: Unable to set default tier to tier ID: <tier ID>.
Explanation: This may be because the tier with the specified ID does not exist, or because a
database error occurred performing the operation.
User Response: Check the tier ID. If it does exist, check UDDI application configuration and
database connectivity. If the problem cannot be resolved, contact your IBM Customer Service
Center.
CWUDM0075E: Unable to update tier with ID: <tier ID>.
Explanation: This is most likely because the tier with the specified ID does not exist, or because
a database error occurred performing the operation.

Chapter 8. Developing WebSphere applications 1271

 User Response: Check the tier ID. If it does exist, check UDDI application configuration and
database connectivity. If the problem cannot be resolved, contact your IBM Customer Service
Center.
CWUDM0076E: Unable to get count of UDDI publishers for tier ID: <tier ID>.
Explanation: This may be because the tier with the specified ID does not exist, or because a
database error occurred performing the operation.
User Response: Check the tier ID. If it does exist, check UDDI application configuration and
database connectivity. If the problem cannot be resolved, contact your IBM Customer Service
Center.
CWUDM0077E: Unable to retrieve collection of entitlements.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0078E: Unable to retrieve collection of limits.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0079I: The default tier cannot be deleted.
Explanation: A tier must always exist that is designated as the tier assigned to UDDI publishers
when auto-registration of UDDI publishers is enabled.
User Response: None.
CWUDM0080I: Unable to delete tier <tier ID> because it is currently assigned to a UDDI publisher.
Explanation: Tiers which have UDDI publishers assigned to them cannot be deleted.
User Response: If you want to remove the tier, assign the UDDI publishers to a different tier first.
CWUDM0100E: Unable to get configuration property information for property with ID: <property
ID> Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0101I: Unable to get configuration property information for property with ID: <property ID>
because it does not exist.
Explanation: The configuration property with the specified ID does not exist.
User Response: None.
CWUDM0102E: Unable to retrieve collection of configuration properties.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0103E: Unable to update configuration properties.
Explanation: This may occur if any of the updated property objects fails validation. Check any
cause exceptions for possible additional information. Alternatively database error may have
occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0104E: Unable to update configuration property with ID: <property ID>
Explanation: This may occur if the updated property object fails validation. Check any cause
exceptions for possible additional information. Alternatively a database error may have occurred
performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0105I: Unable to update configuration property with ID: <property ID> because it does not
exist. Explanation: The configuration property with the specified ID does not exist.

1272 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 User Response: Use a valid configuration property ID. These can be found in PropertyConstants.
CWUDM0106I: Unable to update configuration properties because one or more properties do not
exist in the UDDI node.
Explanation: One or more supplied configuration properties do not exist in the UDDI registry.
User Response: Use valid configuration property IDs. These can be found in PropertyConstants.
CWUDM0107E: Failed to retrieve required properties from database.
Explanation: This indicates a database error occurred when trying to initialize a UDDI node.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0120E: Unable to get policy information for policy with ID: <policy ID>.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0121I: Unable to get policy information for policy with ID: <policy ID> because it does not
exist. Explanation: The policy with the specified ID does not exist.
User Response: None.
CWUDM0122E: Unable to get policy group with group ID: <policy group ID>.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0123E: Unable to retrieve collection of policy groups.
Explanation: A database error occurred performing the operation.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0124E: Unable to update policies.
Explanation: This may occur if any of the updated policy objects fails validation. Check any cause
exceptions for possible additional information. Alternatively a database error may have occurred
performing the operation.
User Response: Ensure all policy IDs and values are valid. Check UDDI application configuration
and database connectivity. If the problem cannot be resolved, contact your IBM Customer Service
Center.
CWUDM0125E: Unable to update policy with ID: <policy ID>.
Explanation: This may occur if the updated policy object fails validation or the ID isn’t recognized.
Check any cause exceptions for possible additional information. Alternatively a database error may
have occurred performing the operation.
User Response: Check the policy ID and value are valid. Check UDDI application configuration
and database connectivity. If the problem cannot be resolved, contact your IBM Customer Service
Center.
CWUDM0126I: Unable to get policy group information for policy group with ID: <policy group ID>
because itdoes not exist.
Explanation: The policy group with the specified ID does not exist.
User Response: Use a valid policy group ID. These can be found in PolicyConstants.
CWUDM0127I: Unable to update policies because one or more policies do not exist in the UDDI
node. Explanation: One or more supplied policies do not exist in the UDDI registry.
User Response: Use valid policy IDs. These can be found in PolicyConstants.
CWUDM0128I: Unable to update policy with ID: <policy ID> because it does not exist.
Explanation: The policy with the specified ID does not exist.
User Response: Use a valid policy ID. These can be found in PolicyConstants.

Chapter 8. Developing WebSphere applications 1273

CWUDM0140E: Unable to change value set tModelKey from <original tModel key> to <new tModel
key>. Explanation: The original tModel key or new tModel key supplied could not be found in the UDDI
registry, or possibly there was a database error.
User Response: Supply keys for tModels that exist in the UDDI registry. Check UDDI application
configuration and database connectivity. If the problem cannot be resolved, contact your IBM
Customer Service Center.
CWUDM0141E: Unable to retrieve value set details for tModel key: <tModel key>.
Explanation: A database error occurred getting the value set details.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0142E: Unable to get value set property: <value set property ID> for value set with tModel
key: <tModel key>.
Explanation: The value set property ID or tModel key supplied was not recognized.
User Response: Supply a valid value set property ID and tModel key. If the problem cannot be
resolved, contact your IBM Customer Service Center.
CWUDM0143E: Unable to retrieve value sets collection.
Explanation: A database error may have occurred.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0144E: Unable to determine if value set with tModel key: <tModel key> exists.
Explanation: The tModel key supplied is not valid or a database error may have occurred.
User Response: Ensure the tModel exists. Check UDDI application configuration and database
connectivity. If the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0145E: Unable to load value set data for value set with tModel key: <tModel key> and file
name <1>.
Explanation: The original tModel key or new tModel key supplied could not be found in the UDDI
registry, or possibly there was a database error.
User Response: Ensure the tModel exists and the value set data object is populated. Check
UDDI application configuration and database connectivity. If the problem cannot be resolved,
contact your IBM Customer Service Center.
CWUDM0146E: Unable to load value set data for value set with tModel key: <tModel key>.
Explanation: The tModel key is not recognized or a database error occurred.
User Response: Ensure the tModel exists and the value set data object is populated. Check
UDDI application configuration and database connectivity. If the problem cannot be resolved,
contact your IBM Customer Service Center.
CWUDM0147E: Could not update value set status with tModel key: <tModel key>.
Explanation: The value set status object supplied is null or the tModel key is not known.
User Response: Supply a valid value set status object with tModel key for a value set tModel that
exists. Check UDDI application configuration and database connectivity. If the problem cannot be
resolved, contact your IBM Customer Service Center.
CWUDM0148E: Could not update value set status with tModel key: <tModel key>, property: <value
set property ID>.
Explanation: A database error occurred updating the supported status of the value set status.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0149E: Could not update value set status with tModel key: <tModel key>.
Explanation: One of the supplied value set status objects contained a tModel key which was not
recognized.
User Response: Supply tModel keys for value set tModels that exist. Check UDDI application
configuration and database connectivity. If the problem cannot be resolved, contact your IBM
Customer Service Center.

1274 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDM0150E: Could not update value set status with tModel key: <tModel key>, property: <value
set property ID>.
Explanation: A database error occurred updating the supported status of one of the value set
status objects.
User Response: Check UDDI application configuration and database connectivity. If the problem
cannot be resolved, contact your IBM Customer Service Center.
CWUDM0151E: Unable to unload value set data with tModel key: <tModel key>.
Explanation: The tModel key is not recognized or a database error occurred.
User Response: Ensure the tModel exists. Check UDDI application configuration and database
connectivity. If the problem cannot be resolved, contact your IBM Customer Service Center.
CWUDM0170E: Loading of configuration file <configuration file URL> failed.
Explanation:
User Response: Check UDDI application configuration. If the problem cannot be resolved, contact
your IBM Customer Service Center.
CWUDM0171E: Parsing of configuration file <configuration file URL> failed.
Explanation:
User Response: Check UDDI application configuration. If the problem cannot be resolved, contact
your IBM Customer Service Center.
CWUDM0172W: An unexpected date format was found while parsing configuration file.
Explanation:
User Response: Check UDDI application configuration. If the problem cannot be resolved, contact
your IBM Customer Service Center.
CWUDM0180I: UDDI node was activated.
Explanation: The UDDI node is ready to accept UDDI API requests.
User Response: None.
CWUDM0181I: UDDI node was deactivated.
Explanation: The UDDI node is set to not accept UDDI API requests. This typically occurs when
configuration settings are being updated by administrative tasks.
User Response: None.
CWUDM0182I: UDDI node initialized successfully.
Explanation: The UDDI node is ready to accept UDDI API requests.
User Response: None.
CWUDM0183I: UDDI publisher <user ID> was created.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0184I: UDDI publisher <user ID> was updated.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0185I: UDDI publisher <user ID> was deleted.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0186I: Tier <tier ID> was created.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0187I: Tier <tier ID> was updated.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0188I: Tier <tier ID> was deleted.
Explanation: This message indicates the administrative operation completed successfully.

Chapter 8. Developing WebSphere applications 1275

 User Response: None.
CWUDM0189I: Configuration property <property ID> was updated to value <property value>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0190I: Policy <policy ID> was updated to value <policy value>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0191I: Default tier was set to <tier ID>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0192I: Loaded value set for tModel key <tModel key> from file <1>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0193I: Loaded value set for tModel key <tModel key>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0194I: Unloaded value set for tModel key <tModel key>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0195I: Updated value set supported status for tModel key <tModel key> to <supported
status>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0196I: Changed tModel key for value set from <original tModel key> to <new tModel key>.
Explanation: This message indicates the administrative operation completed successfully.
User Response: None.
CWUDM0220W: <value or ID> is too short. The length must be in the range <minimum length> to
<maximum length> characters.
Explanation: A value or ID of type String is shorter than expected.
User Response: Supply a value or ID that is in the expected range.
CWUDM0221W: <value or ID> is too long. The length must be in the range <minimum length> to
<maximum length> characters.
Explanation: A value or ID of type String is longer than expected.
User Response: Supply a value or ID that is in the expected range.
CWUDM0222W: <value or ID> is read-only and cannot be updated.
Explanation: The configuration setting is marked as read only, which may be because the setting
is for information only, or because the setting is configured once during UDDI node initialization,
such as the UDDI node ID or root key generator.
User Response: None.
CWUDM0223W: <value or ID> is required.
Explanation: The configuration setting expects a value to be entered.
User Response: Supply a non-empty, valid value for the configuration setting.
CWUDM0224W: <value or ID> must be a valid URL value.
Explanation: The configuration property is expected to be a valid URL.
User Response: Supply a valid URL.
CWUDM0225W: <value or ID> must be a valid xml:lang value.
Explanation: The configuration property supplied is not a valid xml:lang value.
User Response: Supply a valid xml:lang value.

1276 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDM0226W: <value or ID> must be of type: <value type>.
Explanation: The value or ID is not of the expected type.
User Response: Supply a value or ID of the correct type.
CWUDM0227W: <value or ID> cannot be a null value.
Explanation: A property ID was expected but a null value was supplied.
User Response: Supply a valid, non-null ID.
CWUDM0228W: <value or ID> must be in the range <minimum value> to <maximum value>.
Explanation: The value is not in the expected range
User Response: Supply a value in the expected range.
CWUDM0229W: The entitlement object with ID: <entitlement ID> is not valid.
Explanation: The UDDI application doesn’t recognize the entitlement with the supplied ID.
User Response: Supply a valid entitlement ID, which can be found in EntitlementConstants.
CWUDM0230W: The limit object with ID: <limit ID> is not valid.
Explanation: The UDDI application doesn’t recognize the limit with the supplied ID.
User Response: Supply a valid limit ID, which can be found in LimitConstants.
CWUDM0231W: <value> must be a valid UDDI key value.
Explanation: The value supplied was not a UDDI key.
User Response: UDDI keys must start with the text ’uddi:’. See the UDDI specification for further
information about UDDI keys.
CWUDM0232W: <value> must be a valid UDDI key generator key.
Explanation: The value supplied was not a UDDI key generator.
User Response: UDDI key generator values must be valid UDDI keys and end in the string
’keygenerator’. See the UDDI specification for further information about UDDI keys.
CWUDM0240W: The configuration property ID cannot be null or empty.
Explanation: The ID supplied was null or empty.
User Response: Supply a non-null, non-empty ID, valid for the context in which it is used.
CWUDM0241W: The policy group ID cannot be null or empty.
Explanation: The ID supplied was null or empty.
User Response: Supply a non-null, non-empty ID, valid for the context in which it is used.
CWUDM0242W: The policy ID cannot be null or empty.
Explanation: The ID supplied was null or empty.
User Response: Supply a non-null, non-empty ID, valid for the context in which it is used.
CWUDM0243W: The entitlement ID cannot be null or empty.
Explanation: The ID supplied was null or empty.
User Response: Supply a non-null, non-empty ID, valid for the context in which it is used.
CWUDM0244W: The limit ID cannot be null or empty.
Explanation: The ID supplied was null or empty.
User Response: Supply a non-null, non-empty ID, valid for the context in which it is used.
CWUDM0245W: The user ID cannot be null or empty.
Explanation: The ID supplied was null or empty.
User Response: Supply a non-null, non-empty ID, valid for the context in which it is used.
CWUDM0246W: The tier ID cannot be null or empty.
Explanation: The ID supplied was null or empty.
User Response: Supply a non-null, non-empty ID, valid for the context in which it is used.
CWUDM0250W: The configuration property parameter cannot be null or empty.
Explanation: The parameter supplied was null or empty.
User Response: Supply a non-null, non-empty configuration property parameter.

Chapter 8. Developing WebSphere applications 1277

CWUDM0251W: The policy group parameter cannot be null or empty.
Explanation: The parameter supplied was null or empty.
User Response: Supply a non-null, non-empty policy group parameter.
CWUDM0252W: The policy parameter cannot be null or empty.
Explanation: The parameter supplied was null or empty.
User Response: Supply a non-null, non-empty policy parameter.
CWUDM0253W: The entitlement parameter cannot be null or empty.
Explanation: The parameter supplied was null or empty.
User Response: Supply a non-null, non-empty entitlement parameter.
CWUDM0254W: The limit parameter cannot be null or empty.
Explanation: The parameter supplied was null or empty.
User Response: Supply a non-null, non-empty limit parameter.
CWUDM0255W: The user parameter cannot be null or empty.
Explanation: The parameter supplied was null or empty.
User Response: Supply a non-null, non-empty user (UDDI publisher) parameter.
CWUDM0256W: The tier parameter cannot be null or empty.
Explanation: The parameter supplied was null or empty.
User Response: Supply a non-null, non-empty tier parameter.
CWUDM0257I: The collection cannot be null.
Explanation: The collection (typically a list of properties, policies, tiers or users to update)
parameter supplied was null.
User Response: Supply a non-null collection parameter.

CWUDNnnnns (Web Services UDDI Node Manager) messages:

CWUDN0001I: UDDI Node State change, new state:
Explanation: The UDDI has successfully changed to the identified new state.
User Response: None.
CWUDN0002I: Error, invalid Node State requested:
Explanation: The UDDI Registry detected a request for invalid state changes.
User Response: Contact the IBM Customer Service Center.
CWUDN0004E: Error, NodeManager, txnlnit, failed getting persister control
Explanation: NodeManager initialization failure.
User Response: Contact the IBM Customer Service Center.
CWUDN0005E: Error, NodeManager, txnlInit, UDDIFatalErrorException during Init
Explanation: NodeManager initialization failure.
User Response: Contact the IBM Customer Service Center.
CWUDN0006E: Error, NodeManager, txnlInit, UDDIException during initialization.
Explanation: NodeManager initialization failure.
User Response: Contact the IBM Customer Service Center.
CWUDN0007E: Error, NodeManager, txnlInit, Exception during Init
Explanation: NodeManager initialization failure.
User Response: Contact the IBM Customer Service Center.
CWUDN0008E: Error, NodeManager, txnlInit, Throwable during Init
Explanation: NodeManager initialization failure.
User Response: Contact the IBM Customer Service Center.
CWUDN0009E: Error, NodeManager, txnlInit, rollback exception
Explanation: NodeManager initialization failure.
User Response: Contact the IBM Customer Service Center.

1278 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDN0010E: Error, NodeManager, txnlInit, Throwable releasing connection
Explanation: NodeManager initialization failure.
User Response: Contact the IBM Customer Service Center.
CWUDN0011E: Error, NodeManager, txnlDestroy, failed getting Persister control
Explanation: NodeManager application stop or removal error.
User Response: Contact the IBM Customer Service Center.
CWUDN0012E: Error, NodeManager, txnlDestroy, UDDI Exception during destroy
Explanation: NodeManager application stop or removal error.
User Response: Contact the IBM Customer Service Center.
CWUDN0013E: Error, NodeManager, txnlDestroy, rollback Exception
Explanation: NodeManager application stop or removal error.
User Response: Contact the IBM Customer Service Center.
CWUDN0014E: Error, NodeManager, txnlDestroy, Exception releasing connection
Explanation: NodeManager application stop or removal error.
User Response: Contact the IBM Customer Service Center.

CWUDQnnnns (Web Services UDDI Migration) messages:

CWUDQ0001I: UDDI registry migration datasource is present.
Explanation: The UDDI migration datasource is defined when UDDI is started.
User Response: None.
CWUDQ0002I: UDDI registry migration has started.
Explanation: The UDDI database migration process has started. This may take some time to
complete dependent on the size of your database.
User Response: None.
CWUDQ0003I: UDDI registry migration has completed.
Explanation: The UDDI database migration process has finished.
User Response: None.
CWUDQ0004W: UDDI registry not started due to migration errors.
Explanation: The UDDI registry has not been activated because migration errors were
encountered.
User Response: Examine the messages produced during the migration process. Determine if the
problem is user fixable, that is the Version 2 database is quiesced and so on. If the problem is
fixable recreate the Version 3 UDDI database and restart the UDDI application. If the problem
cannot be rectified contact your IBM Customer Service Center. It is still possible to use the UDDI
Administration Console to start the UDDI registry.
CWUDQ0005I: <rows> rows have been inserted into table <table>.
Explanation: An informational message showing the number of database rows converted for each
UDDI table.
User Response: None.
CWUDQ10001E: Row not inserted into <table>.
Explanation: A row was unable to be inserted into a database table.
User Response: See CWUDQ1003E for details of the SQL Exception details
CWUDQ1002E: Table <table> values are: <Key Values>.
Explanation: Contains the table in error and the significant key values of the row being migrated.
User Response: None.
CWUDQ1003E: SQL Exception during migration: <SQL Exception Message>.
Explanation: An SQL Exception has occurred during the migration process. The SQL Exception
details are displayed in the message.

Chapter 8. Developing WebSphere applications 1279

 User Response: Examine the SQL Exception information on its cause. Message CWUDQ1002E
contains table details and significant key values. If the problem cannot be resolved, contact your
IBM Customer Service Center.
CWUDQ1004E: <rows> rows have not been inserted into table <table>.
Explanation: A message showing the number of database rows not converted for a particular
UDDI table.
User Response: None.
CWUDQ1005E: SQL Exception during key value extraction: <SQL Exception Message>.
Explanation: An SQL Exception occurred during the production of the CWUDQ1002E message.
User Response: None.
CWUDQ1006E: Exception during migration: <Exception Message>.
Explanation: An Exception has occurred during the migration process. The Exception details are
displayed in the message.
User Response: Examine the Exception information on its cause. Message CWUDQ1002E
contains table details and significant key values. If the problem cannot be resolved, contact your
IBM Customer Service Center.

CWUDRnnnns (Web Services UDDI Logging and Tracing) messages:

CWUDR0001E: Exception “<exception>” occurred while attempting to get UDDI Message Logger.
Explanation: This message is issued to stderr when an attempt to get the UDDI Message Logger
fails with the indicated exception. Since the attempt to get the message logger failed, the message
cannot be logged. No messages can be logged by this instance of the IBM WebSphere UDDI
Registry.
User Response: Restart the UDDI registry. If the error persists, examine the WebSphere logs for
information on its cause. If the problem cannot be resolved, then contact the IBM Customer
Service Center.
CWUDR0002E: Exception “<exception>” occurred while attempting to get UDDI Trace Logger for
“<component>”.
Explanation: This message is logged when an attempt to get the UDDI Trace Logger for the
specified component (or package) fails with the indicated exception. No trace entries can be
logged for this component or package of the IBM WebSphere UDDI Registry.
User Response: Restart the UDDI registry. If the error persists, examine the WebSphere logs for
information on its cause. If the problem cannot be resolved, then contact the IBM Customer
Service Center.

CWUDSnnnns (Web Services UDDI SOAP Interface) messages:

CWUDS0001E: ParserPool found empty whilst attempting to process request. Request unsatisfied
Explanation: A SOAP request was received, but was unable to be dealt with, as there were no
free Parsers within the ParserPool.
User Response: Consider increasing the number of Parsers within the ParserPool by modifying
the Init Parameter on the SOAP servlets.
CWUDS0002E: Error locating schemas required for UDDI processing. SOAP Servlets unworkable.
Explanation: The SOAP servlet was unable to locate the schemas it requires in order to process
SOAP requests. Without these, the servlet cannot process SOAP requests.
User Response: Check installation of UDDI was performed correctly. If the error persists, examine
the WebSphere logs for information on its cause. If the problem cannot be resolved, then contact
the IBM Customer Service Center.
CWUDS0003W: Servlet unable to locate init parameter ’defaultPoolSize’. Using internal defaults.
Explanation: The SOAP servlet was unable to locate the init parameter which sets the default
size of the ParserPool. It will fall back to an internal default.

1280 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 User Response: If this message occurred after attempting to make changes to the
defaultPoolSize init parameter, ensure the changes were correct. If this message has appeared
after installed, ensure installation was performed correctly.
CWUDS0004W: Servlet unable to understand init parameter ’defaultPoolSize’. Using internal
defaults.
Explanation: The SOAP servlet was unable to parse the init parameter which sets the default size
of the ParserPool. It will fall back to an internal default.
User Response: If this message occurred after attempting to make changes to the
defaultPoolSize init parameter, ensure the changes were correct. If this message has appeared
after installed, ensure installation was performed correctly.
CWUDS0005E: Error occurred during parser creation.
Explanation: An unspecified error occurred during the creation of a SOAP parser
User Response: Restart the UDDI registry. If the error persists, examine the WebSphere logs for
information on its cause. If the problem cannot be resolved, then contact the IBM Customer
Service Center.
CWUDS0006E: Internal configuration error.
Explanation: This error may occur if there was a failure creating a Parser, with accompanying
message CWUDS0005. It may also occur if there was a problem acquiring the Persistence layer.
User Response: Restart the UDDI registry. If the error persists, examine the WebSphere logs for
information on its cause. If the problem cannot be resolved, then please contact the IBM Customer
Service Center.
CWUDS0007E: Error during servlet acquisition of persistence layer.
Explanation: The SOAP servlet was unable to acquire the persistence layer required for it to
communicate with the UDDI datasource
User Response: Restart the UDDI registry. If the error persists, examine the WebSphere logs for
information on its cause. If the problem cannot be resolved, then contact the IBM Customer
Service Center.
CWUDS0008E: Error during servlet release of persistence layer.
Explanation: The persistence layer reported a problem when the SOAP servlet attempted to
release it.
User Response: Restart the UDDI registry. If the error persists, examine the WebSphere logs for
information on its cause. If the problem cannot be resolved, then contact the IBM Customer
Service Center.
CWUDS0009E: Error during sending of response to client.
Explanation: An error occurred when sending a SOAP response message back to a client. The
client may not have received the response
User Response: This error is recorded to enable logging of failed responses to clients. The error
may be the fault of the client disconnecting before the reply could be sent, or may indicate a
network problem. Examine the WebSphere logs for more information on its cause.

CWUDGnnnns (Web Services UDDI User Console) messages:

CWUDG0001I: IBM WebSphere UDDI Registry user console starting initialization.
Explanation: The user console control servlet is starting.
User Response: None.
CWUDG0002I: IBM WebSphere UDDI Registry user console finished initialization.
Explanation: The user console control servlet has completed startup successfully.
User Response: None.
CWUDG0003I: Reading init parameters.
Explanation: The user console control servlet has started reading external parameters in its init
method
User Response: None.

Chapter 8. Developing WebSphere applications 1281

CWUDG0004I: Finished reading init parameters.
Explanation: The user console control servlet has finished reading external parameters in its init
method. This message indicates the user console is ready to accept client requests.
User Response: None.
CWUDG0005E: A serious error has occurred. Error message: <Message> error: <Throwable>. More
information: <Additional information>.
Explanation: This error message indicates an unexpected error has occurred. The <Message>
describes the error that has occurred and the <Throwable> is the type of error that was caught.
<Additional information> may provide further information, if available.
User Response: A trace of the gui component is recommended. Contact IBM support with this
information.
CWUDG0006E: A persistence error has occurred. Error message: <Message> error: <Throwable>.
More information: <Additional information>.
Explanation: An error occurred while performing a database operation. The <Message> describes
the error that occurred and the <Throwable> is the type of error that was caught. <Additional
information> may provide further information, if available.
User Response: Check database connections and state. Provide IBM support with a trace,
including the gui and persistence components.
CWUDG0007E: A User mismatch error has occurred. Error message: <Message> error:
<Throwable>. More information: <Additional information>.
Explanation: The user id provided does not match the user id required or expected whilst
performing an operation that requires authentication. The <Message> describes the error that
occurred and the <Throwable> is the type of error that was caught. <Additional information> may
provide further information, if available.
User Response: Check the user has authority for the operation being requested. If necessary,
contact IBM support detailing the actions taken to recreate the problem.
CWUDG0008E: An invalid key was passed. Error message: <Message> error: <Throwable>. More
information: <Additional information>.
Explanation: The requested operation is trying to retrieve information about an entity with a key
that is invalid. This may occur if the entity has been deleted by another session. The <Message>
describes the error that occurred and the <Throwable> is the type of error that was caught.
<Additional information> may provide further information, if available.
User Response: Ask the client to close existing sessions and attempt the operation in a new
browser session. If the problem persists, contact IBM support with a trace of the gui and api
components.
CWUDG0009E: An invalid value was supplied. Error message: <Message> error: <Throwable>.
More information: <Additional information>
Explanation: An invalid value was passed to an API call. The <Message> describes the error that
occurred and the <Throwable> is the type of error that was caught. <Additional information> may
provide further information, if available.
User Response: Contact IBM support with a trace of the gui and api components.
CWUDG0010E: Failed to introspect ActionForm properties. Exception: <Exception>.
Explanation: String properties of a form object could not be introspected which means that the
form contents cannot be checked for invalid characters.
User Response: Contact IBM support with details of the Exception and a trace of the gui
component.
CWUDG0011E: Failed to invoke reflected methods in ActionForm. Exception: <Exception>.
Explanation: A form object’s declared public method for setting or getting a String value could not
be invoked. This method is required to check for invalid characters.
User Response: Contact IBM support with details of the Exception and a trace of the gui
component.

1282 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDG0012E: User console initialization failed to connect to UDDI database. Exception:
<Exception>.
Explanation: During user console initialization, connection to the database failed, and threw the
exception specified.
User Response: Check the connection to the UDDI database. The included exception message
may yield some clues to help you resolve the problem. If unresolved, contact IBM support with a
trace of the gui component during startup.
CWUDG0013E: User console initialization failed to initialize tModels. Exception: <Exception>.
Explanation: Indicates that an error has occurred during initialization of ActionServlet, specifically
when reading tModels (invoking init method in class TModelNames).
User Response: Check the state of the UDDI database. Visually inspect the TMODEL table and
confirm it is populated with valid data. The included exception message may yield some clues to
help you resolve the problem. If unresolved, contact IBM support with a trace of the gui
component during startup.
CWUDG0014E: User console initialization failed to initialize taxonomies. Exception: <Exception>.
Explanation: Indicates that an error has occurred during initialization of ActionServlet, specifically
when reading taxonomy data (invoking init method of CategoryTaxonomyTree).
User Response: Check the state of the UDDI database. The included exception message may
yield some clues to help you resolve the problem. If unresolved, contact IBM support with a trace
of the gui component during startup.

CWUDUnnnns (Web Services UDDI Utility Tools) messages:

CWUDU0001I: Usage: java -jar UDDIUtilityTools.jar ’{’function’}’ [options]

function:
-promote entity source Promote entities between registries
-export entity source Extract entities from registry to XML
-delete entity source Delete entities from registry
-import Create entities from XML to registry

where entity source is one of:

-tmodel|-business|-service|-binding key Specify single entity type and key
-keysFile | -f filename Specify file containing entity types and keys

options:
-properties filename Specify path to configuration file
-overwrite | -o Overwrite an entity if it already exists
-log | -v Output verbose messages
-definitionFile filename Specify path to UDDI entity definition file
-importReferenced Import entities referenced by source entities

The following options override property settings in configuration file:

-overwrite
-log
-definitionFile
-importReferenced

Example: java -jar UDDIUtilityTools.jar -promote -keysFile C:/uddikeys.txt

Explanation: This is the usage message displayed at the command line when the user has
entered an invalid combination of arguments or options.

User Response: Enter the command according to the usage message.

CWUDU0002I: ********** Starting UDDI Utility Tools **********
Explanation: This message is used as a marker in the message log file to indicate tool start
points.
User Response: None.

Chapter 8. Developing WebSphere applications 1283

CWUDU0003I: Promoting entityType<entity type> key<entity key>...
Explanation: Indicates which entity type (business, tModel and so on) is being promoted, and it’s
key value.
User Response: None.
CWUDU0004I: Bad entityType: received<incorrect entity type>, expected
<tModel|business|service|binding>
Explanation: The user entered an incorrect entity type.
User Response: Use an entity type of tModel, business, service or binding.
CWUDU0005I: Promotion successful.
Explanation: Indicates the promote function completed successfully.
User Response: None.
CWUDU0006I: Import successful.
Explanation: Indicates the import function completed successfully.
User Response: None.
CWUDU0007I: Export successful.
Explanation: Indicates the export function completed successfully.
User Response: None.
CWUDU0008I: Delete successful.
Explanation: Indicates the delete function completed successfully.
User Response: None.
CWUDU0009I: Exporting entities ...
Explanation: Indicates the export function has started.
User Response: None.
CWUDU0010I: Exporting business, businessKey[<business key].
Explanation: Indicates that the businessEntity with the specified key is being exported.
User Response: None.
CWUDU0011I: Exporting service, serviceKey[<service key>].
Explanation: Indicates that the businessService with the specified key is being exported.
User Response: None.
CWUDU0012I: Exporting binding, bindingKey[<binding key>].
Explanation: Indicates that the bindingTemplate with the specified key is being exported.
User Response: None.
CWUDU0013I: Exporting tModel, tModelKey[<tModel key>].
Explanation: Indicates that the tModel with the specified key is being exported.
User Response: None.
CWUDU0014I: Exporting referenced tModel, tModelKey[<tModel key>].
Explanation: Indicates that the referenced tModel with the specified key is being exported.
User Response: None.
CWUDU0015I: Exported <entity count> entities.
Explanation: Indicates that the export function completed, and shows the number of entities
exported.
User Response: None.
CWUDU0016I: Importing entities ...
Explanation: Indicates the import function has started.
User Response: None.
CWUDU0017I: Importing business, businessKey[<business key>].
Explanation: Indicates that the businessEntity with the specified key is being imported.
User Response: None.

1284 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDU0018I: Importing service, serviceKey[<service key>].
Explanation: Indicates that the businessService with the specified key is being imported.
User Response: None.
CWUDU0019I: Importing binding, bindingKey[<binding key>]
Explanation: Indicates that the bindingTemplate with the specified key is being imported.
User Response: None.
CWUDU0020I: Importing tModel, tModelKey[<tModel key>].
Explanation: Indicates that the tModel with the specified key is being imported.
User Response: None.
CWUDU0021I: Importing referenced tModel, tModelKey[<tModel key>].
Explanation: Indicates that the referenced tModel with the specified key is being imported.
User Response: None.
CWUDU0022I: Imported <entity count> entities.
Explanation: Indicates that the import function completed, and shows the number of entities
imported.
User Response: None.
CWUDU0023I: Deleting entities ...
Explanation: Indicates the delete function has started.
User Response: None.
CWUDU0024I: Deleting business, businessKey[<business key>].
Explanation: Indicates that the businessEntity with the specified key is being deleted.
User Response: None.
CWUDU0025I: Deleting service, serviceKey[<service key>].
Explanation: Indicates that the businessService with the specified key is being deleted.
User Response: None.
CWUDU0026I: Deleting binding, bindingKey[<binding key>].
Explanation: Indicates that the bindingTemplate with the specified key is being deleted.
User Response: None.
CWUDU0027I: Deleting tModel, tModelKey[<tModel key>].
Explanation: Indicates that the tModel with the specified key is being deleted.
User Response: None.
CWUDU0028I: Deleted <entity count> entities.
Explanation: Indicates that the delete function completed, and shows the number of entities
deleted.
User Response: None.
CWUDU0029I: Serializing ...
Explanation: Indicates that generation of the Entity Definition File has started.
User Response: None.
CWUDU0030I: Serialized entities.
Explanation: Indicates that generation of the Entity Definition File completed successfully.
User Response: None.
CWUDU0031I: Deserializing ...
Explanation: Indicates that reading of the Entity Definition File and creation of UDDI entities has
started.
User Response: None.
CWUDU0032I: Deserialized entities.
Explanation: Indicates that reading of the Entity Definition File and creation of UDDI entities
completed successfully.

Chapter 8. Developing WebSphere applications 1285

 User Response: None.
CWUDU0033I: Function ’<function>’ completed successfully.
Explanation: Indicates the requested function completed successfully.
User Response: None.
CWUDU0034W: Function ’<function>’ did not complete successfully. See messages log for further
information.
Explanation: Indicates the requested function did not complete successfully.
User Response: The messages log may yield further information if the verbose option is on.
Check the configuration properties file setting are correct. If that does not identify the problem, try
running with trace logging enabled. If that does not yield a solution, contact your IBM support
center.
CWUDU0035W: Parser error: <warning description>
Explanation: The XML parser reports a warning about the content of the Entity Definition File.
User Response: Based on the context of the warning message, check the validity of the Entity
Definition File.
CWUDU0036E: Parser error <error description>
Explanation: The XML parser reports an error about the content of the Entity Definition File.
User Response: Based on the context of the error message, check the validity of the Entity
Definition File.
CWUDU0037E: Unrecognized parser feature: <feature description>
Explanation: A parser feature set by the UDDI Utility Tools is not recognized by the parser.
User Response: Check you are using the correct type and level of XML parser. If correct, contact
your IBM support center.
CWUDU0038E: Unsupported parser feature: <feature description>
Explanation: A parser feature set by the UDDI Utility Tools is not supported by the parser.
User Response: Check you are using the correct type and level of XML parser. If correct, contact
your IBM support center.
CWUDU0039E: Unrecognized parser property: <property description>, value: <value>
Explanation: A parser property set by the UDDI Utility Tools is not recognized by the parser.
User Response: Check you are using the correct type and level of XML parser. If correct, contact
your IBM support center.
CWUDU0040E: Unsupported parser property: <property description>, value: <value>
Explanation: A parser property set by the UDDI Utility Tools is not supported by the parser.
User Response: Check you are using the correct type and level of XML parser. If correct, contact
your IBM support center.
CWUDU0042E: Unable to find the configuration file: <filepath>
Explanation: UDDI Utility Tools cannot locate the specified configuration file.
User Response: UDDI Utility Tools looks for a default configuration properties with the file name
’UDDIUtilityTools.properties’ in the current directory. Check that the configuration file has this
name, or that the argument value supplied with the ’-properties’ option is pointing at a file that
exists.
CWUDU0043E: An Exception occurred trying to read the configuration file.
Explanation: The configuration file could not be read.
User Response: Check the file path points to a valid file and that the current user has permission
to read the file.
CWUDU0044W: Configuration file is missing the ’<property name>’ property.
Explanation: A required property is missing from the configuration file.
User Response: Add the missing property name and value to the configuration file. Check that
the property name is not misspelled.

1286 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDU0045W: Property: ’<property name>’ has value ’<property value>’. It must be either ’true’ or
’false’.
Explanation: A value was given to a property other than ’true’ or ’false’.
User Response: Set the property value to ’true’ or ’false’.
CWUDU0046W: Property: ’<property name>’ has value ’<property value>’. It must be an integer
value. Explanation: A value was given to a property other than an integer value.
User Response: Set the property value to an integer value.
CWUDU0047E: Unable to find the keyFile file: <keys file path>
Explanation: The keys file could not be located at the specified path.
User Response: Check the file name and path and correct and that the file exists.
CWUDU0048E: Unable to read the keyFile file: <keys file path>
Explanation: The keys file could not be read due to an IO error.
User Response: Check that the current user has permission to read the file.
CWUDU0049E: Unable to write to entity definition file: <entity definition file path>
Explanation: During serialization, the Entity Definition File could not be written to.
User Response: Check the file’s read only attribute is not set.
CWUDU0050E: Unable to find UDDI Entity definition file: <entity definition file path>
Explanation: The Entity Definition File could not be found at the specified file path.
User Response: Check the file path is correct and that the file exists.
CWUDU0051E: Unable to read UDDI Entity definition file: <entity definition file path>
Explanation: The Entity Definition File could not be read due to an IO error.
User Response: Check that the current user has permission to read the file.
CWUDU0052E: Unable to close the message file: <file path>
Explanation: The attempt to close the message log file failed.
User Response: The disk might be full. If so, clear some space or direct log output to a different
disk.
CWUDU0053E: Unable to close the trace file: <file path>
Explanation: The attempt to close the trace log file failed.
User Response: The disk might be full. If so, clear some space or direct log output to a different
disk.
CWUDU0054E: The logger was unable to find the file: <file path>
Explanation: The UDDI Utility Tools logger could not find the specified file.
User Response: None.
CWUDU0055E: ERROR OCCURRED ...
Explanation: General purpose error message used in development only.
User Response: None.
CWUDU0056E: Exception:
Explanation: General purpose message prefix used for reporting exceptions.
User Response: None.
CWUDU0057W: Only one function may be specified on the command line.
Explanation: Multiple function commands were entered on the command line.
User Response: Specify one function in accordance with the usage message.
CWUDU0058W: No function was specified.
Explanation: UDDI Utility Tools was invoked with no function specified.
User Response: Specify one function in accordance with the usage message.
CWUDU0059W: The function: <function> was not recognized.
Explanation: The function value did not match any of the allowed functions.
User Response: Specify one function in accordance with the usage message.

Chapter 8. Developing WebSphere applications 1287

CWUDU0060W: The argument ’<argument>’ was not recognized.
Explanation: The argument value does not match any of the allowed arguments.
User Response: Specify arguments in accordance with the usage message.
CWUDU0061W: There was a missing value for <argument> argument.
Explanation: An expected value for the specified argument was not supplied.
User Response: Specify a value for the argument in accordance with the usage message.
CWUDU0062W: Unexpected argument: <argument> (entity key file is already specified).
Explanation: The entity type argument cannot be specified if the keysFile argument has already
been specified.
User Response: Specify arguments in accordance with the usage message.
CWUDU0063W: Unexpected argument: <argument> (entity key is already specified).
Explanation: The keysFile argument cannot be specified if an entity type argument and key value
has already been specified.
User Response: Specify arguments in accordance with the usage message.
CWUDU0064W: Argument: <argument> cannot be specified more than once.
Explanation: An argument was specified twice in the same command.
User Response: Specify arguments in accordance with the usage message.
CWUDU0065E: No entity keys were specified.
Explanation: A keys file or an entity type and key value must be specified for functions using
keys.
User Response: Specify arguments in accordance with the usage message.
CWUDU0066E: Could not load Database driver: dbDriver<database driver>.
Explanation: The specified database driver could not be loaded.
User Response: Check the database driver value in the configuration file is valid, and the driver’s
class is present in the classpath property.
CWUDU0067E: Could not create Database connection: dbUrl, dbUser, (dbPasswd not shown).
Explanation: A connection could not be established with the database at the specified URL with
the specified userid.
User Response: Check the database URL, userid and password values are correct n the
configuration file, and that the database manager is running.
CWUDU0068E: Could not close the database connection.
Explanation: An attempt to close the database connection failed.
User Response: If the problem persists, contact your IBM support center.
CWUDU0069E: Could not create minimal entity for tModel.
Explanation: The minimal data necessary for a valid tModel could not be inserted in the target
UDDI registry database.
User Response: Check the database URL, userid and password values are correct in the
configuration file, and that the database manager is running.
CWUDU0070E: Could not create minimal entity for Service.
Explanation: The minimal data necessary for a valid businessService could not be inserted in the
target UDDI registry database.
User Response: Check the database URL, userid and password values are correct in the
configuration file, and that the database manager is running.
CWUDU0071E: Could not create minimal entity for Business.
Explanation: The minimal data necessary for a valid businessEntity could not be inserted in the
target UDDI registry database.
User Response: Check the database URL, userid and password values are correct in the
configuration file, and that the database manager is running.

1288 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDU0072E: Could not create minimal entity for Binding.
Explanation: The minimal data necessary for a valid bindingTemplate could not be inserted in the
target UDDI registry database.
User Response: Check the database URL, userid and password values are correct in the
configuration file, and that the database manager is running.
CWUDU0073E: There was an error while trying to create an XML Document.
Explanation: An attempt to create the Entity Definition File failed.
User Response: Check the file path specified in the configuration file for the Entity Definition File
is valid and is not set to be read only.
CWUDU0074E: There was an error parsing the entity definition file.
Explanation: An unspecified error occurred when parsing the Entity Definition File.
User Response: Check the entity definition file content is valid according to the UDDI Utility Tools
schema file, promoter.xsd.
CWUDU0075E: One or more errors occurred while parsing the entity definition file. See message
log for details.
Explanation: Errors occurred when parsing the Entity Definition File.
User Response: Check the entity definition file content is valid according to the UDDI Utility Tools
schema file, promoter.xsd.
CWUDU0076W: One or more warnings were raised while parsing the entity definition file. See
message log for details.
Explanation: Warnings occurred when parsing the Entity Definition File.
User Response: Check the entity definition file content is valid according to the UDDI Utility Tools
schema file, promoter.xsd.
CWUDU0078E: Unable to obtain authinfo.
Explanation: AuthInfo could not be obtained from the UDDI registry with the given userid and
password.
User Response: Check the userid and password property values are correct in the configuration
file.
CWUDU0079E: The inquiryURL is malformed: <inquiry URL>.
Explanation: The inquiry URL specified in the configuration file is not valid.
User Response: Correct the value for the inquiry URLs (fromInquiryURL and toInquiryURL) in the
configuration file.
CWUDU0080E: The publishURL is malformed: <publish URL>
Explanation: The publish URL specified in the configuration file is not valid.
User Response: Correct the value for the publish URL (toPublishURL) in the configuration file.
CWUDU0081E: Could not get tModel detail for tModelKey[<tModel key>].
Explanation: The get tModel operation failed on the source registry.
User Response: Check the key exists in the source registry.
CWUDU0082E: Could not get service detail for serviceKey[<service key>].
Explanation: The get service operation failed on the source registry.
User Response: Check the key exists in the source registry.
CWUDU0083E: Could not get business detail for businessKey[<business key>].
Explanation: The get business operation failed on the source registry.
User Response: Check the key exists in the source registry.
CWUDU0084E: Could not get binding detail for bindingKey[<binding key>].
Explanation: The get binding operation failed on the source registry.
User Response: check the key exists in the source registry.
CWUDU0085E: Could not save tModel for tModelKey[<tModel key>].
Explanation: The publish operation failed at the target registry.

Chapter 8. Developing WebSphere applications 1289

 User Response: Check the tModel is not referencing another entity (such as a tModel) that is not
present in the target registry. This may occur if the ’importReferenced’ property is set to ’false’.
Specify referenced tModels in the referencedtModels section of the Entity Definition File and set
’importReferenced’ property in the configuration file to ’true’.
CWUDU0086E: Could not save business for businessKey[<business key>].
Explanation: The publish operation failed at the target registry.
User Response: Check the businessEntity is not referencing another entity (such as a tModel)
that is not present in the target registry. This may occur if the ’importReferenced’ property is set to
’false’. Specify referenced tModels in the referencedtModels section of the Entity Definition File
and set ’importReferenced’ property in the configuration file to ’true’.
CWUDU0087E: Could not save service for parent businessKey[<business key>].
Explanation: The publish operation failed at the target registry.
User Response: Check the businessEntity specified as the parent of the businessService exists in
the target registry.
CWUDU0088E: Could not save binding for parent serviceKey[<service key>].
Explanation: The publish operation failed at the target registry.
User Response: Check the businessService specified as the parent of the bindingTemplate exists
in the target registry.
CWUDU0089W: Did not save service for serviceKey[<service key>] because parent business did
not exist.
Explanation: The parent business for the specified businessService does not exist.
User Response: Check the key value for the parent entity is correct in the Entity Definition File,
and that the entity exists in the target registry.
CWUDU0090W: Did not save binding for bindingKey[<binding key>] because parent service did not
exist. Explanation: The parent service for the specified bindingTemplate does not exist.
User Response: Check the key value for the parent entity is correct in the Entity Definition File,
and that the entity exists in the target registry.
CWUDU0091E: Could not delete business for businessKey[<businness key>].
Explanation: The UDDI4J operation to delete the businessEntity with the specified key failed.
User Response: Check the userid and password property values in the configuration file and that
the entity exists in the target UDDI registry.
CWUDU00921E: Could not delete service for serviceKey[<tModel key>].
Explanation: The UDDI4J operation to delete the businessService with the specified key failed.
User Response: Check the userid and password property values in the configuration file and that
the entity exists in the target UDDI registry.
CWUDU0093E: Could not delete binding for bindingKey[<binding key>].
Explanation: The UDDI4J operation to delete the bindingTemplate with the specified key failed.
User Response: Check the userid and password property values in the configuration file and that
the entity exists in the target UDDI registry.
CWUDU0094E: Could not delete tModel for tModelKey[<tModel key>].
Explanation: The UDDI4J operation to delete the tModel with the specified key failed.
User Response: Check the userid and password property values in the configuration file and that
the entity exists in the target UDDI registry.
CWUDU0096W: <entity type><key value> is not a valid UUID.
Explanation: The key value entered does not comply with the format specified for a UUID in the
UDDI specification.
User Response: Enter a valid UUID key.
CWUDU0097W: Did not save tModel for tModelKey[<tModel key>] as it already exists. Use the
-overwrite argument to overwrite the tModel.
Explanation: The tModel was not saved because the overwrite property is false

1290 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 User Response: If the desired action is to overwrite existing entities, specify -overwrite on the
command line or set the overwrite property in the configuration file to true.
CWUDU0098W: Did not save business for businessKey[<business key>] as it already exists. Use
the -overwrite argument to overwrite the business.
Explanation: The businessEntity was not saved because the overwrite property is false
User Response: If the desired action is to overwrite existing entities, specify -overwrite on the
command line or set the overwrite property in the configuration file to true.
CWUDU0099W: Did not save service for serviceKey[<service key key>] as it already exists. Use the
-overwrite argument to overwrite the service.
Explanation: The businessService was not saved because the overwrite property is false
User Response: If the desired action is to overwrite existing entities, specify -overwrite on the
command line or set the overwrite property in the configuration file to true.
CWUDU0100W: Did not save binding for bindingKey[<binding key key>] as it already exists. Use
the -overwrite argument to overwrite the binding.
Explanation: The bindingTemplate was not saved because the overwrite property is false
User Response: If the desired action is to overwrite existing entities, specify -overwrite on the
command line or set the overwrite property in the configuration file to true.
CWUDU0101W: Bad entity type: received<entity type>, expected
<tModel|business|service|binding>.
Explanation: The entered entity type was not recognized.
User Response: Specify arguments in accordance with the usage message.
CWUDU0102E: Promotion failed.
Explanation: The promote function failed to complete.
User Response: Check the configuration properties file has correct settings.
CWUDU0106E: Unable to commit transaction.
Explanation: The insertion of minimal entity data during the import function failed to commit to the
database.
User Response: Check the database configuration. If necessary, turn on trace logging and look
for the SQLException that is recorded.
CWUDU0107E: Unable to set auto-commit off on the database connection.
Explanation: UDDI Utility Tools needs to control commits of data changes, however the attempt to
turn off auto-commit failed.
User Response: Check the database configuration. If necessary, turn on trace logging and look
for the SQLExecption that is recorded.
CWUDU0109E: The import function requires a UDDI entity definition file to be specified.
Explanation: A required argument value was not supplied.
User Response: Specify -definition <path to Entity Definition File> on the command line, or set
the value of the UDDIEntityDefinitionFile property in the configuration file to the path to the Entity
Definition File.
CWUDU0110E: A cyclic dependency exists in the referenced tModels. The reference from tModel
with key [<tModel key>] to the tModel with key [<tModel key>] completes the detected cycle.
Explanation: A cycle has been detected such that a tModel is being referenced by a tModel that it
directly or indirectly references. This would cause the UDDI Utility Tools to enter an infinite loop
trying to import referenced tModels, so the process is halted.
User Response: Edit the Entity Definition File and temporarily remove the reference to the tModel
in the cycle, taking a note of the referenced details. After the import has successfully completed,
update the tModel in the target registry to reintroduce the reference you previously removed. This
can be done using the UDDI User Console, UDDI4J, or by creating a new Entity Definition File
with just the tModel to be updated, and running the UDDI Utility Tools with the import function.
CWUDU0112E: An unexpected exception has occurred: <Exception message>.
Explanation: An unexpected error occurred.

Chapter 8. Developing WebSphere applications 1291

 User Response: Check configuration file settings and all registries and databases are active. If
necessary, contact your IBM support center.
CWUDU0113E: Could not get a response from UDDI registry at URL: <URL>.
Explanation: A TransPortException occurred while performing an UDDI4J operation on the UDDI
registry at the specified URL.
User Response: Check configuration properties for the UDDI registry in question and ensure the
UDDI registry is active.
CWUDU0114E: An IOException occurred trying to invoke ’java’.
Explanation: When UDDI Utility Tools was invoked using the java -jar syntax, the invocation of the
second JVM failed.
User Response: Check configuration property ’classpath’ value is correct, and that Java is
configured to run from the command line.
CWUDU0115I: Imported <entity count> entities and <referenced entity count> referenced entities.
Explanation: Indicate that the import step of the import or promote function has completed,
showing the number of entities imported.
User Response: None.
CWUDU0116W: Not all minimal entities could be removed. The following remain in the database:
Explanation: A publish step was not successful which may have left one or more minimal entities
in the target registry database. UDDI Utility Tools attempts to remove these minimal entities but in
this case, the removal has failed. Following messages will indicate which minimal entities are left
in the target registry.
User Response: You can attempt to remove the minimal entities using normal methods, such as
the user console, UDDI4J, or using the delete function of the UDDI Utility Tools.
CWUDU0117W: Business minimal entities with businessKey [<business key>] has not been
removed from the database.
Explanation: A business minimal entity was orphaned in the target registry database and attempts
to remove it failed.
User Response: Identify the orphaned minimal entity in the target and attempt to remove using
normal UDDI delete methods, or by using the delete function of the UDDI Utility Tools.
CWUDU0118W: Service minimal entity with serviceKey [<service key>] has not been removed from
the database.
Explanation: A service minimal entity was orphaned in the target registry database and attempts
to remove it failed.
User Response: Identify the orphaned minimal entity in the target registry and attempt to remove
using normal UDDI delete methods, or by using the delete function of the UDDI Utility Tools.
CWUDU0119W: Binding Template minimal entity with bindingKey [<binding key>] has not been
removed from the database.
Explanation: A binding minimal entity was orphaned in the target registry database and attempts
to remove it failed.
User Response: Identify the orphaned minimal entity in the target registry and attempt to remove
using normal UDDI delete methods, or by using the delete function of the UDDI Utility Tools.
CWUDU0120W: TModel minimal entity with tModelKey [<tModel key>] has not been removed from
the database.
Explanation: A tModel minimal entity was orphaned in the target registry database and attempts
to remove it failed.
User Response: Identify the orphaned minimal entity in the target registry and attempt to remove
using normal UDDI delete methods, or by using the delete function of the UDDI Utility Tools.
CWUDU0121I: Created business minimal entity with businessKey [<business key>].
Explanation: Indicates the minimal data required for a businessEntity has successfully been
inserted in the target UDDI registry database.
User Response: None.

1292 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDU0122I: Created service minimal entity with serviceKey [<service key>].
Explanation: Indicates the minimal data required for a businessService has successfully been
inserted in the target UDDI registry database.
User Response: None.
CWUDU0123I: Created binding template minimal entity with bindingKey [<binding key>].
Explanation: Indicates the minimal data required for a bindingTemplate has successfully been
inserted in the target UDDI registry database.
User Response: None.
CWUDU0124I: Created tModel minimal entity with tModelKey [<tModel key>].
Explanation: Indicates the minimal data required for a tModel has successfully been inserted in
the target UDDI registry database.
User Response: None.
CWUDU0125I: Deleted business minimal entity with businessKey [<business key>].
Explanation: Indicates the minimal data inserted for a businessEntity was successfully removed
from the target UDDI registry database. This would normally happen after a publish operation has
failed.
User Response: None.
CWUDU0126I: Deleted service minimal entity with serviceKey [<service key>].
Explanation: Indicates the minimal data required for a businessService was successfully removed
from the target UDDI registry database. This would normally happen after a publish operation has
failed.
User Response: None.
CWUDU0127I: Deleted binding template minimal entity with bindingKey [<binding key>].
Explanation: Indicates the minimal data required for a bindingTemplate was successfully removed
from the target UDDI registry database. This would normally happen after a publish operation has
failed.
User Response: None.
CWUDU0128I: Deleted tModel minimal entity with tModelKey [<tModel key>].
Explanation: Indicates the minimal data required for a tModel was successfully removed from the
target UDDI registry database. This would normally happen after a publish operation has failed.
User Response: None.
CWUDU0129E: Find related businesses failed.
Explanation: The UDDI4J find related businesses operation did not complete.
User Response: Check the configuration properties for the source registry, such as
fromInquiryURL.
CWUDU0130E: Find businesses failed.
Explanation: The UDDI4J find businesses operation did not complete.
User Response: Check the configuration properties for the source registry, such as
fromInquiryURL.
CWUDU0131E: Find services failed.
Explanation: The UDDI4J find services operation did not complete.
User Response: Check the configuration properties for the source registry, such as
fromInquiryURL.
CWUDU0132E: Find tModels failed.
Explanation: The UDDI4J find tModels operation did not complete.
User Response: Check the configuration properties for the source registry, such as
fromInquiryURL.
CWUDU0133E: Find bindings failed.
Explanation: The UDDI4J find bindings operation did not complete.

Chapter 8. Developing WebSphere applications 1293

 User Response: Check the configuration properties for the source registry, such as
fromInquiryURL.
CWUDU0134I: Performing inquiry request ...
Explanation: Indicated the find operation for selecting keys has started.
User Response: None.
CWUDU0135I: Extracted keys from inquiry results.
Explanation: Indicates the find operation to select keys has completed successfully.
User Response: None
CWUDU0136E: node ID value could not be found in UDDI database.
Explanation: The UDDI registries Node ID could not be found in the UDDI database.
User Response: Check that the UDDI application and database have initialized correctly.
CWUDU0137E: Unexpected database SQL exception: <SQL Exception Message>.
Explanation: An unexpected SQL Exception has been encountered.
User Response: Examine the SQL Exception Message to determine the cause of the problem.
CWUDU0138E: Could not delete minimal entity for tModel with tModelKey[<tModel Key>].
Explanation: The entity with the supplied tModel key could not be located and therefore deleted.
User Response: Ensure tModel key is correct.
CWUDU0139E: Could not delete minimal entity for Service with serviceKey[<Service Key>].
Explanation: The entity with the supplied Service key could not be located and therefore deleted.
User Response: Ensure Service key is correct.
CWUDU0140E: Could not delete minimal entity for Business with businessKey[<Business Key>].
Explanation: The entity with the supplied Business Key could not be located and therefore
deleted.
User Response: Ensure Business key is correct.
CWUDU0141E: Could not delete minimal entity for Binding with bindingKey[<Binding Key>].
Explanation: The entity with the supplied Binding key could not be located and therefore deleted.
User Response:
CWUDU0142E: Invalid sequence number for service: <Sequence Number>.
Explanation: The ServiceStub has an invalid sequence number.
User Response: Ensure the sequence number is greater than zero.
CWUDU0143E: Invalid sequence number for binding: <Sequence Number>.
Explanation: The BindingStub has an invalid sequence number.
User Response: Ensure the sequence number is greater than zero.

CWUDVnnnns (Web Services UDDI Value Set Tools) messages:

CWUDV0001E: Unable to find the properties file: >Property File>.
Explanation: The named property file could not be located.
User Response: Supply the correct location of the property file.
CWUDV0002E: The column and string delimiters must not be the same.
Explanation: The column and string delimiters cannot be the same.
User Response: Supply different characters for the column and string delimiters.
CWUDV0003E: A tModel for key <tModel Key> can not be found.
Explanation: The tModel for the given key cannot be found.
User Response: Supply a correct tModel key.
CWUDV0004E: Invalid command arguments.
Explanation: A command argument has been supplied that is unknown.
User Response: Check your arguments with the Usage information given with this error message.

1294 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDV0005E: Different tModel keys are required when using -newKey.
Explanation: Two unique tModel keys are required to move a Value Set from one tModel to
another.
User Response: Supply two unique tModel keys.
CWUDV0006E: Unable to find the value set data file: <Value Set File>.
Explanation: The named value set file could not be located.
User Response: Supply the correct location of the value set file.
CWUDV0007E: There is an unterminated string on line <Line Number>:<Line>.
Explanation: The line at <Line Number> has a starting string delimiter, but not a finishing one.
User Response: Correct the line, or consider using a different string delimiter (-stringDelimiter)
CWUDV0008E: There were fewer fields than expected on line <Line Number>:<Line>.
Explanation: The line at <Line Number> does not contain enough fields.
User Response: Correct the line, of consider using a different column delimiter
(-columnDelimiter).
CWUDV0009E: There were more fields than expected on line <Line Number>:<Line>.
Explanation: The line at <Line Number> contains too many fields.
User Response: Correct the line, or consider using a different column delimiter
(-columnDelimiter).
CWUDV0010E: There is a duplicate Key Code at the same level on line <Line Number>.
Explanation: The Value Set file contains two or more Key Codes of the sasme value for the same
parent key code.
User Response: Correct the line.
CWUDV0011E: An invalid Parent Key Code has been detected on line <Line Number>.
Explanation: The Value Set file contains a parent key code that is invalid in its context.
User Response: Correct the parent key code.
CWUDV0012E: The value set file contains a value <Column Contents> in column <Column
Number> at line <Line Number> that is too long for the database table.
Explanation: The Value Set file contains a value that is too large.
User Response: Decrease the size of the value.
CWUDV0013E: An IO Exception has occurred: <IO Exception Message>.
Explanation: An IO Exception was received when trying to read the Value Set file.
User Response: Ensure the Value Set file is readable and is in UTF-8 format.
CWUDV0014E: There was a problem reading from the properties file: <IO Exception Message>.
Explanation: An IO Exception was received when trying to read the Value Set file.
User Response: Ensure the Value Set file is readable and is in UTF-8 format.
CWUDV0016E: Unable to find the UDDI JMX MBean. Verify UDDI is installed.
Explanation: The UDDI application could not be contacted.
User Response: Ensure UDDI is installed and running on the Host you have targeted. See
arguments -host, -port, -node and -server.
CWUDV0017E: An unexpected Exception has occurred.
Explanation: An unexpected exception was received.
User Response: Examine the Exception stack trace on its cause. If the problem cannot be
resolver, contact your IBM Customer Service Center.
CWUDV1001W: The tModel with key <tModel Key> is checked. To confirm this operation, enter the
command with the -override argument.
Explanation: The targeted tModel has a ″checked″ status and therefore should not have its value
set changed without care.
User Response: To confirm this operation, enter the command with the -override argument.

Chapter 8. Developing WebSphere applications 1295

CWUDV1002W: The tModel with key <tModel Key> has existing value sets. To confirm this
operation, enter the command with the -override argument.
Explanation: The targeted to be loaded already has a value set.
User Response: To confirm this operation and overwrite the existing value set, enter the
command with the -override argument.
CWUDV1003W: UDDI Registry Message: <Number of Lines> lines of data file for tModel key
<tModel Key>.
Explanation: UDDI Registry message was received.
User Response: Examine the message on its cause. If the problem cannot be resolved, contact
your IBM Customer Service Center.
CWUDV2001I: Loaded <Number of Lines> line of data file for tModel key <tModelKey>.
Explanation: An informational message that confirms the number of value set lines loaded for the
tModel.
User Response:
CWUDV2002I: Changed value set from tModel key <tModel Key> to tModel key <tModel Key>.
Explanation: An informational message that confirms the change of value set from one tModel to
another.
User Response: None.
CWUDV2003I: Unloaded value set for tModel key <tModel Key>.
Explanation: An informational message that confirms the removal of the value set for the tModel.
User Response: None.

CWUDXnnnns (Web Services JAXR) messages:

CWUDX0001E: Caught UDDIException on <UDDI API name>
Explanation: This is an Exception message. This message may be received in a
RegistryException thrown by any of the following methods:
v Any method which necessitates sending a request to the UDDI registry.
The JAXR provider caught a org.uddi4j.UDDIException while sending a request to the UDDI
registry.
User Response: The user should interrogate the cause UDDIException of the JAXRException for
more information.
CWUDX0002E: Caught TransportException sending request to registry
Explanation: This is an Exception message. This message may be received in a
RegistryException thrown by any of the following methods:
v Any method which necessitates sending a request to the UDDI registry.
The JAXR provider caught a org.uddi4j.TransportException while sending a request to the UDDI
registry.
User Response: The user should interrogate the cause TransportException of the JAXRException
for more information.
CWUDX0003E: AccessURI and TargetBinding are mutually exclusive
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v ServiceBinding.setAccessURI(String uri)
v ServiceBinding.setTargetBinding(ServiceBinding binding)
An attempt was made to set both the AccessURI and the TargetBinding of a ServiceBinding.
User Response: The user should set only one of AccessURI and TargetBinding.
CWUDX0004E: Source object of an Association must be an Organization
Explanation: This is an Exception message. This message may be received in an
UnexpectedObjectException thrown by the following method:
v Association.setSourceObject(RegistryObject srcObject)

1296 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 The object passed to the setSourceObject method was not an Organization.
User Response: The user should only pass Organization objects to the setSourceObject method.
CWUDX0005E: Source and target objects of an Association must be set in order to save
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v BusinessLifeCycleManager.confirmAssociation(Association assoc)
v BusinesslifeCycleManager.saveAssociations(Collection associations, boolean replace)
v LifeCycleManager.saveObjects(Collection objects) when objects are Associations
An attempt was made to save an Association that did not have both source and target objects set.
User Response: The user should only attempt to save Associations which have both source and
target objects set.
CWUDX0006E: Target object of an Association must be an Organization
Explanation: This is an Exception message. This message may be received in an
UnexpectedObjectException thrown by the following method:
v Association.setTargetObject(RegistryObject targetObject)
The object passed to the setTargetObject method was not an Organization.
User Response: The user should only pass Organization objects to the setTargetObject method.
CWUDX0007E: Format of associationKey is incorrect. Correct format is
<sourceObjectKey>:<targetObjectKey>:<associationType> : <associationKey>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v BusinessLifeCycleManager.deleteAssociations(Collection associationKeys)
The user passed an associationKey to the deleteAssociations method that did not have the correct
format.
User Response: The user should ensure that associationKeys passed to the deleteAssociations
method have the correct format.
CWUDX0008E: AssociationType Concept must come from the AssociationType enumberation, and
have value either HasChild , HasParent, RelatedTo or EquivalentTo
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v BusinessQueryManager.findAssociations(Collection findQualifiers, String sourceObjectId, String
targetObjectId, Collection associationTypes)
v BusinessQueryManager.findCallerAssociations(Collection findQualifiers, Boolean
confirmedByCaller, Boolean confirmedByOtherParty, Collection associationTypes)
v BusinessLifeCycleManager.confirmAssociation(Association assoc)
v BusinessLifeCycleManager.saveAssociations(Collection associations, boolean replace)
v LifeCycleManager.saveObjects(Collection objects) when objects are Associations
When finding Associations, the user passed a Concept in the associationTypes Collection that was
from the AssociationType enumeration, but did not have a value that is valid for UDDI. When
saving Associations, the user passed an Association whose associationType Concept was from the
AssociationType enumeration, but did not have a value that is valid for UDDI.
User Response: The user should only use Concepts for associationTypes that are from the
AssociationType enumeration and have value either HasChild, HasParent, RelatedTo or
EquivalentTo.
CWUDX0009E: AssocationType Concept must come from the AssociationType enumeration
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v BusinessQueryManager.findAssociations(Collection findQualifiers, String sourceObjectId, String
targetObjectId, Collection associationTypes)
v BusinessQueryManager.findCallerAssociations(Collection findQualifiers, Boolean
confirmedByCaller, Boolean confirmedByOtherParty, Collection associationTypes)

Chapter 8. Developing WebSphere applications 1297

 v BusinessLifeCycleManager.confirmAssociation(Association assoc)
v BusinessLifeCycleManager.saveAssociations(Collection associations, boolean replace)
v LifeCycleManager.saveObjects(Collection objects) when objects are Associations
When finding Associations, the user passed a Concept that was not from the AssociationType
enumeration in the associationTypes Collection. When saving Associations, the user passed an
Association whose associationType Concept was not from the AssociationType enumeration.
User Response: The user should only use Concepts from the AssociationType enumeration for
associationTypes.
CWUDX0010E: Cannot create a ClassificationScheme from a taxonomy Concept
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v LifeCycleManager.createClassificationScheme(Concept concept)
The user passed a taxonomy Concept to the createClassificationScheme method.
User Response: This method is provided to allow for Concepts returned by the
BusinessQueryManager.findConcepts call to be safely converted to ClassificationScheme. It is up
to the programmer to make sure that the Concept is indeed semantically a ClassificationScheme.
CWUDX0011E: Connection is closed
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v All methods of BusinessQueryManager and BusinessLifeCycleManager.
v The saveObjects and deleteObjects methods of LifeCycleManager.
v The saveObjects and deleteObjects methods of LifeCycleManager.
The user called a method that required a connection to the registry after they had closed the
Connection by calling the Connection.close() method.
User Response: The user should not call methods that require a connection to the registry after
the Connection has been closed.
CWUDX0012E: ConnectionFactory properties are not set
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v ConnectionFactory.createConnection()
The createConnection() method was called before the properties had been set on the
ConnectionFactory.
User Response: Ensure that the ConnectionFactory properties have been set before attempting
to create a Connection.
CWUDX0013E: Could not create DocumentBuilder
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by the following method:
v RegistryService.makeRegistrySpecificRequest(String request)
The JAXR provider caught a javax.xml.parsers.ParserConfigurationException while attempting to
initialize the XML parser.
User Response: The user should interrogate the cause ParserConfigurationException of the
JAXRException for more information.
CWUDX0014E: Could not parse XML input stream
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by the following method:
v RegistryService.makeRegistrySpecificRequest(String request)
The JAXR provider caught a java.io.IOException while attempting to parse the XML request.
User Response: The user should interrogate the cause IOException of the JAXRException for
more information.

1298 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
CWUDX0015E: Could not serialize XML response
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by the following method:
v RegistryService.makeRegistrySpecificRequest(String request)
The JAXR provider caught a java.io.IOException while attempting to serialize the XML response.
User Response: The user should interrogate the cause IOException of the JAXRException for
more information.
CWUDX0016E: Interface name of object to create not specified
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v LifeCycleManager.createObject(String interfaceName)
The user passed a null interfaceName to the createObject method.
User Response: The user should ensure they only pass a valid interfaceName to the
createObject method.
CWUDX0017W: Enumeration data file <filename> contains an invalid line: <line>
Explanation: This warning message will go to System.err if the JAXR provider encounters an
invalid line in an enumeration data file while the Connection is initialized. The JAXR provider will
ignore the invalid line. Otherwise the JAXR provider will be unaffected.
User Response: The user should ensure that the enumeration data file is valid in order to use all
members of the enumeration. The correct format of each line is <enumeration name><separator
char><concept value>.
CWUDX0018E: Could not read enumeration data file: <filename>
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by the following method:
v ConnectionFactory.createConnection(
The JAXR provider caught a java.io.IOException while attempting to read an enumeration data file.
User Response: The user should interrogate the cause IOException of the JAXRException for
more information.
CWUDX0019W: enumerationConfig.properties file contains an invalid property value: <property
value>
Explanation: This warning message will go to System.err if the JAXR provider encounters an
invalid property value in the enumerationConfig.properties file while the Connection is initializsed.
The JAXR provider will ignore the invalid property, and hence ignore the corresponding
enumeration. Otherwise the JAXR provider will be unaffected.
User Response: The user should ensure that the enumerationConfig.properties file is valid in
order to use all enumerations. The correct format of each line is <enumeration ID>=<enumeration
name>,<data filename>,<separator char>
CWUDX0020E: An IOException occurred while attempting to read the enumerationConfig.properties
file Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by the following method:
v ConnectionFactory.createConnection()
The JAXR provider caught a java.io.IOException while attempting to read the
enumerationConfig.properties file.
User Response: The user should interrogate the cause IOException of the JAXRException for
more information.
CWUDX0021E: An IOException occurred while attempting to read the taxonomyConfig.properties
file Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by the following method:
v ConnectionFactory.createConnection()

Chapter 8. Developing WebSphere applications 1299

 The JAXR provider caught a java.io.IOException while attempting to read the
taxonomyConfig.properties file.
User Response: The user should interrogate the cause IOException of the JAXRException for
more information.
CWUDX0022E: External URI is malformed: <External URI>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v ExternalLink.setExternalURI(String uri)
A malformed URI was passed to the setExternalURI method when URI validation has set to true
by passing true to the ExternalLink.setValidateURI(boolean validate) method.
User Response: Either the user should ensure that the URI is well formed, or URI validation
should be set to false.
CWUDX0023E: External URI is not accessible: <External URI>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v ExternalLink.setExternalURI(String uri)
An inaccessible URI was passed to the setExternalURI method when URI validation has set to
true by passing true to the ExternalLink.setValidateURI(boolean validate) method.
User Response: Either the user should ensure that the URI is accessible, or URI validation
should be set to false.
CWUDX0024E: Invalid interface name: <interface name>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v LifeCycleManager.createObject(String interfaceName)
The user passed an invalid interface name to the createObject method.
User Response: The user should only pass valid interface names to the createObject method.
Valid interface names are public final static String fields of the LifeCycleManager class.
CWUDX0025E: Cannot change the ClassificationScheme of an internal Classification
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Classification.setClassificationScheme(ClassificationScheme classificationScheme)
The user called the setClassificationScheme method of an internal Classification.
User Response: The user should not attempt to modify the ClassificationScheme of an internal
Classification directly. The ClassificationScheme of an internal Classification is determined by the
Classification’s Concept and cannot be modified independently.
CWUDX0026E: Cannot change the name of an internal Classification
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Classification.setName(InternationalString name
The user called the setName method of an internal Classification.
User Response: The user should not attempt to modify the name of an internal Classification
directly. The name of an internal Classification is determined by the Classification’s Concept and
cannot be modified independently.
CWUDX0027E: Cannot change the value of an internal Classification
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Classification.setValue(String value)
The user called the setValue method of an internal Classification.

1300 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 User Response: The user should not attempt to modify the value of an internal Classification
directly. The value of an internal Classification is determined by the Classification’s Concept and
cannot be modified independently.
CWUDX0028E: The Concept of an internal Classification must have a parent ClassificationScheme
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Classification.setConcept(Concept concept)
The user passed a non-null Concept without a parent ClassificationScheme to the setConcept
method.
User Response: Setting a Classification’s Concept causes a Classification to become internal.
The Classification’s ClassificationScheme is then set to the parent ClassificationScheme of the
Concept. If the Concept has no parent ClassificationScheme (that is, it is not a taxonomy
Concept), that is invalid. The user should therefore only pass taxonomy Concepts to the
setConcept method.
CWUDX0029E: Taxonomy Concepts cannot be saved as UDDI tModels
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v BusinessLifeCycleManager.saveConcepts(Collection concepts)
v LifeCycleManager.saveObjects(Collection objects) when the objects are Concepts.
The user attempted to save a taxonomy Concept as a UDDI tModel in the registry.
User Response: Taxonomy Concepts cannot be saved as tModels in a UDDI registry. They are
used to classify objects saved in the registry but cannot be saved independently. The user should
not attempt to save taxonomy Concepts in the registry.
CWUDX0030E: The parent RegistryObject of a taxonomy Concept must be either a Concept or a
ClassificationScheme
Explanation: This is an Exception message. This message may be received in an
UnexpectedObjectException thrown by any of the following methods:
v LifeCycleManager.createConcept(RegistryObject parent, InternationalString name, String value)
v LifeCycleManager.createConcept(RegistryObject parent, String name, String value)
The user attempted to create a taxonomy Concept whose parent was not a Concept or a
ClassificationScheme.
User Response: The parent of a taxonomy Concept can only be another Concept or a
ClassificationScheme, so the user should only attempt to set one of these as the parent of a
taxonomy Concept.
CWUDX0031E: Concept does not have a parent, therefore does not have a path
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Concept.getPath()
The user called the getPath() method on a Concept that was not a taxonomy Concept. Only
taxonomy Concepts have parents.
User Response: Only taxonomy Concepts have parents, therefore only taxonomy Concepts have
paths. The user should not attempt to call the getPath() method on a Concept that is not a
taxonomy Concept.
CWUDX0032E: Concept does not have a value, therefore does not have a path
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Concept.getPath()
The user called the getPath() method on a Concept that did not have a value.
User Response: A Concept must have a value in order to have a path, so the user should not
attempt to call the getPath() method on Concepts that do not have a value.

Chapter 8. Developing WebSphere applications 1301

CWUDX0033E: Concept’s parent ClassificationScheme does not have an ID, therefore the Concept
does not have a path
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Concept.getPath()
The user called the getPath() method on a Concept whose ClassificationScheme did not have an
ID.
User Response: A Concept’s ClassificationScheme must have an ID in order for the Concept to
have a path. The user should not attempt to call the getPath() method on a Concept whose
ClassificationScheme does not have an ID.
CWUDX0034E: The ConnectionFactory property javax.xml.registry.uddi.maxRows does not contain
a parsable integer:<javax.xml.registry.uddi.maxrows property value>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v ConnectionFactory.createConnection()
The user called the createConnection method when the ConnectionFactory property
javax.xml.registry.uddi.maxRows did not contain a parsable integer.
User Response: The user should ensure that if the javax.xml.registry.uddi.maxRows
ConnectionFactory property is set that it contains a parsable integer.
CWUDX0035E: Invalid UDDI XML String
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by the following method:
v RegistryService.makeRegistrySpecificRequest(String xmlString)
The String passed to the makeRegistrySpecificRequest method was not valid XML.
User Response: The user should ensure that the String passed to the
makeRegistrySpecificRequest method is valid XML.
CWUDX0036E: The ConnectionFactory property javax.xml.registry.lifeCycleManagerURL specifies a
malformed URL
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v ConnectionFactory.createConnection()
The user called the createConnection method when the ConnectionFactory property
javax.xml.registry.lifeCycleManagerURL contained a malformed URL.
User Response: The user should ensure that the javax.xml.registry.lifeCycleManagerURL
ConnectionFactory property contains a well formed URL.
CWUDX0037E: The ConnectionFactory property javax.xml.registry.queryManagerURL specifies a
malformed URL
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v ConnectionFactory.createConnection()
The user called the createConnection method when the ConnectionFactory property
javax.xml.registry.queryManagerURL contained a malformed URL.
User Response: The user should ensure that the javax.xml.registry.queryManagerURL
ConnectionFactory property contains a well formed URL.
CWUDX0038E: Multiple matches on find ClassificationScheme by name
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v BusinessQueryManager.findClassificationSchemeByName(Collection findQualifiers, String
namePattern)
More than one ClassificationScheme was found that matched the search criteria.

1302 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 User Response: The user should narrow their search criteria to find only one
ClassificationScheme.
CWUDX0039E: Invalid objectType: <object type>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v LifeCycleManager.deleteObjects(Collection keys, String objectType)
v QueryManager.getRegistryObjects(String objectType)
v QueryManager.getRegistryObject(String id, String objectType)
v QueryManager.getRegistryObjects(Collection objectKeys, String objectType)
The user passed an invalid objectType to one of the above methods.
User Response: The user should ensure they pass a valid objectType to the above methods. The
valid objectTypes for these methods are:
LifeCycleManager.CLASSIFICATION_SCHEME
LifeCycleManager.CONCEPT
LifeCycleManager.ORGANIZATION
LifeCycleManager.SERVICE
LifeCycleManager.SERVICE_BINDING

The deletObjects method also accepts an objectType of LifeCycleManager.ASSOCIATION.

CWUDX0040E: Cannot save objects of type: <object class>
Explanation: This is an Exception message. This message may be received in an
UnexpectedObjectException thrown by the following method:
v LifeCyclemanager.saveObjects(Collection objects)
An object was passed to the saveObjects method of a type that cannot be saved directly in the
registry.
User Response: The user should ensure that objects passed to the saveObjects method are of a
valid type. Valid types are Association, ClassificationScheme, Concept, Organization, Service and
ServiceBinding.
CWUDX0041E: RegistryObject is a ClassificationScheme not a Concept: <RegistryObject ID>
Explanation: This is an Exception message. This message may be received in a FindException
thrown by any of the following methods:
v QueryManager.getRegistryObject(String id, String objectType)
v QueryManager.getRegistryObjects(Collection objectKeys, String objectType)
An objectType of LifeCycleManager.CONCEPT was passed to one of the above methods, but the
id or one of the objectKeys was that of a ClassificationScheme.
User Response: The user should ensure that they specify the correct objectType corresponding
to the object keys.
CWUDX0042E: RegistryObject is a Concept not a ClassificationScheme: <RegistryObject ID>
Explanation: This is an Exception message. This message may be received in a FindException
thrown by any of the following methods:
v QueryManager.getRegistryObject(String id, String objectType)
v QueryManager.getRegistryObjects(Collection objectKeys, String objectType)
An objectType of LifeCycleManager.CLASSIFICATIONSCHEME was passed to one of the above
methods, but the id or one of the objectKeys was that of a Concept.
User Response: The user should ensure that they specify the correct objectType corresponding
to the object keys.
CWUDX0043E: RequestID not found: <RequestID>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v RegistryService.getBulkResponse(String requestId
The requestId specified was not found.

Chapter 8. Developing WebSphere applications 1303

 User Response: The user should only pass valid requestIds to the getBulkResponse method.
Note that once the getBulkResponse method has been called once for a particular requestId, that
requestId is removed from the cache and subsequent calls to getBulkResponse passing that
requestId will result in an InvalidRequestException.
CWUDX0044E: <concept path> is not a valid path of a concept in a defined internal taxonomy
Explanation: This message will go to System.err when a Connection is created if the
javax.xml.registry.semanticEquivalences ConnectionFactory property defines a semantic
equivalence between a Concept in the PostalAddressAttributes enumeration and a Concept which
has not been defined in any internal taxonomy.
User Response: The user should ensure that the Concept paths used in the
javax.xml.registry.semanticEquivalences ConnectionFactory property have been defined in a
internal taxonomy.
CWUDX0045W: Semantic equivalence pair does not have exactly 2 elements: <keyPair>
Explanation: This message will go to System.err when a Connection is created if the
javax.xml.registry.semanticEquivalences ConnectionFactory contains a keyPair which contains
more than two elements.
User Response: The user should ensure that the javax.xml.registry.semanticEquivalences
ConnectionFactory property has the correct format, as defined in the JAXR specification.
CWUDX0046E: Semantic equivalence pair does not contain a key in the postalAddressAttributes
enumeration: <keyPair>
Explanation: This message will go to System.err when a Connection is created if the
javax.xml.registry.semanticEquivalences ConnectionFactory contains a keyPair which does not
contain the path of a Concept in the PostalAddressAttributes enumeration. Semantic equivalences
for a UDDI JAXR providers are only allowed for Concepts in the PostalAddressAttributes
enumeration.
User Response: The user should only attempt to define semantic equivalences for Concepts in
the PostalAddressAttributes enumeration.
CWUDX0047E: Invalid Slot name: <Slot name>
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v All methods of the ExtensibleObject interface.
The user passed an invalid slot name to one of the methods of the ExtensibleObject interface.
User Response: The user should ensure that the slot name is valid for the particular instance of
ExtensibleObject.
CWUDX0048E: A Slot instance cannot have duplicate values
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v Slot.setValues(Collection values)
The user passed a collection of values to the setValues method that contained duplicate values.
User Response: The user should pass only a collection of unique values to setValues method.
CWUDX0049E: A sortCode Slot must have only 1 value
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v PostalAddress.addSlot(Slot slot)
The user passed a Slot with name Slot.SORT_CODE_SLOT and multiple values to the addSlot
method.
User Response: When adding a Slot with name Slot.SORT_CODE_SLOT to a PostalAddress, the
user should ensure that it only has 1 value.
CWUDX0050E: A specificationLink can only have one ExternalLink
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:

1304 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v SpecificationLink.addExternalLink(ExternalLink externalLink)
v SpecificationLink.addExternalLinks(Collection externalLinks)
v SpecificationLink.setExternalLinks(Collection externalLinks)
The user attempted to give a SpecificationLink more than one ExternalLink. A SpecificationLink
may only have one ExternalLink.
User Response: The user should give a SpecificationLink a maximum of one ExternalLink.
CWUDX0051E: A SpecificationLink can only have one UsageParameter
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v SpecificationLink.setUsageParameters(Collection usageParameters)
The user attempted to give the SpecificationLink more than one usage parameter. A
SpecificationLink can only have one usage parameter.
User Response: The user should give a SpecificationLink a maximum of one usage parameter.
CWUDX0052E: SpecificationObject must be a Concept with no parent
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by any of the following methods:
v SpecificationLink.setSpecificationObject(RegistryObject obj)
The user attempted to set a Concept with a parent (that is, a taxonomy Concept) as the
specification object of the SpecificationLink.
User Response: The user must set a specification Concept as the specification object of a
SpecificationLink.
CWUDX0053E: SpecificationObject must be a Concept
Explanation: This is an Exception message. This message may be received in an
UnexpectedObjectException thrown by the following method:
v SpecificationLink.setSpecificationObject(RegistryObject obj)
The user attempted to set a RegistryObject that was not a Concept as the specification object of a
SpecificationLink.
User Response: The user must set a specification Concept as the specification object of a
SpecificationLink.
CWUDX0054E: Invalid escape sequence found during SQL-92 LIKE Processing: <escape
sequence>
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by any of the following methods:
v BusinessQueryManager.findClassificationSchemeByName(Collection findQualifiers, String
namePattern)
v BusinessQueryManager.findClassificationSchemes(Collection findQualifiers, Collection
namePatterns, Collection classifications, Collection externalLinks)
The user passed a namePattern to one of the above methods which contained an invalid escape
sequence.
User Response: The user should ensure that namePatterns do not contain invalid escape
sequences.
CWUDX0055E: Invalid escape sequence found terminating pattern during SQL-92 LIKE processing:
<escape sequence>
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by any of the following methods:
v BusinessQueryManager.findClassificationSchemeByName(Collection findQualifiers, String
namePattern)
v BusinessQueryManager.findClassificationSchemes(Collection findQualifiers, Collection
namePatterns, Collection classifications, Collection externalLinks)

Chapter 8. Developing WebSphere applications 1305

 The user passed a namePattern to one of the above methods which contained an invalid escape
sequence terminating the pattern.
User Response: The user should ensure that namePatterns do not contain invalid escape
sequences.
CWUDX0056E: The System property http.proxyPort does not contain a parsable integer: <Value of
http.proxyPort property>
Explanation: This is an Exception message. This message may be received in a
java.lang.NumberFormatException thrown by the following method:
v ConnectionFactory.createConnection()
The user called the createConnection() method when the System property http.proxyPort
contained a String that was not parsable as an integer.
User Response: The user should ensure that if the System property http.proxyPort is set it
contains a parsable integer.
CWUDX0057W: Taxonomy data file <filename> contains an invalid line: <invalid line>
Explanation: This message will go to System.err when a Connection is created if a taxonomy
data file contains an invalid line.
User Response: The format of each line is <taxonomy ID><Concept name><Concept
value><Concept parent>
CWUDX0058W: Warning: Unable to locate parentConcept named <parent Concept name> for
concept named <Concept name> in taxonomy datafile <filename>
Explanation: This message will go to System.err when a Connection is created if a taxonomy
data file contains an line for a Concept whose parent cannot be located in that file.
User Response: The user should ensure that a parent exists for each Concept in the taxonomy
data file.
CWUDX0059E: Could not read taxonomy data file: <filename>
Explanation: This is an Exception message. This message may be received in a JAXRException
thrown by any of the following methods:
v ConnectionFactory.createConnection()
The JAXR provider caught a java.io.IOException while attempting to read the taxonomy data file.
User Response: The user should interrogate the cause IOException of the JAXRException for
more information.
CWUDX0060W: taxonomyConfig.properties file contains an invalid property value: <property
value>
Explanation: This warning message will go to System.err if the JAXR provider encounters an
invalid property value in the taxonomyConfig.properties file while the Connection is initialized. The
JAXR provider will ignore the invalid property, and hence ignore the corresponding taxonomy.
Otherwise the JAXR provider will be unaffected.
User Response: The user should ensure that the taxonomyConfig.properties file is valid in order
to use all taxonomies. The correct format of each line is <taxonomy ID>=<tModelKey>,<data
filename>,<separator char>.
CWUDX0061E: Expecting object of type: <objectType String>. Got object of type: <object class>
Explanation: This is an Exception message. This message may be received in an
UnexpectedObjectException thrown by the following method:
v All methods which accept objects of ambiguous type.
The user passed an object to a method that was not expecting an object of that type.
User Response: The user should only pass objects of the appropriate type to JAXR methods.
CWUDX0062E: Expecting object of type String or LocalizedString. Got object of type: <object
class>
Explanation: This is an Exception message. This message may be received in an
UnexpectedObjectException thrown by any of the following methods:
v All query methods which accept a Collection of namePattern objects.

1306 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 The user passed an object which was not a String or a LocalizedString as a namePattern to a
query method.
User Response: The user should only use Strings of LocalizedStrings as namePattern objects.
CWUDX0063E: The ConnectionFactory property javax.xml.registry.queryManagerURL is not
specified
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown by the following method:
v ConnectionFactory.createConnection(
The user attempted to create a Connection without specifying the
javax.xml.registry.queryManagerURL ConnectionFactory property.
User Response: The user must specify the javax.xml.registry.queryManagerURL
ConnectionFactory property before attempting to create a Connection.
CWUDX0064E: Unsupported value for the ConnectionFactory property
Explanation: This is an Exception message. This message may be received in an
InvalidRequestException thrown bythe following method:
v ConnectionFactory.createConnection()
The user attempted to create a Connection with an invalid value of the
javax.xml.registry.security.authenticationMethod ConnectionFactory property.
User Response: The user should only use a valid vale for this property. Valid values are
UDDI_GET_AUTHTOKEN and HTTP_BASIC.

UDDI Registry samples

The UDDI samples, and documentation on how to use them, are available through the Web Services
UDDI samples link on the Samples Central page of the IBM WebSphere Developer Domain Web site.

Removing and reinstalling UDDI Registry

An IBM WebSphere UDDI Registry node consists of a WebSphere application, a store of data (using a
relational database management system - RDBMS) referred to as the UDDI database and a means to
connect the application to the data (a data source and related elements). All the data relating to UDDI is
stored within the UDDI database and therefore exits irrespective of the UDDI application.

With these facts in mind, consider the following options:

v v To remove a node from a WebSphere Application Server the database need not be deleted. Only the
UDDI application and any associated resources such as the data source used (and J2C Authentication
Data if used) need to be removed as the data in the UDDI database is separate from the UDDI
application.
v v It is not necessary to remove the UDDI application to start a new UDDI Registry node. Instead, a new,
replacement node can be created by changing the datasource which the UDDI application uses to
access new UDDI database.

Remove the UDDI application if you no longer want a UDDI facility on a particular WebSphere Application
Server (the UDDI Registry node may subsequently be move to a different WebSphere Application Server).

Reinstall the UDDI application if you wish to continue to provide the UDDI facility on a particular
WebSphere Application Server.

Reinstall the UDDI application if you wish to continue to provide the UDDI facility on a particular
WebSphere Application Server.

To reinstall a UDDI Registry node, see Reinstalling the UDDI application, or to remove a UDDI application
or to remove a UDDI Registry node, see ″Removing a UDDI Node″ in the information center.

Chapter 8. Developing WebSphere applications 1307

Removing a UDDI Registry node
v Remove the UDDI Registry application from an application server.
You might want to do this in order to reinstall the application because it has become corrupted for some
reason, or to apply service. See also the topic on Reinstalling the UDDI Registry application.
v Delete the UDDI Registry database. You might want to do this in order to use a different database
product as the persistence store for your UDDI data, to delete all your UDDI Registry data in order to
publish fresh data (for example, if you have completed a test cycle), or to cause the UDDI Registry
node to re-initialize with new UDDI property settings (for example, to move from a default UDDI node to
a customized UDDI node). Note that deleting a UDDI Registry database will cause all UDDI data for
that UDDI Registry to be lost.
v Completely remove a UDDI Registry node from an application server. You might want to do this in order
to move the UDDI Registry to a different application server, or to remove a UDDI Registry that has been
used for testing.

Depending on what you wish to achieve, complete one of the following steps:
1. Removing a UDDI Registry application
To remove the UDDI application from an application server, run the wsadmin script uddiRemove.jacl,
which was installed into the WAS_HOME\bin directory when you installed WebSphere
At a command prompt enter:
wsadmin -f uddiRemove.jacl
nodename
servername
[default]
> removeuddi.log
where
v nodename and servername are the name of the WebSphere node and application server in which
the UDDI application is deployed (these are the names that you specified when you ran
uddiDeploy.jacl to install the UDDI application).
v [default] is optional. Specifying default will remove the UDDI Cloudscape datasource but not the
UDDI Cloudscape database. This is only applicable if default was used when the uddiDeploy.jacl
script was run to deploy the UDDI Registry, and is only applicable in a standalone application server
environment.
v by default output will go to the screen, but, optionally, you can specify ’> removeuddi.log’ to direct
the output to a log file (where removeuddi.log can be any log name of your choice).
For example:
wsadmin -f uddiRemove.jacl MyNode server1
will remove the UDDI application from server server1 running in node MyNode, and will send any
messages to the screen.

Note: If running in a Network Deployment configuration, the default option cannot be used, and the
command must be executed against the deployment manager profile.
2. Deleting a UDDI Registry database
Note that this will cause all UDDI data in that UDDI Registry to be destroyed.
v For DB2, use the database facilities to delete the UDDI database.
v For Oracle, delete the schemas IBMUDI30 and IBMUDS30.
v For Cloudscape, delete the directory tree containing the UDDI database. By default, this will be
located in WAS_HOME:/profiles/profile_name/databases/com.ibm.uddi/UDDI30.
3. Completely Remove a UDDI Registry node
To completely remove a UDDI Registry node from an application server, you need to remove the UDDI
registry application and database, and also the resources that were used to reference the UDDI
Registry database.
a. Run uddiRemove.jacl as described above, to remove the UDDI Registry application.

1308 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 b. Delete the UDDI Registry database, as described above.
c. This last step is only needed if you ran uddiRemove without the default option (use of the default
option will perform this step for you, but is only valid if the UDDI Registry was previously deployed
using uddiDeploy.jacl with the default option).
v Delete the UDDI datasource that references the UDDI Registry database (this will have been
created when the UDDI Registry was set up), any UDDI JDBC provider that was created (if you
did not reuse an existing JDBC provider), and any J2C Authentication Data Entry that was
created.

Reinstalling the UDDI Registry application

Perform this task if you want to continue providing UDDI services with your existing UDDI database but
require that the UDDI application code be changed.

If you wish to reinstall the UDDI application, follow the instructions below:
1. 1. Execute the following command
wsadmin [-conntype none] –f uddiDeploy.jacl <node> <server>
which will uninstall the UDDI application and install the uddi.ear located in
WAS_HOME/installableApps, resulting in a reinstalled UDDI application.

Note: No JDBC Providers, Data Sources or J2C Application data will be created, changed or deleted
during this process.

Configuring the UDDI Registry Application

The UDDI Registry is supplied as a J2EE application file, uddi.ear.

You can configure the following aspects of the UDDI Registry:

v Configuring security roles
v Multiple language encoding support in UDDI
v Customizing the UDDI User Console (GUI)
v Configuring SOAP API and GUI services
v Configuring WebSphere to use HTTPS and SSL

Configuring UDDI Security Roles

Each interface to the UDDI Registry (either through Version 1 and 2 SOAP, Version 3 SOAP, EJB or the
GUI) is supplied with two roles:
Publish role(s) and custody transfer
mapped to AllAuthenticatedUsers. By default, this is configured to use SSL (that is HTTPS), but
this only applies when WebSphere security is enabled.
Inquiry role
mapped to Everyone. By default, this is configured to use HTTP (that is not SSL).

In addition UDDI Version 3 SOAP has an additional role for version 3 SOAP Custody Transfer, which is
mapped in the same way as the Publish Role.

The security role mappings can be altered by users through the Administration Console.

Authentication uses the standard WebSphere facilities and there is no separate registration function for the
Registry. If WebSphere security is enabled, you will need to supply your WebSphere userid and password
for Publish functions (unless you have changed the supplied Publish role).

Chapter 8. Developing WebSphere applications 1309

You will need to set up WebSphere security configuration to be used by UDDI. It is expected that, for
development use, security will be disabled and security will be enabled for production environments.

The V3 SOAP services also support the use of the V3 Security API set get_authToken and
discard_authToken, but its use is optional, and defined by a combination of UDDI Policy and Security
Roles.
v If security is enabled, and the service’s Role is set to AllAuthenticated Users, WebSphere security takes
priority over UDDI authentication, but if the Publish (or Custody Transfer) Role is mapped to Everyone
and policy is set to require Authorization for publish (or Custody Transfer) (see WebSphere
Administration console (UDDI => UDDI Nodes => UDDI NodeID => Policy Groups => APIs => General
Properties)) then an authToken is required, and the user and password supplied in get_authToken will
be checked by WebSphere.
v If security is disabled, Role Mapping does not apply, and the use of the V3 Security API set is defined
by policy. If the ’Use authInfo if provided’ option is checked (see WebSphere Administrative console
(UDDI => UDDI Nodes => General Properties)) the userid supplied in get_authToken is used (but the
password will not be checked). If ’Use authInfo if provided’ is not checked the default user, set to
UNAUTHENTICATED by default (but configurable, see WebSphere Administrative console (UDDI =>
UDDI Nodes => General Properties => Default user ID)) is used.

The V1/2 SOAP interface also supports the UDDI API for get_authToken and discard_authToken API but
use of this is optional.
v If security is disabled and get_authToken is not called, the default user, UNAUTHENTICATED, is used.
v If security is disabled and get_authToken is called, the specified userid is used (but the password is not
checked).
v If WebSphere security is enabled, it takes priority over UDDI authentication, but if the Publish role is
mapped to Everyone, get_authToken must be used and the userid and password will be checked by
WebSphere.

The Security Roles provided with the UDDI Registry are as follows:
v GUI_Publish_User
v GUI_Inquiry_User
v SOAP_Publish_User
v SOAP_Inquiry_user
v EJB_Inquiry_Role
v EJB_Publish_Role
v V3 SOAP_Inquiry_User_Role
v V3 SOAP_Publish_User_Role
v V3 SOAP_CustodyTransfer_User_Role
v V3 SOAP_Security_User_Role

Multiple language encoding support in UDDI

UDDI API

UDDI Version 3 supports both UTF-8 and UTF-16 encoding. Internally UTF-16 characters are stored as
UTF-8. This is transparent to the user application.

UDDI User Console

The UDDI user console only supports UTF-8 encoding. To enable this, you must configure the application
server into which the UDDI Registry application is installed with UTF-8 encoding enabled. To do this, refer
to ″Configuring application servers for UTF-8 encoding″ elsewhere in the WebSphere Information Center.

1310 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Customizing the UDDI User Console (GUI)
The look and feel of the UDDI console is determined by the styles defined in the .css files which are
located in the /v3gui.war/theme directory of the installed UDDI Registry application directory. The UDDI
Registry application directory will be one of the following, depending on where you have installed the UDDI
Registry:
v If you have installed the UDDI Registry into an application server within a deployment manager cell, the
directory is
WAS_HOME/profiles/installedApps/<currentcell>/UDDIRegistry.<nodename>.<servername>.ear/v3gui.war
v If you have installed the UDDI Registry into a single application server which is not part of a deployment
manager cell, the directory is <WAS_HOME>\profiles\<profile
name>\installedApps\<node_name>\UDDIRegistry.<nodename>.<servername>.ear\v3gui.war under the
installedApps directory of the WebSphere Application Server in which you have installed the UDDI
registry application as shown in the example below.

Style class definitions in these files can be edited to alter the overall theme of the user console, including
font attributes, layout and colors.

Configuring SOAP API and GUI service

Configuring V1/V2 SOAP API services

You can configure the following Version 1 and Version 2 SOAP interface properties:
v defaultPoolSize - the number of SOAP parsers with which to initialize the parser pool for the SOAP
interface. You can set this independently for the Publish (uddipublish) and Inquiry (uddi) APIs. For
example, if you expect more inquiries than publish requests through the SOAP interface, you can set a
larger pool size for the Inquiry API. The default initial size for both APIs is 10.
v Whether the API is to be secure (accessed using HTTPS) or insecure (accessed using HTTP). The
default for Publish is to use HTTPS and Inquiry to use HTTP.

To configure these properties after the UDDI application has been installed:
v Edit the active deployment descriptor (web.xml) for the V1/2 SOAP module (soap.war) . This file is
located in the soap.war\WEB-INF subdirectory of the saved configuration data for the deployed uddi.ear
application. For example:
WAS_HOME\AppServer\profiles\<hostname>Profile01\config\cells\
<hostname>Node01Cell\applications\UDDI V3 Registry\soap.war\WEB-INF\web.xml)
v To modify defaultPoolSize for V1/2 Publish modify the ’param-value‘ element in the servlet with
’servlet-name‘ = uddipublish
v To modify defaultPoolSize for V1/2 Inquiry modify the ’param-value‘ element in the ’servlet‘ with
’servlet-name‘ = uddi
v To modify the user data constraint transport guarantee for V1/2 publish which determines whether the
Publish service is to be confidential (accessed using HTTPS) or insecure (using HTTP) find the
’security-constraint‘ with id = ’UDDIPublishTransportConstraint‘ and set its ’user-data-constraint‘
’transport-guarantee‘ to CONFIDENTIAL or NONE
v Stop and restart the application server for the changes to take effect

Configuring V3 SOAP API services

You can configure the following Version 3 SOAP interface properties:

v Whether the Publish, Custody Transfer, Security and Inquiry API services are to be secure (accessed
using HTTPS ) or insecure (accessed using HTTP). The default for Publish, CustodyTransfer and
Security APIs is to use HTTPS and Inquiry to use HTTP

To configure these properties after the UDDI application has been installed:

Chapter 8. Developing WebSphere applications 1311

v v Edit the active deployment descriptor (web.xml) for the v3 SOAP module (v3soap.war) . This file is
located in the v3soap.war\WEB-INF subdirectory of the saved configuration data for the deployed
uddi.ear application. For example:
WAS_HOME\AppServer\profiles\<hostname>Profile01\config\cells\
<hostname>Node01Cell\applications\UDDI V3 Registry\v3soap.war\WEB-INF\web.xml)
v To modify the user data constraint transport guarantee for V3 publish which determines whether the V3
Publish service is to be confidential (accessed using HTTPS) or insecure (using HTTP) find the
’security-constraint‘ with ’display-name‘ = ’AxisServlet Publish Resource Collection‘ and set its
’user-data-constraint‘ ’transport-guarantee‘ to CONFIDENTIAL or NONE
v To modify the user data constraint transport guarantee for V3 custody transfer which determines
whether the V3 Custody Transfer service is to be confidential (accessed using HTTPS) or insecure (via
HTTP) find the ’security-constraint‘ with ’display-name‘ = ’AxisServlet CustodyTransfer Resource
Collection‘ and set its ’user-data-constraint‘ ’transport-guarantee‘ to CONFIDENTIAL or NONE
v v To modify the user data constraint transport guarantee for V3 security which determines whether the
V3 Security service is to be confidential (accessed using HTTPS) or insecure (via HTTP) find the
’security-constraint‘ with ’display-name‘ = ’AxisServlet Security Resource Collection‘ and set its
’user-data-constraint‘ ’transport-guarantee‘ to CONFIDENTIAL or NONE
v To modify the user data constraint transport guarantee for V3 inquiry which determines whether the V3
Inquiry service is to be confidential (accessed using HTTPS) or insecure (via HTTP) find the
’security-constraint‘ with ’display-name‘ = ’AxisServlet Inquiry Resource Collection‘ and set its
’user-data-constraint‘ ’transport-guarantee‘ to CONFIDENTIAL or NONE
v Stop and restart the application server for the changes to take effect.

Configuring V3 GUI services

You can configure the following Version 3 GUI properties:

v Whether the Publish and Inquiry API services are to be secure (accessed using HTTPS ) or insecure
(accessed using HTTP). The default for Publish, is to use HTTPS and Inquiry to use HTTP

To configure these properties after the UDDI application has been installed:
v Edit the active deployment descriptor (web.xml) for the V3 GUI module (v3gui.war) . This file is located
in the v3gui.war\WEB-INF subdirectory of the saved configuration data for the deployed uddi.ear
application. For example:
WAS_HOME\AppServer\profiles\<hostname>Profile01\config\cells\
<hostname>Node01Cell\applications\UDDI V3 Registry\v3gui.war\WEB-INF\web.xml)
v To modify the user data constraint transport guarantee for V3 publish which determines whether the V3
Publish service is to be confidential (accessed using HTTPS) or insecure (via HTTP) find the
’security-constraint id‘ = ’UDDIPublishSecurityContraint‘ and set its ’user-data-constraint‘
’transport-guarantee‘ to CONFIDENTIAL or NONE
v To modify the user data constraint transport guarantee for V3 inquiry which determines whether the V3
Inquiry service is to be confidential (accessed using HTTPS) or insecure (via HTTP) find the
’security-constraint id‘ =‘ ’UDDIInquireSecurityConstraint‘ and set its ’user-data-constraint‘
’transport-guarantee‘ to CONFIDENTIAL or NONE
v Stop and restart the application server for the changes to take effect

Configuring WebSphere to use HTTPS and SSL

To support the use of secure access with the IBM WebSphere UDDI Registry, you must configure
WebSphere to use HTTPS and SSL. Refer to Secure Sockets Layer settings for custom properties
elsewhere in this Information Center for configuring SSL in WebSphere Application Server. It is assumed
throughout the information for the UDDI Registry that, where SSL is used, it has been configured on port
9443.

1312 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Managing the UDDI Registry
You can use either the WebSphere Application Server administrative console or the Java Management
Extensions (JMX) management interface to manage UDDI Registries.

In previous version of WebSphere Application Server and UDDI a properties file was used, but from
WebSphere Application Server Version 6, all policies and properties are managed through either the JMX
management interface or the administrative console.

JMX can be used to programmatically monitor and configure UDDI registries, and is explained in ″Using
administrative programs (JMX)″ in the information center. See IBM WebSphere Registry Administrative
Interface for full details on using the UDDI administrative interface. To manage UDDI registries using the
WebSphere Application Server administrative console, start from the UDDI link in the left navigation pane
as described below.

Using the UDDI management functions available in the WebSphere Application Server administrative
console, you can perform the following operations:
v view and manage the status of all UDDI nodes in a cell
v initialize UDDI nodes with required settings
v configure general properties that affect UDDI runtime behavior
v manage UDDI policy settings
v create, view and update UDDI publishers
v create, view and update publisher tiers which limit how many UDDI entries may be published
v view and manage the status of value sets

UDDI node collection

To configure node properties, policies, value set status and user entitlements, complete the following
steps:

From the administrative console, expand UDDI in the navigation pane then click UDDI Nodes. This
displays the collection of UDDI nodes in the cell.

Each UDDI node is represented by a UDDI Node ID, Description, UDDI Application Name and Status. The
Status can be either Initialization Pending, Activated or Deactivated. To activate UDDI nodes that are
Deactivated, select them by checking the corresponding check boxes in the Select column and click the
Activate button. Similarly to deactivate UDDI nodes, select them and click the Deactivate button.

To manage an individual UDDI node, click on its UDDI Node ID link. This takes you to the Configuration
page where you can manage its general properties, initialize it if the status is set to Initialization Pending,
and access pages for managing policies, UDDI publishers, tiers and value sets. Refer to UDDI node
settings for details on the next available topic.

Important: To be able to manage a UDDI node, the associated UDDI application must be running. If the
application is not running you will not see the UDDI node in the list of available choices.

UDDI node settings:

This topic contains details of the general properties that you can configure for a UDDI node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id.

By clicking on a node in the UDDI node ID column the UDDI node detail page is displayed. The UDDI
node detail page displays a set of General Properties for the UDDI node, some of which may be editable

Chapter 8. Developing WebSphere applications 1313

depending on the state of the node. There are also links to Additional Properties (Value sets, Tiers and
UDDI Publishers) and links to Policy Groups where UDDI node policy may be viewed and changed.

Unless the UDDI node has been installed as a default UDDI node (as defined in ″UDDI Registry
terminology″ in the information center) there are some important general properties that need to be set
before the UDDI node can be initialized. These properties are all marked as being required (indicated by
the presence of a ’*’ next to the input field). You may set the values as many times as you wish before
initialization. However, once the UDDI node has been initialized, these properties will become read only for
the lifetime of that UDDI node. It is very important to set these properties correctly. Other general
properties of the UDDI node may be set before, and after, initialization.

Once the general properties have been set to appropriate values, you can click OK (which saves your
changes and exits the page), or Apply (which saves your changes and leaves you on the same page). At
this point the changes will have been stored.

If the UDDI node is in the Not Initialized state, indicated on the UDDI node detail page by the presence of
an Initialize button (above the General Properties section), the UDDI node can be initialized by clicking the
Initialize button. This operation may take a while to complete. It is important to remember to save any
changes you have made to the general properties by clicking Apply or OK before the Initialize button is
pressed.

The other UDDI settings that a UDDI administrator can manage are shown to the right of the screen and
are described in the following topics:
v Value set collection
This topic contains details of the value sets settings that you can configure for a UDDI node.
v Tier collection
This topic contains details of the UDDI publisher tiers that you can configure for a UDDI node.
v UDDI Publisher collection
This topic contains details of the publishers that have been registered with the UDDI node.
v Policy groups
This topic contains links to the detailed settings information for every policy group that you can
configure for a UDDI node.

UDDI Node ID:

The unique identifier given to a UDDI node in a UDDI registry. This must be a valid UDDI key.

The value for the node ID will also be the domain key for this UDDI node.

Required Yes
Data type String
Default A valid domain key for this UDDI node

UDDI node description:

The user supplied description of this UDDI node.

Required Yes
Data type String

Root key generator:

Specifies the root key space of the registry.

1314 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Registries intending to become affiliate registries may want to specify a root key space in a partition below
the root key generator of the parent root registry, for example, uddi:thisregistry.com:keygenerator.

Required Yes
Data type String
Default uddi:default:keygenerator

Prefix for generated discoveryURLs:

The URL prefix for the GET servlet.

The URL prefix applied to generated discoveryURLs in businessEntity elements so they can be returned
on HTTP GET requests. The format is ’http://hostname:port/uddisoap/’, where ’uddisoap’ is the UDDI
version 2 SOAP servlet’s context root. This property applies to UDDI version 2 API requests only.

Required Yes
Data type String
Default http://localhost:9080/uddisoap

Maximum inquiry result set size:

The maximum size of result set which the registry will process for an inquiry API request. If the result set
exceeds this value, an E_resultSetTooLarge error is returned to the user. Setting the value higher allows
larger result sets but may cause increased response times.

Note: If this value is set too low users will get an E_resultSetTooLarge error message, whereas setting to
too high might cause increased response times. If the value is set too low and users use imprecise
search criteria the likelihood of receiving the E_resultSetTooLarge is increased.

Data type Integer

Default 500
Range 0 to 1024

Maximum inquiry response set size:

For inquiry API requests, this value controls the maximum number of results returned in each response. If
the number of results in the result set is greater than this value, the response will only include a subset of
results. The user can retrieve remaining results using the listDescription feature as described in the UDDI
specification. Setting this value too low will require the user to make more requests to retrieve the
remainder of the result set.

Note: This value can not be higher than the value set for ″Maximum inquiry results″. Setting this value too
low increases the number of requests needed to achieve the full result set.

Data type Integer

Default 500
Range 0 to 1024

Maximum search names:

The maximum number of names that can be supplied in an inquiry API request. Increasing this value can
significantly slow response times of the UDDI node.

Chapter 8. Developing WebSphere applications 1315

This can be used to control the complexity of requests that this UDDI node will allow. The recommendation
is to not set this value above 8.

Data type Integer

Default 5
Range 1 to 64

Maximum search keys:

The maximum number of keys that can be supplied in an inquiry API request. This limits the number of
references that can be specified in categoryBag, identifierBag, tModelBag and discoveryURLs. Increasing
this value can significantly increase response times for the UDDI node.

This can be used to control the complexity of requests that this UDDI node will allow. The recommended
setting for this is 5 or less.

In exceptional cases, the UDDI node may reject complex requests with excessive numbers of keys even if
the value of maxSearchKeys is not exceeded.

Data type Integer

Default 5
Range 1 to 64

Key space requests require digital signature:

Specifies whether tModel:keyGenerator requests must be digitally signed.

Use tier limits:

Specifies whether an approval manager is used to check publication tier limits.

If set to false, the number of UDDI entities that can be published is unlimited.

Use authInfo credentials if provided:

Specifies if authInfo contents in UDDI API requests are used to validate users when WebSphere global
security is off. If this setting is true, the UDDI node will use the request’s authInfo element, otherwise the
default user name is used.

Data type Integer

Default True

Authentication token expiry period:

The period after which authentication tokens are invalidated (in minutes), and a new authToken is required.

Note: The setting should be sufficient to ensure operational success. Longer settings can increase the
risk of illegal authToken use.

Data type Integer

Default 30
Range 1 to 10080 (minutes - 1 week)

Automatically register UDDI publishers:

1316 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies if UDDI publishers are automatically registered, and assigned to the default tier.

Automatically registered UDDI publishers are given default entitlements.

Default user name:

Specifies the user name used for publish operations when WebSphere security is disabled.

Data type String

Default UNAUTHENTICATED

Default language code:

Applies only to UDDI Version 1 and Version 2 requests, the default language code to be used for xml:lang
when not otherwise specified.

Data type String

Default en

Value set collection:

Use this page to view and configure the value sets that have been installed in a UDDI node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >Value Sets.

Value sets in a UDDI node are either supported or not supported by policy. Value sets in a UDDI node are
either supported or not supported by policy. By default, new value sets are not supported. When you have
published a value set tModel and loaded value set data, you can control whether other UDDI entities can
reference this value set tModel by setting the Supported policy.

To enable support for one or more value sets, select the value sets by clicking on the appropriate check
boxes in the Select column. Click the Enable Support button. The supported field for all the selected value
sets will be updated to reflect the new status.

To disable support for a value set, which may be necessary before it is removed from the UDDI node,
select the value sets in the same manner as for enabling support. Click the Disable Support button.

Clicking on a value set name in the list takes you to the general properties page for that value set as
described in Value set settings.

Name:

The name of the tModel that represents the value set.

tModelkey:

The key for the tModel that represents the value set.

Supported:

Indicates whether references to this value set are supported by policy in this UDDI node.

Value set settings:

Use this page to view the attributes of a value set in a UDDI node.

Chapter 8. Developing WebSphere applications 1317

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >Value Sets >
value_set_name.

This page shows the values of keyedReferences in the tModel that represents this value set. It also shows
the Supported status of the value set as described on the Value set collection page. All properties are
read-only. The Supported status can be changed on the Value Set page.

Unvalidatable:

Specifies whether this value set is unvalidatable. This is set by the value set tModel publisher to indicate if
the value set is available or not for use by publish requests.

Checked:

Specifies whether this value set is checked. If set to true, UDDI entities that reference this value set will be
validated to ensure their values are present in this value set.

Cached:

Specifies whether this value set is cached in this UDDI node.

Externally cacheable:

Specifies whether this value set is externally cacheable.

Externally validated:

Specifies whether this value set is externally validated.

Supported:

Specifies whether this value set is supported by policy in this UDDI node.

Last cached:

Specifies the date when this value set was last cached in the UDDI node.

Tier collection:

This topic contains a list of the available tiers for the UDDI node. You can also create new tiers and delete
tiers from this page.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >Tiers.

This page shows the available tiers for the UDDI node. Clicking a tier name will show the General
Properties for the specific tier as detailed in Tier settings. To delete a Tier from the list, select the relevant
name and click Delete. Clicking New will take you to the General Properties page with the same properties
as described in Tier settings.

One of the tiers in the collection will be marked as the default tier, indicated by (default) appearing next to
the tier’s name. The default tier will be assigned to UDDI publishers that are registered automatically when
automatic user registration is turned on. To set the default tier, select the appropriate tier in the collection
and press the Set default button. Note that it is not possible to delete a tier if it is currently marked as the
default tier, or it is currently assigned to a UDDI publisher.

Name:

1318 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The name of the tier.

Description:

User supplied descriptive text about the tier.

UDDI Tier settings:

This topic contains details of the general properties that you can configure for a UDDI publisher tier.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >Tiers > tier_name.

Name:

The name of the tier.

Required Yes
Data type String
Range 1 to 255

Description:

The user supplied description of the tier.

Data type String

Default Empty
Range 0 to 255

Maximum businesses:

The maximum number of businesses that UDDI publishers in this tier are allowed to publish in this tier.

Maximum services:

The maximum number of services UDDI publishers in this tier are allowed to publish.

Maximum bindings:

The maximum number of bindings UDDI publishers in this tier are allowed to publish.

Maximum tModels:

The maximum number of tModels UDDI publishers in this tier are allowed to publish.

Maximum publisher assertions:

The maximum number of publisher assertions UDDI publishers in this tier are allowed to add.

For each of the maximum fields described above, the data is:

Required Yes
Data type Integer
Default 0
Range 0 to 2147483647 (for all intents and purposes, unlimited)

Chapter 8. Developing WebSphere applications 1319

UDDI Publisher collection:

This page shows the WebSphere users that are currently registered as UDDI publishers.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >UDDI Publishers.

To create a UDDI publisher click on the New button. This opens the UDDI publisher settings page where
details about the publisher can be entered.

It is possible to assign multiple publishers to a tier without having to edit each one individually. To do this
select the appropriate publishers in the collection table. From the selection box at the top of the collection
table choose from one of the tiers available on the UDDI node. Finally, click the Assign tier button to
update the selected publishers.

To delete publishers select them in the collection table and then press the Delete button.

After the users have been registered as UDDI publishers, their entitlements can be edited as described in
UDDI Publisher settings.

User name:

The name of the UDDI publisher.

Tier:

The publication limits tier to which the UDDI publisher has been assigned.

Create UDDI Publishers:

Use this page to register existing WebSphere Application Server users as UDDI publishers. Create each
UDDI publisher individually using the New button on the UDDI publisher collection page.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >UDDI Publishers →
New.

Users known to the application server can be registered as UDDI publishers.

Assign entitlements and a tier to the selected group

UDDI publishers are given permission to perform specific actions with entitlements. Set the entitlements for
the selected UDDI publishers with the check-box next to each entitlement.

After the users have been registered as UDDI publishers, their entitlements can be edited as described in
UDDI Publisher settings.

User name:

The name of the UDDI publisher to be created. This should be a user known to the application server.

Allowed to publish keyGenerator:

The UDDI publisher has permission to publish tModel:keyGenerator.

If false, UDDI publishers cannot publish keyGenerators of any kind. In this situation all the entitlement
settings are disregarded, irrespective of how they are set.

1320 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Allowed to publish keyGenerator with a domain key:

The UDDI publisher has permission to publish tModel:keyGenerator with a domain key.

Allowed to publish keyGenerator with a derived key:

The UDDI publisher has permission to publish tModel:keyGenerator with a derived key.

The tModel:keyGenerator is a request for key space. An example of a legal derived key is
uddi:tempuri.com:fish:buyingService where the key is based on the derivedKey ″uddi:tempuri.com:fish″. the
string ’buyingService’ is the key’s key specific string (KSS).

Allowed to publish keyGenerator with UUID keys:

The UDDI publisher user has permission to publish tModel:keyGenerator providing a UUID key.

Allowed to publish with UUID key:

The UDDI publisher has permission to publish elements providing a UUID key.

Allowed to subscribe:

The UDDI publisher can register requests to receive notifications of specific registry content changes.

Tier:

The tier to which the selected UDDI publishers are assigned.

UDDI Publisher settings:

Use this page to view and edit the properties of UDDI publishers.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >UDDI Publishers >
user_name.

This page shows the entitlements and publication limits tier for a particular UDDI publisher.

Allowed to publish keyGenerator:

The UDDI publisher has permission to publish tModel:keyGenerator.

If false, UDDI publishers cannot publish keyGenerators of any kind. In this situation the following
permissions (’Allowed to publish keyGenerator with a domain key’, ’Allowed to publish keyGenerator with a
derived key’, ’Allowed to publish keyGenerator with UUID keys’, ’Allowed to publish with UUID keys’ and
’Allowed to subscribe’) will be disregarded irrespective of how they are set.

Allowed to publish keyGenerator with a domain key:

The UDDI publisher has permission to publish tModel:keyGenerator with a domain key.

Allowed to publish keyGenerator with a derived key:

The UDDI publisher has permission to publish tModel:keyGenerator with a derived key.

The tModel:keyGenerator is a request for key space. An example of a legal derived key is
uddi:tempuri.com:fish:buyingService where the key is based on the derivedKey ″uddi:tempuri.com:fish″. the
string ’buyingService’ is the key’s key specific string (KSS).

Chapter 8. Developing WebSphere applications 1321

Allowed to publish keyGenerator with UUID keys:

The UDDI publisher user has permission to publish tModel:keyGenerator providing a UUID key.

Allowed to publish with UUID key:

The UDDI publisher has permission to publish elements providing a UUID key.

Allowed to subscribe:

The UDDI publisher can register requests to receive notifications of specific registry content changes.

Tier:

The tier to which the UDDI publisher is assigned.

Policy groups:

This topic contains links to the detailed settings information for every policy group that you can configure
for a UDDI Registry node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id.

To the right of the page is a list of the Policy Groups that can be acted upon. Clicking on a specific group
will open the page for the group required.

The policy groups available to act upon are:

v “UDDI keying policy settings”
v “UDDI user policy settings”
v “UDDI node API policy settings” on page 1323
v “UDDI data custody policy settings” on page 1323
v “UDDI value set policy” on page 1324
v “UDDI node miscellaneous” on page 1324

UDDI keying policy settings:

This topic contains details of the UDDI keying settings that you can configure for a UDDI Registry.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >UDDI Keying.

Registry key generation:

Allows publishers to publish key generator tModels.

Defines whether a given UDDI node or publisher is allowed to register a key generator tModel. When true,
this allows the set of publishers to be managed using the facilities provided in the UDDI Publisher settings

Registry support of UUID keys:

Allow publisher supplied uuidKeys in publish requests.

If true, this allows the set of publishers to be managed using the facilities provided in UDDI Publisher
settings

UDDI user policy settings:

1322 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This topic contains details of the user policy settings that you can configure for a UDDI Registry node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >User policies.

Allow transfer of ownership:

When true, data ownership can be transferred between owners within the UDDI node.

UDDI node API policy settings:

This topic contains details of the API settings that you can configure for a UDDI Registry node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id > APIs.

Authorization for inquiry:

Specifies if authorization using the authInfo element is required for inquiry API requests.

Typically, UDDI registries are configured not to require authorization for registry API requests. This setting
is only relevant if the V3SOAP_Inquiry_User_Role is set to everyone and WebSphere Application Server
global security is on. If WebSphere Application Server global security is off, this setting is ignored. If
WebSphere Application Server global security is on and the V3SOAP_Inquiry_User_role is not set to
everyone, this setting is ignored.

Authorization for publish:

Specifies if authorization using the authInfo element is required for publish API requests.

Typically, UDDI registries are configured not to require authorization for registry API requests. This setting
is only relevant if the V3SOAP_Publish_User_Role is set to everyone and WebSphere Application Server
global security is on. If WebSphere Application Server global security is off, this setting is ignored. If
WebSphere Application Server global security is on and the V3SOAP_Publish_User_role is not set to
everyone, this setting is ignored.

Authorization for custody transfer:

Specifies if authorization using the authInfo element is required for custody transfer API requests.

Typically, UDDI registries are configured not to require authorization for registry API requests. This setting
is only relevant if the V3SOAP_CustodyTransfer_User_Role is set to everyone and WebSphere Application
Server global security is on. If WebSphere Application Server global security is off, this setting is ignored.
If WebSphere Application Server global security is on and the V3SOAP_CustodyTransfer_User_role is not
set to everyone, this setting is ignored.

UDDI data custody policy settings:

This topic contains details of the data custody settings that you can configure for a UDDI Registry node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >Data custody.

Transfer token expiration period:

The length of time (in minutes) after the issue of a transfer token before it expires.

Chapter 8. Developing WebSphere applications 1323

Note: Setting too large a value might expose the UDDI registry to a risk of misuse.

Data type Integer

Default 1440
Range 1 to 2147483647 (for all intents and purposes, unlimited)

UDDI value set policy:

This topic contains details of the value set policy settings that you can configure for a UDDI Registry node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id >Value Set Policy.

Enable checked value sets:

Specifies if checked value sets are supported. When false, publish requests containing references to
checked value sets are be rejected.

UDDI node miscellaneous:

This topic contains details of the miscellaneous settings that you can configure for a UDDI node.

To view this administrative console page, click UDDI → UDDI Nodes > UDDI_node_id > Miscellaneous.

Node generates discoveryURLs:

Defines whether the UDDI node generates discoveryURLs.

Node supports HTTP Get Service:

Specifies if the UDDI node supports an HTTP GET service for access to the XML representations of UDDI
data structures.

URL prefix for V3 GET servlet:

The URL prefix for the UDDI version 3 GET servlet

The prefix for the URL to the GET servlet used to retrieve the XML representation of a published entity.
When a businessEntity is published, if the policy for Node Discovery URLs is set to true, the discoveryURL
value is generated based on the prefix value. Otherwise, the discoveryURL value will be empty.

The UDDI Version 3 specification recommends that discoveryURLs are not generated as they can affect
the use of digital signatures. If you do enable generation of discoveryURLs, it is recommended that the
URL prefix is not changed after the point at which the policy to enable generation of discoveryURLs is
enabled. Not doing so will mean discoveryURLs generated using the earlier URL prefix would no longer
work.

Data type URL

Default http://localhost:9080/uddiv3soap/

UDDI Registry Administrative Interface Overview

The UDDI Registry Administrative Interface allows you to inspect and manage the runtime configuration of
a UDDI application. This includes managing the the information and the activation state about a UDDI
node, updating properties and policies, setting publish tier limits, registration of UDDI publishers, and
controlling value set support. The operations of the UDDI Registry Administrative Interface can be read
and invoked using standard JMX (Java Management Extensions) interfaces.

1324 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The use of JMX is explained in ″Using administrative programs (JMX)″ in the information center. See the
IBM WebSphere UDDI Registry Administrative Interface for full details on using the UDDI administrative
interface.

Backing up and restoring the UDDI Registry database

If you want to protect the data in your UDDI Registry database, you can back up and restore the database
using the facilities of the database product your UDDI node is on.

Cloudscape

To back-up a Cloudscape based registry, ensure that the UDDI application is stopped (and hence, not
accessing the Cloudscape database), and ensure that no other application is using the Cloudscape
UDDI30 database, then make a copy of the UDDI30 directory using the file system that the directory
resides upon.

Non-Cloudscape

Use the appropriate import and export tools for the database being used to contain the UDDI Registry.
v Backup
Include elements in schemas named IBMUDI30 and IBMUDS30
v Restore
For restoration we recommend deleting the schemas IBMUDI30 and IBMUDS30, recreating database
structures using the original scripts - with slight modifications - and importing the previously saved data,
as described in the steps below:
1. Delete the schemas IBMUDI30 and IBMUDS30 this will result in any IBM UDDI structures being
destroyed.
2. Create database structures (for DB2 see Creating a DB2 database, for Oracle see Creating an
Oracle database or, for Cloudscape, see Creating a Cloudscape database for details) as per the
original creation except that the final step (xxxxxx_70xxxx.*) must not be run this will result in a
virgin, and almost empty, database into which your backed-up data may be imported.
3. Delete all rows in the table IBMUDS30.UDDIDBSCHEMAVER to avoid a clash between a row
inserted by the scripts and the row backed-up using the command:
delete from IBMUDS30.UDDIDBSCHEMAVER
4. Restore the previously backed-up data in schemas IBMUDI30 and IBMUDS30

Data access resources

Task overview: Accessing data from applications

Various enterprise information systems (EIS) use different methods for storing data. These backend data
stores might be relational databases, procedural transaction programs, or object-oriented databases. IBM
WebSphere Application Server provides several options for accessing an information system’s backend
data store:
v Programming directly to the database through the JDBC 2.0 optional package API or the JDBC 3.0 API.
v Programming to the procedural backend transaction through various J2EE Connector Architecture (JCA)
1.0 or 1.5 compliant connectors.
v Programming in the bean-managed persistence (BMP) bean or servlets indirectly accessing the
backend store through either the JDBC API or JCA compliant connectors.
v Using container-managed persistence (CMP) beans.
v Using embedded Structured Query Language in Java (SQLJ) support with applications that use DB2 as
a backend database.

Chapter 8. Developing WebSphere applications 1325

v Using the IBM data access beans, which also use the JDBC API, but give you a rich set of features and
function that hide much of the complexity associated with accessing relational databases.

For all of these options, except for using the JCA 1.0 or 1.5 compliant connectors, the prerequisite Web
site details which databases and drivers are currently supported. See ″Hardware and software
requirements″ in the information center for more information.
1. Develop data access applications. Develop your application to access data using the various ways
available through the WebSphere Application Server. You can access data through APIs,
container-managed persistence beans, bean-managed persistence beans, session beans, or Web
components.
2. Assemble data access applications using the assembly tool. Assemble your application by creating and
mapping resource references.
3. Prepare for deployment: Ensure that the appropriate database objects are available. Create or
configure any databases or tables required, set necessary configuration parameters to handle
expected load, and configure any necessary JDBC providers and data source objects for servlets,
enterprise beans, and client applications to use.
4. Install the application on your application server.

Resource adapter
A resource adapter is a system-level software driver that a Java application uses to connect to an
enterprise information system (EIS).

A resource adapter plugs into an application server and provides connectivity between the EIS, the
application server, and the enterprise application.

An application server vendor extends its system once to support the J2EE Connector Architecture (JCA)
and is then assured of seamless connectivity to multiple EISs. Likewise, an EIS vendor provides one
standard resource adapter with the capability to plug into any application server that supports the
connector architecture.

WebSphere Application Server provides the WebSphere Relational Resource Adapter (RRA)
implementation. This resource adapter provides data access through JDBC calls to access the database
dynamically. The connection management is based on the JCA connection management architecture. It
provides connection pooling, transaction, and security support. WebSphere Application Server version 6.0
supports JCA versions 1.0 and 1.5.

Data access for container-managed persistence (CMP) beans is managed by the WebSphere Persistence
Manager indirectly. The JCA specification supports persistence manager delegation of the data access to
the JCA resource adapter without knowing the specific backend store. For the relational database access,
the persistence manager uses the relational resource adapter to access the data from the database. You
can find the supported database platforms for the JDBC API at the WebSphere Application Server
prerequisite Web site.

J2EE Connector Architecture resource adapters:

A J2EE Connector Architecture (JCA) resource adapter is any resource adapter conforming to the JCA
Specification.

The product supports any resource adapter that implements version 1.0 or 1.5 of this specification. IBM
supplies resource adapters for many enterprise systems separately from the WebSphere Application
Server package, including (but not limited to): the Customer Information Control System (CICS), Host
On-Demand (HOD), Information Management System (IMS), and Systems, Applications, and Products
(SAP) R/3 .

1326 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The general approach to writing an application that uses a JCA resource adapter is to develop EJB
session beans or services with tools such as Rational Application Developer. The session bean uses the
javax.resource.cci interfaces to communicate with an enterprise information system through the resource
adapter.

WebSphere relational resource adapter settings:

Use this page to view the default WebSphere relational resource adapter settings.

This is the WebSphere-provided relational resource adapter for handling data access to any relational data
base. This adapter is preinstalled by WebSphere Application Server. Although the default relational
resource adapter settings are viewable, you cannot make changes to them.

To view this administrative console page, click Resources > Resource Adapters > WebSphere
Relational Resource Adapter.

Name:

Specifies the name of the resource provider.

Data type String

Description:

Specifies a description of the relational resource adapter.

Data type String

Archive path:

Specifies the path to the Resource Adapter Archive (RAR) file containing the module for this resource
adapter.

Data type String

Class path:

Specifies a list of paths or Java Archive (JAR) file names, which together form the location for the resource
provider classes.

Data type String

Native path:

Specifies a list of paths that forms the location for the resource provider native libraries.

Data type String

WebSphere Relational Resource Adapter:

The WebSphere Relational Resource Adapter (RRA) provides enterprise applications deployed on
WebSphere Application Server access to relational databases.

Chapter 8. Developing WebSphere applications 1327

The WebSphere RRA is installed and runs as part of WebSphere Application Server, and needs no further
administration.

The RRA supports both the configuration and use of JDBC data sources and J2EE Connection
Architecture (JCA) connection factories. The RRA supports the configuration and use of data sources
implemented as either JDBC data sources or J2EE Connector Architecture connection factories. Data
sources can be used directly by applications, or they can be configured for use by container-managed
persistence (CMP) entity beans.

For more information about the WebSphere Relational Resource Adapter, see the following topics:
v For information about resource adapters, see “Resource adapter” on page 1326
v For information about resource adapters and data access, see “Data access portability features”
v For RRA settings, see “WebSphere relational resource adapter settings” on page 1327
v For information about CMP connection factories, see “Connection factory” on page 1332
v For information about enterprise beans, see ″Introduction: EJB applications″ in the information center

Data access portability features: The WebSphere Application Server relational resource adapter (RRA)
provides a portability feature that enables applications to access data from different databases without
changing the application. In addition, WebSphere Application Server enables you to plug in a data source
that is not supported by WebSphere persistence. However, the data source must be implemented as either
the XADataSource type or the ConnectionPoolDataSource type, and it must be in compliance with the
JDBC 2.x specification.

You can achieve application portability through the following:

DataStoreHelper interface
With this interface, each data store platform can plug in its own private data store specific
functions that the relational resource adapter run time uses. WebSphere Application Server
provides an implementation for each supported JDBC provider.
In addition, the interface also provides a GenericDataStoreHelper class for unsupported data
sources to use. You can subclass the GenericDataStoreHelper class or other WebSphere provided
helpers to support any new data source.

Note: If you are configuring data access through a user-defined JDBC provider, do not implement
the DataStoreHelper interface directly. Either subclass the GenericDataStoreHelper class or
subclass one of the DataStoreHelper implementation classes provided by IBM (if your
database behavior or SQL syntax is similar to one of these provided classes).
For more information, see the API documentation DataStoreHelper topic (as listed in the API
documentation index).
The following code segment shows how a new data store helper is created to add new error
mappings for an unsupported data source.
public class NewDSHelper extends GenericDataStoreHelper
{
public NewDSHelper(java.util.Properties dataStoreHelperProperties)
{
super(dataStoreHelperProperties);
java.util.Hashtable myErrorMap = null;
myErrorMap = new java.util.Hashtable();
myErrorMap.put(new Integer(-803), myDuplicateKeyException.class);
myErrorMap.put(new Integer(-1015), myStaleConnectionException.class);
myErrorMap.put("S1000", MyTableNotFoundException.class);
setUserDefinedMap(myErrorMap);
...
}
}

1328 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
WSCallHelper class
This class provides two methods that enable you to use vendor-specific methods and classes that
do not conform to the standard JDBC APIs (and are not part of WebSphere Application Server
extension packages).
v jdbcCall() method
By using the static jdbcCall() method, you can invoke vendor-specific, nonstandard JDBC
methods on your JDBC objects. (For more information, see the API documentation
WSCallHelper topic.) The following code segment illustrates using this method with a DB2 data
source:

Connection conn = ds.getConnection();

// get connection attribute
String connectionAttribute =(String) WSCallHelper.jdbcCall(DataSource.class, ds,
"getConnectionAttribute", null, null);
// setAutoClose to false
WSCallHelper.jdbcCall(java.sql.Connection.class,
conn, "setAutoClose",
new Object[] { new Boolean(false)},
new Class[] { boolean.class });
// get data store helper
DataStoreHelper dshelper = WSCallHelper.getDataStoreHelper(ds);
v jdbcPass() method
Use this method to exploit the nonstandard JDBC classes that some database vendors provide.
These classes contain methods that require vendors’ proprietary JDBC objects to be passed as
parameters.
In particular, implementations of Oracle can involve use of nonstandard classes furnished by the
vendor. Methods contained within these classes include:
oracle.sql.ArrayDescriptor ArrayDescriptor.createDescriptor(java.lang.String,
java.sql.Connection)
oracle.sql.ARRAY new ARRAY(oracle.sql.ArrayDescriptor, java.sql.Connection,
java.lang.Object)
oracle.xml.sql.query.OracleXMLQuery(java.sql.Connection, java.lang.String)
oracle.sql.BLOB.createTemporary(java.sql.Connection, boolean, int)
oracle.sql.CLOB.createTemporary(java.sql.Connection, boolean, int)
oracle.xdb.XMLType.createXML(java.sql.Connection, java.lang.String)
The following code examples demonstrate the difference between a call to the
XMLType.createXML() method over a direct connection to Oracle, and a call to the same
method within WebSphere Application Server.
1. Over a direct connection:
XMLType poXML = XMLType.createXML(conn, poString);
2. Within Application Server, using the jdbcPass() method:
XMLType poXML (XMLType)(WSCallHelper.jdbcPass(XMLType.class,
"createXML", new Object[]{conn,poString},
new Class[]{java.sql.Connection.class, java.lang.String.class},
new int[]{WSCallHelper.CONNECTION,WSCallHelper.IGNORE}));
There are two different jdbcPass() methods available, one for use in invoking static methods,
another for use when invoking non-static methods. See the API documentation WSCallHelper
topic.

Note: Because of the possible problems that can occur by passing an underlying object to a
method, WebSphere Application Server strictly controls which methods are allowed to be
invoked using the jdbcPass() method support. If you require support for a method that is
not listed previously in this document, please contact WebSphere Application Server
support with information on the method you require.
WARNING: Use of the jdbcPass() method causes the JDBC object to be used outside of
WebSphere’s protective mechanisms. Performing certain operations (such as setting
autoCommit, or transaction isolation settings, etc.) outside of these protective mechanisms will

Chapter 8. Developing WebSphere applications 1329

 cause problems with the future use of these pooled connections. IBM does not guarantee
stability of the object after invocation of this method; it is the user’s responsibility to ensure that
invocation of this method does not perform operations that harm the object. Use at your own
risk.

Example: Developing your own DataStoreHelper class: The DataStoreHelper interface supports each
data store platform plugging in its own private data store specific functions that are used by the Relational
Resource Adapter run time.
package com.ibm.websphere.examples.adapter;

import java.sql.SQLException;
import javax.resource.ResourceException;

import com.ibm.websphere.appprofile.accessintent.AccessIntent;
import com.ibm.websphere.ce.cm.*;
import com.ibm.websphere.rsadapter.WSInteractionSpec;

/**
* Example DataStoreHelper class, demonstrating how to create a user-defined DataStoreHelper.
* Implementation for each method is provided only as an example. More detail would likely be
* required for any custom DataStoreHelper created for use by a real application.
*/
public class ExampleDataStoreHelper extends com.ibm.websphere.rsadapter.GenericDataStoreHelper
{
static final long serialVersionUID = 8788931090149908285L;

public ExampleDataStoreHelper(java.util.Properties props)

{
super(props);

// Update the DataStoreHelperMetaData values for this helper.

getMetaData().setGetTypeMapSupport(false);

// Update the exception mappings for this helper.

java.util.Map xMap = new java.util.HashMap();

// Add an Error Code mapping to StaleConnectionException.

xMap.put(new Integer(2310), StaleConnectionException.class);
// Add an Error Code mapping to DuplicateKeyException.
xMap.put(new Integer(1062), DuplicateKeyException.class);
// Add a SQL State mapping to the user-defined ColumnNotFoundException
xMap.put("S0022", ColumnNotFoundException.class);
// Undo an inherited StaleConnection SQL State mapping.
xMap.put("S1000", Void.class);

setUserDefinedMap(xMap);

// Note: If you are extending a helper class, it is

// normally not necessary to issue ’getMetaData().setHelperType(...)’
// because your custom helper will inherit the helper type from its
// parent class. However, certain applications may need to differentiate
// between a custom helper and an existing helper of the same type,
// so WebSpehere has provided the value ’DataStoreHelper.CUSTOM_HELPER’
// for this purpose. If this functionality is needed by your application
// insert the following line into your code:
// getMetaData().setHelperType(DataStoreHelper.CUSTOM_HELPER);

public void doStatementCleanup(java.sql.PreparedStatement stmt) throws SQLException

{
// Clean up the statement so it may be cached and reused.

1330 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 stmt.setCursorName("");
stmt.setEscapeProcessing(true);
stmt.setFetchDirection(java.sql.ResultSet.FETCH_FORWARD);
stmt.setMaxFieldSize(0);
stmt.setMaxRows(0);
stmt.setQueryTimeout(0);
}

public int getIsolationLevel(AccessIntent intent) throws ResourceException

{
// Determine an isolation level based on the AccessIntent.

if (intent == null) return java.sql.Connection.TRANSACTION_SERIALIZABLE;

return intent.getConcurrencyControl() == AccessIntent.CONCURRENCY_CONTROL_OPTIMISTIC ?

java.sql.Connection.TRANSACTION_READ_COMMITTED :
java.sql.Connection.TRANSACTION_REPEATABLE_READ;
}
public int getLockType(AccessIntent intent) {
if ( intent.getConcurrencyControl() == AccessIntent.CONCURRENCY_CONTROL_PESSIMISTIC) {
if ( intent.getAccessType() == AccessIntent.ACCESS_TYPE_READ ) {
return WSInteractionSpec.LOCKTYPE_SELECT;
}
else {
return WSInteractionSpec.LOCKTYPE_SELECT_FOR_UPDATE;
}
}
return WSInteractionSpec.LOCKTYPE_SELECT;
}

public int getResultSetConcurrency(AccessIntent intent) throws ResourceException

{
// Determine a ResultSet concurrency based on the AccessIntent.

return intent == null || intent.getAccessType() == AccessIntent.ACCESS_TYPE_READ ?

java.sql.ResultSet.CONCUR_READ_ONLY :
java.sql.ResultSet.CONCUR_UPDATABLE;
}

public int getResultSetType(AccessIntent intent) throws ResourceException

{
// Determine a ResultSet type based on the AccessIntent.

if (intent == null) return java.sql.ResultSet.TYPE_SCROLL_INSENSITIVE;

return intent.getCollectionAccess() == AccessIntent.COLLECTION_ACCESS_SERIAL ?

java.sql.ResultSet.TYPE_FORWARD_ONLY :
java.sql.ResultSet.TYPE_SCROLL_SENSITIVE;
}
}

ColumnNotFoundException
package com.ibm.websphere.examples.adapter;

import java.sql.SQLException;
import com.ibm.websphere.ce.cm.PortableSQLException;

/**
* Example PortableSQLException subclass, which demonstrates how to create a user-defined
* exception for exception mapping.
*/
public class ColumnNotFoundException extends PortableSQLException

Chapter 8. Developing WebSphere applications 1331

{
public ColumnNotFoundException(SQLException sqlX)
{
super(sqlX);
}
}

Connection factory
An application component uses a connection factory to access a connection instance, which the
component then uses to connect to the underlying enterprise information system (EIS).

Examples of connections include database connections, Java Message Service connections, and SAP R/3
connections.

CMP Connection Factories collection:

Use this page to view existing CMP connection factories settings.

These are the connection factories used by a container-managed persistence (CMP) bean to access any
backend data store. A CMP Connection Factory is used by EJB model 2.x Entities with CMP version 2.x.
Connection factories listed on this page are created automatically under the WebSphere Relational
Resource Adapter when you check the box Use this DataSource in container managed persistence (CMP)
in the General Properties area on the Data Source page. You cannot modify the settings for a CMP
Connection Factory, and you can not delete CMP Connection Factories from this collection. To remove the
CMP Connection Factory object, you must navigate to the data source associated with the CMP
Connection Factory and uncheck the Use this DataSource for CMP checkbox.

To view this administrative console page, click Resources >Resource Adapters >WebSphere Relational
Resource Adapter > CMP Connection Factories.

Name:

Specifies a list of the display names for the resources.

Data type String

JNDI Name:

Specifies the JNDI name of the resource.

Data type String

Description:

Specifies a description for the resource.

Data type String

Category:

Specifies a category string which can be used to classify or group the resource.

Data type String

CMP connection factory settings:

1332 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Use this page to view the settings of a connection factory that is used by a CMP bean to access any
backend data store. This connection factory is only in ″read″ mode. It cannot be modified or deleted.

To view this administrative console page, click Resources >Resource Adapters > WebSphere Relational
Resource Adapter> CMP Connection Factories > connection_factory

Name:

Specifies the display name for the resource.

Data type String

JNDI name:

Specifies the JNDI name of the resource.

Data type String

Description:

Specifies a description for the resource.

Data type String

Category:

Specifies a category string which can be used to classify or group the resource.

Data type String

Authentication Preference:

Specifies which of the authentication mechanisms that are defined for the corresponding resource adapter
applies to this connection factory. This property is deprecated starting with version 6.0.

For example, if two authentication mechanism entries are defined for a resource adapter (KerbV5 and
Basic Password), this specifies one of those two types. If the authentication mechanism preference
specified is not an authentication mechanism available on the corresponding resource adapter, it is
ignored.

Data type String

Component-managed authentication alias:

References authentication data for component-managed signon to the resource.

Data type Drop-down list

Container-managed authentication alias:

References authentication data for container-managed signon to the resource. This property is deprecated
starting with version 6.0.

Chapter 8. Developing WebSphere applications 1333

Data type Drop-down list

JDBC providers
Installed applications use JDBC providers to access data from databases.

For applications that need access to relational databases, the JDBC provider and data source together are
functionally equivalent to the J2EE Connector Architecture (JCA) connection factory. The WebSphere
Application Server prerequisite Web site has a current list of supported providers. See ″Hardware and
software requirements″ in the information center for more information.

Data sources
Installed applications uses a data source to access the data from the database.

A data source is associated with a JDBC provider that supplies the specific JDBC driver implementation
class. The data source represents the J2EE Connector Architecture (JCA) connection factory for the
relational resource adapter. Application components use the data source to access connection instances to
a specific database; a connection pool is associated with each data source.

You can create multiple data sources with different settings, and associate them with the same JDBC
provider. (One reason to do this is to provide access to different databases.) JDBC providers that are
supported by WebSphere Application Server are required to implement one or both of the following data
source interfaces, which are defined by Sun Microsystems. These interfaces enable the application to run
in a single-phase or two-phase transaction protocol.
v ConnectionPoolDataSource - a data source that supports application participation in local and global
transactions, excepting two-phase commit transactions.

Note: In two cases, a connection pool data source does support two-phase commit transactions: when
the JDBC provider is DB2 for z/OS Local JDBC provider (RRS), or when the data source is
making use of Last Participant support. (Last participant support enables a single one-phase
commit resource to participate in a global transaction with one or more two-phase commit
resources.)
When a connection pool data source is involved in a global transaction, transaction recovery is not
provided by the transaction manager. The application is responsible for providing the backup recovery
process if multiple resource managers are involved.
v XADataSource - a data source that supports application participation in any single-phase or two-phase
transaction environment. When this data source is involved in a global transaction, the WebSphere
Application Server transaction manager provides transaction recovery.

In WebSphere Application Server releases prior to version 5.0, the function of data access was provided
by a single connection manager (CM) architecture. This connection manager architecture remains
available to support J2EE 1.2 applications, but another connection manager architecture is provided,
based on the JCA architecture supporting the new J2EE 1.3 application style (also for J2EE 1.4
applications).

These two separate architectures are represented by two types of data sources. To choose the right data
source, administrators must understand the nature of their applications, EJB modules, and enterprise
beans.
v Data source (Version 4.0) - This data source runs under the original CM architecture. Applications using
this data source behave as if they were running in Version 4.0.
v Data source - This data source uses the JCA standard architecture to provide support for J2EE version
1.3 applications and beyond. It runs under the JCA connection manager and the relational resource
adapter.

1334 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Choice of data source
v J2EE 1.2 application - all EJB 1.1 enterprise beans, JDBC applications, or Servlet 2.2 components must
use the 4.0 data source.
v J2EE 1.3 (and subsequent releases) application -
– EJB 1.1 Module - all EJB 1.x beans must use the 4.0 data source.
– EJB 2.0 (and subsequent releases) Module - enterprise beans that include container-managed
persistence (CMP) Version 1.x, 2.0, and beyond must use the new data source.
– JDBC applications and Servlet 2.3+ components - must use the new data source.

Data access beans

Data access beans provide a rich set of features and function, while hiding much of the complexity
associated with accessing relational databases.

They are Java classes written to the Enterprise JavaBeans specification.

You can use the data access beans in JavaBeans-compliant tools, such as the IBM Rational Application
Developer. Because the data access beans are also Java classes, you can use them like ordinary classes.

The data access beans (in the package com.ibm.db) offer the following capabilities:
Feature
Details
Caching query results
You can retrieve SQL query results all at once and place them in a cache. Programs using the
result set can move forward and backward through the cache or jump directly to any result row in
the cache.
For large result sets, the data access beans provide ways to retrieve and manage packets,
subsets of the complete result set.
Updating through result cache
Programs can use standard Java statements (rather than SQL statements) to change, add, or
delete rows in the result cache. You can propagate changes to the cache in the underlying
relational table.
Querying parameter support
The base SQL query is defined as a Java String, with parameters replacing some of the actual
values. When the query runs, the data access beans provide a way to replace the parameters with
values made available at run time. Default mappings for common data types are provided, but you
can specify whatever your Java program and database require.
Supporting metadata
A StatementMetaData object contains the base SQL query. Information about the query (metadata)
enables the object to pass parameters into the query as Java data types.
Metadata in the object maps Java data types to SQL data types (as well as the reverse). When
the query runs, the Java-datatyped parameters are automatically converted to SQL data types as
specified in the metadata mapping.
When results return, the metadata object automatically converts SQL data types back into the
Java data types specified in the metadata mapping.

Connection management architecture

The connection management architecture for both relational and procedural access to enterprise
information systems (EIS) is based on the J2EE Connector Architecture (JCA) specification. The
Connection Manager (CM), which pools and manages connections within an application server, is capable
of managing connections obtained through both resource adapters (RAs) defined by the JCA specification,
and data sources defined by the JDBC 2.0 (and later) Extensions specification.

Chapter 8. Developing WebSphere applications 1335

To make data source connections manageable by the CM, the WebSphere Application Server provides a
resource adapter (the WebSphere Relational Resource Adapter) that enables JDBC data sources to be
managed by the same CM that manages JCA connections. From the CM point of view, JDBC data
sources and JCA connection factories look the same. Users of data sources do not experience any
programmatic or behavioral differences in their applications because of the underlying JCA architecture.
JDBC users still configure and use data sources according to the JDBC programming model.

Applications migrating from previous versions of WebSphere Application Server might experience some
behavioral differences because of the specification changes from various J2EE requirements levels. These
differences are not related to the adoption of the JCA architecture.

If you have J2EE 1.2 applications using the JDBC API that you wish to run in WebSphere Application
Server 6.0, the JDBC CM from Application Server version 4.0 is still provided as a configuration option.
Using this configuration option enables J2EE 1.2 applications to run unaltered. If you migrate a Version 4.0
application to Version 6.0, using the Version 6.0 migration tools, the application automatically uses the
Version 4.0 connection manager after migration. However, EJB 2.x modules in J2EE 1.3 (or later versions)
applications cannot use the JDBC CM from WebSphere Application Server Version 4.0.

Connection pooling:

When accessing any database, establishing connections is an expensive operation. Connection pooling
enables administrators to establish a pool of database connections that applications can share on an
application server. When connection pooling capabilities are used, performance improvements up to 20
times the normal results are realized.

Each time a resource attempts to access a backend store (such as a database), the resource must
connect to that data store. A connection requires resources to create, maintain, and then release the
connection when it is no longer required.

The total data store overhead for an application is particularly high for Web-based applications because
Web users connect and disconnect more frequently. In addition, user interactions are typically shorter.
Often, more effort is spent connecting and disconnecting than is spent during the interactions. Also,
because Internet requests can arrive from virtually anywhere, you can find usage volumes large and
difficult to predict.

To help lessen these overhead problems, the WebSphere Application Server enables administrators to
establish a pool of backend connections that applications can share on an application server. Connection
pooling spreads the connection overhead across several user requests, thereby conserving resources for
future requests.

WebSphere Application Server supports JDBC 3.0 APIs to provide support for connection pooling and
connection reuse. The connection pool is used to direct JDBC calls within the application, as well as for
enterprise beans using the database.

Each entity bean transaction requires an additional connection to the database specifically to handle the
transaction. Take this into account when calculating the number of data source connections.

On UNIX platforms, a separate DB2 process is created for each connection and these processes quickly
affect performance on systems with low memory and cause errors.

If clones are used, one data pool exists for each clone. This is important when configuring the database
maximum connections.

Benefits of connection pooling: Connection pooling can improve the response time of any application that
requires connections, especially Web-based applications. When a user makes a request over the Web to a
resource, the resource accesses a data source. With connection pooling, most user requests do not incur

1336 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
the overhead of creating a new connection because the data source can locate and use an existing
connection from the pool of connections. When the request is satisfied and the response is returned to the
user, the resource returns the connection to the connection pool for reuse. The overhead of a
disconnection is avoided. Each user request incurs a fraction of the cost for connecting or disconnecting.
After the initial resources are used to produce the connections in the pool, additional overhead is
insignificant because the existing connections are reused.

When to use connection pooling: Use WebSphere connection pooling in an application that meets any of
the following criteria:
v It cannot tolerate the overhead of obtaining and releasing connections whenever a connection is used.
v It requires Java Transaction API (JTA) transactions within WebSphere Application Server.
v It needs to share connections among multiple users within the same transaction.
v It needs to take advantage of product features for managing local transactions within the application
server.
v It does not manage the pooling of its own connections.
v It does not manage the specifics of creating a connection, such as the database name, user name, or
password

How connections are pooled together: Whenever you configure a unique data source or connection
factory, you are required to give it a unique Java Naming and Directory Interface (JNDI) name. This JNDI
name, along with its configuration information, is used to create a connection pool. A separate connection
pool exists for each configured data source or connection factory.

A separate instance of a given configured connection pool is created on each application server that uses
that data source or connection factory. For example, if you run a three server cluster in which all of the
servers use myDataSource, and myDataSource has a maximum connections setting of 10, then you can
generate up to 30 connections (three servers times 10 connections). Be sure to consider this fact when
determining how many connections to your backend resource you can support.

It is also important to note that when using connection sharing, it is only possible to share connections
obtained from the same connection pool.

Avoiding a deadlock: Deadlock can occur if the application requires more than one concurrent connection
per thread, and the database connection pool is not large enough for the number of threads. Suppose
each of the application threads requires two concurrent database connections and the number of threads
is equal to the maximum connection pool size. Deadlock can occur when both of the following are true:
v Each thread has its first database connection, and all are in use.
v Each thread is waiting for a second database connection, and none would become available since all
threads are blocked.

To prevent the deadlock in this case, the Maximum Connections value for the database connection pool
should be increased by at least one. Doing this allows for at least one of the waiting threads to obtain its
second database connection and to avoid a deadlock.

To avoid deadlock, code the application to use, at most, one connection per thread. If the application is
coded to require C concurrent database connections per thread, the connection pool must support at least
the following number of connections, where T is the maximum number of threads.
T * (C - 1) + 1

The connection pool settings are directly related to the number of connections that the database server is
configured to support. If the maximum number of connections in the pool is raised, and the corresponding
settings in the database are not raised, the application fails and SQL exception errors are displayed in the
stderr.log file.

Chapter 8. Developing WebSphere applications 1337

Deferred Enlistment: In the WebSphere Application Server environment, deferred enlistment is a term
used to refer to the technique of waiting until a connection is first used to enlist it in its unit of work (UOW)
scope.

In one example, the technique works like this: a component calls getConnection() from within a global
transaction, and at some point later in time, the component uses the connection. The call that uses the
connection is intercepted, and the XA resource for that connection is enlisted with the transaction service
(which in turn calls XAResource.start()). Next, the actual call is sent to the resource manager.

In contrast, if a component gets a connection within a global transaction without deferred enlistment, then
the connection is enlisted in the transaction and has all the overhead associated with that transaction. For
XA connections, this includes the two phase commit (2PC) protocol to the resource manager. Deferred
enlistment offers better performance in the case where a connection is obtained, but not used within the
UOW scope. This saves all the overhead of participating in the UOW when it is not needed.

The WebSphere Application Server relational resource adapter automatically supports deferred enlistment
without any additional configuration needed.

Lazy Transaction Enlistment Optimization: The J2EE Connector Architecture (JCA) Version 1.5
specification calls the deferred enlistment technique lazy transaction enlistment optimization. This support
comes through a marker interface (LazyEnlistableManagedConnection) and a new method on the
connection manager (LazyEnlistableConnectionManager()):
package javax.resource.spi;
import javax.resource.ResourceException;
import javax.transaction.xa.Xid;

interface LazyEnlistableConnectionManager { // application server

void lazyEnlist(ManagedConnection) throws ResourceException;
}

interface LazyEnlistableManagedConnection { // resource adapter

}

A resource adapter is not required to support this functionality. Check with the resource adapter provider if
you need to know if the resource adapter provides this functionality.

Connection and connection pool statistics: Performance Monitoring Infrastructure (PMI) method calls that
are supported in the two existing Connection Managers (JDBC and J2C) are still supported in this version
of WebSphere Application Server. The calls include:
v ManagedConnectionsCreated
v ManagedConnectionsAllocated
v ManagedConnectionFreed
v ManagedConnectionDestroyed
v BeginWaitForConnection
v EndWaitForConnection
v ConnectionFaults
v Average number of ManagedConnections in the pool
v Percentage of the time that the connection pool is using the maximum number of ManagedConnections
v Average number of threads waiting for a ManagedConnection
v Average percent of the pool that is in use
v Average time spent waiting on a request
v Number of ManagedConnections that are in use
v Number of Connection Handles
v FreePoolSize
v UseTime

1338 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Java Specification Request (JSR) 77 requires statistical data to be accessed through managed beans
(Mbeans) to facilitate this. The Connection Manager passes the ObjectNames of the Mbeans created for
this pool. In the case of Java Message Service (JMS) null is passed in. The interface used is :
PmiFactory.createJ2CPerf(
String pmiName, // a unique Identifier for JCA /JDBC. This is the
// ConnectionFactory name.

ObjectName providerName,// the ObjectName of the J2CResourceAdapter

// or JDBCProvider Mbean

ObjectName factoryName // the ObjectName of the J2CConnectionFactory

// or DataSourceMbean.
)

The following Unified Modeling Language (UML) diagram shows how JSR 77 requires statistics to be
<<JavaInterface>> <<JavaInterface>>
JCAStats JDBCStats

+ getConnections ( ) + getConnections ( )
+ getConnectionPools ( ) + getConnectionPools ( )

<<JavaInterface>> <<JavaInterface>>
JCAConnectionStats JDBCConnectionStats

+ getConnectionFactory ( ) + getJdbcDataSource ( ) JDBCDataSource

+ getManageConnectionFactory ( ) + getWaitTime ( ) 1
+ getWaitTime ( ) + getUseTime ( )
+ getUseTime ( ) + Operation1 ( )

<<JavaInterface>> <<JavaInterface>>
JCAConnectionPoolStats JDBCConnectionPoolStats

+ getCloseCount ( ) + getCreateCount ( )
+ getCreateCount ( ) + getCloseCount ( )
+ getFreePoolSize ( ) + getPoolSize ( )
+ getPoolSize ( ) + getFreePoolSize ( )
+ getWaitingThreadCount ( ) + getWaitingThreadCount ( )
reported :

In WebSphere Application Server Version 5.x, the JCAStats interface was implemented by the
J2CResourceAdapter Mbean, and the JDBCStats interface was implemented by the JDBCProvider Mbean.
The JCAConnectionStats and JDBCConnectionStats interfaces are not implemented because they collect
statistics for non pooled connections - which are not present in the JCA 1.0 Specification.
JCAConnectionPoolStats, and JDBCConnectionPoolStats do not have a direct implementing Mbean; those
statistics are gathered through a call to PMI. A J2C resource adapter, and JDBC provider each contain a
list of ConnectionFactory or DataSource ObjectNames, respectively. The ObjectNames are used by PMI to
find the appropriate connection pool in the list of PMI modules.

The JCA 1.5 Specification allows an exception from the matchManagedConnection() method that indicates
that the resource adapter requests that the connection not be pooled. In that case, statistics for that
connection are provided separately from the statistics for the connection pool.

Connection life cycle:

A ManagedConnection object is always in one of three states: DoesNotExist, InFreePool, or InUse.

Chapter 8. Developing WebSphere applications 1339

Before a connection is created, it must be in the DoesNotExist state. After a connection is created, it can
be in either the InUse or the InFreePool state, depending on whether it is allocated to an application.

Between these three states are transitions. These transitions are controlled by guarding conditions. A
guarding condition is one in which true indicates when you can take the transition into another legal state.
For example, you can make the transition from the InFreePool state to InUse state only if:
v the application has called the data source or connection factory getConnection() method (the
getConnection condition)
v a free connection is available in the pool with matching properties (the freeConnectionAvailable
condition)
v and one of the two following conditions are true:
– the getConnection() request is on behalf of a resource reference that is marked unsharable
– the getConnection() request is on behalf of a resource reference that is marked shareable but no
shareable connection in use has the same properties.

This transition description follows:

InFreePool > InUse:

getConnection AND
freeConnectionAvailable AND
NOT(shareableConnectionAvailable)

Here is a list of guarding conditions and descriptions.

Condition Description
ageTimeoutExpired Connection is older then its ageTimeout value.
close Application calls close method on the Connection object.
fatalErrorNotification A connection has just experienced a fatal error.
freeConnectionAvailable A connection with matching properties is available in the
free pool.
getConnection Application calls getConnection method on a data source
or connection factory object.
markedStale Connection is marked as stale, typically in response to a
fatal error notification.
noOtherReferences There is only one connection handle to the managed
connection, and the Transaction Service is not holding a
reference to the managed connection.
noTx No transaction is in force.
poolSizeGTMin Connection pool size is greater than the minimum pool
size (minimum number of connections)
poolSizeLTMax Pool size is less than the maximum pool size (maximum
number of connections)
shareableConnectionAvailable The getConnection() request is for a shareable
connection, and one with matching properties is in use
and available to share.
TxEnds The transaction has ended.
unshareableConnectionRequest The getConnection() request is for an unshareable
connection.
unusedTimeoutExpired Connection is in the free pool and not in use past its
unused timeout value.

1340 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Getting connections: The first set of transitions covered are those in which the application requests a
connection from either a data source or a connection factory. In some of these scenarios, a new
connection to the database results. In others, the connection might be retrieved from the connection pool
or shared with another request for a connection.

DoesNotExist

Every connection begins its life cycle in the DoesNotExist state. When an application server starts, the
connection pool does not exist. Therefore, there are no connections. The first connection is not created
until an application requests its first connection. Additional connections are created as needed, according
to the guarding condition.
getConnection AND
NOT(freeConnectionAvailable) AND
poolSizeLTMax AND
(NOT(shareableConnectionAvailable) OR
unshareableConnectionRequest)

This transition specifies that a connection object is not created unless the following conditions occur:
v The application calls the getConnection() method on the data source or connection factory
v No connections are available in the free pool (NOT(freeConnectionAvailable))
v The pool size is less than the maximum pool size (poolSizeLTMax)
v If the request is for a sharable connection and there is no sharable connection already in use with the
same sharing properties (NOT(shareableConnectionAvailable)) OR the request is for an unsharable
connection (unshareableConnectionRequest)

All connections begin in the DoesNotExist state and are only created when the application requests a
connection. The pool grows from 0 to the maximum number of connections as applications request new
connections. The pool is not created with the minimum number of connections when the server starts.

If the request is for a sharable connection and a connection with the same sharing properties is already in
use by the application, the connection is shared by two or more requests for a connection. In this case, a
new connection is not created. For users of the JDBC API these sharing properties are most often
userid/password and transaction context; for users of the Resource Adapter Common Client Interface
(CCI) they are typically ConnectionSpec, Subject, and transaction context.

InFreePool

The transition from the InFreePool state to the InUse state is the most common transition when the
application requests a connection from the pool.
InFreePool>InUse:
getConnection AND
freeConnectionAvailable AND
(unshareableConnectionRequest OR
NOT(shareableConnectionAvailable))

This transition states that a connection is placed in use from the free pool if:
v the application has issued a getConnection() call
v a connection is available for use in the connection pool (freeConnectionAvailable),
v and one of the following is true:
– the request is for an unsharable connection (unsharableConnectionRequest)
– no connection with the same sharing properties is already in use in the transaction.
(NOT(sharableConnectionAvailable)).

Any connection request that a connection from the free pool can fulfill does not result in a new connection
to the database. Therefore, if there is never more than one connection used at a time from the pool by any
number of applications, the pool never grows beyond a size of one. This number can be less than the

Chapter 8. Developing WebSphere applications 1341

minimum number of connections specified for the pool. One way that a pool grows to the minimum
number of connections is if the application has multiple concurrent requests for connections that must
result in a newly created connection.

InUse

The idea of connection sharing is seen in the transition on the InUse state.
InUse>InUse:
getConnection AND
ShareableConnectionAvailable

This transition indicates that if an application requests a shareable connection (getConnection) with the
same sharing properties as a connection that is already in use (ShareableConnectionAvailable), the
existing connection is shared.

The same user (user name and password, or subject, depending on authentication choice) can share
connections but only within the same transaction and only when all of the sharing properties match. For
JDBC connections, these properties include the isolation level, which is configurable on the
resource-reference (IBM WebSphere extension) to data source default. For a resource adapter factory
connection, these properties include those specified on the ConnectionSpec object. Because a transaction
is normally associated with a single thread, you should never share connections across threads.

Note: It is possible to see the same connection on multiple threads at the same time, but this situation is
an error state usually caused by an application programming error.

Returning connections: All of the transitions discussed previously involve getting a connection for
application use. With that goal, the transitions result in a connection closing, and either returning to the
free pool or being destroyed. Applications should explicitly close connections (note: the connection that the
user gets back is really a connection handle) by calling close() on the connection object. In most cases,
this action results in the following transition:
InUse>InFreePool:
(close AND
noOtherReferences AND
NoTx AND
UnshareableConnection)
OR
(ShareableConnection AND
TxEnds)

Conditions that cause the transition from the InUse state are:
v If the application or the container calls close() (producing the close condition) and there are no
references (the noOtherReferences condition) either by the application (in the application sharing
condition) or by the transaction manager (in the NoTx condition, meaning that the transaction manager
holds a reference when the connection is enlisted in a transaction), the connection object returns to the
free pool.
v If the connection was enlisted in a transaction but the transaction manager ends the transaction (the
txEnds condition), and the connection was a shareable connection (the ShareableConnection condition),
the connection closes and returns to the pool.

When the application calls close() on a connection, it is returning the connection to the pool of free
connections; it is not closing the connection to the data store. When the application calls close() on a
currently shared connection, the connection is not returned to the free pool. Only after the application
drops the last reference to the connection, and the transaction is over, is the connection returned to the
pool. Applications using unsharable connections must take care to close connections in a timely manner.
Failure to do so can starve out the connection pool, making it impossible for any application running on the
server to get a connection.

1342 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
When the application calls close() on a connection enlisted in a transaction, the connection is not returned
to the free pool. Because the transaction manager must also hold a reference to the connection object, the
connection cannot return to the free pool until the transaction ends. Once a connection is enlisted in a
transaction, you cannot use it in any other transaction by any other application until after the transaction is
complete.

There is a case where an application calling close() can result in the connection to the data store closing
and bypassing the connection return to the pool. This situation happens if one of the connections in the
pool is considered stale. A connection is considered stale if you can no longer use it to contact the data
store. For example, a connection is marked stale if the data store server is shut down. When a connection
is marked as stale, the entire pool is cleaned out by default because it is very likely that all of the
connections are stale for the same reason (or you can set your configuration to clean just the failing
connection). This cleansing includes marking all of the currently InUse connections as stale so they are
destroyed upon closing. The following transition states the behavior on a call to close() when the
connection is marked as stale:
InUse>DoesNotExist:
close AND
markedStale AND
NoTx AND
noOtherReferences

This transition states that if the application calls close() on the connection and the connection is marked as
stale during the pool cleansing step (markedStale), the connection object closes to the data store and is
not returned to the pool.

Finally, you can close connections to the data store and remove them from the pool.

This transition states that there are three cases in which a connection is removed from the free pool and
destroyed.
1. If a fatal error notification is received from the resource adapter (or data source). A fatal error
notification (FatalErrorNotification) is received from the resource adaptor when something happens to
the connection to make it unusable. All connections currently in the free pool are destroyed.
2. If the connection is in the free pool for longer than the unused timeout period (UnusedTimeoutExpired)
and the pool size is greater than the minimum number of connections (poolSizeGTMin), the connection
is removed from the free pool and destroyed. This mechanism enables the pool to shrink back to its
minimum size when the demand for connections decreases.
3. If an age timeout is configured and a given connection is older than the timeout. This mechanism
provides a way to recycle connections based on age.

Unshareable and shareable connections:

WebSphere Application Server supports both unshareable and shareable connections. An unshareable
connection is not shared with other components in the application. The component using this connection
has full control of this connection.

You can share a shareable connection with other components within the same transaction as long as each
getConnection() request has the same connection properties. To enable connection sharing for data
sources, the following connection properties must be the same:
v Java Naming and Directory Interface (JNDI) name. While not actually a connection property, this
requirement simply means that you can only share connections from the same data source in the same
server.
v Resource authentication
v In relational databases:
– Isolation level (corresponds to access intent policies applied to CMP beans)
– Readonly
– Catalog
– TypeMap
Chapter 8. Developing WebSphere applications 1343
To enable connection sharing for resource adapters within the same transaction, the following connection
properties must be the same:
v JNDI name. While not actually a connection property, this requirement simply means that you can only
share connections from the same resource adapter in the same server.
v Resource authentication

In addition, the ConnectionSpec object used to get the connection must also be the same. For more
information on sharing a connection with a CMP bean, see Sharing a connection with a CMP bean.

Java Message Service (JMS) connections cannot be shared with non-JMS connections.

Access to a resource marked as unshareable means that there is a one-to-one relationship between the
connection handle a component is using and the physical connection with which the handle is associated.
This access implies that every call to the getConnection() method returns a connection handle solely for
the requesting user. Typically, you must choose unshareable if you might do things to the connection that
could result in unexpected behavior occurring in another application that is sharing the connection (for
example, unexpectedly changing the isolation level).

Marking a resource as shareable allows for greater scalability. Instead of creating new physical
connections on every getConnection() invocation, the physical connection (that is, managed connection) is
shared through multiple connection handles, as long as each getConnection request has the same
connection properties. However, sharing a connection means that each user must not do anything to the
connection that could change its behavior and disrupt a sharing partner (for example, changing the
isolation level). The user also cannot code an application that assumes sharing to take place because it is
up to the run time to decide whether or not to share a particular connection.

For WebSphere Application Server, all sharing of connections is relative to the current Unit of Work (UOW)
boundary. Anyone within a specific transaction, when getting a connection from a specific connection pool,
gets a handle to the same physical connection (if the sharing properties are the same).

Factors that determine sharing: The listing here is not an exhaustive one. The product might or might not
share connections under different circumstances.
v Only connections acquired with the same resource reference (resource-ref) that specifies the
res-sharing-scope as shareable are candidates for sharing. The resource reference properties of
res-sharing-scope and res-auth and the IBM extension isolationLevel help determine if it is possible to
share a connection. IBM extension isolationLevel is stored in IBM deployment descriptor extension file;
for example: ibm-ejb-jar-ext.xmi.
v You can only share connections that are requested with the same properties.
v Connection Sharing only occurs between different component instances if they are within a transaction
(container- or user-initiated transaction).
v Connection Sharing only occurs within a sharing boundary. Current sharing boundaries include
Transactions and LocalTransactionContainment (LTC) boundaries.
v Connection Sharing rules within an LTC Scope:
– For shareable connections, only Connection Reuse is allowed within a single component instance.
Connection reuse occurs when the following actions are taken with a connection: get, use,
commit/rollback, close; get, use, commit/rollback, close. Note that if you use the LTC
resolution-control of ContainerAtBoundary then no start/commit is needed because that action is
handled by the container.
The connection returned on the second get is the same connection as that returned on the first get
(if the same properties are used). Because the connection use is serial, only one connection handle
to the underlying physical connection is used at a time, so true connection sharing does not take
place. The term ″reuse″ is more accurate.
More importantly, the LocalTransactionContainment boundary enclosing both get actions is not
complete; no cleanUp() method is invoked on the ManagedConnection object. Therefore the second
get action inherits all of the connection properties set during the first getConnection() call.

1344 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Shareable connections between transactions (either container-managed transactions (CMT),
bean-managed transactions (BMT), or LTC transactions) follow these caching rules:
– In general, setting properties on shareable connections is not allowed because a user of one
connection handle might not anticipate a change made by another connection handle. This limitation
is part of the J2EE 1.3 standard.
– General users of resource adapters can set the connection properties on the connection factory
getConnection() call by passing them in a ConnectionSpec.
However, the properties set on the connection during one transaction are not guaranteed to be the
same when used in the next transaction. Because it is not valid to share connections outside of a
sharing scope, connection handles are moved off of the physical connection with which they are
currently associated when a transaction ends. That physical connection is returned to the free
connection pool. Connections are cleaned before going in the free pool. The next time the handle is
used, it is automatically associated with an appropriate connection. The appropriateness is based on
the security login information, connection properties, and (for the JDBC API) the isolation level
specified in the extended resource reference, passed in on the original request that returned the
current handle. Any properties set on the connection after it was retrieved are lost.
– For JDBC users, WebSphere Application Server provides an extension to enable passing the
connection properties through the ConnectionSpec.
Use caution when setting properties and sharing connections in a local transaction scope. Ensure
that other components with which the connection is shared are expecting the behavior resulting from
your settings.
v You cannot set the isolation level on a shareable connection for the JDBC API using a relational
resource adapter in a global transaction. The product provides an extension to the resource reference to
enable you to specify the isolation level. If your application requires the use of multiple isolation levels,
create multiple resource references and map them to the same data source or connection factory.

Sharing a connection with a CMP bean: WebSphere Application Server allows you to share a physical
connection between a CMP bean, a BMP bean, and a JDBC application to reduce the resource allocation
or deadlock scenarios. There are several ways to ensure that all of these entity beans and the JDBC
applications are sharing the same physical connection.
v Sharing a connection between CMP beans or methods
When all CMP bean methods use the same access intent, they all share the same physical connection.
A different access intent policy triggers the allocation of a different physical connection. For example, a
CMP bean has two methods; method 1 is associated with wsPessimisticUpdate intent, whereas method
2 has wsOptimisticUpdate access intent. Method 1 and method 2 cannot share the same physical
connection within a transaction. In other words, an XA data source is required to run in a global
transaction.
You can experience some deadlocks from a database if both methods try to access the same table.
Therefore, sharing a connection is determined by the access intents that are defined in the CMP
methods.
v Sharing a connection between CMP and BMP beans
There are two options to ensure that both CMP and BMP beans share the same physical connection:
– Define the same access intent on both CMP and BMP bean methods. Because both use the same
access intent, they share the same physical connection. The advantage to using this option is that
the backend is transparent to a BMP bean; however, this BMP is not portable because it uses the
WebSphere extended API to handle the isolation level. For more information, refer to the code
example in Example: Accessing data using IBM extended APIs to share connections between
container-managed and bean-managed persistence beans.
– Determine the isolation level that the access intent uses on a CMP bean method, then use the
corresponding isolation level that is specified on the resource reference to look up a data source and
a connection. This option is more of a manual process, and the isolation level might be different from
database to database. For more information refer to the isolation level and access intent mapping
table: Access intent isolation levels and update locks and the Isolation level and resource reference
section.

Chapter 8. Developing WebSphere applications 1345

v Sharing a connection between CMP and a JDBC application that is used by a servlet or a
session bean
Determine the isolation level that the access intent uses on a CMP bean method, then use the
corresponding isolation level specified on the resource reference to look up a data source and a
connection. For more information refer to Access intent isolation levels and update locks and Isolation
level and resource reference.

Connection sharing violations: There is a new exception, the SharingViolation exception, that the
resource adapter can issue whenever an operation violates sharing requirements. Possible violations
include changing connection attributes, security settings, or isolation levels, among others. When such a
mutable operation is performed against a managed connection, the SharingViolation exception can occur
when both of the following conditions are true:
v The number of connection handles associated with the managed connection is more than one.
v The managed connection is associated with a transaction, either local or XA.

Both the component and the J2C run time might need to detect this SharingViolation exception,
depending on when and how the managed connection becomes unshareable. If the managed connection
becomes unshareable because of an operation through the connection handle (for example, you change
the isolation level), then the component needs to process the exception. If the managed connection
becomes unshareable without being recognized by the application server (due to some component
interaction with the connection handle), then the resource adapter can reject the creation of a connection
handle by issuing the SharingViolation exception.

Connection handles:

A connection handle is a representation of a physical connection.

To use a backend resource (such as a relational database) in WebSphere Application Server you must get
a connection to that resource. When you call the getConnection() method, you get a connection handle
returned. The handle is not the physical connection. The physical connection is managed by the
connection manager.

There are two significant configurations that affect how connection handles are used and how they
behave. The first is the res-sharing-scope, which is defined by the resource-reference used to look up the
DataSource or Connection Factory. This property tells the connection manager whether or not you can
share this connection.

The second factor that affects connection handle behavior is the usage pattern. There are essentially two
usage patterns. The first is called the get/use/close pattern. It is used within a single method and without
calling another method that might get a connection from the same data source or connection factory. An
application using this pattern does the following:
1. gets a connection
2. does its work
3. commits (if appropriate)
4. closes the connection.

The second usage pattern is called the cached handle pattern. This is where an application:
1. gets a connection
2. begins a global transaction
3. does work on the connection
4. commits a global transaction
5. does work on the connection again

A cached handle is a connection handle that is held across transaction and method boundaries by an
application. Keep in mind the following considerations for using cached handles:

1346 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Cached handle support requires some additional connection handle management across these
boundaries, which can impact performance. For example, in a JDBC application, Statements,
PreparedStatements, and ResultSets are closed implicitly after a transaction ends, but the connection
remains valid.
v You are encouraged not to cache the connection across the transaction boundary for shareable
connections; the get/use/close pattern is preferred.
v Caching of connection handles across servlet methods is limited to JDBC and Java Message Service
(JMS) resources. Other non-relational resources, such as Customer Information Control System (CICS)
or IMS objects, currently cannot have their connection handles cached in a servlet; you need to get,
use, and close the connection handle within each method invocation. (This limitation only applies to
single-threaded servlets because multithreaded servlets do not allow caching of connection handles.)

The following code segment shows the cached connection pattern.

Connection conn = ds.getConnection();
ut.begin();
conn.prepareStatement("....."); --> Connection runs in global transaction mode
...
ut.commit();
conn.prepareStatement("....."); ---> Connection still valid but runs in autoCommit(True);
...

Unshareable connections: Some characteristics of connection handles retrieved with a res-sharing-scope

of unshareable are described in the following sections.

The possible benefits of unshared connections

v Your application always maintains a direct link with a physical connection (managed connection).
v The connection always has a one-to-one relationship between the connection handle and the managed
connection.
v In most cases, the connection does not close until the application closes it.
v You can use a cached unshared connection handle across multiple transactions.
v The connection can have a performance advantage in some cached handle situations. Because
unshared connections do not have the overhead of moving connection handles off managed
connections at the end of the transaction, there is less overhead in using a cached unshared
connection.

The possible drawbacks of unshared connections

v Inefficient use of your connection resources. For example, if within a single transaction you get more
than one connection (with the same properties) using the same data source or connection factory (same
resource-ref) then you use multiple physical connections when you use unshareable connections.
v Wasted connections. It is important not to keep the connection handle open (that is, your application
does not call the close() method) any longer then it is needed. As long as an unshareable connection is
open, the physical connection is unavailable to any other component, even if your application is not
currently using that connection. Unlike a shareable connection, an ushareable connection is not closed
at the end of a transaction or servlet call.
v Deadlock considerations. Depending on how your components interact with the database within a
transaction, using unshared connections can lead to deadlock in the database. For example, within a
transaction, component A gets a connection to data source X and updates table 1, and then calls
component B. Component B gets another connection to data source X, and updates/reads table 1 (or
even worse the same row as component A). In some circumstances, depending on the particular
database, its locking scheme, and the transaction isolation level, a deadlock can occur.
In the same scenario, but with a shared connection, deadlock does not occur because all the work is
done on the same connection. It is worth noting that when writing code that uses shared connections,
you use a strategy that calls for multiple work items to be performed on the same connection, possibly
within the same transaction. If you decide to use an unshareable connection, you must set the
maximum connections property on the connection factory or data source correctly. An exception might

Chapter 8. Developing WebSphere applications 1347

 occur for waiting connection requests if you exceed the maximum connections value, and unshareable
connections are not being closed before the connection wait time-out is exceeded.

Shareable connections: Some characteristics of connection handles that are retrieved with a
res-sharing-scope of shareable are described in the following sections.

The possible benefits of shared connections

v Within an instance of connection sharing, application components can share a managed connection with
one or more connection handles, depending on how the handle is retrieved and which connection
properties are used.
v They can more efficiently use resources. Shareable connections are not valid outside of their sharing
boundary. For this reason, at the end of a sharing boundary (such as a transaction) the connection
handle is no longer associated with the managed connection it was using within the sharing boundary
(this applies only when using the cached handle pattern). The managed connection is returned to the
free connection pool for reuse. Connection resources are not held longer than the end of the current
sharing scope.
If the cached handle pattern is used, then the next time the handle is used within a new sharing scope,
the application server run time ensures that the handle is reassociated with a managed connection that
is appropriate for the current sharing scope, and has the same properties with which the handle was
originally retrieved. Remember that it is not appropriate to change properties on a shareable connection.
If properties are changed, other components that share the same connection might experience
unexpected behavior. Futhermore, when using cached handles, the value of the changed property might
not be remembered across sharing scopes.

The possible drawbacks of shared connections

v Sharing within a single component (such as an enterprise bean and its related Java objects) is not
always supported. The current specification allows resource adapters the choice of only allowing one
active connection handle at a time.
If a resource adapter chooses to implement this option then the following scenario results in an invalid
handle exception: A component using shareable connections gets a connection and uses it. Without
closing the connection, the component calls a utility class (Java object) that gets a connection handle to
the same managed connection and uses it. Because the resource adapter only supports one active
handle, the first connection handle is no longer valid. If the utility object returns without closing its
handle, the first handle is not valid and triggers an exception at any attempt to use it.

Note: This exception occurs only when calling a utility object (a Java object).
Not all resource adapters have this limitation; it occurs only in certain implementations. The WebSphere
Relational Resource Adapter (RRA) does not have this limitation. Any data source used through the
RRA does not have this limitation. If you encounter a resource adapter with this limitation you can work
around it by serializing your access to the managed connection. If you always close your connection
handle before getting another (or close your handle before calling code that gets another handle), and
before returning from a method, you can allow two pieces of code to share the same managed
connection. You simply cannot use the connection for both events at the same time.
v Trying to change the isolation level on a shareable JDBC-based connection in a global transaction (that
is supported by the RRA) causes an exception. The correct way to get connections with different
transaction isolation levels is by configuring the IBM extended resource-reference.
v Closing connection handles for shareable connections by an application is NOT supported and causes
errors. However, you can avoid this limitation by using the Relational Resource Adapter.

Lazy connection association optimization: In WebSphere Application Server Version 5.0, the Java 2
Platform, Enterprise Edition (J2EE) Connector (J2C) connection manager implemented smart handle
support. This technology enables allocation of a connection handle to an application while the managed
connection associated with that connection handle is used by other applications (assuming that the
connection is not being used by the original application). This concept is part of the J2EE Connector
Architecture (JCA) 1.5 specification. (You can find it in the JCA 1.5 specification document in the section

1348 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
entitled ″Lazy Connection Association Optimization.″) Smart handle support introduces use a method on
the ConnectionManager object, the LazyAssociatableConnectionManager() method , and a new marker
interface, the DissociatableManagedConnection class. You must configure the provider of the resource
adapter to make this functionality available in your environment. (In the case of the RRA, WebSphere
Application Server itself is the provider.) The following code snippet shows how to include smart handle
support:
package javax.resource.spi;
import javax.resource.ResourceException;

interface LazyAssociatableConnectionManager { // application server

void associateConnection(
Object connection, ManagedConnectionFactory mcf,
ConnectionRequestInfo info) throws ResourceException;
}

interface DissociatableManagedConnection { // resource adapter

void dissociateConnections() throws ResourceException;
}

This DissociatableManagedConnection interface introduces another state to the Connection object:

inactive. A Connection can now be active, closed, and inactive. The connection object enters the inactive
state when a corresponding ManagedConnection object is cleaned up. The connection stays inactive until
an application component attempts to re-use it. Then the resource adapter calls back to the connection
manager to re-associate the connection with an active ManagedConnection object.

Connections and transactions:

All connection usage occurs within the scope of either a global transaction or a local transaction
containment (LTC) boundary.

Connection behavior depends on your current operating scope. This article discusses some of the
common characteristics you see when using connections in one of the transaction scopes.

You can only share connections within a global transaction scope (assuming other sharing rules are met).
However, you can serially reuse connections within an LTC scope. A get/use/close connection pattern
followed by another instance of get/use/close (to the same data source or connection factory) enables you
to reuse the same connection. See the “Unshareable and shareable connections” on page 1343 topic for
more details.

JDBC AutoCommit behavior

All JDBC connections, when first obtained through a getConnection() call, contain the setting AutoCommit
= TRUE by default.
v If you operate within an LTC and have its resolution-control set to Application, then AutoCommit remains
TRUE unless changed by the application.
v If you operate within an LTC and have its resolution-control set to ContainerAtBoundary, then the
application should not touch the AutoCommit setting. The WebSphere Application Server run time sets
the AutoCommit value to FALSE before work begins, then commits or rolls back the work as appropriate
at the end of the LTC scope.
v If you use a connection within a global transaction, the database ignores the AutoCommit setting so that
the transaction service that controls the commit and rollback processing can manage the transaction.
This action takes place upon first use of the connection to do work, regardless of the user changing the
AutoCommit setting. After the transaction completes, the AutoCommit value returns to the value it had
before the first use of the connection. So even if the AutoCommit value is set to TRUE before the
connection is used in a global transaction, you need not set the value to FALSE since the value is
ignored by the database. In this example, after the transaction completes, the AutoCommit value of the
connection returns to TRUE.

Chapter 8. Developing WebSphere applications 1349

v If you use multiple distinct connections within a global transaction, all work is guaranteed to commit or
roll back together. This is not the case for a local transaction containment (LTC scope). Within an LTC,
work done on one connection commits or rolls back independently from work done on any other
connection within the LTC.

One-phase commit and two-phase commit resources: One-phase commit resources are such that work
being done on a one phase connection cannot mix with other connections and ensure that the work done
on all of the connections completes or fails atomically . The product does not allow more than one
one-phase commit connection in a global transaction. Futhermore, it does not allow a one-phase commit
connection in a global transaction with one or more two-phase commit connections. You can coordinate
only multiple two-phase commit connections within a global transaction.

WebSphere Application Server provides last participant support that enables a single one-phase commit
resource to participate in a global transaction with one or more two-phase commit resources.

Note that any time you do multiple getConnection() calls using a resource reference that specifies
res-sharing-scope=Unshareable , then you get multiple physical connections. This situation also occurs
when res-sharing-scope=Shareable, but the sharing rules are broken. In either case, if you run in a global
transaction, ensure the resources involved are enabled for two-phase commit (also sometimes referred to
as JTA Enabled). Failure to do so results in an XA exception that logs the following message: WTRN0063E:
An illegal attempt to enlist a one phase capable resource with existing two phase capable
resources has occurred.

Passing client information to a database: Some databases enable you to set client information on the
database connections using a backend-specific proprietary connection API. For some databases (such as
DB2) you can also set the client information as a data source property. WebSphere Application Server
before Version 6.0 only enables setting the client information as a data source property. This capability is
somewhat limited, however, because the client information cannot be dynamically changed on the data
source or the connections obtained from that data source. Also, setting the client information on the data
source causes all connections created from that data source to have the same information. For example, if
you set the ApplicationName as part of the data source clientInformation, all connections from that data
source have the same application name. Because many different applications can access the same data
source, this might not be desired.

With WebSphere Application Server Version 6.0, you can set the client information on some connections
and not others, and you can set different client information on different database connections from the
same data source. You can pass client information in one of two ways:
v Explicitly, by calling a proprietary API, setClientInformation(Properties) on the
com.ibm.websphere.rsadapter.WSConnection.
v Implicitly, using the WAS.clientinfo trace string. You can enable this dynamically from the administrative
console just like a normal trace. For more information about passing client information implicitly, see
“Setting client information implicitly” on page 1351.

The API is defined on the WSConnection class which is part of the com.ibm.websphere.rsadapter
package. You must cast your database connection in your applications to
com.ibm.websphere.rsadapter.WSConnection before calling the API, as this is a WebSphere Application
Server proprietary API. The API takes a properties object as an input parameter that provides the flexibility
of adding new client information if and when it is introduced by the backend database, without any
changes to this API itself.
public void setClientInformation (Properties props)throws SQLException;

For an example of using this API, see “Example: setClientInformation(Properties) API.”

Example: setClientInformation(Properties) API:

1350 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Usage Scenario

This API enables you to set client information on the WebSphere Application Server connection. Some of
the client information is passed on to the backend database if that database supports such functionality.

Example
import com.ibm.websphere.rsadapter.WSConnection;
.....
try {
InitialContext ctx = new InitialContext();
//Perform a naming service lookup to get the DataSource object.
DataSource ds = (javax.sql.DataSource)ctx.lookup("java:comp/jdbc/myDS");
}catch (Exception e) {System.out.println("got an exception during lookup: " + e);}

WSConnection conn = (WSConnection) ds.getConnection();

Properties props = new properties();
props.setProperty(WSConnection.CLIENT_ID, "user123");
props.setProperty(WSConnection.CLIENT_LOCATION, "127.0.0.1");
props.setProperty(WSConnection.CLIENT_ACCOUNTING_INFO, "accounting");
props.setProperty(WSConnection.CLIENT_APPLICATION_NAME, "appname");
props.setProperty(WSConnection.CLIENT_OTHER_INFO, "cool stuff");
conn.setClientInformation(props);
conn.close()

Parameters

props contains the client information to be passed. Possible values are:

v WSConnection.CLIENT_ACCOUNTING_INFO
v WSConnection.CLIENT_LOCATION
v WSConnection.CLIENT_ID
v WSConnection.CLIENT_APPLICATION_NAME
v WSConnection.CLIENT_OTHER_INFO
v WSConnection.OTHER_CLIENT_TYPE

Refer to the WSConnection documentation for more details on which client information is passed to the
backend database. To reset the client information, call the method with a null parameter.

Exceptions

This API creates an SQL exception if the database issues an exception when setting the data.

Setting client information implicitly: You can choose to explicitly pass client information of application
requests to database connections by calling an IBM proprietary API, setClientInformation(Properties), on
the com.ibm.websphere.rsadapter.WSConnection object within your application code. In some cases,
however, you might want WebSphere Application Server to handle the passing of client information to
database connections. This method of setting the client information is referred to as implicit. You might
choose the implicit method because:
v You want to keep your application free of proprietary APIs, or
v Your application uses container-managed persistence (CMP), in which case you cannot use the
proprietary API to set client information on database connections.

The WebSphere Application Server trace facility provides the capability for setting client information
implicitly. You can designate one of two special trace groups to enable or disable client information
passing: WAS.clientinfo trace or WAS.clientinfopluslogging trace .

Note:

Chapter 8. Developing WebSphere applications 1351

 Connection sharing:
In the case of connection sharing, setting the client information implicitly is done only on the
first acquired connection handle. If connection sharing is enabled and two or more
getConnection() methods are called (resulting in two handles on the same connection), then
only the first getConnection() call causes the client information to be implicitly passed to the
back-end database. This is not true for the explicit case; every setClientinformation()
method is driven down to the database regardless of connection sharing.
Implicit/explicit co-existence:
When both explicit and implicit are used, some combination of the explicitly set data and
implicitly set data is combined, but for the most part the explicit takes precedence. For
example, if the application sets the client accounting information to ″myAccountingInfo″, the
final accountingInfo string that is passed to the backend database looks something like:
000325_WSRdbManagedConnectionImpl@1234_myAccountingInfo: where 000325 is the
thread id, WSRdbManagedConnectionImpl@1234 is the websphere connection instance.
Client information reset:
In the implicit case, client information is reset when the connection is put back in the pool
and only if the WAS.clientinfo and WAS.clientinfopluslogging are disabled (that is,
WAS.clientinfo=all=disabled:WAS.clientinfopluslogging=all=disabled).
In the explicit case however, the reset is done only when the application issues
setClientInformation(null) on the WSConnection.

WAS.clientinfo trace

By default, the implicit mechanism is disabled. You can turn on this mechanism dynamically (without
stopping and starting your application server) or statically by setting the WebSphere Application Server
trace group WAS.clientinfo=all=enabled.

The information implicitly collected and set on the database connection consists of the user name, user
location and application name.

Note: User name and user location can only be implicitly collected and set on the database connection if
you enable WebSphere global security.
username
Name of the user that initiated the application request. This option is collected and passed to the
backend database (when supported) only if WebSphere global security is enabled. Information
here is collected by calling WSSecurityHelper.getFirstCaller().
user location
In the form of cell:node:server. This option is collected and passed to the backend database (when
appropriate) only when WebSphere global security is enabled. Information here is collected by
calling WSSecurityHelper.getFirstServer().
application name
Name of the application running. This value is the output of getApplication() from the J2EEName
object. This value is collected regardless of the Global Security setting.

WAS.clientinfopluslogging trace

When debugging database problems, such as deadlocks, there is a set of information that is needed to
help with the debugging effort. This information is typically obtained by enabling RRA trace, and EJB
container trace. However, there are some cases where timing is an issue when reproducing a given
problem. Having too much tracing information can alter the behavior of the application (such as change
the timing), and the problem might no longer occur.

1352 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Because of this, a new trace group is provided where only a minimum set of information is collected. This
trace group is WAS.clientinfopluslogging. This function sets the client information implicitly on the
connection (just like the WAS.clientinfo trace), as well as logs and traces important application activities.
Those activities are:
v SQL Strings that were run (such as, select userId from tabl1 where id=? for update).
v Start, commit, and rollback of transactions.
v EJB calls (such as, Create, Remove, findByPrimaryKey, and so on).

Cache instances
An application uses a cache instance to store, retrieve, and share data objects within the dynamic cache.

Each cache instance can be configured independently for Java Naming and Directory Interface (JNDI)
name, cache size, priority, and disk offload. Objects that are stored in a particular cache instance are not
affected by other cache instances. This means that if you store an object named object_1 with a value of
object_data in cache_instance_x, you can also store an object with the same name, but different value in
cache_instance_y.

Objects that are stored in a particular cache instance are available to applications on other servers by
accessing a cache instance of the same name. The two servers must be within the same replication
domain to share data.

There are two types of cache instances, object cache instances and servlet cache instances.

An object cache instance is a location in addition to the default shared dynamic cache where Java 2
Platform, Enterprise Edition (J2EE) applications can store, distribute, and share objects. After configuring
object cache instances, you can use the DistributedMap or DistributedObjectCache interfaces in the
com.ibm.websphere.cache package to programmatically access your cache instances. See the for more
information about the DistributedMap or DistributedObjectCache interfaces.

Servlet cache instances are locations in addition to the default dynamic cache where dynamic cache can
store, distribute, and share the output and the side effects of an invoked servlet. By configuring a servlet
cache instance, your applications have greater flexibility and better tuning of cache resources. The Java
Naming and Directory Interface (JNDI) name that is specified for the cache instance in the administrative
console maps to the <cache-instance> element in the cachespec.xml configuration file. Any <cache-entry>
elements that are specified within a <cache-instance> element are created in that specific cache instance.
Any <cache-entry> elements that are specified outside of a <cache-instance> element are stored in the
default dynamic cache instance. See ″Using servlet cache instances″ in the information center for more
information.

Resource adapter archive file

A Resource Adapter Archive (RAR) file is a Java archive (JAR) file used to package a resource adapter for
the Java 2 Connector (J2C) Architecture for WebSphere Application Server.

A RAR file can contain the following:

v Enterprise information system (EIS) supplied resource adapter implementation code in the form of JAR
files or other runnable components, such as dynamic link lists.
v Utility classes.
v Static documents, such as HTML files, images, and sound files.

The standard file extension of a RAR file is .rar.

Data access : Resources for learning

Use the following links to find relevant supplemental information about data access. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of the
information.

Chapter 8. Developing WebSphere applications 1353

These links are provided for convenience. Often, the information is not specific to this product but is useful
all or in part for understanding the product. When possible, links are provided to technical papers and
Redbooks that supplement the broad coverage of the release documentation with in-depth examinations of
particular product areas.

View links to additional information about:

v Programming Specifications
v CMP persistence functions
v Container-managed relationships
v Resource references
v Resource adapters
v Miscellaneous articles from the Sun Developer Network and IBM developerWorks Web sites
v Rational Application Developer
v WebSphere Version 5.x Information Center
v IBM Cloudscape
v Oracle
v DB2 database software
v Supported hardware, software, and APIs

Programming Specifications
v Enterprise JavaBeans Technology (Source for download of the Enterprise Javabeans 2.1 specification)
v JavaTM 2 Platform, Enterprise Edition (J2EETM)
v JavaTM Management Extensions (JMX)
v JDBCTM 3.0 API Documentation
v J2EE Connector Architecture Version 1.5 specification
v What’s New in the J2EE Connector Architecture 1.5
v What’s New in the J2EE Connector Architecture 1.5 (Part 2)

CMP persistence functions

Though this article addresses the EJB 2.0 specification, you still might find parts of it pertinent to your
environment.
v Enterprise JavaBeansTM 2.0 Container-Managed Persistence Example

Container-managed relationships

Though this article addresses the EJB 2.0 specification, you still might find parts of it pertinent to your
environment.
v Enterprise JavaBeansTM 2.0 Container-Managed Persistence Example

Resource references

Though this article addresses the EJB 2.0 specification, you still might find parts of it pertinent to your
environment.
v Accessing Databases from Web Applications

Resource adapters
v The J2EE Connector Architecture Resource Adapter

Miscellaneous articles from the Sun Developer Network and IBM developerWorks Web sites
v Developer Technical Articles & Tips -- Articles: Database Access (Sun Developer Network)
v Sharing connections in WebSphere Application Server V5 (Still pertinent to WebSphere Application
Server Version 6.0)
v Database authentication in WebSphere Application Server V5 (Still pertinent to WebSphere Application
Server Version 6.0)
v Understanding WebSphere Application Server EJB access intents

1354 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Rational Application Developer
v Rational Application Developer for WebSphere Software

WebSphere Version 5.x Information Center

v IBM WebSphereTM Version 5.x Information Center

IBM Cloudscape
v IBM Cloudscape
v developerWorks article: Cloudscape Network Server with WebSphere Application Server

Oracle
v Oracle

DB2 database software

v DB2

Supported hardware, software, and APIs

v Supported hardware, software, and APIs

Deploying data access applications

Before installing a data access application into the WebSphere Application Server environment, you must
first ensure that the appropriate database objects are available. This action includes creating and
configuring any databases or tables required, setting necessary configuration parameters to handle
expected load, and configuring any necessary JDBC providers and data source objects for servlets,
enterprise beans, and client applications to use.
1. If your database configuration does not already exist:
a. Create a database to hold the data.
b. Create tables required by your application.
If your application uses entity enterprise beans to access the data
You can create the tables using the data definition language (DDL) generated from the
enterprise bean configuration. For more information, see Recreating database tables from
the exported table data definition language.
If your application does not use entity beans
You must use your database server interfaces to create the tables.
c. See Minimum required properties for vendor-specific data sources for certain vendors’ databases
requirements.
2. Migrate Version 4.0 data access applications
3. If your enterprise application contains a Web application or an EJB application that uses connection
pooling to access a relational database, see “Creating and configuring a JDBC provider and data
source” on page 1364.
4. If your application requires access to a non-relational database, you need to configure a resource
adapter and a connection factory rather than a JDBC provider and a data source.
5. If your enterprise application contains an application client that accesses a relational database, see
Configuring data access for application clients.
6. Consider the security of lookups with component managed authentication. See Security of lookups with
component managed authentication for more information.

Relationship of assembly and administrative console data access settings

This article provides miscellaneous tips for using supported databases. See also the related links.

Always consult the product documentation for a list of the database brands and versions that are
supported by your particular WebSphere Application Server version, edition, and FixPak.

Chapter 8. Developing WebSphere applications 1355

Notes about various databases
v When using local DB2 databases for data access by session clients on AIX Version 4.3.3 or later
versions, in some cases you cannot establish multiple connections for session clients. This is because
AIX , by default, does not permit 32-bit applications to attach to more than 11 shared memory segments
per process. Of these 11 shared segments, a maximum of 10 can be used for local DB2 connections.
To use EXTSHM with DB2 and avoid stale connections when there are large numbers of session
clients, do the following:
– In DB2 client environment (that is the WebSphere Application Server run time environment in this
case):
export EXTSHM=ON
– In DB2 UDB Server environment:
export EXTSHM=ON
db2set DB2ENVLIST=EXTSHM
v When using Sybase 11.x, you might encounter the following error when HttpSession persistence is
enabled:
DBPortability W Could not create database table: "sessions"
com.sybase.jdbc2.jdbc.SybSQLException: The ’CREATE TABLE’ command is not
allowed within a multi-statement transaction in the ’database_name’ database

where database_name is the name of the database for holding sessions.

If you encounter the error, issue the following commands at the Sybase command line:
use database_name
go
sp_dboption db,"ddl in tran ",true
go
v Sybase 12.0 does not support local transaction modes with a JTA enabled data source. To use a
connection from a JTA enabled data source in a local transaction, install Sybase patch EBF9422.

Additional administrative tasks for specific databases

For your convenience, this article provides instructions for enabling some popular database drivers, and
performing other administrative tasks often required to provide data access to applications running on
WebSphere Application Server. These tasks are performed outside of the WebSphere Application Server
administrative tools, often using the database product tools. Always refer to the documentation
accompanying your database driver as the authoritative and complete source of driver information.

See the Supported hardware, software, and APIs for the latest information about supported databases,
drivers, and operating systems.
Enabling JDBC 2.0
Ensure that your operating system environment is set up to support JDBC 2.0. This action is
required to use data sources created through WebSphere Application Server.
The following steps make it possible to find the appropriate JDBC 2.0 driver for use with
WebSphere Application Server administration:
Enabling JDBC 2.0 with DB2 on Windows NT systems
To enable JDBC 2.0 use on Windows NT systems:
v For DB2 Version 7.2
1. Stop the DB2 JDBC Applet Server service.
2. Run the following batch file:
SQLLIB\java12\usejdbc2.bat
3. Stop WebSphere Application Server (if it is running) and start it again.
v For DB2 Version 8.1
– JDBC 2.0 is supported by default, there are no additional steps for you to perform.
Perform the steps once for each system.

1356 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Determining the level of the JDBC API in use for DB2 on Windows NT systems
To determine the JDBC level in use on your system:
v For DB2 Version 7.2
– If JDBC 2.0 is in use, this file exists:
SQLLIB\java12\inuse
– If JDBC 1.0 is in use, this file exists:
SQLLIB\java11\inuse

or no java11 directory exists.

v For DB2 Version 8.1
– Go to directory SQLLIB\samples\java, compile and run the class db2JDBCVersion.java.
Enabling JDBC 2.0 with DB2 on UNIX systems
v For DB2 Version 7.2
– Before starting WebSphere Application Server, call $INSTHOME/sqllib/java12/usejdbc2 to
use JDBC 2.0. For convenience, you might want to put this in your root user’s startup script.
For example, on AIX, add the following to the root user’s .profile:
if [ -f /usr/lpp/db2_07_01/java12/usejdbc2 ] ; then
. /usr/lpp/db2_07_01/java12/usejdbc2
fi
v For DB2 Version 8.1
– JDBC 2.0 is supported by default, there are no additional steps for you to perform.
Determining the level of the JDBC API in use for DB2 on UNIX systems
v For DB2 Version 7.2
– To determine if you are using JDBC 2.0, you can echo $CLASSPATH. If it contains
$INSTHOME/sqllib/java12/db2java.zip
then JDBC 2.0 is in use.
If it contains
$INSTHOME/sqllib/java/db2java.zip
then JDBC 1.0 is in use.
v For DB2 Version 8.1
– Go to directory sqllib/samples/java, compile and run the class db2JDBCVersion.java.
Sourcing the db2profile script on UNIX systems
Before starting WebSphere Application Server to host applications requiring data access, source
the db2profile:
. ~db2inst1/sqllib/db2profile

where db2inst1 is the user created during DB2 installation.

Using Java Transaction API drivers
Instructions are available for using Java Transaction API (JTA) drivers on particular operating
systems. See your operating system documentation for more information.
The goal of this section is to provide information about the steps that make DB2 work well with
applications utilizing XA classes -- that is, those whose dataSourceClasses implement
javax.sql.XADataSource.
Using Java Transaction API drivers for DB2 on Windows NT systems
To enable JTA drivers for DB2 on Windows NT systems, follow these steps:
1. Bind the necessary packages to the database. From the DB2 Command Line Processor
window, issue the following commands:
db2=> connect to mydb2jta
db2=> bind db2home\bnd\@db2cli.lst
db2=> bind db2home\bnd\@db2ubind.lst
db2=> disconnect mydb2jta

Chapter 8. Developing WebSphere applications 1357

 where mydb2jta is the name of the database to enable for the JTA, and db2home is the DB2
root installation directory path (for example, D:\ProgramFiles\SQLLIB\bnd\@db2cli.lst).
2. Specify the following settings when you use an IBM WebSphere Application Server
administrative client (such as the administrative console) to configure a JDBC driver:
v Server class path = %DB2_ROOT%/Sqllib/java/db2java.zip
v Implementation class name = COM.ibm.db2.jdbc.DB2XADataSource
Using Java Transaction API drivers for DB2 on UNIX systems
To enable JTA drivers on UNIX systems, follow these steps:
1. Stop all DB2 services.
2. Stop the IBM WebSphere Application Server administrative service.
3. Stop any other processes that use the db2java.zip file.
4. Make sure that you already enabled JDBC 2.0.
5. Start the DB2 services.
6. Bind the necessary packages to the database. From the DB2 command-line process or
window, issue the following commands:
db2=> connect to mydb2jta
db2=> bind db2home\bnd\@db2cli.lst
db2=> bind db2home\bnd\@db2ubind.lst
db2=> disconnect mydb2jta
7. Specify the following settings when you use an IBM WebSphere Application Server
administrative client (such as the administrative console) to configure a JDBC driver:
v Server class path = $INSTHOME/sqllib/java12/db2java.zip
For example, if $INSTHOME is /home/test, the path will be
/home/test/sqllib/java12/db2java.zip
v Implementation class name = COM.ibm.db2.jdbc.DB2XADataSource
For Oracle 8.1.7 two phase commit support
You can use the Oracle 8.1.7 thin driver for JTA two-phase support with the following restrictions:
v The thin driver that comes shipped with 8.1.7 might or might not work. Future patches from
Oracle might work as well, but are not tested. The driver that was available from the Oracle
Technology Network Web site as of February 20, 2001 does work and is the recommended
driver. Later versions on this Web site are expected to work, but are not tested.
To obtain the driver from the Oracle support Web site, visit:
http://technet.oracle.com/
You need to be a registered user for the Oracle Technology Network to get the driver from this
site. Contact Oracle for access. After you have access download the 8.1.7 driver for the
platforms you use and follow the instructions for installing the new driver.
v You must use the 8.1.7 driver with 8.1.7 databases, 8.1.6 databases do not support the
recover() and forget() methods and other problems are encountered running with 8.1.6. Oracle
does not support JTA with 8.1.6.
v For Oracle, you can only use JTA with container-managed persistence (CMP) beans.
v For the bean to create the table, you must start the bean with the JTA set to false. After the
bean creates the table, you can set the JTA back to true.
v Configure an entity bean that accesses Oracle with JTA set to true as follows:
– Click deployment descriptor properties > Transactions > Remote tab. Set the Transaction
Attribute to TX_REQUIRED.
– Click Isolation > Remote tab. Set the Isolation Level to
TRANSACTION_READ_COMMITTED.
v Configure a session bean that is used with an entity bean that accesses Oracle with JTA set to
true as follows:
– Click deployment descriptor properties > Transactions > Remote tab. Set the Transaction
Attribute to TX_BEAN_MANAGED.
– Click Isolation > Remote tab. Set the Isolation Level to
TRANSACTION_READ_COMMITTED.

1358 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Using Java Transaction API drivers for Sybase products on AIX systems
To enable Java Transaction API (JTA) drivers for use with Sybase products on the AIX operating
system, follow these steps:
1. Enable the Data Transaction Manager (DTM) by issuing these commands (one per line) at a
command prompt:
isql -Usa -Ppassword -Sservername
sp_configure "enable DTM", 1
go
2. Stop the Sybase Adaptive Server database and start it again.
3. Grant the appropriate role authorization to the enterprise bean user at a command prompt:
isql -Usa -Ppassword -Sservername
grant role dtm_tm_role to EJB
go
Notes about Sybase Java Transaction API drivers
Do not use a Sybase Java Transaction API (JTA) connection in an enterprise bean method with an
unspecified transaction context. A Sybase JTA connection does not support the local transaction
mode. The implication is that you must use the Sybase JTA connection in a global transaction
context.

Recreating database tables from the exported table data definition language:

When the WebSphere Application Server deployment tooling deploys an EJB jar file containing
container-managed persistence (CMP) enterprise beans, it selects the target database and creates a
corresponding Table.ddl file. This file contains the SQL statement necessary to generate the database
table for your CMP beans. You must then run the ddl file on your database server to create the tables.

Following is an example of how to use such a Table.ddl file for DB2, on Windows and z/OS:
1. The container-managed bean (CMP) enterprise bean JAR file has a Table.ddl file that the assembly
tool generates. Extract the Table.ddl file to a working directory such as C:\temp.
2. Run this command -- C:\temp>db2cmd A new command window appears in which you enter the
following commands.
3. Run this command -- C:\temp>db2 connect to dbname
4. Run this command -- C:\temp>db2 -tf Table.ddl The command runs and creates tables for your CMP
enterprise bean.
5. Run this command -- C:\temp>db2 disconnect all

Note: If you use DB2 on Unix, use these same commands. Simply run them from a user with
permissions for DB2, rather than from a DB2 command window.

Installing J2EE Connector resource adapters

1. Click Resources.
2. Click Resource Adapters.
3. Select the scope at which you want to define this resource adapter. (This scope becomes the scope of
your connection factory.) You can choose cell, node, cluster, or server. For more information, see
″Administrative console scope settings″ in the information center.
4. Click Install RAR. The Install RAR button opens a dialog that enables you to install a J2EE Connector
Architecture (JCA) connector and create a resource adapter for it. You can also use the New button,
but the New button creates only a new resource adapter (the JCA connector must already be installed
on the system).

Note: When installing a RAR file using this dialog, the scope you define on the Resource Adapters
page has no effect on where the RAR file is installed. You can install RAR files only at the node
level. The node on which the file is installed is determined by the scope on the Install RAR

Chapter 8. Developing WebSphere applications 1359

 page. (The scope you set on the Resource Adapters page determines the scope of the new
resource adapters, which you can install at the server, node, or cell level.)
5. Browse to find the appropriate RAR file.
v If your RAR file is located on your local workstation, select Local path and browse to find the file.
v If your RAR file is located on your server, select Server path and specify the fully qualified path to
the file.
6. Click Next.
7. Enter the resource adapter name and any other properties needed under General Properties. If you
install a J2C Resource Adapter that includes Native path elements, consider the following: If you have
more than one native path element, and one of the native libraries (native library A) is dependent on
another library (native library B), then you must copy native library B to a system directory. Because of
limitations on Windows NT and most Unix platforms, an attempt to load a native library does not look
in the current directory.
8. Click OK.

Installing resource adapters within applications:

1. Assemble an application with resource adapter archive (RAR) modules in it. See ″Assembling
applications″ in the information center.
2. Install the application following the steps in Installing a new application. In the Map modules to
servers step, specify target servers or clusters for each RAR file. Be sure to map all other modules
that use the resource adapters defined in the RAR modules to the same targets. Also, specify the Web
servers as targets that serve as routers for requests to this application. The plug-in configuration file
(plugin-cfg.xml) for each Web server is generated based on the applications that are routed through
it.

Note: When installing a RAR file onto a server, WebSphere Application Server looks for the manifest
(MANIFEST.MF) for the connector module. It looks first in the connectorModule.jar file for the
RAR file and loads the manifest from the _connectorModule.jar file. If the class path entry is in
the manifest from the connectorModule.jar file, then the RAR uses that class path.

To ensure that the installed connector module finds the classes and resources that it needs,
check the Class path setting for the RAR using the console. For more information, see
“Resource Adapter settings” on page 1361 and “WebSphere relational resource adapter
settings” on page 1327.
3. Click Finish > Save to save the changes.
4. Create connection factories for the newly installed application.
a. Open the administrative console.
b. Click Applications > Enterprise Applications > application name.
c. Click Connector Modules in the Related Items section of the page.
d. Click filename.rar.
e. Click Resource adapter in the Additional Properties section of the page.
f. Click J2C Connection Factories in the Additional Properties section of the page.
g. Click on an existing connection factory to update it, or New to create a new one.
If you install a J2C Resource Adapter that includes Native path elements, consider the following: If
you have more than one native path element, and one of the native libraries (native library A) is
dependent on another library (native library B), then you must copy native library B to a system
directory. Because of limitations on Windows NT and most Unix platforms, an attempt to load a
native library does not look in the current directory.
After you create and save the connection factories, you can modify the resource references defined
in various modules of the application and specify the Java Naming and Directory Interface (JNDI)
names of the connection factories wherever appropriate.

1360 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Note: A given native library can only be loaded one time for each instance of the Java virtual machine
(JVM). Because each application has its own classloader, separate applications with embedded
RAR files cannot both use the same native library. The second application receives an
exception when it tries to load the library.

If any application deployed on the application server uses an embedded RAR file that includes
native path elements, then you must always ensure that you shut down the application server
cleanly, with no outstanding transactions. If the application server does not shut down cleanly it
performs recovery upon server restart and loads any required RAR files and native libraries. On
completion of recovery, do not attempt any application-related work. Shut down the server and
restart it. No further recovery is attempted by the application server on this restart, and normal
application processing can proceed.

Resource Adapters collection:

This page contains the list of installed and configured resource adapters and is used to install new
resource adapters, create additional configurations of installed resource adapters or delete resource
adapter configurations.

A resource adapter is an implementation of the J2EE Connector Architecture (JCA) Specification that
provides access for applications to resources outside of the server or provides access for an enterprise
information system (EIS) to applications on the server. It can provide application access to resources such
as DB2, CICS, SAP and PeopleSoft. It can provide an EIS with the ability to communicate with
message-driven beans that are configured on the server. Some resource adapters are provided by IBM;
however, third party vendors can provide their own resource adapters. A resource adapter implementation
is provided in a resource adapter archive file; this file has an extension of .rar. A resource adapter can be
provided as a standalone adapter or as part of an application, in which case it is referred to as an
embedded adapter. Use this panel to install a standalone resource adapter archive file. Embedded
adapters are installed as part of the application installation. This panel can be used to work with either
kind of adapter.

To view this administrative console page, click Resources >Resource Adapters.

Scope:

Specifies the level to which this resource adapter is visible. For general information, see Administrative
console scope settings in the Related Reference section.

Some considerations that you should keep in mind for this particular panel are:
v Changing the scope enables you to see which resource adapter definitions exist at that level.
v Changing the scope does not have any effect on installation. Installations are always done under a
scope of node, no matter what you set the scope to.
v When you create a new resource adapter from this panel, you must change the scope to what you want
it to be before clicking New.

Name:

Specifies the name of the resource adapter.

A string with no spaces meant to be a meaningful text identifier for the resource adapter.

Data type String

Resource Adapter settings:

Chapter 8. Developing WebSphere applications 1361

Use this page to specify settings for a Resource Adapter.

A resource adapter is an implementation of the J2EE Connector Architecture (JCA) Specification that
provides access for applications to resources outside of the server or provides access for an enterprise
information system (EIS) to applications on the server. It can provide application access to resources such
as DB2, CICS, SAP and PeopleSoft. It can provide an EIS with the ability to communicate with message
driven beans that are configured on the server. Some resource adapters are provided by IBM; however,
third party vendors can provide their own resource adapters. A resource adapter implementation is
provided in a resource adapter archive file; this file has an extension of .rar. A resource adapter can be
provided as a standalone adapter or as part of an application, in which case it is referred to as an
embedded adapter. Use this panel to install a standalone resource adapter archive file. Embedded
adapters are installed as part of the application installation.

To view this administrative console page, click Resources >Resource Adapters > resource_adapter.

Scope:

Specifies the level to which this resource definition is visible. For general information, see Administrative
console scope settings in the Related Reference section.

The Scope field is a read only string field that shows where the particular definition for a resource adapter
is located. This is set either when the resource adapter is installed (which can only be at the node level) or
when a new resource adapter definition is added.

Name:

Specifies the name of the resource adapter definition.

This property is required.

A string with no spaces meant to be a meaningful text identifier for the resource adapter.

Data type String

Description:

Specifies a text description of the resource adapter.

A free-form text string to describe the resource adapter and its purpose.

Data type String

Archive path:

Specifies the path to the RAR file containing the module for this resource adapter.

This property is required.

Data type String

Class path:

Specifies a list of paths or JAR file names which together form the location for the resource adapter
classes.

1362 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This includes any additional libraries needed by the resource adapter. The resource adapter code base
itself is automatically added to the class path, but if anything outside the RAR is needed it can be
specified here.

Data type String

Native path:

Specifies a list of paths which forms the location for the resource adapter native libraries.

The resource adapter code base itself is automatically added to the class path, but if anything outside the
RAR is needed it can be specified here.

Data type String

ThreadPool Alias:

Specifies the name of a thread pool that is configured in the server that is used by the resource adapter’s
Work Manager.

If there is no thread pool configured in the server with this name, the default configured thread pool
instance, named Default, is used. This property is only necessary if this resource adapter uses Work
Manager.

Data type String

Pretesting pooled connections to ensure validity

When a database fails, pooled connections that are not valid might exist in the free pool. This scenario is
likely to occur when you have a failingConnectionOnly purge policy, which mandates that only failing
connections be removed from the pool. Whether the remaining connections in the pool are valid varies
with the cause of the failure. Connection pretesting is a way to test connections from the free pool before
giving them to the client.

If your application uses pooled connections, you can enable the PreTest Connections feature in the
administrative console to help prevent your application from obtaining connections that are no longer valid.

The feature is particularly useful for routine database outages. Because these outages are usually
scheduled for periods of low use, connections to the database are likely to be in the free pool rather than
in active use. Active connections are not pretested; pretesting impedes performance during normal
operation. Pretesting ensures that users do not waste time trying to resume connections that became bad
before the outage.
1. In the administrative console, click Resources > JDBC providers.
2. Select a provider and click Data Sources under Additional properties.
3. Select a data source and click WebSphere Application Server data source properties under
Additional properties.
4. Select the PreTest Connections check box.
5. Type a value for the PreTest Connection Retry Interval, which is measured in seconds. This property
determines the frequency with which a new connection request is made after a pretest operation fails.
6. Type a valid SQL statement for the PreTest SQL String. Use a reliable SQL command, with minimal
performance impact; this statement is processed each time a connection is obtained from the free
pool.

Chapter 8. Developing WebSphere applications 1363

 For example, you might specify SELECT COUNT(*) from TESTTABLE. (For an Oracle database, use
SELECT USER FROM DUAL.)

Creating and configuring a JDBC provider and data source

Determine which version of data source you need. If you are using the Enterprise JavaBean (EJB) 1.0
specification or the Java Servlet 2.2 specification, you need the version 4.0 data source; see the topic
Data Sources (Version 4). If you are using more advanced releases of these specifications, see the topic
Data Source collection .
1. Create a JDBC provider.
From the administrative console, see Creating a JDBC provider using the administrative console.
OR
Using the wsadmin scripting client, see ″Configuring a JDBC provider using scripting″ in the
information center.
OR
Using the Java Management Extensions (JMX) API, see Creating a JDBC provider and data source
using the Java Management Extensions API.
2. Create a data source.
From the administrative console, see Creating a data source using the administrative console.
OR
Using the wsadmin scripting client, see ″Configuring new data sources using scripting″ in the
information center. (For V4 data sources, see ″Configuring new WAS40 data sources using scripting.″)
OR
Using the JMX API, see Creating a JDBC provider and data source using the Java Management
Extensions API.
3. Bind the resource reference. See ″Binding to a data source″ in the information center.
4. Test the connection (for non-container-managed persistence usage). See Test connection.

Note: When you save the data source configuration, it is saved in the resource.xml file. You should
not need to modify the jdbc-resource-provider-templates.xml. However, special consideration
should be taken if you need to update the jdbc-resource-provider-templates.xml file. For
details, consult J2EE Connector Architecture migration tips.

Verifying a connection:

Many connection problems can be easily fixed by verifying some configuration parameters. This article
provides a checklist of steps that you must complete to enable a successful connection. Click on the link
for more information on a specific step.

If your connection is still not successful after completing these steps and reviewing the applicable
information, check the SystemOut.log for warning or exception messages. Then use the technical support
search function to find known problems.
1. Create the authentication data alias.
2. Create the JDBC provider.
3. Create a data source.
4. Save the data source.
5. If you created a new authentication alias, restart the server for which you need to verify connectivity.
6. Test the connection
You can test your connection from the data source collection view or the data source details view.
Access either view in the administrative console, and then select a connection from the list. Click the
Test Connection button on the connection.

1364 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Creating and configuring a JDBC provider using the administrative console:

An application installed on WebSphere Application Server accesses a relational database through a JDBC
provider, which is essentially a system-level software driver. For at-a-glance information on which provider
type is appropriate for your database configuration and application requirements, see the JDBC provider
table.

You can easily establish a JDBC provider from the administrative console.
1. Open the administrative console.
2. Click Resources > JDBC Providers.
3. Select the scope of your definition. (This scope becomes the scope of your data source.) You can
choose cell, node, cluster, or server. For more information, see ″Administrative console scope
settings″ in the information center.
4. Click New.

Note: If Java script is disabled for your browser, you do not see the three drop-down lists that are
described in the next three steps (for database type, provider type, and implementation type) .
Instead, you see a single drop-down box that lists all JDBC provider choices simultaneously
(inclusive of every database, provider, and implementation type).
5. Use the first drop-down list to select the database type of the JDBC provider you need to create. If
the list of supported JDBC provider types does not include the JDBC provider that you want to use,
select the User-Defined JDBC Provider. Then consult the JDBC provider vendor’s documentation
for information on specific properties required for data sources associated with this provider, and skip
to step eight of this list.
6. From the second drop-down list, select your JDBC provider type.
7. From the third drop-down list, select the implementation type necessary for your application. If your
application does not require that connections support two-phase commit transactions, choose
Connection Pool Data Source. Choose XA Data Source, however, if your application requires
connections that support two-phase commit transactions. Applications using this data source
configuration have the benefit of container-managed transaction recovery.
8. Click Next to view the general property settings page for your JDBC provider.
9. Ensure that all required properties have valid values. For more information, see JDBC Provider
settings.
10. Click Apply to view the page with your new JDBC provider settings. Note that two active data source
links now appear under the Additional Properties heading on this page. To set up a data source,
click the link that corresponds to the type required by your application, the Version 4 data source or
the later version data source. (For more information, refer to the section entitled ″Choice of data
source″ in the “Data sources” on page 1334 topic.)
11. Click OK to return to the JDBC providers page, where your new JDBC provider appears in the list.

For more information about creating a data source for association with your JDBC provider, see “Creating
and configuring a data source using the administrative console” on page 1370.

JDBC Provider collection:

Use this page to view a JDBC provider.

To view this administrative console page, click Resources > JDBC Providers in the console navigation
tree.

Notice the Scope of your JDBC provider. If you pick anything other than the default of Node the provider
might not be available in other scope contexts. New items created in this view are created within the
selected scope.

Chapter 8. Developing WebSphere applications 1365

Name:

Specifies a text identifier for this provider.

For example, this field can be DB2 JDBC Provider (XA).

Data type String

Description:

Specifies a text string describing this provider.

Data type String

JDBC provider settings:

Use this page to create or modify JDBC provider settings.

To view this administrative console page, click Resources > JDBC Providers > JDBC_provider.

Name:

Specifies the name of the resource provider.

Data type String

Description:

Specifies a text description for the resource provider.

Data type String

Class path:

Specifies a list of paths or JAR file names which together form the location for the resource provider
classes.

For example, D:/SQLLIB/java/db2java.zip.

Class path entries are separated by using the ENTER key and must not contain path separator characters
(such as ’;’ or ’:’). Class paths contain variable (symbolic) names which you can substitute using a variable
map. Check the driver installation notes for the specific required JAR file names.

Data type String

Native Library Path:

Specifies a list of paths that forms the location for the resource provider native libraries.

Native path entries are separated by using the ENTER key and must not contain path separator
characters (such as ’;’ or ’:’). Native paths can contain variable (symbolic) names which you can substitute
using a variable map.

1366 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type String

Implementation class name:

Specifies the Java class name of the JDBC driver implementation.

This class is available in the driver file mentioned in the class path description above. For example,
COM.ibm.db2.jdbc.DB2XADataSource.

Note: If you modify the implementation class name of the JDBC provider after you have created the
provider, you might disconnect the provider from the template used to create it. As a result, data
sources created from this JDBC provider do not have an associated template; you must manually
configure a working data source through setting custom properties.

Data type String

New JDBC Provider:

Use this page to create a new JDBC provider.

To view this administrative console page, click Resources >JDBC Providers > New.

Step 1: Select the database type:

Choose a supported database type.

If the list of supported database types does not include the type that you want to use, select
User-Defined. You might need to consult the documentation for the database for more information on
specific properties that database requires.

Data type Drop-down list

Step 2: Select the JDBC provider type:

Choose a supported JDBC Provider type.

Only JDBC provider types that are appropriate for the database type you selected in step 1 will appear in
the list. For at-a-glance information on which provider type is appropriate for your database configuration
and application requirements, see the JDBC provider table.

Data type Drop-down list

Step 3: Select the implementation type:

Choose a supported implementation type.

Only the implementation types supported by the JDBC provider you selected in step 2 will appear in the
list.

Note: If two choices appear on the implementation type list, select Connection Pool DataSource if your
application runs in a single phase or local transaction. Otherwise, choose XA DataSource to run in
a global transaction.

Chapter 8. Developing WebSphere applications 1367

Data type Drop-down list

JDBC provider summary:

Version and other

Database type JDBC Provider Transaction support
considerations
DB2 Universal JDBC One phase only
Provider
DB2 Universal JDBC One and two phase
DB2 on Windows, UNIX, Provider (XA)
or workstation-based
LINUX DB2 legacy CLI-based Type One phase only
2 JDBC Provider
DB2 legacy CLI-based Type One and two phase
2 JDBC Provider (XA)
DB2 UDB for iSeries One phase only Recommended for use with
(Native) WebSphere Application
Server run on iSeries
DB2 UDB for iSeries One and two phase Recommended for use with
(Native XA) WebSphere Application
Server run on iSeries
DB2 UDB for iSeries One phase only Recommended for use with
(Toolbox) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 UDB for iSeries One and two phase Recommended for use with
(Toolbox XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 UDB for iSeries DB2 legacy CLI-based Type One phase only -Only for use with
2 JDBC Provider WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect driver (available
from DB2)
DB2 legacy CLI-based Type One and two phase -Only for use with
2 JDBC Provider (XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect driver (available
from DB2)

1368 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Version and other
Database type JDBC Provider Transaction support
considerations
DB2 for z/OS Local JDBC One and two phase Only for use with
Provider (RRS) WebSphere Application
Server run on z/OS
DB2 Universal JDBC One phase only Only for use with
Provider WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 Universal JDBC One and two phase Only for use with
Provider (XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 legacy CLI-based Type One phase only -Only for use with
DB2 on z/OS 2 JDBC Provider WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect program (available
from DB2)
DB2 legacy CLI-based Type One and two phase -Only for use with
2 JDBC Provider (XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect program (available
from DB2)
Cloudscape JDBC Provider One phase only - Not for use in clustering
environment: Cloudscape is
accessible from a single
JVM only

- Does not support Version

4 data sources
Cloudscape JDBC Provider One and two phase - Not for use in clustering
Cloudscape
(XA) environment: Cloudscape is
accessible from a single
JVM only

- Does not support Version

4 data sources
Cloudscape Network Server One phase only Does not support Version 4
using Universal JDBC driver data sources
Informix JDBC Driver One phase only
Informix
Informix JDBC Driver (XA) One and two phase
Sybase JDBC Driver One phase only
Sybase
Sybase JDBC Driver (XA) One and two phase
Oracle JDBC Driver One phase only
Oracle
Oracle JDBC Driver (XA) One and two phase

Chapter 8. Developing WebSphere applications 1369

 Version and other
Database type JDBC Provider Transaction support
considerations
DataDirect ConnectJDBC One phase only Only for use with the
type 4 driver for MS SQL corresponding driver from
Server DataDirect Technologies
DataDirect ConnectJDBC One and two phase Only for use with the
type 4 driver for MS SQL corresponding driver from
Server (XA) DataDirect Technologies
WebSphere embedded One phase only - Not available for
ConnectJDBC driver for MS Application Server on z/OS
MS SQL Server SQL Server
- Cannot be used outside of
WebSphere Application
Server environment
WebSphere embedded One and two phase - Not available for
ConnectJDBC driver for MS Application Server on z/OS
SQL Server (XA)
- Cannot be used outside of
WebSphere Application
Server environment

Creating and configuring a data source using the administrative console:

After you create a JDBC provider, you must create a data source to access the backend data store.
Application components use the data source to access connection instances to your database; a
connection pool is associated with each data source. The product supports two different versions of data
source:
v Version 4.0, for use with the Enterprise JavaBeans (EJB) 1.0 specification and the Java Servlet 2.2
specification
v The latest standard version for use with more advanced releases of these specifications
1. Open the administrative console.
2. Click Resources > JDBC Providers.
3. Choose the JDBC resource provider under which you want to create your data source. The detail page
for this provider is displayed.
4. Under Additional Properties, click the Data Sources link that is appropriate for your application. The
Data sources or Data sources (Version 4) page is displayed.
5. Click New to display the Data source settings page.
6. Verify that all the required properties have valid values.
For data sources of the latest standard version:
a. Select a DataStoreHelper class name from the list entitled DataStoreHelpers provided by
WebSphere Application Server, or leave the default selection as is. If you want to use a data store
helper other than those available in the drop-down list, click Specify a user-defined
DataStoreHelper. Type a fully qualified class name in the field that is provided.
b. The next section of properties varies according to the database selection, provider type, and
implementation that you chose for your JDBC provider. These properties are either required or
highly recommended for your data source. Provide valid values for these settings if you do not
want to accept the default values.
c. Click Component-managed Authentication Alias if your database requires a user ID and
password for a connection. This alias is used only when the application resource reference is using
res-auth = Application.
Important:(For components with res-auth=Container) Both the Container-managed Authentication
Alias and Mapping-Configuration Alias settings are deprecated. They are superseded by the

1370 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 specification of a login configuration on the resource-reference mapping at deployment time. You
must now use this login setting to define the aliases at deployment.
d. If you chose XA Data Source as the implementation type of your JDBC provider, you need to
specify the alias used during transaction recovery processing. An additional section entitled
Authentication Alias for XA Recovery is available. Select either Use Application Authentication
Alias to use the same value that you chose for component-managed authentication, or select
Specify: to choose a different alias from the drop-down list.
7. Click Apply to view a page with your new data source settings. Additional properties and Related
items sections are now available on this page. Additional properties contains the Connection pool,
Custom properties, and WebSphere Application Server data source properties choices. (If you are
using a Version 4 data source, however, you see only the first two choices.)
a. Click on the first link to define settings that affect the behavior of the Java 2 Connector (J2C)
connection pool manager.
a. Go to the Custom properties page to view and modify additional properties that the database
vendor might require for the connection of its product to an application server.
b. Use the WebSphere Application Server data source properties page to input settings that
exclusively affect the WebSphere Application Server connection to the database.
c. The Related items section (applicable only to later version data sources, not Version 4 data
sources) contains the J2C Authentication data entries choice. Here, you can specify a list of user
IDs and passwords for J2C security to use.
8. Click Save.
9. Return to the data source page to confirm that your new data source is displayed in the list.

You are now ready to install the application for which you configured the data sources. During installation,
you can bind resource references to these data sources.

Data source collection:

Use this page to create or modify a data source.

To view this administrative console page, click Resources > JDBC Providers > JDBC_provider > Data
sources.

Note: If you are using the Enterprise JavaBean (EJB) 1.0 specification and the Java Servlet 2.2
specification, you must use the Data sources (Version 4) console page.

Name:

Specifies the display name of this data source.

Data type String

JNDI name:

Specifies the Java Naming and Directory Interface (JNDI) name for this data source.

Data type String

Description:

Specifies a text description of the data source.

Data type String

Chapter 8. Developing WebSphere applications 1371

Category:

Specifies a string that you can use to classify or group a data source.

Data type String

Data source settings:

Use this page to create a data source for association with your JDBC provider. Think of the data source as
a pooled set of connections necessary for conducting transactions between your application and database.

To view this administrative console page, click Resources > JDBC Providers > JDBC_provider > Data
sources > New (if you are creating a new data source) or > data_source (if you are viewing an
established data source).

Note: If your application uses an Enterprise JavaBean (EJB) 1.1 or a Java Servlet 2.2 module, you must
use the Data sources (Version 4) > data_source console page.

Name:

Specifies the display name for the data source.

Valid characters for this name include letters and numbers, but NOT most of the special characters. For
example you can set this field to Test Data Source. But any name starting with a period (v) or containing
special characters ( \ / , : ; ″ * ? < > | = + & % ’ `) is not a valid name.

Data type String

JNDI name:

Specifies the Java Naming and Directory Interface (JNDI) name.

Distributed computing environments often employ naming and directory services to obtain shared
components and resources. Naming and directory services associate names with locations, services,
information, and resources.

Naming services provide name-to-object mappings. Directory services provide information on objects and
the search tools required to locate those objects.

There are many naming and directory service implementations, and the interfaces to them vary. JNDI
provides a common interface that is used to access the various naming and directory services.

For example, you can use the name jdbc/markSection.

If you leave this field blank a JNDI name is generated from the name of the data source. For example, a
data source name of markSection generates a JNDI name of jdbc/markSection.

After you set this value, save it, and restart the server, you can see this string when you run the dump
name space tool.

Data type String

Container-managed persistence:

Specifies if this data source is used for container-managed persistence of enterprise beans.
1372 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If this field is checked, a CMP Connector Factory that corresponds to this data source is created for the
relational resource adapter.

Data type Checkbox

Default Enabled (The field is checked.)

Description:

Specifies a text description for the resource.

Data type String

Category:

Specifies a category string you can use to classify or group the resource.

Data type String

Data store helper class name:

Specifies the name of the DataStoreHelper implementation class that extends the capabilities of your
selected JDBC driver implementation class to perform database-specific functions.

WebSphere Application Server provides a set of DataStoreHelper implementation classes for each of the
JDBC provider drivers it supports. These implementation classes are in the package
com.ibm.websphere.rsadapter. For example, if your JDBC provider is DB2, then your default
DataStoreHelper class is com.ibm.websphere.rsadapter.DB2DataStoreHelper. The administrative console
page you are viewing, however, might make multiple DataStoreHelper class names available to you in a
drop-down list; be sure to select the one required by your database configuration. Otherwise, your
application might not work correctly. If you want to use a DataStoreHelper other than those displayed in
the drop-down list, select Specify a user-defined DataStoreHelper and type a fully qualified class name.
Refer to the Information Center topic ″Example: Developing your own DataStoreHelper class.″

Data type Drop-down list or string (if user-defined DataStoreHelper

is selected)

Important data source properties: These properties are specific to the data source that corresponds to
your selected JDBC provider. They are either required by the data source, or are especially useful for the
data source. You can find a complete list of the properties required for all supported JDBC providers in the
topic ″Vendor-specific data sources minimum required settings″ in the Information Center.

Component-managed Authentication Alias:

This alias is used for database authentication at run time.

The Component-managed Authentication Alias is only used when the application resource reference is
using res-auth = Application.

If your database (for example, Cloudscape) does not support user ID and password, then do not set the
alias in the component-managed authentication alias or container-managed authentication alias fields.
Otherwise, you see the warning message in the system log to indicate that the user and password are not
valid properties. (This message is only a warning message; the data source is still created successfully.)

Chapter 8. Developing WebSphere applications 1373

If you do not set an alias (component-managed or otherwise), and your database requires the user ID and
password to get a connection, then you receive an exception during run time.

Data type Drop-down list

Container-managed Authentication Alias (deprecated):

Specifies authentication data (a string path converted to userid and password) for container-managed
sign-on to the resource.

Note: Beginning with WebSphere Application Server Version 6.0, the container-managed authentication
alias is superseded by the specification of a login configuration on the resource-reference mapping
at deployment time, for components with res-auth=Container.

Choose from aliases defined under Security>JAAS Configuration> J2C Authentication Data.

To define a new alias not already appearing in the pick list:

v Click Apply to expose Related Items.
v Click J2C Authentication Data Entries.
v Define an alias.
v Click the connection factory name at the top of the J2C Authentication Data Entries page to return to
the connection factory page.
v Select the alias.

Data type Drop-down list

Mapping-Configuration Alias (deprecated):

Allows users to select from the Security > JAAS Configuration > Application Logins Configuration list.

Note: Beginning with WebSphere Application Server Version 6.0, the Mapping-Configuration Alias is
superseded by the specification of a login configuration on the resource-reference mapping at
deployment time, for components with res-auth=Container.

The DefaultPrincipalMapping JAAS configuration maps the authentication alias to the userid and
password. You may define and use other mapping configurations.

Data type Drop-down list

Authentication Alias for XA Recovery:

This optional field is used to specify the authentication alias that should be used during XA recovery
processing.

If the resource adapter does not support XA transactions, then this field will not be displayed. The default
value will come from the selected alias for application authentication (if specified).
Use Component-managed Authentication Alias
Selecting this radio button specifies that the alias set for Component-managed Authentication is
used at XA recovery time.

Data type Radio button

Specify:
Selecting this radio button enables you to choose an authentication alias from a drop-down list of

1374 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 configured aliases.

Data type Radio button

WebSphere Application Server data source properties collection:

Use this page to view the WebSphere Application Server data source properties. These properties apply to
the WebSphere Application Server connection, rather than to the database connection.

To view this administrative console page, click Resources >JDBC Providers > JDBC_provider > Data
sources > data_source > WebSphere Application Server connection properties.

Statement Cache Size:

Specifies the number of free statements that are cached per connection.

The WebSphere Application Server data source optimizes the processing of prepared statements. A
prepared statement is a precompiled SQL statement that is stored in a prepared statement object. This
object is used to efficiently execute the given SQL statement multiple times.

If the cache is not large enough, useful entries are discarded to make room for new entries. To determine
the largest value for your cache size to avoid any cache discards, add the number of uniquely prepared
statements and callable statements (as determined by the sql string, concurrency, and the scroll type) for
each application that uses this data source on a particular server. This value is the maximum number of
possible prepared statements that are cached on a given connection over the life of the server. Setting the
cache size to this value means you never have cache discards. In general, the more statements your
application has, the larger the cache should be. For example, if the application has 5 SQL statements, set
the statement cache size to 5, so that each connection has 5 statements.

You can also use the Tivoli Performance Viewer to minimize cache discards. Use a standard workload that
represents a typical number of incoming client requests, use a fixed number of iterations, and use a
standard set of configuration settings. Note: The higher the statement cache, the more system resources
are delayed. Therefore, if you set the number too high, you could lack resources because your system is
not able to open that many prepared statements.

In test applications, tuning the statement cache improved throughput by 10-20%. However, because of
potential resource limitations, this might not always be possible.

Data type Integer

Default Depends on the database. Most are 10. Informix Version 7.3, 9.2, or 9.3
without latest fix must be 0. A default of 0 means there is no cache statement.

Enable Multithreaded Access Detection: If checked, the application server detects the existence of
access by multiple threads.

Enable WebSphere Connection Pooling: If checked, the application server sets up connect pools for this
datasource.

Enable Database Reauthentication: If checked, there is not be an exact match on connections retrieved
out of the WebSphere Application Server connection pool (that is, connection pool search criteria do not
include user name and password). Instead, the reauthentication of connection is done in the
doConnectionSetupPerTransaction() of the DataStoreHelper class. Note that WebSphere Application
Server runtime does NOT provide connection reauthentication implementation. Therefore, when this box is
checked you MUST extend the DataStoreHelper class to provide implementation of the
doConnectionSetupPerTransaction() method where the reauthentication takes place. Failure to do that

Chapter 8. Developing WebSphere applications 1375

results in wrong connections being handed out to users. For more information, refer to the Javadoc API
documentation for com.ibm.websphere.rsadapter.DataStoreHelper#doConnectionSetupPerTransaction(...).

Connection reauthentication can help improve performance by reducing the overhead of opening and
closing connections, particularly for applications that always request connections with different user names
and passwords.

Enable JMS One Phase Optimization Support: If checked, the application server allows JMS to get
optimized connections from this data source. This property prevents JDBC applications from sharing
connections with CMP applications.

PreTest Connections: If checked, the application server tries to connect to this data source before it
attempts to send data to or receive data from this data source. If you select this property, you can specify
how often, in seconds, the application server retries to make a connection if the initial attempt fails.

PreTest Connection Retry Interval: When PreTest Connection is checked, use this property to specify
how long, in seconds, the application server waits before retrying to make a connection if the initial attempt
fails.

PreTest SQL String:

Specifies the string of data that the application server sends to the database to test the connection.

Data type Integer

Data sources (Version 4):

Use this page to view the settings of a Version 4.0 style data source.

These Version 4.0 data sources use the WebSphere Application Server Version 4.0 Connection Manager
architecture. All EJB 1.1 modules must use a Version 4.0 data source.

To view this administrative console page, click Resources > JDBC Providers > JDBC_provider > Data
sources (Version 4).

Name:

Specifies a text identifier of the data source.

Data type String

JNDI Name:

Specifies the Java Naming and Directory Interface (JNDI) name of the data source.

Data type String

Description:

Specifies a text description of the data source.

Data type String

Category:

1376 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies a text string that you can use to classify or group the data source.

Data type String

Data source (Version 4) settings:

Use this page to create a Version 4.0 style data source. This data source uses the WebSphere Application
Server Version 4.0 connection manager architecture. All of your EJB1.x modules must use this data
source.

To view this administrative console page, click Resources > JDBC Providers > JDBC_provider > Data
Sources (Version 4) > data_source.

Scope:

Specifies the level to which this resource definition is visible -- the cell, node, or server level.

Resources such as JDBC providers, namespace bindings, or shared libraries can be defined at multiple
scopes, with resources defined at more specific scopes overriding duplicates which are defined at more
general scopes.

Note that no matter what the scope of a defined resource, the resource’s properties only apply at an
individual server level. For example, if you define the scope of a data source at the cell level, all users in
that cell can look up and use that data source, which is unique within that cell. However, resource property
settings are local to each server in the cell. For example, if you define max connections to 10, then each
server in that cell can have 10 connections.
Cell The most general scope. Resources defined at the cell scope are visible from all nodes and
servers, unless they are overridden. To view resources defined in the cell scope, do not specify a
server or a node name in the scope selection form.
Node The default scope for most resource types. Resources defined at the node scope override any
duplicates defined at the cell scope and are visible to all servers on the same node, unless they
are overridden at a server scope on that node. To view resources defined in a node scope, do not
specify a server, but select a node name in the scope selection form.
Server
The most specific scope for defining resources. Resources defined at the server scope override
any duplicate resource definitions defined at the cell scope or parent node scope and are visible
only to a specific server. To view resources defined in a server scope, specify a server name as
well as a node name in the scope selection form.

When resources are created, they are always created into the current scope selected in the panel. To view
resources in other scopes, specify a different node or server in the scope selection form.

Data type String

Name:

Specifies the display name for the resource.

For example, you can set this field to Test Data Source.

Data type String

JNDI Name:

Specifies the Java Naming and Directory Interface (JNDI) name.

Chapter 8. Developing WebSphere applications 1377
Distributed computing environments often employ naming and directory services to obtain shared
components and resources. Naming and directory services associate names with locations, services,
information, and resources.

Naming services provide name-to-object mappings. Directory services provide information on objects and
the search tools required to locate those objects.

There are many naming and directory service implementations, and the interfaces to them vary. JNDI
provides a common interface that is used to access the various naming and directory services.

For example, you can use the name jdbc/markSection.

If you leave this field blank a JNDI name is generated from the name of the data source. For example, a
data source name of markSection generates a JNDI name of jdbc/markSection.

After you set this value, save it, and restart the server, you can see this string when you run the dump
name space tool.

Data type String

Description:

Specifies a text description for the resource.

Data type String

Category:

Specifies a category string that you can use to classify or group the resource.

Data type String

Database Name:

Specifies the name of the database that this data source accesses.

For example, you can call the database SAMPLE.

Data type String

Default User ID:

Specifies the user name to use for connecting to the database.

For example, you can use the ID db2admin.

Data type String

Default Password:

Specifies the password used for connecting to the database.

1378 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
For example, you can use the password db2admin.

Data type String

Custom properties collection:

Use this page to view and configure the custom properties of a J2EE resource provider.

You can configure custom property collections for numerous resource types. According to the resource
type with which a collection is associated, your ability to add, delete, and modify individual properties and
settings varies. Begin the configuration process by clicking on the Required field to sort those column
values in descending order. All of the required (true) values are then sorted at the beginning of the page.
Be sure to set all required properties.

Name:

Specifies the property name.

You must ensure that the resource provider has the setting for this name.

Data type String

Value:

Specifies the property value.

Data type Variable; see “Custom property settings” for more

information.

Description:

Specifies text to describe any bounds or well-defined values for this property.

Data type String

Required:

Specifies whether this property is required for the resource provider.

Data type Boolean or Check box

Custom property settings:

Use this page to view and set custom properties that might be required for resource providers and
resource factories.

According to the resource type with which a property collection is associated, your ability to modify
individual property settings varies. Therefore, consider the following descriptions as a general reference for
custom property settings. (The administrative console page that you are using to configure your custom
property may only allow you to modify a subset of the following settings.)

Required:

Specifies properties that are required for this resource.

Chapter 8. Developing WebSphere applications 1379

Data type Check box

Name:

Specifies the name associated with this property (PortNumber, ConnectionURL, etc).

Data type String

Value:

Specifies the value associated with this property in this property set.

Data type Determined by the Type setting, which you select from a
drop-down list. If the type is java.lang.String then the
value is of type String; if the type is java.lang.Integer,
then the value is of type Integer; and so on.

Description:

Specifies text to describe any bounds or well-defined values for this property.

Data type String

Type:

Specifies the fully qualified Java data type of this property .

There are specific types that are valid:

v java.lang.Boolean
v java.lang.String
v java.lang.Integer
v java.lang.Double
v java.lang.Byte
v java.lang.Short
v java.lang.Long
v java.lang.Float
v java.lang.Character

Data type Drop-down list

Custom Properties (Version 4) collection:

Use this page to view properties for a Version 4.0 data source.

To view this administrative console page, click Resources > JDBC Providers > JDBC_provider > Data
Sources (Version 4) > data_source > Custom Properties

Name:

Specifies the name of the custom property

Data type String

1380 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Value:

Specifies the value of the custom property.

Data type Integer

Description:

Specifies text to describe any bounds or well-defined values for this property.

Data type String

Required:

Specifies properties that are required for this resource.

Data type String

Custom property (Version 4) settings:

Use this page to add properties for a Version 4.0 data source.

To view this administrative console page, click Resources >JDBC Providers> JDBC_provider > Data
Sources (Version 4) > data_source > Custom Properties > custom_property.

Scope:

Specifies the level to which this resource definition is visible -- the cell, node, or server level.

Resources such as JDBC providers, namespace bindings, or shared libraries can be defined at multiple
scopes, with resources defined at more specific scopes overriding duplicates which are defined at more
general scopes.

Note that no matter what the scope of a defined resource, the resource’s properties only apply at an
individual server level. For example, if you define the scope of a data source at the cell level, all users in
that cell can look up and use that data source, which is unique within that cell. However, resource property
settings are local to each server in the cell. For example, if you define max connections to 10, then each
server in that cell can have 10 connections.
Cell The most general scope. Resources defined at the cell scope are visible from all nodes and
servers, unless they are overridden. To view resources defined in the cell scope, do not specify a
server or a node name in the scope selection form.
Node The default scope for most resource types. Resources defined at the node scope override any
duplicates defined at the cell scope and are visible to all servers on the same node, unless they
are overridden at a server scope on that node. To view resources defined in a node scope, do not
specify a server, but select a node name in the scope selection form.
Server
The most specific scope for defining resources. Resources defined at the server scope override
any duplicate resource definitions defined at the cell scope or parent node scope and are visible
only to a specific server. To view resources defined in a server scope, specify a server name as
well as a node name in the scope selection form.

When resources are created, they are always created into the current scope selected in the panel. To view
resources in other scopes, specify a different node or server in the scope selection form.

Chapter 8. Developing WebSphere applications 1381

Data type String

Required:

Specifies properties that are required for this resource.

Data type Check box

Name:

Specifies the name associated with this property (PortNumber, ConnectionURL, etc).

Data type String

Value:

Specifies the value associated with this property in this property set.

Data type Integer

Description:

Specifies text to describe any bounds or well-defined values for this property.

Data type String

Type:

Specifies the fully qualified Java type of this property (java.lang.Integer, java.lang.Byte).

Data type String

Creating a data source for a clustered environment:

Use these steps to define a data source on multiple nodes that comprise a cluster.

The first part of this task defines a JDBC provider with a cluster scope setting. Be aware that all members
of your cluster must run at least Version 6 of WebSphere Application Server to use this scope setting for
the cluster. (See ″Administrative console scope settings″ in the information center for more information
about scope settings in general.)

The cluster scope has precedence over the node and cell scopes. Create a data source for a cluster if you
want the data source to:
v Be available for all the members of this cluster to use
v Override any resource factories that have the same JNDI name that is defined within the cell scope
1. Open the administrative console.
2. Click Resources > JDBC Providers. In the Scope section, note that the default scope setting is at
the node level.
3. Click Browse Clusters. The JDBC providers > Select a Cluster Scope panel is displayed.
4. Select the cluster for which you want to define a data source, and click OK. The JDBC providers
panel is displayed again.

1382 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 5. Click Apply.
6. Click New to create a new JDBC provider at the cluster level. The class path for your new JDBC
provider is already filled in; part of that class path is specified using a symbolic variable, for example:
${DB2390_JDBC_DRIVER_PATH}/classes/db2j2classes.zip. Leave it at the default.
7. Finish creating the JDBC provider.
8. Click Environment.
9. Click WebSphere Variables.
10. For each node, select the symbolic variable used in the class path of your JDBC provider, and
provide a value that is appropriate for the selected node. For example, if the class path of your JDBC
provider uses the symbolic variable ${DB2390_JDBC_DRIVER_PATH}, you might supply the value
/usr/lpp/db2 on one node and /usr/lpp/db2710 on another node, depending on where your DB2
390 installation is located.
11. Click DB2_JDBC_DRIVER_PATH (this already exists by default). Here provide the path (in the value
field) where db2java.zip exists on the selected node.
12. Click Apply and save the changes.

Note: This variable must be defined on each node within the cluster.

You are now ready to configure your data source. For guidance, refer to “Creating and configuring a data
source using the administrative console” on page 1370.

Creating and configuring a JDBC provider and data source using the Java Management Extensions
API:

If your application requires access to a JDBC connection pool from a J2EE 1.3 or 1.4 level WebSphere
Application Server component, you can create the necessary JDBC provider and data source objects
using the Java Management Extensions (JMX) API exclusively. Alternatively, you can use the JMX API in
combination with the WSadmin - scripting tool.

Note: Use the JMX API to create only data sources for which the product does not provide a template.
For every JDBC provider WebSphere Application Server supports, the product provides a
corresponding data source template. You can create supported providers and associated data
sources through the administrative console, or by using the WSadmin - scripting tool. For a
complete list of supported JDBC providers (and therefore a complete list of data sources that must
be created using a template), refer to the topic “Vendor-specific data sources minimum required
settings” on page 1421.

These steps outline the general procedure for using the JMX API to create a JDBC provider and data
source, on WebSphere Application Server running on Windows platforms:
1. Set your classpath.
You need two JAR files in your classpath -- wsexception.jar and wasjmx.jar. The following command is
an example for setting your classpath (shown on 2 lines for publication):
set classpath=%classpath%;D:\WebSphere\AppServer\lib\wsexception.jar;
D:\WebSphere\AppServer\lib\wasjmx.jar
2. Look up the host and get an administration client handle.
3. Get a configuration service handle.
4. Update the resource.xml file using the configuration service as desired.
a. Add a JDBC provider.
b. Add the data source.
c. Add the connection factory. (This step is necessary only for data sources that must support
container-managed persistence.)

Chapter 8. Developing WebSphere applications 1383

5. Reload the resource.xml file to bind the newly created data source into the JNDI namespace. Perform
this step if you want to use the newly created data source right away without restarting the application
server.
a. Locate the DataSourceConfigHelper MBean using the name.
b. Put together the signature and parameters for the call.
c. Invoke the reload() call.

Example: Using the Java Management Extensions API to create a JDBC driver and data source for
container-managed persistence:
//
// "This program may be used, executed, copied, modified and distributed without royalty for the
// purpose of developing, using, marketing, or distributing."
//
// Product 5630-A36, (C) COPYRIGHT International Business Machines Corp., 2001, 2002
// All Rights Reserved * Licensed Materials - Property of IBM
//
import java.util.*;
import javax.sql.*;
import javax.transaction.*;
import javax.management.*;

import com.ibm.websphere.management.*;
import com.ibm.websphere.management.configservice.*;
import com.ibm.ws.exception.WsException;

/**
* Creates a node scoped resource.xml entry for a DB2 XA datasource.
* The datasource created is for CMP use.
*
* We need following to run (shown on multiple lines for publication):
* set classpath=%classpath%;D:\WebSphere\AppServer\lib\wsexception.jar;
D:\WebSphere\AppServer\lib\wasjmx.jar;D:\$WAS_HOME\lib\wasx.jar
*/
public class CreateDataSourceCMP {

String dsName = "markSection"; // ds display name , also jndi name and CF name
String dbName = "SECTION"; // database name
String authDataAlias = "db2admin"; // an authentication data alias
String uid = "db2admin"; // userid
String pw = "db2admin"; // password
String dbclasspath = "D:/SQLLIB/java/db2java.zip"; // path to the db driver

/**
* Main method.
*/
public static void main(String[] args) {
CreateDataSourceCMP cds = new CreateDataSourceCMP();

try {
cds.run(args);
} catch (com.ibm.ws.exception.WsException ex) {
System.out.println("Caught this " + ex );
ex.printStackTrace();
//ex.getCause().printStackTrace();
} catch (Exception ex) {
System.out.println("Caught this " + ex );
ex.printStackTrace();
}
}

/**

1384 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 * This method creates the datasource using JMX.
* The datasource created here is only written into resources.xml.
* It is not bound into namespace until the server is restarted, or an application started
*/
public void run(String[] args) throws Exception {

try {
// Initialize the AdminClient.
Properties adminProps = new Properties();
adminProps.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
adminProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
adminProps.setProperty(AdminClient.CONNECTOR_PORT, "8880");
AdminClient adminClient = AdminClientFactory.createAdminClient(adminProps);

// Get the ConfigService implementation.

com.ibm.websphere.management.configservice.ConfigServiceProxy configService =
new com.ibm.websphere.management.configservice.ConfigServiceProxy(adminClient);

Session session = new Session();

// Use this group to add to the node scoped resource.xml.

ObjectName node1 = ConfigServiceHelper.createObjectName(null, "Node", null);
ObjectName[] matches = configService.queryConfigObjects(session, null, node1, null);
node1 = matches[0]; // use the first node found

// Use this group to add to the server1 scoped resource.xml.

ObjectName server1 = ConfigServiceHelper.createObjectName(null, "Server", "server1");
matches = configService.queryConfigObjects(session, null, server1, null);
server1 = matches[0]; // use the first server found

// Create the JDBCProvider

String providerName = "DB2 JDBC Provider (XA)";
System.out.println("Creating JDBCProvider " + providerName );

// Prepare the attribute list

AttributeList provAttrs = new AttributeList();
provAttrs.add(new Attribute("name", providerName));
provAttrs.add(new Attribute("implementationClassName",
"COM.ibm.db2.jdbc.DB2XADataSource"));
provAttrs.add(new Attribute("description","DB2 JDBC2-compliant XA Driver"));

//create it
ObjectName jdbcProv =
configService.createConfigData(session,node1,"JDBCProvider",
"resources.jdbc:JDBCProvider",provAttrs);
// now plug in the classpath
configService.addElement(session,jdbcProv,"classpath",dbclasspath,-1);

// Search for RRA so we can link it to the datasource

ObjectName rra =
ConfigServiceHelper.createObjectName(null, "J2CResourceAdapter", null);
matches = configService.queryConfigObjects(session, node1, rra, null);
rra = matches[0]; // use the first J2CResourceAdapter segment for builtin_rra

// Prepare the attribute list

AttributeList dsAttrs = new AttributeList();
dsAttrs.add(new Attribute("name", dsName));
dsAttrs.add(new Attribute("jndiName", "jdbc/" + dsName));
dsAttrs.add(new Attribute("datasourceHelperClassname",
"com.ibm.websphere.rsadapter.DB2DataStoreHelper"));
dsAttrs.add(new Attribute("statementCacheSize", new Integer(10)));
dsAttrs.add(new Attribute("relationalResourceAdapter",
rra)); // this is where we make the link to "builtin_rra"
dsAttrs.add(new Attribute("description", "JDBC Datasource for mark section CMP 2.0 test"));
dsAttrs.add(new Attribute("authDataAlias",authDataAlias));

Chapter 8. Developing WebSphere applications 1385

 // Create the datasource
System.out.println(" ** Creating datasource");
ObjectName dataSource =
configService.createConfigData(session,jdbcProv,"DataSource",
"resources.jdbc:DataSource",dsAttrs);

// Add a propertySet.
AttributeList propSetAttrs = new AttributeList();
ObjectName resourcePropertySet =
configService.createConfigData(session,dataSource,"propertySet","",propSetAttrs);

// Add resourceProperty databaseName

AttributeList propAttrs1 = new AttributeList();
propAttrs1.add(new Attribute("name", "databaseName"));
propAttrs1.add(new Attribute("type", "java.lang.String"));
propAttrs1.add(new Attribute("value", dbName));

configService.addElement(session,resourcePropertySet,"resourceProperties",propAttrs1,-1);

// Now Create the corresponding J2CResourceAdapter Connection Factory object.

ObjectName jra = ConfigServiceHelper.createObjectName(null,"J2CResourceAdapter",null);

// Get all the J2CResourceAdapter, and I want to add my datasource

System.out.println(" ** Get all J2CResourceAdapter’s");
ObjectName[] jras = configService.queryConfigObjects(session, node1, jra, null);

int i=0;

for (;i< jras.length;i++) {

System.out.println(ConfigServiceHelper.getConfigDataType(jras[i])+ " " + i + " = "
+ jras[i].getKeyProperty(SystemAttributes._WEBSPHERE_CONFIG_DATA_DISPLAY_NAME)
+ "\nFrom scope ="
+ jras[i].getKeyProperty(SystemAttributes._WEBSPHERE_CONFIG_DATA_ID));
// quit on the first builtin_rra
if (jras[i].getKeyProperty(SystemAttributes._WEBSPHERE_CONFIG_DATA_DISPLAY_NAME)
.equals("WebSphere Relational Resource Adapter")) {
break;
}
}

if (i >= jras.length) {
System.out.println(
"Did not find builtin_rra J2CResourceAdapter object creating CF anyways" );
} else {
System.out.println(
"Found builtin_rra J2CResourceAdapter object at index " + i + " creating CF" );
}

// Prepare the attribute list

AttributeList cfAttrs = new AttributeList();
cfAttrs.add(new Attribute("name", dsName + "_CF"));
cfAttrs.add(new Attribute("authMechanismPreference","BASIC_PASSWORD"));
cfAttrs.add(new Attribute("authDataAlias",authDataAlias));
cfAttrs.add(new Attribute("cmpDatasource",
dataSource )); // this is where we make the link to DataSource’s xmi:id
ObjectName cf =
configService.createConfigData(session,jras[i],"CMPConnectorFactory",
"resources.jdbc:CMPConnectorFactory",cfAttrs);

// ===== start Security section

System.out.println("Creating an authorization data alias " + authDataAlias);

// Find the parent security object

ObjectName security = ConfigServiceHelper.createObjectName(null, "Security", null);
ObjectName[] securityName =

1386 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 configService.queryConfigObjects(session, null, security, null);
security=securityName[0];

// Prepare the attribute list

AttributeList authDataAttrs = new AttributeList();
authDataAttrs.add(new Attribute("alias", authDataAlias));
authDataAttrs.add(new Attribute("userId", uid));
authDataAttrs.add(new Attribute("password", pw));
authDataAttrs.add(new Attribute("description","Auto created alias for datasource"));

//create it
ObjectName authDataEntry =
configService.createConfigData(session,security,"authDataEntries",
"JAASAuthData",authDataAttrs);
// ===== end Security section

// Save the session

System.out.println("Saving session" );
configService.save(session, false);

// reload resources.xml to bind the new datasource into the name space
reload(adminClient,true);
} catch (Exception ex) {
ex.printStackTrace(System.out);
throw ex;
}
}

/**
* Get the DataSourceConfigHelperMbean and call reload() on it
*
* @param adminClient
* @param verbose true - print messages to stdout
*/
public void reload(AdminClient adminClient,boolean verbose) {
if (verbose) {
System.out.println("Finding the Mbean to call reload()");
}

// First get the Mbean

ObjectName handle = null;
try {
ObjectName queryName = new ObjectName("WebSphere:type=DataSourceCfgHelper,*");
Set s = adminClient.queryNames(queryName, null);
Iterator iter = s.iterator();
if (iter.hasNext()) handle = (ObjectName)iter.next();
} catch (MalformedObjectNameException mone) {
System.out.println("Check the program variable queryName" + mone);
} catch (com.ibm.websphere.management.exception.ConnectorException ce) {
System.out.println("Cannot connect to the application server" + ce);
}

if (verbose) {
System.out.println("Calling reload()");
}
Object result = null;
try {
result = adminClient.invoke(handle, "reload", new Object[] {}, new String[] {});
} catch (MBeanException mbe) {
if (verbose) {
System.out.println("\tMbean Exception calling reload" + mbe);
}
} catch (InstanceNotFoundException infe) {
System.out.println("Cannot find reload ");
} catch (Exception ex) {
System.out.println("Exception occurred calling reload()" + ex);
}

Chapter 8. Developing WebSphere applications 1387

 if (result==null && verbose) {
System.out.println("OK reload()");
}
}

Example: Using the Java Management Extensions API to create a JDBC driver and data source for
bean-managed persistence, session beans, or servlets:
//
// "This program may be used, executed, copied, modified and distributed without royalty for the
// purpose of developing, using, marketing, or distributing."
//
// Product 5630-A36, (C) COPYRIGHT International Business Machines Corp., 2001, 2002
// All Rights Reserved * Licensed Materials - Property of IBM
//
import java.util.*;
import javax.sql.*;
import javax.transaction.*;
import javax.management.*;

import com.ibm.websphere.management.*;
import com.ibm.websphere.management.configservice.*;
import com.ibm.ws.exception.WsException;

/**
* Creates a node scoped resource.xml entry for a DB2 XA datasource.
* The datasource created is for BMP use.
*
* We need following to run (shown on 2 lines for publication):
* set classpath=%classpath%;D:\WebSphere\AppServer\lib\wsexception.jar;
D:\WebSphere\AppServer\lib\wasjmx.jar;D:\$WAS_HOME\lib\wasx.jar
*/
public class CreateDataSourceBMP {

String dsName = "markSection"; // ds display name , also jndi name and CF name
String dbName = "SECTION"; // database name
String authDataAlias = "db2admin"; // an authentication data alias
String uid = "db2admin"; // userid
String pw = "db2admin"; // password
String dbclasspath = "D:/SQLLIB/java/db2java.zip"; // path to the db driver

/**
* Main method.
*/
public static void main(String[] args) {
CreateDataSourceBMP cds = new CreateDataSourceBMP();

try {
cds.run(args);
} catch (com.ibm.ws.exception.WsException ex) {
System.out.println("Caught this " + ex );
ex.printStackTrace();
//ex.getCause().printStackTrace();
} catch (Exception ex) {
System.out.println("Caught this " + ex );
ex.printStackTrace();
}
}

1388 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
/**
* This method creates the datasource using JMX.
*
* The datasource created here is only written into resources.xml.
* It is not bound into namespace until the server is restarted, or an application started
*/
public void run(String[] args) throws Exception {

try {
// Initialize the AdminClient.
Properties adminProps = new Properties();
adminProps.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
adminProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
adminProps.setProperty(AdminClient.CONNECTOR_PORT, "8880");
AdminClient adminClient = AdminClientFactory.createAdminClient(adminProps);

// Get the ConfigService implementation.

com.ibm.websphere.management.configservice.ConfigServiceProxy configService =
new com.ibm.websphere.management.configservice.ConfigServiceProxy(adminClient);

Session session = new Session();

// Use this group to add to the node scoped resource.xml.

ObjectName node1 = ConfigServiceHelper.createObjectName(null, "Node", null);
ObjectName[] matches = configService.queryConfigObjects(session, null, node1, null);
node1 = matches[0]; // use the first node found

// Use this group to add to the server1 scoped resource.xml.

ObjectName server1 = ConfigServiceHelper.createObjectName(null, "Server", "server1");
matches = configService.queryConfigObjects(session, null, server1, null);
server1 = matches[0]; // use the first server found

// Create the JDBCProvider

String providerName = "DB2 JDBC Provider (XA)";
System.out.println("Creating JDBCProvider " + providerName );

// Prepare the attribute list

AttributeList provAttrs = new AttributeList();
provAttrs.add(new Attribute("name", providerName));
provAttrs.add(
new Attribute("implementationClassName", "COM.ibm.db2.jdbc.DB2XADataSource"));
provAttrs.add(new Attribute("description","DB2 JDBC2-compliant XA Driver"));

//create it
ObjectName jdbcProv =
configService.createConfigData(session,node1,"JDBCProvider",
"resources.jdbc:JDBCProvider",provAttrs);
// now plug in the classpath
configService.addElement(session,jdbcProv,"classpath",dbclasspath,-1);

// Search for RRA so we can link it to the datasource

ObjectName rra = ConfigServiceHelper.createObjectName(null, "J2CResourceAdapter", null);
matches = configService.queryConfigObjects(session, node1, rra, null);
rra = matches[0]; // use the first J2CResourceAdapter segment for builtin_rra

// Prepare the attribute list

AttributeList dsAttrs = new AttributeList();
dsAttrs.add(new Attribute("name", dsName));
dsAttrs.add(new Attribute("jndiName", "jdbc/" + dsName));
dsAttrs.add(new Attribute("datasourceHelperClassname",
"com.ibm.websphere.rsadapter.DB2DataStoreHelper"));
dsAttrs.add(new Attribute("statementCacheSize", new Integer(10)));
dsAttrs.add(new Attribute(

Chapter 8. Developing WebSphere applications 1389

 "relationalResourceAdapter", rra)); // this is where we make the link to "builtin_rra"
dsAttrs.add(new Attribute("description", "JDBC Datasource for mark section CMP 2.0 test"));
dsAttrs.add(new Attribute("authDataAlias",authDataAlias));

// Create the datasource

System.out.println(" ** Creating datasource");
ObjectName dataSource =
configService.createConfigData(session,jdbcProv,"DataSource",
"resources.jdbc:DataSource",dsAttrs);

// Add a propertySet.
AttributeList propSetAttrs = new AttributeList();
ObjectName resourcePropertySet =
configService.createConfigData(session,dataSource,"propertySet","",propSetAttrs);

// Add resourceProperty databaseName

AttributeList propAttrs1 = new AttributeList();
propAttrs1.add(new Attribute("name", "databaseName"));
propAttrs1.add(new Attribute("type", "java.lang.String"));
propAttrs1.add(new Attribute("value", dbName));

configService.addElement(session,resourcePropertySet,"resourceProperties",propAttrs1,-1);

// ===== start Security section

System.out.println("Creating an authorization data alias " + authDataAlias);

// Find the parent security object

ObjectName security = ConfigServiceHelper.createObjectName(null, "Security", null);
ObjectName[] securityName =
configService.queryConfigObjects(session, null, security, null);
security=securityName[0];

// Prepare the attribute list

AttributeList authDataAttrs = new AttributeList();
authDataAttrs.add(new Attribute("alias", authDataAlias));
authDataAttrs.add(new Attribute("userId", uid));
authDataAttrs.add(new Attribute("password", pw));
authDataAttrs.add(new Attribute("description","Auto created alias for datasource"));

//create it
ObjectName authDataEntry =
configService.createConfigData(session,security,"authDataEntries",
"JAASAuthData",authDataAttrs);
// ===== end Security section

// Save the session

System.out.println("Saving session" );
configService.save(session, false);

// reload resources.xml
reload(adminClient,true);

} catch (Exception ex) {

ex.printStackTrace(System.out);
throw ex;
}
}

/**
* Get the DataSourceConfigHelperMbean and call reload() on it
*
* @param adminClient
* @param verbose true - print messages to stdout
*/
public void reload(AdminClient adminClient,boolean verbose) {
if (verbose) {

1390 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 System.out.println("Finding the Mbean to call reload()");
}

// First get the Mbean

ObjectName handle = null;
try {
ObjectName queryName = new ObjectName("WebSphere:type=DataSourceCfgHelper,*");
Set s = adminClient.queryNames(queryName, null);
Iterator iter = s.iterator();
if (iter.hasNext()) handle = (ObjectName)iter.next();
} catch (MalformedObjectNameException mone) {
System.out.println("Check the program variable queryName" + mone);
} catch (com.ibm.websphere.management.exception.ConnectorException ce) {
System.out.println("Cannot connect to the application server" + ce);
}

if (verbose) {
System.out.println("Calling reload()");
}
Object result = null;
try {
result = adminClient.invoke(handle, "reload", new Object[] {}, new String[] {});
} catch (MBeanException mbe) {
if (verbose) {
System.out.println("\tMbean Exception calling reload" + mbe);
}
} catch (InstanceNotFoundException infe) {
System.out.println("Cannot find reload ");
} catch (Exception ex) {
System.out.println("Exception occurred calling reload()" + ex);
}

if (result==null && verbose) {

System.out.println("OK reload()");
}
}
}

Example: Creating a JDBC provider and data source using Java Management Extensions API and the
scripting tool: The following code is a JACL (WSadmin - scripting tool) script used to create a data
source.

Note: Use this script to create only data sources for which the product does not provide a template. For
every JDBC provider WebSphere Application Server supports, the product provides a corresponding
data source template. See the topic ″Creating configuration objects using the wsadmin tool″ in the
information center for instructions on how to use the createUsingTemplate command to establish
these data sources. For a complete list of supported JDBC providers (and therefore a complete list
of data sources that must be created using a template), refer to the topic “Vendor-specific data
sources minimum required settings” on page 1421.

This script:
v Creates a data source fvtDS_1
v Creates a 4.0 data source fvtDS_3
v Creates a container-managed persistence (CMP) data source linked to fvtDS_1
#AWE -- Set up XA DB2 data sources, both Version 4.0 and J2EE Connector
architecture (JCA)-compliant data sources

#UPDATE THESE VALUES:

#The classpath that will be used by your database driver
set driverClassPath "c:/sqllib/java/db2java.zip"

set server "server1"

Chapter 8. Developing WebSphere applications 1391

set fvtbase "c:/wssb/fvtbase"

#Users and passwords..

set defaultUser1 "dbuser1"
set defaultPassword1 "dbpwd1"
set aliasName "alias1"

set databaseName1 "jtest1"

set databaseName2 "jtest2"
#END OF UPDATES

puts "Add an alias alias1"

set cell [$AdminControl getCell]
set sec [$AdminConfig getid /Cell:$cell/Security:/]

#---------------------------------------------------------
# Create a JAASAuthData object for component-managed authentication
#---------------------------------------------------------
puts "create JAASAuthData object for alias1"

set alias_attr [list alias $aliasName]

set desc_attr [list description "Alias 1"]
set userid_attr [list userId $defaultUser1]
set password_attr [list password $defaultPassword1]
set attrs [list $alias_attr $desc_attr $userid_attr $password_attr]

set authdata [$AdminConfig create JAASAuthData $sec $attrs]

$AdminConfig save

puts "Installing DB2 datasource for XA"

puts "Finding the old JDBCProvider.."

#Remove the old jdbc provider...
set jps [$AdminConfig list JDBCProvider]
foreach jp $jps {
set jpname [lindex [lindex [$AdminConfig show $jp {name}] 0] 1]
if {($jpname == "FVTProvider")} {
puts "Removing old JDBC Provider"
$AdminConfig remove $jp
$AdminConfig save
}
}

#Get the server name...

puts "Finding the server $server"
set servlist [$AdminConfig list Server]
set servsize [llength $servlist]
foreach srvr $servlist {
set sname [lindex [lindex [$AdminConfig show $srvr {name}] 0] 1]
if {($sname == $server)} {
puts "Found server $srvr"
set serv $srvr
}
}

puts "Finding the Resource Adapter"

set rsadapter [$AdminConfig list J2CResourceAdapter $serv]

#Now create a JDBC Provider for the data sources

puts "Creating the provider for COM.ibm.db2.jdbc.DB2XADataSource"
set attrs1 [subst {{classpath $driverClassPath} {
implementationClassName COM.ibm.db2.jdbc.DB2XADataSource} {
name "FVTProvider2"} {description "DB2 JDBC Provider"}}]
set provider1 [$AdminConfig create JDBCProvider $serv $attrs1]

1392 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
#Create the first data source
puts "Creating the datasource fvtDS_1"
set attrs2 [subst {{name fvtDS_1} {description "FVT DataSource 1"}}]
set ds1 [$AdminConfig create DataSource $provider1 $attrs2]

#Set the properties for the data source.

set propSet1 [$AdminConfig create J2EEResourcePropertySet $ds1 {}]

set attrs3 [subst {{name databaseName} {type java.lang.String} {value $databaseName1}}]

$AdminConfig create J2EEResourceProperty $propSet1 $attrs3

set attrs10 [subst {{jndiName jdbc/fvtDS_1} {statementCacheSize 10} {

datasourceHelperClassname com.ibm.websphere.rsadapter.DB2DataStoreHelper} {
relationalResourceAdapter $rsadapter} {authMechanismPreference "BASIC_PASSWORD"} {
authDataAlias $aliasName}}]
$AdminConfig modify $ds1 $attrs10

#Create the connection pool object...

$AdminConfig create ConnectionPool $ds1 {{connectionTimeout 1000} {maxConnections 30} {
minConnections 1} {agedTimeout 1000} {reapTime 2000} {unusedTimeout 3000} }

#Now create the 4.0 data sources..

puts "Creating the 4.0 datasource fvtDS_3"
set ds3 [$AdminConfig create WAS40DataSource $provider1 {{name fvtDS_3} {
description "FVT 4.0 DataSource"}}]

#Set the properties on the data source

set propSet3 [$AdminConfig create J2EEResourcePropertySet $ds3 {}]

#These attributes should be the same as fvtDS_1

set attrs4 [subst {{name user} {type java.lang.String} {value $defaultUser1}}]
set attrs5 [subst {{name password} {type java.lang.String} {value $defaultPassword1}}]
$AdminConfig create J2EEResourceProperty $propSet3 $attrs3
$AdminConfig create J2EEResourceProperty $propSet3 $attrs4
$AdminConfig create J2EEResourceProperty $propSet3 $attrs5
set attrs10 [subst {{jndiName jdbc/fvtDS_3} {databaseName $databaseName1}}]
$AdminConfig modify $ds3 $attrs10

$AdminConfig create WAS40ConnectionPool $ds3 {{orphanTimeout 3000} {connectionTimeout 1000} {

minimumPoolSize 1} {maximumPoolSize 10} {idleTimeout 2000}}

#Now add a CMP connection factory for the JCA-compliant data source. This step is not
#necessary for Version 4 data sources, as they contain built-in CMP connection factories.
puts "Creating the CMP Connector Factory for fvtDS_1"
set attrs12 [subst {{name "FVT DS 1_CF"} {authMechanismPreference BASIC_PASSWORD} {
cmpDatasource $ds1} {authDataAlias $aliasName}}]
set cf1 [$AdminConfig create CMPConnectorFactory $rsadapter $attrs12]

#Set the properties for the data source.

$AdminConfig create MappingModule $cf1 {{mappingConfigAlias "DefaultPrincipalMapping"} {
authDataAlias "alias1"}}

$AdminConfig save

Test connection service:

WebSphere Application Server provides a test connection service for testing connections to the data
sources that you configure for database access.

If the definition of your data source includes a WebSphere variable, you need to determine how your
scope settings for both the variable and data source can affect the test connection results. Your next step
is to choose which of the three ways you want to activate the test connection service: through the
administrative console, the wsadmin tool, or a Java stand-alone program.

Chapter 8. Developing WebSphere applications 1393

Verifying your scope settings

Use of a WebSphere variable in your data source definition can elicit test connection results that are
incongruent with the actual run-time behavior of your data access application. In some cases, a test
connection operation fails, but the data source functions normally during application run time. The reverse
scenario can also occur. The cause of the potential conflict is the difference between how your application
server handles WebSphere variable scope settings at run time, and how it handles those scope settings
for a test connection operation. Understanding the difference helps you choose a successful configuration
for your data source.

At run time, an application server resolves environment variables from the most specific scope to the
broadest scope. That is, the server checks for the resolution of a variable in the server scope, then the
cluster scope, then the node scope, and lastly the cell scope. When testing a connection, however, the
most specific scope level at which the server checks variable definitions is determined by the scope at
which the data source was created.

The test connection operation itself is performed in the JVM that corresponds with the scope of the data
source. If the data source is configured at the cell scope, the test connection operation is carried out in the
deployment manager process. If the data source is configured in the node scope, the test connection
operation is performed in the node agent process for that node. For cluster-scoped data sources, the test
connection operation is attempted in the node agent for each node that contains a cluster member. For
server-scoped data sources, the test connection operation is first attempted in the server. If the server is
unavailable, the test connection operation is retried in the node agent for the node that contains the
application server.

Note: For any data source, regardless of scope setting, you must restart the associated JVM if you add or
modify the authentication alias object.

Processing data source configurations in this way yields different, sometimes misleading, test connection
results for different scope settings, as shown in the following table:
Table 17. Test connection results for different data source and environment variable combinations
Data source scope Cell level variables Node level variables Server level variables
*
Cell level Ok (See the following Fail Fail
section)
Node level Ok Ok Fail
Server level Ok Ok Ok

Contrary to expectations, these test connection failures generally do not translate into run-time failures,
assuming that you are conscientious about configuring your WebSphere variables. A variable cannot be
found exception results from attempted use of a data source that is configured with undefined variables.

Test connection success, but run-time failure

One of the scope combinations listed in the table, however, produces the reverse scenario: the test
connection operation succeeds, but the data source fails at run time. This anomaly occurs in the case of a
cell-scoped data source that uses a cell-scoped WebSphere variable. At run time, the cell-scoped variable
is preempted by a default scope setting. In a default WebSphere Application Server installation, the
supported database driver variables are defined and initialized to an empty string at the node scope. That
empty setting effectively overrides any variable definition you provide at the cell scope level for a
cell-scoped data source.

Because the run-time server checks the node scope for the variable before it checks the cell scope, it
reads the empty string variable and accepts it as a value for the database driver class path. The incorrect

1394 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
class path elicits a classNotFound exception when the server attempts to use the data source. To make
the data source work for both test connection and run time, define the driver class path variable at the cell
scope (indicating the location of the driver files on the deployment manager node), as well as at each
node on which the data source must function. Alternatively, you can delete the node scope definitions if
the database location is the same as the cell-scoped variable.

Bypassing variable lookups

You can bypass the environment variable lookups by changing the class path entries for the JDBC
provider to hard-coded values. However, this strategy succeeds only if the class path is the same on all
nodes where the data source must function.

Activating the test connection service

There are three ways to activate the test connection service: through the administrative console, the
wsadmin tool, or a Java stand-alone program. Each process invokes the same methods on the same
MBean.

Administrative console

WebSphere Application Server allows you to test a connection from the administrative console by simply
pushing a button: the Data source collection, Data source settings, Version 4 data source collection, and
Version 4 data source settings pages all have Test Connection buttons. After you define and save a data
source, you can click this button to ensure that the parameters in the data source definition are correct. On
the collection page, you can select several data sources and test them all at once. Note that there are
certain conditions that must be met first. For more information, see Testing a connection with the
administrative console.

WsAdmin tool

The wsadmin tool provides a scripting interface to a full range of WebSphere Application Server
administration activities. Because the Test Connection functionality is implemented as a method on an
MBean, and wsadmin can invoke MBean methods, wsadmin can be utilized to test connections to data
sources. You have two options for testing a data source connection through wsadmin:

The AdminControl object of wsadmin has a testConnection operation that tests the configuration properties
of a data source object. For information, see Testing a connection using wsadmin.

You can also test a connection by invoking the MBean operation. Use ″Example: Testing data source
connection using wsadmin″ in the information center as a guide for this technique.

Java stand-alone program

Finally, you can test a connection by executing the testConnection() method on the DataSourceCfgHelper
MBean. This method allows you to pass the configuration ID of the configured data source. The Java
program connects to a running Java Management Extensions (JMX) server to access the MBean. In a
Network Deployment installation of Application Server, you connect to the JMX server running in the
deployment manager, usually running on port 8879.

The return value from this invocation is either 0, a positive number, or an exception. 0 indicates that the
operation completed successfully, with no warnings. A positive number indicates that the operation
completed successfully, with the number of warnings. An exception indicates that the test of the connection
failed.

You can find an example of this code in Example: Test a connection using testConnection(ConfigID).

Chapter 8. Developing WebSphere applications 1395

Testing a connection with the administrative console:

After you have defined and saved a data source, you can click the Test Connection button to ensure that
the parameters in the data source definition are correct. On the collection panel, you can select multiple
data sources and test them all at once. Be sure that the following conditions are met before using the Test
Connection button.
1. Depending on your specific needs, a valid Authentication Data alias might need to exist and be
supplied on the data source panels.
2. If you are testing a connection using a WebSphere Application Server Version 4.0 type of data source,
ensure that the user and password information is filled in.
3. If you used a WebSphere Environment entry for the class path or other fields, such as
${DB2_JDBC_DRIVER_PATH}/db2java.zip, make sure that you assign it a value in the WebSphere
Variables page. Note that if you add a new WebSphere environment variable, or modify it , the process
(node agents and deployment manager) might need restarting.
4. Verify that the environment variables used exist in the scope of the test. For example, if the node
scoped data source you defined uses ${DB2_JDBC_DRIVER_PATH}, check that there exists a node
level definition for DB2_JDBC_DRIVER_PATH = c:\sqllib\java( or your system dependent value).
5. Ensure that the deployment manager and node agent are up and running.
6. Click Test Connection.
A Test Connection operation can have three different outcomes, each resulting in a different message
being displayed in the messages panel of the page on which you press the Test Connection button.
a. The test can complete successfully, meaning that a connection is successfully obtained to the
database using the configured data source parameters. The resulting message states: Test
Connection for data source DataSourceName on process ProcessName at node NodeName was
successful.
b. The test can complete successfully with warnings. This means that while a connection is
successfully obtained to the database, warnings were issued. The resulting message states: Test
Connection for data source DataSourceName on process ProcessName at node NodeName was
successful with warning(s). View the JVM Logs for more details.
The View the JVM Logs text is a hyperlink that takes you to the JVM Logs console screen for the
process.
c. The test can fail. A connection to the database with the configured parameters is not obtained. The
resulting message states: Test Connection failed for data source DataSourceName on process
ProcessName at node NodeName with the following exception: ExceptionText. View the JVM Logs
for more details.
Again, the text for View the JVM Logs is a hyperlink to the appropriate logs screen.

Testing a connection using wsadmin:

The AdminControl object of wsadmin has a testConnection operation that tests the configuration properties
of a data source object. It takes a configuration ID as an argument.

Note: There is no way to pass a user ID and password to this invocation. This invocation can only be
used for databases that do not require a user ID and password to make a connection (such as DB2
on a Windows machine), or for data sources that have a component-managed or
container-managed authentication alias set on the data source object.
1. Invoke the getid() method for your data source.
2. Set the value of the configuration id to a variable.
set myds [$AdminConfig getid /JDBCProvider:mydriver/DataSource:mydatasrc/]

where /JDBCProvider:mydriver/DataSource:mydatasrc/ is the data source you want to test. After you
have the configuration ID of the data source, you can test the connection to the database.
3. Test the connection to the database.

1396 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 $AdminControl testConnection $myds

Example: Test a connection using testConnection(ConfigID): This program uses JMX to connect to a
running server and invoke the testConnection method on the DataSourceCfgHelper MBean.
/**
* Description
* Resource adapter test program to make sure that the MBean interfaces work.
* Following interfaces are tested
*
* --- testConnection()
*
*
* We need following to run
* C:\src>java -Djava.ext.dirs=
C:\WebSphere\AppServer\lib;C:\WebSphere\AppServer\java\jre\lib\ext testDSGUI
* must include jre for log.jar and mail.jar, else get class not found exception
*
*
*/

import java.util.Iterator;
import java.util.Locale;
import java.util.Properties;
import java.util.Set;

import javax.management.InstanceNotFoundException;
import javax.management.MBeanException;
import javax.management.MalformedObjectNameException;
import javax.management.ObjectName;
import javax.management.RuntimeMBeanException;
import javax.management.RuntimeOperationsException;

import com.ibm.websphere.management.AdminClient;
import com.ibm.websphere.management.AdminClientFactory;
import com.ibm.ws.rsadapter.exceptions.DataStoreAdapterException;

public class testDSGUI {

//Use port 8880 for base installation or port 8879 for ND installation
String port = "8880";
// String port = "8879";
String host = "localhost";
final static boolean verbose = true;

// eg a configuration ID for DataSource declared at the node level for base

private static final String resURI = "cells/cat/nodes/cat:resources.xml#DataSource_1";

// eg a 4.0 DataSource declared at the node level for base

// private static final String resURI =
// "cells/cat/nodes/cat:resources.xml#WAS40DataSource_1";

// eg Cloudscape DataSource declared at the server level for base

//private static final String resURI =
// "cells/cat/nodes/cat/servers/server1/resources.xml#DataSource_6";

// eg node level DataSource for ND

//private static final String resURI =
// "cells/catNetwork/nodes/cat:resources.xml#DataSource_1";

// eg server level DataSource for ND

//private static final String resURI =
// "cells/catNetwork/nodes/cat/servers/server1:resources.xml#DataSource_4";

// eg cell level DataSource for ND

//private static final String resURI = "cells/catNetwork:resources.xml#DataSource_1";

Chapter 8. Developing WebSphere applications 1397

public static void main(String[] args) {
testDSGUI cds = new testDSGUI();
cds.run(args);
}

/**
* This method tests the ResourceMbean.
*
* @param args
* @exception Exception
*/
public void run(String[] args) {

try {

System.out.println("Connecting to the application server.......");

/*************************************************************************/
/** Initialize the AdminClient */
/*************************************************************************/
Properties adminProps = new Properties();
adminProps.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
adminProps.setProperty(AdminClient.CONNECTOR_HOST, host);
adminProps.setProperty(AdminClient.CONNECTOR_PORT, port);
AdminClient adminClient = null;
try {
adminClient = AdminClientFactory.createAdminClient(adminProps);
} catch (com.ibm.websphere.management.exception.ConnectorException ce) {
System.out.println("NLS: Cannot make a connection to the application server\n");
ce.printStackTrace();
System.exit(1);
}

/*************************************************************************/
/** Locate the Mbean */
/*************************************************************************/
ObjectName handle = null;
try {
// Send in a locator string
// eg for a Baseinstallation this is enough
ObjectName queryName = new ObjectName("WebSphere:type=DataSourceCfgHelper,*");

// for ND you need to specify which node/process you would like to test from
// eg run in the server
//ObjectName queryName = new OjectName(
// "WebSphere:cell=catNetwork,node=cat,process=server1,type=DataSourceCfgHelper,*");
// eg run in the node agent
//ObjectName queryName =
// new ObjectName(
// "WebSphere:cell=catNetwork,node=cat,process=nodeagent,type=DataSourceCfgHelper,*");
// eg run in the Deployment Manager
//ObjectName queryName =
// new ObjectName(
// "WebSphere:cell=catNetwork,node=catManager,process=dmgr,type=DataSourceCfgHelper,*");
Set s = adminClient.queryNames(queryName, null);
Iterator iter = s.iterator();
while (iter.hasNext()) {
// use the first MBean that is found
handle = (ObjectName) iter.next();
System.out.println("Found this ->" + handle);
}
if (handle == null) {
System.out.println("NLS: Did not find this MBean>>" + queryName);
System.exit(1);
}
} catch (MalformedObjectNameException mone) {
System.out.println("Check the program variable queryName" + mone);

1398 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
} catch (com.ibm.websphere.management.exception.ConnectorException ce) {
System.out.println("Cannot connect to the application server" + ce);
}

/*************************************************************************/
/** Build parameters to pass to Mbean */
/*************************************************************************/
String[] signature = { "java.lang.String" };
Object[] params = { resURI };
Object result = null;

if (verbose) {
System.out.println("\nTesting connection to the database using " + handle);
}

try {
/*************************************************************************/
/** Start to test the connection to the database */
/*************************************************************************/
result = adminClient.invoke(handle, "testConnection", params, signature);
} catch (MBeanException mbe) {
// ****** all user exceptions come in here
if (verbose) {
Exception ex = mbe.getTargetException(); // this is the real exception from the Mbean
System.out.println("\nNLS:Mbean Exception was received contains " + ex);
ex.printStackTrace();
System.exit(1);
}
} catch (InstanceNotFoundException infe) {
System.out.println("Cannot find " + infe);
} catch (RuntimeMBeanException rme) {
Exception ex = rme.getTargetException();
ex.printStackTrace(System.out);
throw ex;
} catch (Exception ex) {
System.out.println("\nUnexpected Exception occurred: " + ex);
ex.printStackTrace();
}

/*************************************************************************/
/** Process the result. The result will be the number of warnings */
/** issued. A result of 0 indicates a successful connection with */
/** no warnings. */
/*************************************************************************/

//A result of 0 indicates a successful connection with no warnings.

System.out.println("Result= " + result);

} catch (RuntimeOperationsException roe) {

Exception ex = roe.getTargetException();
ex.printStackTrace(System.out);
} catch (Exception ex) {
System.out.println("General exception occurred");
ex.printStackTrace(System.out);
}
}
}

Configuring J2EE Connector connection factories in the administrative console

1. Click Resources.
2. Click Resource Adapters.
3. Select a resource adapter under Resource Adapters.
4. Click J2C Connection Factories under Additional Properties .
5. Click New.

Chapter 8. Developing WebSphere applications 1399

 6. Specify General Properties .
7. Select the authentication preference.
8. Select aliases for component-managed authentication, container-managed authentication, or
both. If none are available, or you want to define a different one, click Apply > J2C Authentication
Data Entries under Related Items.
a. Click J2C Auth Data Entries under Related Items.
b. Click New.
c. Specify General Properties.
d. Click OK.
9. Click OK.
10. Click the J2C connection factory you just created.
11. Under Additional Properties click Connection Pool.
12. Change any values desired by clicking the property name.
13. Click OK.
14. Click Custom Properties under Additional Properties.
15. Click any property name to change its value. Note that UserName and Password if present, are
overridden by the component-managed authentication alias you specified in a previous step.
16. Click Save.

Connection pool settings:

Use this page to configure connection pool settings.

This administrative console page is common to a range of resource types; for example, JDBC data
sources and JMS queue connection factories. To view this page, the path depends on the type of
resource, but generally you select an instance of the resource provider, then an instance of the resource
type, then click Connection Pool. For example: click Resources > JDBC Providers > JDBC_provider >
Data Sources > data_source > Connection Pool.

Connection Timeout:

Specifies the interval, in seconds, after which a connection request times out and a
ConnectionWaitTimeoutException is thrown.

This value indicates the number of seconds a request for a connection waits when there are no
connections available in the free pool and no new connections can be created, usually because the
maximum value of connections in the particular connection pool has been reached. For example, if
Connection Timeout is set to 300, and the maximum number of connections are all in use, the pool
manager waits for 300 seconds for a physical connection to become available. If a physical connection is
not available within this time, the pool manager initiates a ConnectionWaitTimeout exception. It usually
does not make sense to retry the getConnection() method; if a longer wait time is required you should
increase the Connection Timeout setting value. If a ConnectionWaitTimeout exception is caught by the
application, the administrator should review the expected connection pool usage of the application and
tune the connection pool and database accordingly.

If the Connection Timeout is set to 0, the pool manager waits as long as necessary until a connection
becomes available. This happens when the application completes a transaction and returns a connection
to the pool, or when the number of connections falls below the value of Maximum Connections, allowing a
new physical connection to be created.

If Maximum Connections is set to 0, which enables an infinite number of physical connections, then the
Connection Timeout value is ignored.

1400 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Integer
Units Seconds
Default 180
Range 0 to max int

Maximum Connections:

Specifies the maximum number of physical connections that you can create in this pool.

These are the physical connections to the backend resource. Once this number is reached, no new
physical connections are created and the requester waits until a physical connection that is currently in
use returns to the pool, or a ConnectionWaitTimeout exception is issued.

For example, if the Maximum Connections value is set to 5, and there are five physical connections in use,
the pool manager waits for the amount of time specified in Connection Timeout for a physical connection
to become free.

If Maximum Connections is set to 0, the connection pool is allowed to grow infinitely. This also has the
side effect of causing the Connection Timeout value to be ignored.

If multiple standalone application servers use the same data source, there is one pool for each application
server. If clones are used, one data pool exists for each clone. Knowing the number of data pools is
important when configuring the database maximum connections.

You can use the Tivoli Performance Viewer to find the optimal number of connections in a pool. If the
number of concurrent waiters is greater than 0, but the CPU load is not close to 100%, consider increasing
the connection pool size. If the Percent Used value is consistently low under normal workload, consider
decreasing the number of connections in the pool.

Data type Integer

Default 10
Range 0 to max int

Minimum Connections:

Specifies the minimum number of physical connections to maintain.

If the size of the connection pool is at or below the minimum connection pool size, the Unused Timeout
thread does not discard physical connections. However, the pool does not create connections solely to
ensure that the minimum connection pool size is maintained. Also, if you set a value for Aged Timeout,
connections with an expired age are discarded, regardless of the minimum pool size setting.

For example if the Minimum Connections value is set to 3, and one physical connection is created, the
Unused Timeout thread does not discard that connection. By the same token, the thread does not
automatically create two additional physical connections to reach the Minimum Connections setting.

Data type Integer

Default 1
Range 0 to max int

Reap Time:

Specifies the interval, in seconds, between runs of the pool maintenance thread.

Chapter 8. Developing WebSphere applications 1401

For example, if Reap Time is set to 60, the pool maintenance thread runs every 60 seconds. The Reap
Time interval affects the accuracy of the Unused Timeout and Aged Timeout settings. The smaller the
interval, the greater the accuracy. If the pool maintenance thread is enabled, set the Reap Time value less
than the values of Unused Timeout and Aged Timeout. When the pool maintenance thread runs, it
discards any connections remaining unused for longer than the time value specified in Unused Timeout,
until it reaches the number of connections specified in Minimum Connections. The pool maintenance
thread also discards any connections that remain active longer than the time value specified in Aged
Timeout.

The Reap Time interval also affects performance. Smaller intervals mean that the pool maintenance thread
runs more often and degrades performance.

To disable the pool maintenance thread set Reap Time to 0, or set both Unused Timeout and Aged
Timeout to 0. The recommended way to disable the pool maintenance thread is to set Reap Time to 0, in
which case Unused Timeout and Aged Timeout are ignored. However, if Unused Timeout and Aged
Timeout are set to 0, the pool maintenance thread runs, but only physical connections which timeout due
to non-zero timeout values are discarded.

Data type Integer

Units Seconds
Default 180
Range 0 to max int

Unused Timeout:

Specifies the interval in seconds after which an unused or idle connection is discarded.

Set the Unused Timeout value higher than the Reap Timeout value for optimal performance. Unused
physical connections are only discarded if the current number of connections exceeds the Minimum
Connections setting. For example, if the unused timeout value is set to 120, and the pool maintenance
thread is enabled (Reap Time is not 0), any physical connection that remains unused for two minutes is
discarded. Note that accuracy of this timeout, as well as performance, is affected by the Reap Time value.
See Reap Time for more information.

Data type Integer

Units Seconds
Default 1800
Range 0 to max int

Aged Timeout:

Specifies the interval in seconds before a physical connection is discarded.

Setting Aged Timeout to 0 supports active physical connections remaining in the pool indefinitely. Set the
Aged Timeout value higher than the Reap Timeout value for optimal performance. For example, if the
Aged Timeout value is set to 1200, and the Reap Time value is not 0, any physical connection that
remains in existence for 1200 seconds (20 minutes) is discarded from the pool. Note that accuracy of this
timeout, as well as performance, are affected by the Reap Time value. See Reap Time for more
information.

Data type Integer

Units Seconds
Default 0
Range 0 to max int

1402 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Purge Policy:

Specifies how to purge connections when a stale connection or fatal connection error is detected.

Valid values are EntirePool and FailingConnectionOnly. JCA data sources can have either option.
WebSphere Version 4.0 data sources always have a purge policy of EntirePool.

Data type String

Default EntirePool
Range
EntirePool
All connections in the pool are marked stale. Any
connection not in use is immediately closed. A
connection in use is closed and issues a stale
connection Exception during the next operation
on that connection. Subsequent getConnection()
requests from the application result in new
connections to the database opening. When
using this purge policy, there is a slight possibility
that some connections in the pool are closed
unnecessarily when they are not stale. However,
this is a rare occurrence. In most cases, a purge
policy of EntirePool is the best choice.
FailingConnectionOnly
Only the connection that caused the stale
connection exception is closed. Although this
setting eliminates the possibility that valid
connections are closed unnecessarily, it makes
recovery from an application perspective more
complicated. Because only the currently failing
connection is closed, there is a good possibility
that the next getConnection() request from the
application can return a connection from the pool
that is also stale, resulting in more stale
connection exceptions.
The connection pretest function attempts to
insulate an application from pooled connections
that are not valid. When a backend resource,
such as a database, goes down, pooled
connections that are not valid might exist in the
free pool. This is especially true when the purge
policy is failingConnectionOnly; in this case, the
failing connection is removed from the pool.
Depending on the failure, the remaining
connections in the pool might not be valid.

Connection pool advanced settings:

Use this page to specify connection pooling related settings.

Properties-shared partitions, free pool partitions, and free pool distribution table size are properties related
to reducing the time a thread needs to wait for a synchronization lock.

Partition support is always enabled. The default values of 0 should be used enabling the connection pool
to pick the best values for performance. In some cases where large multiprocessor systems are used,
adjusting the partition support properties might help performance.

Chapter 8. Developing WebSphere applications 1403

To view this administrative console page, click Resources > Resource Adapters > resource_adapter >
J2C Connection Factories > connection_factory > Connection Pool > Advanced Connection Pool.

Number of shared partitions:

Specifies the number of partitions that are created in each of the shared pools.

Data type integer

Default value 0
Range 0 to max int

Number of free pool partitions:

Specifies the number of partitions that are created in each of the free pools.

Data type integer

Default value 0
Range 0 to max int

Free pool distribution table size:

The free pool distribution table size is used for better distribution of the Subject and CRI hash values
within a hash table to minimize collisions for faster retrieval of a matching free connection.

If there are many incoming requests with varying credentials, this value can help with the distribution of
finding a free pool for a connection for that user. Larger values are more common for installations that
have many different credentials accessing the resource. Smaller values (1) should be used if the same
credentials apply to all incoming requests for the resource.

Data type integer

Default value 0
Range 0 to max int

Surge threshold:

Specifies the number of connections created before surge protection is activated.

Surge protection is designed to prevent overloading of a data source when too many connections are
created at the same time. Surge protection is controlled by two properties, surge threshold and surge
creation interval.

The surge threshold property specifies the number of connections created before surge protection is
activated. After you reach the specified number of connections, you enter surge mode.

The surge creation interval property specifies the amount of time, in seconds, between the creation of
connections when in surge mode.

For example, assume the follow settings:

v maxConnections = 50
v surgeThreshold = 10
v surgeCreationInterval = 30 seconds

If the connection pool receives 15 connection requests, 10 connections are created at about the same
time. The 11th connection is created 30 seconds after the first 10 connections. The 12th connection is

1404 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
created 30 seconds after the 11th connection. Connections continue to be created every 30 seconds until
there are no more new connections needed or you reach the maxConnections value.

Surge connection support starts if the surge threshold is > -1 and the surge creation interval is > 0. The
surge threshold property has a default value of -1, which indicates that it is turned off.

wsadmin examples
$AdminControl getAttribute $objectname surgeCreationInterval
$AdminControl setAttribute $objectname surgeCreationInterval 30
$AdminControl getAttribute $objectname surgeThreshold
$AdminControl setAttribute $objectname surgeThreshold 15

Data type integer

Default value -1
Range -1 to max int

Surge creation interval:

Specifies the amount of time between connection creates when you are in surge protection mode.

If the number of connections specified in the surge threshold property have been made, each request for a
new connection must wait to be created on the surge creation interval. This property has a default value of
20, which indicates that at least 20 seconds should pass between connections being created. Valid values
for this property are any positive integer.

Data type integer

Default value 20
Range 0 to max int

Stuck timer time:

A stuck connection is an active connection that is not responding or returning to the connection pool. If the
pool appears to be stuck (you have reached the stuck threshold), a resource exception is given to all new
connection requests until the pool is unstuck. The stuck timer time property is the interval for the timer.
This is how often the connection pool checks for stuck connections. The default value is 5 seconds.

If an attempt to change the stuck time, stuck timer time, or stuck threshold properties using the wsadmin
scripting tool fails, an IllegalState exception occurs. The pool cannot have any active requests or active
connections during this request. For the stuck connection support to start, all three stuck property values
must be greater than 0 and maximum connections must be greater than 0.

Also, the stuck timer time, if it is set, must be less than the stuck time value. In fact, it is suggested that
the stuck timer time should be one-quarter to one-sixth the value of stuck time so that the connection pool
checks for stuck connections 4 to 6 times before a connection is declared stuck. This reduces the
likelihood of false positives

wsadmin examples
$AdminControl getAttribute $objectname stuckTime
$AdminControl setAttribute $objectname stuckTime 30
$AdminControl getAttribute $objectname stuckTimerTime
$AdminControl setAttribute $objectname stuckTimerTime 15
$AdminControl getAttribute $objectname stuckThreshold
$AdminControl setAttribute $objectname stuckThreshold 10

Data type integer

Default value 5

Chapter 8. Developing WebSphere applications 1405

Range 0 to max int

Stuck time:

A stuck connection is an active connection that is not responding or returning to the connection pool. If the
pool appears to be stuck (you have reached the stuck threshold), a resource exception is given to all new
connection requests until the pool is unstuck. The stuck time property is the interval, in seconds, allowed
for a single active connection to be in use to the backend resource before it is considered to be stuck.

Data type integer

Default value 0
Range 0 to max int

Stuck threshold:

A stuck connection is an active connection that is not responding or returning to the connection pool. If the
pool appears to be stuck (you have reached the stuck threshold), a resource exception is given to all new
connection requests until the pool is unstuck. An application can explicitly catch this exception and
continue processing. The pool will continue to periodically check for stuck connections when the number of
stuck connections is past the threshold. If the number of stuck connections drops below the stuck
threshold, the pool will detect this during its periodic checks and enable the pool to begin servicing
requests again. The stuck threshold is the number of connections that need to be considered stuck for the
pool to be in stuck mode.

Data type integer

Default value 0
Range 0 to max int

Connection pool (Version 4) settings:

Use this page to create a connection pool for a Version 4.0 data source.

To view this administrative console page, click Resources > JDBC Providers > JDBC_provider > Data
Sources (Version 4) > data_source > Connection Pool.

Scope:

Specifies the level to which this resource definition is visible -- the cell, node, or server level.

Resources such as JDBC providers, namespace bindings, or shared libraries can be defined at multiple
scopes, with resources defined at more specific scopes overriding duplicates which are defined at more
general scopes.

Note that no matter what the scope of a defined resource, the resource’s properties only apply at an
individual server level. For example, if you define the scope of a data source at the cell level, all users in
that cell can look up and use that data source, which is unique within that cell. However, resource property
settings are local to each server in the cell. For example, if you define max connections to 10, then each
server in that cell can have 10 connections.
Cell The most general scope. Resources defined at the cell scope are visible from all nodes and
servers, unless they are overridden. To view resources defined in the cell scope, do not specify a
server or a node name in the scope selection form.
Node The default scope for most resource types. Resources defined at the node scope override any
duplicates defined at the cell scope and are visible to all servers on the same node, unless they

1406 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 are overridden at a server scope on that node. To view resources defined in a node scope, do not
specify a server, but select a node name in the scope selection form.
Server
The most specific scope for defining resources. Resources defined at the server scope override
any duplicate resource definitions defined at the cell scope or parent node scope and are visible
only to a specific server. To view resources defined in a server scope, specify a server name as
well as a node name in the scope selection form.

When resources are created, they are always created into the current scope selected in the panel. To view
resources in other scopes, specify a different node or server in the scope selection form.

Data type String

Minimum Pool Size:

Specifies the minimum number of connections to maintain in the pool.

The minimum pool size can affect the performance of an application. Smaller pools require less overhead
when the demand is low because fewer connections are held open to the database. When the demand is
high, the first applications experience a slow response because new connections are created if all others
in the pool are in use.

Data type Integer

Default 1
Range Any non-negative integer.

Maximum Pool Size:

Specifies the maximum number of connections to maintain in the pool.

If the maximum number of connections is reached and all connections are in use, additional requests for a
connection wait up to the number of seconds specified as the connection timeout. The maximum pool size
can affect the performance of an application. Larger pools require more overhead when demand is high
because there are more connections open to the database at peak demand. These connections persist
until idled out of the pool. If the maximum value is smaller, longer wait times or possible connection
timeout errors during peak times can occur. Ensure that the database can support the maximum number
of connections in the application server, in addition to any load that it has outside of the application server.

Data type Integer

Default 10
Range Any positive integer

Connection Timeout:

Specifies the maximum number of seconds an application waits for a connection from the pool before
timing out and issuing a ConnectionWaitTimeout exception to the application.

Setting this value to 0 disables the connection timeout.

Data type Integer

Units Seconds
Default 180
Range Any non-negative integer

Chapter 8. Developing WebSphere applications 1407

Idle Timeout:

Specifies the maximum number of seconds that an idle (unallocated) connection can remain in the pool
before being removed to free resources.

Connections need to idle out of the pool because keeping connections open to the database can cause
database memory problems. However, not all connections are idled out of the pool, even if they are older
than the Idle Timeout setting. A connection is not idled if removing the connection would cause the pool to
shrink below its minimum size. Setting this value to 0 disables the idle timeout.

Data type Integer

Units Seconds
Default 1800
Range Any non-negative integer

Orphan Timeout:

Specifies the maximum number of seconds that an application can hold a connection without using it
before the connection returns to the pool

If there is no activity on an allocated connection for longer than the Orphan Timeout setting, the
connection is marked for orphaning. After another Orphan Timeout number of seconds, if the connection
still has no activity, the connection returns to the pool. If the application tries to use the connection again, it
is issued a stale connection exception. Connections that are enlisted in a transaction are not orphaned.
Setting this value to 0 disables the orphan timeout.

Data type Integer

Units Seconds
Default 1800
Range Any non-negative integer

Statement Cache Size:

Specifies the number of cached prepared statements to keep per connection.

The largest value you would need to set your cache size to if you do not want any cache discards is
determined as follows: for each application that uses this data source on a particular server, add up the
number of unique prepared statements (as determined by the sql string, concurrency, and the scroll type).
This is the maximum number of possible prepared statements that can be cached on a given connection
over the life of the server. Setting the cache size to this value means you never have cache discards. This
provides better performance. However, because of potential resource limitations, this might not always be
possible.

Data type Integer

Default 10
Range Any non-negative integer

Auto Connection Cleanup:

Specifies whether or not the connection pooling software automatically closes connections from this data
source at the end of a transaction.

The default is false, which indicates that when a transaction completes, WebSphere Application Server
closes the connection and returns it to the pool. Any use of the connection after the transaction has ended

1408 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
results in a stale connection exception because the connection is closed and has returned to the pool.
This mechanism ensures that connections are not held indefinitely by the application. If the value is set to
true, the connection is not returned to the pool at the end of a transaction. In this case, the application
must return the connection to the pool by calling close(). If the application does not close the connection,
the pool can run out of connections for other applications to use.

Data type Check box

Default False (clear)

Configuring connection factories for resource adapters within applications:

1. Click Applications.
2. Click Install New Application.
3. Browse to find the appropriate EAR file, which contains an RAR file.
4. Click Next.
5. Select resource ref mapping to a J2C Connection Factory, then click Next.
6. After the application installs, click Applications.
7. Select the application just installed.
8. Click Connector Modules under Related Items.
9. Select an RAR file name on the Connector Modules page.
10. Click Resource Adapter under Additional Properties.
11. Click J2C Connection Factories under Additional Properties.
12. Click New.
13. Specify General Properties.
14. Select a Component-managed authentication alias if any application components with Application
or Per connection factory authentication specified in the resource reference are going to be getting
connections from this connection factory using the empty-argument getConnection() method. For
resources supporting XA, you can optionally specify an Authentication alias for XA recovery. If a
desired alias is not available, or you want to define a different one, click Apply > J2C Authentication
Data Entries under Related Items.
a. Click J2C Auth Data Entries under Related Items.
b. Click New.
c. Specify General Properties.
d. Click OK.
15. Click OK.
16. Click the J2C connection factory you just created.
17. Click Connection Pool under Additional Properties .
18. Change any values desired by clicking on the property name.
19. Click OK.
20. Click Custom Properties under Additional Properties.
21. Click any property name to change its value. Note that UserName and Password if present, are
overridden by the component-managed authentication alias you specified in a previous step.
22. Click Save.

J2C Connection Factories collection:

Use this page to select a connection factory, which represents one set of connection configuration values.

Application components such as enterprise beans have resource reference descriptors that refer to the
connection factory, not the resource adapter. The connection factory is really a configuration properties list

Chapter 8. Developing WebSphere applications 1409

holder. In addition to the arbitrary set of configuration properties defined by the vendor of the resource
adapter, there are several standard configuration properties that apply to the connection factory. These
standard properties are used by the Java 2 Connectors connection pool manager in the application server
run time and are not known by the vendor-supplied resource adapter code.

To view this administrative console page, click Resources > Resource Adapters > resource_adapter >
J2C Connection Factories.

Name:

Specifies a list of the connection factory display names.

Data type String

JNDI name:

Specifies the Java Naming and Directory Interface (JNDI) name of this connection factory.

Data type String

Description:

Specifies a text description of this connection factory.

Data type String

Category:

Specifies a string that you can use to classify or group this connection factory.

Data type String

J2C Connection Factories settings:

Use this page to specify settings for a connection factory.

To view this administrative console page, click Resources > Resource Adapters > resource_adapter >
J2C Connection Factories > connection_factory.

Name:

Specifies a list of connection factory display names.

This is a required property.

Data type String

JNDI Name:

Specifies the JNDI name of this connection factory.

For example, the name could be eis/myECIConnection.

1410 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
After you set this value, save it and restart the server. You can see this string when you run the
dumpNameSpace tool. This is a required property. If you do not specify a JNDI name, it is filled in by
default using the Name field.

Data type String

Default eis/display name

Description:

Specifies a text description of this connection factory.

Data type String

Connection Factory Interface:

Specifies the fully qualified name of the Connection Factory Interfaces supported by the resource adapter.

This is a required property. For new objects, the list of available classes is provided by the resource
adapter in a drop-down list. After you create the connection factory, the field is a read only text field.

Data type Drop-down list or text

Category:

Specifies a string that you can use to classify or group this connection factory.

Data type String

Authentication Alias for XA Recovery:

This optional field is used to specify the authentication alias that should be used during XA recovery
processing.

If the resource adapter does not support XA transactions, then this field will not be displayed. The default
value will come from the selected alias for application authentication (if specified).
Use Component-managed Authentication Alias
Selecting this radio button specifies that the alias set for component-managed authentication is
used at XA recovery time.

Data type Radio button

Specify:
Selecting this radio button enables you to choose an authentication alias from a drop-down list of
configured aliases.

Data type Radio button

Component-managed Authentication Alias:

Specifies authentication data for component-managed signon to the resource.

Choose from aliases defined under Security>JAAS Configuration> J2C Authentication Data.

Chapter 8. Developing WebSphere applications 1411

To define a new alias not already appearing in the pick list:
v Click Apply to expose Related Items.
v Click J2C Authentication Data Entries.
v Define an alias.
v Click the connection factory name at the top of the J2C Authentication Data Entries page to return to
the connection factory page.
v Select the alias.

Data type Pick-list

Container-managed Authentication Alias (deprecated):

Specifies authentication data (a string path converted to userid and password) for container-managed
signon to the resource.

Note: Beginning with WebSphere Application Server Version 6.0, the container-managed authentication
alias is superseded by the specification of a login configuration on the resource-reference mapping
at deployment time, for components with res-auth=Container.

Choose from aliases defined under Security>JAAS Configuration> J2C Authentication Data.

To define a new alias not already appearing in the pick list:

v Click Apply to expose Related Items.
v Click J2C Authentication Data Entries.
v Define an alias.
v Click the connection factory name at the top of the J2C Authentication Data Entries page to return to
the connection factory page.
v Select the alias.

Data type Pick-list

Authentication Preference (deprecated):

Specifies the authentication mechanisms defined for this connection factory.

Note: Beginning with WebSphere Application Server Version 6.0, the authentication preference is
superseded by the combination of the <res-auth> application component deployment descriptor
setting and the specification of a login configuration on the resource-reference mapping at
deployment time.

This setting specifies which of the authentication mechanisms defined for the corresponding resource
adapter applies to this connection factory. Common values, depending on the capabilities of the resource
adapter, are: KERBEROS, BASIC_PASSWORD, and None.

If None is chosen, the application component is expected to manage authentication (<res-

auth>Application</res-auth>). In this case, the user ID and password are taken from one of the following:
v The component-managed authentication alias
v UserName, Password Custom Properties
v Strings passed on the getConnection method

For example, if two authentication mechanism entries are defined for a resource adapter in the ra.xml
document:
v <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
v <authentication-mechanism-type>Kerbv5</authentication-mechanism-type>

1412 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
the authentication preference specifies the mechanism to use for container-managed authentication. An
exception is issued during server startup if a mechanism that is not supported by the resource adapter is
selected.

Data type Pick-list

Default BASIC_PASSWORD

Mapping-Configuration Alias (deprecated):

Allows users to select from the Security > JAAS Configuration > Application Logins Configuration list.

Note: Beginning with WebSphere Application Server Version 6.0, the Mapping-Configuration Alias is
superseded by the specification of a login configuration on the resource-reference mapping at
deployment time, for components with res-auth=Container.

The DefaultPrincipalMapping JAAS configuration maps the authentication alias to the userid and
password. You may define and use other mapping configurations.

Data type Pick-list

J2C Connection Factory advanced settings:

Use this page to specify settings for a connection factory.

To view this administrative console page, click Resources > Resource Adapters > resource_adapter >
J2C Connection Factories > connection_factory > Advanced Connection Factory Properties.

Manage cached handles:

Specifies whether cached handles (handles held in inst vars in a bean) should be tracked by the
container.

Data type Checkbox

Log missing transaction contexts:

Specifies whether or not the container logs that there is a missing transaction context when a connection
is obtained.

Data type Checkbox

Connection factory JNDI name tips: Distributed computing environments often employ naming and
directory services to obtain shared components and resources. Naming and directory services associate
names with locations, services, information, and resources.

Naming services provide name-to-object mappings. Directory services provide information on objects and
the search tools required to locate those objects. There are many naming and directory service
implementations, and the interfaces to them vary.

Java Naming and Directory Interface (JNDI) provides a common interface that is used to access the
various naming and directory services. After you have set this value, saved it, and restarted the server,
you should be able to see this string when you invoke name space dump tool.

Chapter 8. Developing WebSphere applications 1413

For WebSphere Application Server specifically, when you create a data source the default JNDI name is
set to jdbc/data_source_name. When you create a connection factory, its default name is
eis/j2c_connection_factory_name. You can, of course, override these values by specifying your own.

In addition, if you click the checkbox for the Use this data source for container managed persistence
(CMP) option when you create the data source, another reference is created with the name of
eis/jndi_name_of_datasource_CMP. For example, if a data source has a JNDI name of
jdbc/myDatasource, the CMP JNDI name is eis/jdbc/myDatasource_CMP. This name is used internally by
CMP and is provided simply for informational purposes.

When creating a connection factory or data source, a JNDI name is given by which the connection factory
or data source can be looked up by a component. Preferably an ″indirect″ name with the java:comp/env
prefix should be used and must be used in future releases. An ″indirect″ name makes any
resource-reference data associated with the application available to the connection management runtime,
to better manage resources based on the res-auth, res-isolation-level, res-sharing-scope, and
res-resolution-control settings.

Though you can use a direct JNDI name, this naming method is deprecated in Version 6 of WebSphere
Application Server. Application Server assigns default values to the resource-reference data when you use
this method. An informational message, resembling the following, is logged to document the defaults:
J2CA0294W: Deprecated usage of direct JNDI lookup of resource jdbc/IOPEntity.
The following default values are used: [Resource-ref settings]

res-auth: 1 (APPLICATION)
res-isolation-level: 0 (TRANSACTION_NONE)
res-sharing-scope: true (SHAREABLE)
loginConfigurationName: null
loginConfigProperties: null
[Other attributes]

res-resolution-control: 999 (undefined)

isCMP1_x: false (not CMP1.x)
isJMS: false (not JMS)

These default values can lead to unexpected behavior in your resources. For example, an application
component (such as a JAAS login module) that accesses a resource with container-managed
authentication data might fail to authenticate with the backend resource. Because the res-auth setting is
assigned the default level of Application, rather than Container, the application server cannot find it.

This message can occur when you try using the fully qualified names of resources when looking up
resources through Java Naming Directory Interface (JNDI). The J2EE programming model recommends
the use of resource references and the local JNDI java:comp/env context. To correct this problem, modify
the application to use the preferred J2EE programming model with resource references and the local JNDI
java:comp/env context.

Security of lookups with component managed authentication

External Java clients (stand alone clients or servers from other cells) with Java Naming and Directory
Interface (JNDI) access can look up a Java 2 Connector (J2C) resource such as a data source or Java
Message Service (JMS) queue. However, they are not permitted to take advantage of the component
managed authentication alias defined on the resource. This alias is a default value used when the user
and password are not supplied on the getConnection() call. Therefore, if an external client needs to get a
connection, it must assume responsibility for the authentication by passing it through arguments on the
getConnection() call.

Any client running in the WebSphere Application Server process (such as a Servlet or an enterprise bean)
within the same cell that can look up a resource in the JNDI namespace can obtain connections without
explicitly providing authentication data on the getConnection() call. In this case, if the component‘s

1414 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
res-auth setting is Application, authentication is taken from the component-managed authentication alias
defined on the connection factory. With res-auth set to Container, authentication is taken from the login
configuration defined on the component‘s resource-reference. It is important to note that J2C
authentication alias is per cell. An enterprise bean or Servlet in one application server cannot look up a
resource in another server process which is in a different cell, because the alias would not be resolved.

Configuring data access for the Application Client

Configuring data access for the Application Client involves specifying the resource reference and
associated database information required for data access. This specification is done as part of the
assembly and deployment steps for the Application Client.

There are two tools needed to configure data sources used by J2EE application clients:
v An assembly tool such as the Application Server Toolkit (AST) or Rational Web Developer for defining
the resource reference in the deployment descriptor; and
v The Application Client Resource Configuration Tool (ACRCT) for defining the connection to the database
in the client deployment environment.

Data access from an application client uses the JDBC driver connection functions directly from the client
side. It does not take advantage of the additional pooling support available in the WebSphere Application
Server run time. Configuring data access for an application client does not require configuration of a JDBC
provider and data source on the WebSphere Application Server server machine.

If you want to take advantage of the pooling and additional database functions provided by WebSphere
Application Server, it is recommended that your client application utilize an enterprise bean running on the
server side to perform data access.

Defining an application client resource reference using an assembly tool

1. Assemble your application client module as described in Assembling application clients.
2. Create a new resource reference:
a. In a Project Explorer view, right-click your application client module and click Open With >
Deployment Descriptor Editor.
b. On the References tab, click Add > Resource reference > Next.
c. On the Resource Reference page, enter the Name of this resource reference. The Application
Client for WebSphere Application Server run time uses this name for two purposes: to bind the
object into the java:comp/env portion of the JNDI namespace, and to find client specific
configuration information. If the code for the Application Client performs a lookup for
java:comp/env/jdbc/myDB, the name of the resource reference should be jdbc/myDB.
d. For Type, select javax.sql.DataSource for JDBC connections.
e. For Authentication, select Application if your client application intends to provide authentication
information. If the Application Client for WebSphere Application Server run time provides the
authentication information (as configured by the Application Client Resource Configuration tool),
select Container.
f. Ignore the Sharing scope setting; it is unused in an application client resource reference. All
Application Client resources are not shared.
g. Click Finish.
h. Close the deployment descriptor and save your changes.

The JNDI name field appears under WebSphere Bindings after your add the reference.

Client configuration with the ACRCT:

There are two client resources for you to configure in the Application Client Resource Configuration Tool
(ACRCT) to enable data access from an application client: a data source provider and a data source.

Chapter 8. Developing WebSphere applications 1415

Notes

Note: The following WebSphere objects, which can be bound into the server name space, are not
supported on the client:
v Java 2 Connector (J2C) objects
v Connection manager objects

The WebSphere Application Server Client does not provide client database drivers. If your client
application uses a database directly, rather than using an enterprise bean, you must provide the
database drivers on the client machine. This action can involve contacting your database vendor to
acquire client database driver code and licenses.

Instead of accessing the database directly, it is recommended that your client application use an
enterprise bean. Accessing a database through an enterprise bean eliminates the need to have
database drivers on the client machine because the database access is handled by the enterprise
bean running on the WebSphere Application Server. Enterprise beans can also take advantage of
the additional database functions provided by the WebSphere Application Server run time.
1. Configure a new data source provider as described in Configuring new data source providers. This
provider describes the JDBC database implementation for your client application.
2. Enter the following information on the General tab:
a. A name for this data source provider.
b. Optional: A description.
c. The classpath to the data source provider implementation classes or JAR files. This is optional if
the implementation classes or JAR files are already in the class path configuration of the client.
d. The name of the implementation class. For example, for DB2 this value is
COM.ibm.db2.jdbc.DB2DataSource. Remember this class must implement the
javax.sql.DataSource class. The ACRCT does not verify this class and you receive an error when
you run your client application if the class does not implement javax.sql.DataSource.
Use the Custom tab to configure non-standard properties of the data source provider. This panel
enables you to enter property-value pairs. During run time the implementation class name is created
and any custom properties added on this panel are set on the newly created data source object using
reflection. Any properties configured on this panel must have an appropriate set method on the data
source class. For example, assume there is a property called use2Phase and its value should be 1.
On the custom panel you enter the value use2Phase into the name column and the value 1 into the
value column. The Application Client for WebSphere Application Server run time then uses reflection to
find a property on the data source class called, typically setUse2Phase and call that method passing
the value of 1. See your database product documentation for valid properties on your data source
implementation.
3. Click OK.
4. Configure a new data source as described in Configuring new data sources for application clients. This
describes the client properties of the database your client application uses.
5. Enter the following information on the General tab:
a. A Name. This field is required and identifies a name for the Application Client Resource
Configuration Tool to use. This name is not used by your client application program.
b. Optional: A description.
c. The JNDI name. This field is required and must match the value entered in the Name field on the
Add Resource Reference page of the assembly tool. In the example above, set this value to
jdbc/myDB.
d. Optional: The Database Name.
e. Optional: Your userid in the User field.
f. Optional: Your password in the Password field. This password does not display.

1416 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 g. Your password again to confirm in the Re-Enter password field. Note: The User and Password
fields are used only when the Authentication field on the Add Resource Reference page of the
assembly tool is set to Container.

Configuring Cloudscape Version 5.1.60x

Cloudscape provides the following two separate frameworks for running Cloudscape with WebSphere
Application Server:
v Embedded: This framework is the same as the one for Cloudscape Version 5.0. To use this framework,
define a Cloudscape JDBC provider. See the Cloudscape section in the minimum required settings
article for more information.
You must use the embedded framework if you are running XA. Cloudscape does not support XA on
Network Server.
v Network Server: This framework was a new feature in Cloudscape Version 5.1, and removes these
limitations that existed in earlier versions of Cloudscape:
– inability to access a remote Cloudscape instance
– only one JVM can boot up the same database instance
The following steps describe how to configure and run the Network Server framework.
1. Start the Network Server on the machine that hosts the database instance.
To start the Network Server, run the startNetworkServer.bat file, which is located in the
WAS_HOME/cloudscape/bin/networkserver directory. On UNIX platforms, the file is
startNetwokServer.sh.
2. Update the db2j.properties file, which is located in the WAS_HOME/cloudscape directory, if necessary.
Cloudscape should work without any modifications to this file.
Use the entries in the db2j.properties file to turn on trace, change the port number on which Network
Server listens, and enable other functions of the Network Server framework. The default port number
on which the Network Server listens is port 1527.
For more information on this file, see the Cloudscape documentation at
www.ibm.com/software/data/cloudscape/pubs/collateral.html.
3. Define a Cloudscape Network Server using Universal JDBC driver to connect Cloudscape with
WebSphere Application Server using the Network Server framework.
4. Stop the Network Server by invoking the stopNetworkServer.bat file.
You can find this file in the WAS_HOME/cloudscape/bin/networkserver directory. On UNIX platforms, the
file is stopNetworkServer.sh.
5. Review additional tools available in the Network Server framework.
Find these tools in the WAS_HOME/cloudscape/bin/networkserver directory. These tools are:
v sysinfo
v cview
v ij
v dropSYSIBM Use this tool to drop the SYSIBM schema and its contents.
6. Create a SYSIBM schema.
If you do not create the SYSIBM schema, you cannot see the datatypes when you create tables using
the cview graphical user interface. The db2j.drda.loadSYSIBM property in the db2j.properties file
controls whether the schema is created on the first connection to the database. The
db2j.drda.loadSYSIBM property default value is true.
Note: When you run ij, surround the dbname by double quotation marks (″ ″) if it includes the full path
name; for example: ij> connect ’″c:temp;create=true″’
This is ’ ″ ″ ’ without spaces.

Cloudscape Version 5.1.60x post installation instructions:

Chapter 8. Developing WebSphere applications 1417

After installing Cloudscape Version 5.1.60x, you must complete the following steps before you can access
the database.

If you are running a WebSphere Application Server Network Deployment configuration, you must ensure
the correct server or scope is set before completing these steps.
1. Upgrade or migrate any existing database instances.
a. Backup an existing database.
You must complete a backup in case you have to access the previous version of Cloudscape. After
you migrate a database, you cannot access your old database unless you perform a backup.
b. Migrate an existing database by doing the following:
v Set the connectionAttributes custom property to upgrade=true.
The data source is located in the WebSphere Application Server administrative console under
the JDBC providers.
v If you are using the cview interface, located in the WAS_HOME/cloudscape51/bin/embedded
directory, click yes when you see the upgrade database prompt.
Note: Ensure you migrate defaultDB, which is located in the WAS_HOME/bin/DefaultDB directory.
2. Set or change the class path definitions in any existing JDBC providers, which are defined to use
Cloudscape. Cloudscape JAR files will not load when WebSphere Application Server is active.
Use the WebSphere Application Server environment variable
${CLOUDSCAPE_JDBC_DRIVER_PATH}\db2j.jar to point to the new version of Cloudscape.
The CLOUDSCAPE_JDBC_DRIVER_PATH environment variable is defined in WebSphere Application Server
with a value of WAS_HOME/cloudscape/lib.
In a Network Deployment configuration, you must ensure the correct server or scope is set for this
variable to take effect. Typically the scope is the server on which you are running Cloudscape.
3. If the application server is running Cloudscape as a persistent store for UDDI in previous versions,
additional steps are necessary.
The server SystemOut log might issue this message:
The data source class name com.ibm.db2j.jdbc.db2jConnectionPoolDataSource could not be found.
This is because the Cloudscape JAR file has moved to from its location in version 5.x to a new
location in version 5.1x.
To correct this situation, do the following:
a. Upgrade the database to Cloudscape 5.1.60x.
b. Rerun the install script, or edit the class path field in the data source.

DB2 tuning parameters

DB2 has many parameters that you can configure to optimize database performance. For complete DB2
tuning information, refer to the DB2 UDB Administration Guide: Performance.

DB2 logging
v Description: DB2 has corresponding log files for each database that provides services to
administrators, including viewing database access and the number of connections. For systems with
multiple hard disk drives, you can gain large performance improvements by setting the log files for each
database on a different hard drive from the database files.
v How to view or set: At a DB2 command prompt, issue the command: db2 update db cfg for
[database_name] using newlogpath [fully_qualified_path].
v Default value: Logs reside on the same disk as the database.
v Recommended value: Use a separate high-speed drive, preferably performance enhanced through
RAID.

For more information about using AIX with DB2 see ″Tuning operating systems″ in the information center.

DB2 configuration advisor

1418 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Located in the DB2 Control Center, this advisor calculates and displays recommended values for the DB2
buffer pool size, the database, and the database manager configuration parameters, with the option of
applying these values. See more information about the advisor in the online help facility within the Control
Center.

Use TCP/IP sockets for DB2 on Linux

v Description: On Linux platforms, whether the DB2 server resides on a local machine with WebSphere
Application Server or on a remote machine, configure the DB2 application databases to use TCP/IP
sockets for communications with the database.
v How to view or set: Locate the directions for configuring DB2 on Linux in the Installing your application
serving environment PDF. This document specifies setting DB2COMM for TCP/IP and corresponding
changes required in the etc/service file.
v Default value: Shared memory for local databases
v Recommended value: On Linux, change the specification for the DB2 application databases and any
session databases from shared memory to TCP/IP sockets.

Number of connections to DB2 - MaxAppls and MaxAgents

When configuring the data source settings for the databases, confirm the DB2 MaxAppls setting is greater
than the maximum number of connections for the data source. If you are planning to establish clones, set
the MaxAppls value as the maximum number of connections multiplied by the number of clones. The
same relationship applies to the session manager number of connections. The MaxAppls setting must be
equal to or greater than the number of connections. If you are using the same database for session and
data sources, set the MaxAppls value as the sum of the number of connection settings for the session
manager and the data sources.

For example, MaxAppls = (# of connections set for data source + # of connections in session manager) x
# of clones.

After calculating the MaxAppls settings for the WebSphere database and each of the application
databases, verify that the MaxAgents setting for DB2 is equal to or greater than the sum of all of the
MaxAppls values, for example, MaxAgents = sum of MaxAppls for all databases.

DB2 buffpage
v Description: Improves database system performance. Buffpage is a database configuration parameter.
A buffer pool is a memory storage area where database pages containing table rows or index entries
are temporarily read and changed. Data is accessed much faster from memory than from disk.
v How to view or set: To view the current value of buffpage for database x, issue the DB2 command get
db cfg for x and look for the value BUFFPAGE. To set BUFFPAGE to a value of n, issue the DB2
command update db cfg for x using BUFFPAGE n and set NPAGES to -1 as follows:
db2 <-- go to DB2 command mode, otherwise the following "select" does not work as is
connect to x <-- (where x is the particular DB2 database name)
select * from syscat.bufferpools
(and note the name of the default, perhaps: IBMDEFAULTBP)
(if NPAGES is already -1, there is no need to issue following command)
alter bufferpool IBMDEFAULTBP size -1
(re-issue the above "select" and NPAGES now equals -1)
You can collect a snapshot of the database while the application is running and calculate the buffer pool
hit ratio as follows:
1. Collect the snapshot:
a. Issue the update monitor switches using bufferpool on command.
b. Make sure that bufferpool monitoring is on by issuing the get monitor switches command.
c. Clear the monitor counters with the reset monitor all command.
2. Run the application.
3. Issue the get snapshot for all databases command before all applications disconnect from the
database, otherwise statistics are lost.
4. Issue the update monitor switches using bufferpool off command.
Chapter 8. Developing WebSphere applications 1419
 5. Calculate the hit ratio by looking at the following database snapshot statistics:
– Buffer pool data logical reads
– Buffer pool data physical reads
– Buffer pool index logical reads
– Buffer pool index physical reads
v Default value: 250
v Recommended value: Continue increasing the value until the snapshot shows a satisfactory hit rate.

The buffer pool hit ratio indicates the percentage of time that the database manager did not need to load a
page from disk to service a page request. That is, the page was already in the buffer pool. The greater the
buffer pool hit ratio, the lower the frequency of disk input and output. Calculate the buffer pool hit ratio as
follows:
v P = buffer pool data physical reads + buffer pool index physical reads
v L = buffer pool data logical reads + buffer pool index logical reads
v Hit ratio = (1-(P/L)) * 100%

DB2 query optimization level

v Description: Sets the amount of work and resources that DB2 puts into optimizing the access plan.
When a database query is executed in DB2, various methods are used to calculate the most efficient
access plan. The range is from zero to 9. An optimization level of 9 causes DB2 to devote a lot of time
and all of its available statistics to optimizing the access plan.
v How to view or set: The optimization level is set on individual databases and can be set with either the
command line or with the DB2 Control Center. Static SQL statements use the optimization level
specified on the prep and bind commands. If the optimization level is not specified, DB2 uses the
default optimization as specified by the dft_queryopt setting. Dynamic SQL statements use the
optimization class specified by the current query optimization special register, which is set using the
SQL Set statement. For example, the following statement sets the optimization class to 1:
Set current query optimization = 1

If the current query optimization register is not set, dynamic statements are bound using the default
query optimization class.
v Default value: 5
v Recommended value: Set the optimization level for the needs of the application. Use high levels only
when there are very complicated queries.

DB2 reorgchk
v Description: Obtains the current statistics for data and rebinding. Use this parameter because SQL
statement performance can deteriorate after many updates, deletes or inserts.
v How to view or set: Use the DB2 reorgchk update statistics on table all command to issue runstats
on all user and system tables for the database to which you are currently connected. Rebind packages
using the bind command. If runstats exists, issue the db2 -v ″select tbname, nleaf, nlevels,
stats_time from sysibm.sysindexes″ command on DB2 CLP. If no runstats exist, nleaf and nlevels are
-1, and stats_time has an empty entry , for example ″-″. If runstats was previously done, the real-time
stamp from completion of the runstats also displays under stats_time. If you think the time shown for the
previous runstats is too old, execute runstats again.
v Default value: None
v Recommended value: None

DB2 MinCommit
v Description: Delays the writing of log records to a disk until a minimum number of commits is
performed, reducing the database manager overhead associated with writing log records. For example,
if MinCommit is set to 2, a second commit causes output to the transaction log for the first and second
commits. The exception occurs when a one-second timeout forces the first commit to be output if a
second commit does not occur within one second.
In test applications, up to 90% of the disk input and output was related to the DB2 transaction log.
Changing MinCommit from 1 to 2 reduced the results to 45%.
1420 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Adjust this parameter if the disk input and output wait is more than 5% and there is DB2 transaction log
activity from multiple sources. When a lot of activity occurs from multiple sources, it is less likely that a
single commit has to wait for another commit, or the one second timeout. Do not adjust this parameter if
you have an application with a single thread performing a series of commits because each commit can
hit the one second delay.
v How to view or set:
1. Issue the DB2 get db cfg for xxxxxxcommand, where xxxxxx is the name of the application
database, to list database configuration parameters.
2. Look for ″Group commit count (MINCOMMIT)″.
3. Set a new value by issuing the DB2 update db cfg for xxxxxx using mincommit n command,
where xxxxxx is the name of the application database and n is a value between 1 and 25 inclusive.
The new setting takes effect immediately.
The following are several metrics that are related to DB2 MinCommit:
– The disk input and output wait can be observed on AIX with the command vmstat 5. This shows
statistics every 5 seconds. Look for the wa column under the CPU area.
– The percentage of time a disk is active can be observed on AIX with the command iostat 5. This
shows statistics every 5 seconds. Look for the %tm_act column.
– The DB2 get snapshot for db on xxxxxx command , where xxxxxx is the name of the application
database, shows counters for log pages read and log pages written.
v Default value: 1.
v Recommended value: 1 or 2, if the circumstance permits.

DB2 Deadlock Event Monitor

v Description:For DB2 V8 or later, deadlock event monitor is turned on by default when a database is
created. This event monitor captures critical information about all connections involved in deadlock
when the particular event occurs. Although there is not much overhead on faster SMP systems, it can
be turned off.
v How to view or set: In DB2 command window, issue following commands:
db2 connect to [db name]
db2 set event monitor db2detaildeadlock state 0
db2 drop event monitor db2detaildeadlock
db2 connect reset
db2 terminate

.
v Default value: Event monitor is ON by default.
v Recommended value: Turn OFF event monitor, if it is not required.

For more information about using AIX with DB2 see ″Tuning operating systems.″.

Vendor-specific data sources minimum required settings

Use this table as an at-a-glance reference of JDBC providers that can be defined for use with WebSphere
Application Server Version 6.x. A list that contains detailed descriptions for all of these providers follows
the table.

Version and other

Database type JDBC Provider Transaction support
considerations
DB2 Universal JDBC One phase only
Provider
DB2 Universal JDBC One and two phase
DB2 on Windows, UNIX, Provider (XA)
or workstation-based
LINUX DB2 legacy CLI-based Type One phase only
2 JDBC Provider
DB2 legacy CLI-based Type One and two phase
2 JDBC Provider (XA)

Chapter 8. Developing WebSphere applications 1421

 Version and other
Database type JDBC Provider Transaction support
considerations
DB2 UDB for iSeries One phase only Recommended for use with
(Native) WebSphere Application
Server run on iSeries
DB2 UDB for iSeries One and two phase Recommended for use with
(Native XA) WebSphere Application
Server run on iSeries
DB2 UDB for iSeries One phase only Recommended for use with
(Toolbox) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 UDB for iSeries One and two phase Recommended for use with
(Toolbox XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 UDB for iSeries DB2 legacy CLI-based Type One phase only -Only for use with
2 JDBC Provider WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect driver (available
from DB2)
DB2 legacy CLI-based Type One and two phase -Only for use with
2 JDBC Provider (XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect driver (available
from DB2)

1422 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Version and other
Database type JDBC Provider Transaction support
considerations
DB2 for z/OS Local JDBC One and two phase Only for use with
Provider (RRS) WebSphere Application
Server run on z/OS
DB2 Universal JDBC One phase only Only for use with
Provider WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 Universal JDBC One and two phase Only for use with
Provider (XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX
DB2 legacy CLI-based Type One phase only -Only for use with
DB2 on z/OS 2 JDBC Provider WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect program (available
from DB2)
DB2 legacy CLI-based Type One and two phase -Only for use with
2 JDBC Provider (XA) WebSphere Application
Server run on Windows,
UNIX, or workstation-based
LINUX

- Requires the DB2

Connect program (available
from DB2)
Cloudscape JDBC Provider One phase only - Not for use in clustering
environment: Cloudscape is
accessible from a single
JVM only

- Does not support Version

4 data sources
Cloudscape JDBC Provider One and two phase - Not for use in clustering
Cloudscape
(XA) environment: Cloudscape is
accessible from a single
JVM only

- Does not support Version

4 data sources
Cloudscape Network Server One phase only Does not support Version 4
using Universal JDBC driver data sources
Informix JDBC Driver One phase only
Informix
Informix JDBC Driver (XA) One and two phase
Sybase JDBC Driver One phase only
Sybase
Sybase JDBC Driver (XA) One and two phase
Oracle JDBC Driver One phase only
Oracle
Oracle JDBC Driver (XA) One and two phase

Chapter 8. Developing WebSphere applications 1423

 Version and other
Database type JDBC Provider Transaction support
considerations
DataDirect ConnectJDBC One phase only Only for use with the
type 4 driver for MS SQL corresponding driver from
Server DataDirect Technologies
DataDirect ConnectJDBC One and two phase Only for use with the
type 4 driver for MS SQL corresponding driver from
Server (XA) DataDirect Technologies
WebSphere embedded One phase only - Not available for
ConnectJDBC driver for MS Application Server on z/OS
MS SQL Server SQL Server
- Cannot be used outside of
WebSphere Application
Server environment
WebSphere embedded One and two phase - Not available for
ConnectJDBC driver for MS Application Server on z/OS
SQL Server (XA)
- Cannot be used outside of
WebSphere Application
Server environment

Detailed JDBC provider list

The following list contains a description of every JDBC provider that can be defined for use with
WebSphere Application Server Version 6.x. It also shows the supported data source classes and their
required properties. Specific fields are designated for the user and password properties. Inclusion of a
property in the list does not imply that you should add it to the data source properties list. Rather, inclusion
in the list means that a value is typically required for that field.

Use these links to find your provider information:

v DB2 on Windows, UNIX, or workstation-based LINUX
v DB2 UDB for iSeries
v DB2 on z/OS, connecting to Application Server on Windows, UNIX, or workstation-based LINUX
v Cloudscape
v Informix
v Sybase
v Oracle
v MS SQL Server

DB2 on Windows, UNIX, or workstation-based LINUX

1. DB2 Universal JDBC Provider
The DB2 Universal JDBC Driver is an architecture-neutral JDBC driver for distributed and local DB2
access. Because the Universal Driver architecture is independent of any particular JDBC driver
connectivity or target platform, it allows both Java connectivity (Type 4) or Java Native Interface (JNI)
based connectivity (Type 2) in a single driver instance to DB2.
This JDBC driver allows applications to use both JDBC and Structured Query Language in Java
(SQLJ) access.
The DB2 Universal JDBC Driver Provider supports one phase data source:
com.ibm.db2.jcc.DB2ConnectionPoolDataSource

Requires JDBC driver files:

v db2jcc.jar After you install DB2, you can find this jar file in the DB2 java directory. For Type 4
JDBC driver support from a client machine where DB2 is not installed, copy this file to the local
machine. If you install any fixes or upgrades to DB2, you must update this file as well. You must

1424 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 also set the DB2UNIVERSAL_JDBC_DRIVER_PATH path variable to point to the db2jcc.jar file.
See the Cloudscape section for more information on the DB2UNIVERSAL_JDBC_DRIVER_PATH
path variable.

Note: To find out the version of the universal driver you are using, issue this DB2 command:
java com.ibm.db2.jcc.DB2Jcc -version

The output for the above example is:

IBM DB2 JDBC Universal Driver Architecture 2.2.xx
v db2jcc_license_cu.jar This is the DB2 Universal JDBC driver license file that allows access to the
DB2 Universal database. Use this jar file or the next one to gain access to the database. This jar file
ships with WebSphere Application Server in a directory defined by
${UNIVERSAL_JDBC_DRIVER_PATH}environment variable.
v db2jcc_license_cisuz.jar This is the DB2 Universal JDBC driver license file that allows access to
the following databases:
– DB2 Universal
– DB2 for iSeries
– DB2 for z/OS
– SQLDS
The db2jcc_license_cisuz.jar does not ship with Websphere Application Server and should be
located in the same directory as the db2jcc.jar file, so that the
DB2UNIVERSAL_JDBC_DRIVER_PATH points to both.
The classpath for this provider is set as follows:

<classpath>${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc.jar </classpath>
<classpath>${UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cu.jar</classpath>
<classpath>${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cisuz.jar</classpath>

Note: The license jar files are independent of each other; therefore, order does not matter.
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2UniversalDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v databaseName This is an actual database name if the driverType is set to 4, or a locally cataloged
database name if the driverType is set to 2.
v driverType The JDBC connectivity type of a data source. There are two permitted values: 2 and 4.
If you want to use Universal JDBC Type 2 driver, set this value to 2. If you want to use Universal
JDBC Type 4 driver, set this value to 4.
v serverName The TCP/IP address or host name for the Distributed Relational Database Architecture
(DRDA) server. Provide a value for this property only if your driverType is set to 4. This property is
not required if your driverType is set to 2.
v portNumber The TCP/IP port number where the DRDA server resides. Provide a value for this
property only if your driverType is set to 4. This property is not required if your driverType is set to
2.
2. DB2 Universal JDBC Provider (XA)
The DB2 Universal JDBC Provider (XA) is an architecture-neutral JDBC provider for distributed and
local DB2 access. Whether you use this provider for Java connectivity or Java Native Interface (JNI)
based connectivity depends on the version of DB2 you are running. Application Server Version 6.0
minimally requires DB2 8.1 Fix Pack 6. This version of DB2 only supports XA connectivity over the
Java Native Interface (JNI) based connectivity (Type 2) driver. In order to use XA connectivity with the
Type 4 driver, DB2 8.1 Fix Pack 7 or higher is required.
The DB2 Universal JDBC Driver (XA) supports two phase transactions and the more advanced data
source option offered by Application Server (as opposed to the other option, Version 4 data sources).
This driver also allows applications to use both JDBC and SQLJ access.

Chapter 8. Developing WebSphere applications 1425

 The DB2 Universal JDBC Driver Provider supports the two phase data source:
com.ibm.db2.jcc.DB2XADataSource
Requires JDBC driver files:
v db2jcc.jar After you install DB2, you can find this .jar file in the DB2 java directory. For Type 4
JDBC driver support from a client machine where DB2 is not installed, copy this file to the local
machine. If you install any fixes or upgrades to DB2, you must update this file as well. You must
also set the DB2UNIVERSAL_JDBC_DRIVER_PATH environment variable to point to the
db2jcc.jar file. See the Cloudscape section for more information on the
DB2UNIVERSAL_JDBC_DRIVER_PATH environment variable.

Note: To find the level of universal driver you are using, issue the following DB2 command:
java com.ibm.db2.jcc.DB2Jcc -version

example output of the above:

IBM DB2 JDBC Universal Driver Architecture 2.2.xx
v db2jcc_license_cu.jar This is the DB2 Universal JDBC driver license file that allows access to the
DB2 Universal database. Use this jar file or the next one to gain access to the database. This jar file
ships with WebSphere Application Server in the WAS_HOME/universalDriver/lib directory.
v db2jcc_license_cisuz.jar This is the DB2 Universal JDBC driver license file that allows access to
the following databases:
– DB2 Universal
– DB2 for iSeries
– DB2 for z/OS
– SQLDS
You must use the right license jar file to access a specific database backend.
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2UniversalDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v databaseName This is an actual database name if the driverType is set to 4, or a locally cataloged
database name if the driverType is set to 2.
v driverType The JDBC connectivity type of a data source. There are two permitted values: 2 and 4.
If you want to use Universal JDBC Type 2 XA driver, set this value to 2. If you want to use Universal
JDBC Type 4 XA driver (which requires DB2 8.1 Fix Pack 7 or higher), set this value to 4.
v serverName The TCP/IP address or host name for the Distributed Relational Database Architecture
(DRDA) server. Provide a value for this property only if your driverType is set to 4. This property is
not required if your driverType is set to 2.
v portNumber The TCP/IP port number where the DRDA server resides. Provide a value for this
property only if your driverType is set to 4. This property is not required if your driverType is set to
2.
3. DB2 legacy CLI-based Type 2 JDBC Driver
The DB2 legacy CLI-based Type 2 JDBC Driver Provider is built on top of DB2 CLI (Call Level
Interface). It uses the DB2 CLI interface to communicate with DB2 UDB servers.
DB2 legacy CLI-based Type 2 JDBC Driver supports one phase data source:
COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource
Requires JDBC driver files: db2java.zip (Note: If you run SQLJ in DB2 Version 8, db2jcc.jar is also
required.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2DataStoreHelper
Does not require a valid authentication alias if Application Server is running on the same machine as
the database. Otherwise, connectivity through this driver does require an alias.
Requires properties:

1426 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
4. DB2 legacy CLI-based Type 2 JDBC Driver (XA)
The DB2 legacy CLI-based Type 2 JDBC Driver (XA) is built on top of DB2 CLI (Call Level Interface).
It uses the DB2 CLI interface to communicate with DB2 UDB servers.
DB2 legacy CLI-based Type 2 JDBC Driver (XA) supports two phase data source:
COM.ibm.db2.jdbc.DB2XADataSource
Requires JDBC driver files: db2java.zip (Note: If you run SQLJ in DB2 Version 8, db2jcc.jar is also
required.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2DataStoreHelper
Does not require a valid authentication alias if Application Server is running on the same machine as
the database. Otherwise, connectivity through this driver does require an alias.
Requires properties:
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.

For more information on DB2, visit the DB2 Web site at: http://www.ibm.com/software/data/db2/.

For information on configuring WebSphere Application Server for DB2 access, see the ″Configuring DB2″
article in the information center.

DB2 UDB for iSeries

1. DB2 UDB for iSeries (Native)
The iSeries Developer Kit for Java contains this Type 2 JDBC driver that is built on top of the iSeries
DB2 Call Level Interface (CLI) native libraries. Only use this driver for local DB2 connections on
iSeries. It is not recommended for remote access. Use this driver for iSeries V5R2, or later releases.
DB2 UDB for iSeries (Native V5R2 and later) supports one phase data source:
com.ibm.db2.jdbc.app.UDBConnectionPoolDataSource
Requires JDBC driver files: db2_classes.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2AS400DataStoreHelper
Does not require an authentication alias.
Requires properties:
v databaseName The name of the relational database to which the data source connections are
established. This name must appear in the iSeries Relational Database Directory. The default is
*LOCAL.
2. DB2 UDB for iSeries (Native XA)
The iSeries Developer Kit for Java contains this XA-compliant Type 2 JDBC driver built on top of the
iSeries DB2 Call Level Interface (CLI) native libraries. Only use this driver for local DB2 connections on
iSeries. It is not recommended for remote access. Use this driver for iSeries V5R2 or later releases.
DB2 UDB for iSeries (Native XA - V5R2 and later) supports two phase data source:
com.ibm.db2.jdbc.app.UDBXADataSource
Requires JDBC driver files: db2_classes.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2AS400DataStoreHelper
Does not require an authentication alias.
Requires properties:

Chapter 8. Developing WebSphere applications 1427

 v databaseName The name of the relational database to which the data source connections are
established. This name must appear in the iSeries Relational Database Directory. The default is
*LOCAL.
3. DB2 UDB for iSeries (Toolbox)
This JDBC driver, also known as iSeries Toolbox driver for Java, is provided in the DB2 for iSeries
database server. Use this driver for remote DB2 connections on iSeries. We recommend you use this
driver instead of the IBM Developer Kit for Java JDBC Driver to access remote DB2 UDB for iSeries
systems.
DB2 UDB for iSeries (Toolbox) supports one phase data source:
com.ibm.as400.access.AS400JDBCConnectionPoolDataSource
Requires JDBC driver files: jt400.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2AS400DataStoreHelper
Does not require an authentication alias if WebSphere Application Server and DB2 UDB for iSeries are
installed in the same server. If they are installed in different servers, the user ID and password are
required.
Requires properties:
v serverName The name of the server from which the data source obtains connections. Example:
myserver.mydomain.com.
4. DB2 UDB for iSeries (Toolbox XA)
This XA compliant JDBC driver, also known as iSeries Toolbox XA compliant driver for Java, is
provided in the DB2 for iSeries database server. Use this driver for remote DB2 connections on
iSeries. We recommend you use this driver instead of the IBM Developer Kit for Java JDBC Driver to
access remote DB2 UDB for iSeries systems.
DB2 UDB for iSeries (Toolbox XA) supports two phase data source:
com.ibm.as400.access.AS400JDBCXADataSource
Requires JDBC driver files: jt400.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2AS400DataStoreHelper
Does not require an authentication alias if WebSphere Application Server and DB2 UDB for iSeries are
installed in the same server. If they are installed in different servers, the user ID and password are
required.
Requires properties:
v serverName The name of the server from which the data source obtains connections. Example:
myserver.mydomain.com.
5. DB2 legacy CLI-based Type 2 JDBC Driver
The DB2 legacy CLI-based Type 2 JDBC Driver Provider is built on top of DB2 CLI (Call Level
Interface). It uses the DB2 CLI interface to communicate with DB2 UDB servers. This provider is
intended for remote connections to DB2 running on iSeries; for use with Application Server on
Windows, UNIX, or workstation-based LINUX, it therefore requires the DB2 Connect Driver (which is
available from DB2).
DB2 legacy CLI-based Type 2 JDBC Driver supports one phase data source:
COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource
Requires JDBC driver files: db2java.zip (Note: If you run SQLJ in DB2 Version 8, db2jcc.jar is also
required.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2DataStoreHelper
Does not require a valid authentication alias.
Requires properties:

1428 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
6. DB2 legacy CLI-based Type 2 JDBC Driver (XA)
The DB2 legacy CLI-based Type 2 JDBC Driver (XA) is built on top of DB2 CLI (Call Level Interface).
It uses the DB2 CLI interface to communicate with DB2 UDB servers. This provider is intended for
remote connections to DB2 running on iSeries; for use with Application Server on Windows, UNIX, or
workstation-based LINUX, it therefore requires the DB2 Connect Driver (which is available from DB2).
DB2 legacy CLI-based Type 2 JDBC Driver (XA) supports two phase data source:
COM.ibm.db2.jdbc.DB2XADataSource
Requires JDBC driver files: db2java.zip (Note: If you run SQLJ in DB2 Version 8, db2jcc.jar is also
required.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2DataStoreHelper
Does not require a valid authentication alias.
Requires properties:
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
7. DB2 UDB for iSeries (Native - Version 5 Release 1 and earlier) -- Deprecated
This JDBC provider is deprecated because it corresponds to a version of the iSeries operating system
that WebSphere Application Server Version 6.x does not support. You must now use iSeries V5R2 or a
later release of the iSeries operating system, for which the WebSphere Application Server
administrative console lists one native iSeries DB2 non-XA provider: DB2 UDB for iSeries (Native).
The iSeries Developer Kit for Java contains this Type 2 JDBC driver that is built on top of the iSeries
DB2 Call Level Interface (CLI) native libraries. Only use this driver for local DB2 connections on
iSeries. It is not recommended for remote access. Use this driver for iSeries V5R1, or earlier releases.
DB2 UDB for iSeries (Native V5R1 and earlier) supports one phase data source:
com.ibm.db2.jdbc.app.DB2StdConnectionPoolDataSource
Requires JDBC driver files: db2_classes.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2AS400DataStoreHelper
Does not require an authentication alias.
Requires properties:
v databaseName The name of the relational database to which the data source connections are
established. This name must appear in the iSeries Relational Database Directory. The default is
*LOCAL.
8. DB2 UDB for iSeries (Native XA - Version 5 Release 1 and earlier) -- Deprecated
This JDBC provider is deprecated because it corresponds to a version of the iSeries operating system
that WebSphere Application Server Version 6.x does not support. You must now use iSeries V5R2 or a
later release of the iSeries operating system, for which the administrative console lists one native
iSeries DB2 XA provider: DB2 UDB for iSeries (Native XA).
The iSeries Developer Kit for Java contains this XA-compliant Type 2 JDBC driver built on top of the
iSeries DB2 Call Level Interface (CLI) native libraries. Only use this driver for local DB2 connections on
iSeries. It is not recommended for remote access. Use this driver for iSeries V5R1, or earlier releases.
DB2 UDB for iSeries (Native XA - V5R1 and earlier) supports two phase data source:
com.ibm.db2.jdbc.app.DB2StdXADataSource
Requires JDBC driver files: db2_classes.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2AS400DataStoreHelper
Does not require an authentication alias.
Requires properties:

Chapter 8. Developing WebSphere applications 1429

 v databaseName The name of the relational database to which the data source connections are
established. This name must appear in the iSeries Relational Database Directory. The default is
*LOCAL.

For more information on DB2 UDB for iSeries, visit the DB2 Web site at:
http://www.ibm.com/software/data/db2/

DB2 on z/OS, connecting to Application Server on Windows, UNIX, or workstation-based LINUX

1. DB2 Universal JDBC Provider
The DB2 Universal JDBC Driver is an architecture-neutral JDBC driver for distributed and local DB2
access. Because the Universal Driver architecture is independent of any particular JDBC driver
connectivity or target platform, it allows both Java connectivity (Type 4) or Java Native Interface (JNI)
based connectivity (Type 2) in a single driver instance to DB2. Starting with WebSphere Application
Server Version 5.0.2, the product now supports both Type 2 and Type 4 JDBC drivers. To use the Type
4 driver, you must install DB2 Version 8.1 or a later version. To use the Type 2 driver, you must install
DB2 Version 8.1 Fix Pack 2 or a later version.
This JDBC driver allows applications to use both JDBC and Structured Query Language in Java
(SQLJ) access.
The DB2 Universal JDBC Driver Provider supports one phase data source:
com.ibm.db2.jcc.DB2ConnectionPoolDataSource

Requires JDBC driver files:

v db2jcc.jar After you install DB2, you can find this jar file in the DB2 java directory. For Type 4
JDBC driver support from a client machine where DB2 is not installed, copy this file to the local
machine. If you install any fixes or upgrades to DB2, you must update this file as well. You must
also set the DB2UNIVERSAL_JDBC_DRIVER_PATH path variable to point to the db2jcc.jar file.
See the Cloudscape section for more information on the DB2UNIVERSAL_JDBC_DRIVER_PATH
path variable.

Note: To find out the version of the universal driver you are using, issue this DB2 command:
java com.ibm.db2.jcc.DB2Jcc -version

The output for the above example is:

IBM DB2 JDBC Universal Driver Architecture 2.2.xx
v db2jcc_license_cu.jar This is the DB2 Universal JDBC driver license file that allows access to the
DB2 Universal database. Use this jar file or the next one to gain access to the database. This jar file
ships with WebSphere Application Server in a directory defined by
${UNIVERSAL_JDBC_DRIVER_PATH}environment variable.
v db2jcc_license_cisuz.jar This is the DB2 Universal JDBC driver license file that allows access to
the following databases:
– DB2 Universal
– DB2 for iSeries
– DB2 for z/OS
– SQLDS
The db2jcc_license_cisuz.jar does not ship with Websphere Application Server and should be
located in the same directory as the db2jcc.jar file, so that the
DB2UNIVERSAL_JDBC_DRIVER_PATH points to both.
The classpath for this provider is set as follows:

<classpath>${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc.jar </classpath>
<classpath>${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cu.jar</classpath>
<classpath>${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cisuz.jar</classpath>

Note: The license jar files are independent of each other; therefore, order does not matter.
Requires DataStoreHelper class:

1430 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 com.ibm.websphere.rsadapter.DB2UniversalDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v databaseName This is an actual database name if the driverType is set to 4, or a locally cataloged
database name if the driverType is set to 2.
v driverType The JDBC connectivity type of a data source. There are two permitted values: 2 and 4.
If you want to use Universal JDBC Type 2 driver, set this value to 2. If you want to use Universal
JDBC Type 4 driver, set this value to 4.
v serverName The TCP/IP address or host name for the Distributed Relational Database Architecture
(DRDA) server. Provide a value for this property only if your driverType is set to 4. This property is
not required if your driverType is set to 2.
v portNumber The TCP/IP port number where the DRDA server resides. Provide a value for this
property only if your driverType is set to 4. This property is not required if your driverType is set to
2.
2. DB2 Universal JDBC Provider (XA)
The DB2 Universal JDBC Driver (XA) is an architecture-neutral JDBC driver for distributed and local
DB2 access. In WebSphere Application Server Version 5.0.2, this driver only supports Java Native
Interface (JNI) based connectivity (Type 2) in a single driver instance to DB2. To use this driver, you
must install DB2 Version 8.1 Fix Pack 2 or a later version. This driver supports two phase transactions
and the WebSphere Application Server Version 5.0 data source. This driver allows applications to use
both JDBC and SQLJ access.
The DB2 Universal JDBC Driver Provider supports the two phase data source:
com.ibm.db2.jcc.DB2XADataSource
Requires JDBC driver files:
v db2jcc.jar After you install DB2, you can find this .jar file in the DB2 java directory. For Type 4
JDBC driver support from a client machine where DB2 is not installed, copy this file to the local
machine. If you install any fixes or upgrades to DB2, you must update this file as well. You must
also set the DB2UNIVERSAL_JDBC_DRIVER_PATH environment variable to point to the
db2jcc.jar file. See the Cloudscape section for more information on the
DB2UNIVERSAL_JDBC_DRIVER_PATH environment variable.

Note: To find the level of universal driver you are using, issue the following DB2 command:
java com.ibm.db2.jcc.DB2Jcc -version

example output of the above:

IBM DB2 JDBC Universal Driver Architecture 2.2.xx
v db2jcc_license_cu.jar This is the DB2 Universal JDBC driver license file that allows access to the
DB2 Universal database. Use this jar file or the next one to gain access to the database. This jar file
ships with WebSphere Application Server in the WAS_HOME/universalDriver/lib directory.
v db2jcc_license_cisuz.jar This is the DB2 Universal JDBC driver license file that allows access to
the following databases:
– DB2 Universal
– DB2 for iSeries
– DB2 for z/OS
– SQLDS
You must use the right license jar file to access a specific database backend.
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2UniversalDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v databaseName This is a locally cataloged database name.
v driverType This is the JDBC connectivity type of a data source. If you are running a version of DB2
prior to DB2 V8.1 FP6, you are restricted to using only the type 2 driver.

Chapter 8. Developing WebSphere applications 1431

 v serverName The TCP/IP address or host name for the Distributed Relational Database Architecture
(DRDA) server. Provide a value for this property only if your driverType is set to 4. This property is
not required if your driverType is set to 2.
v portNumber The TCP/IP port number where the DRDA server resides. Provide a value for this
property only if your driverType is set to 4. This property is not required if your driverType is set to
2.
3. DB2 legacy CLI-based Type 2 JDBC Driver
The DB2 legacy CLI-based Type 2 JDBC Driver Provider is built on top of DB2 CLI (Call Level
Interface). It uses the DB2 CLI interface to communicate with DB2 UDB servers. For use with
Application Server on Windows, UNIX, or workstation-based LINUX, this provider requires DB2
Connect (which is available from DB2).
DB2 legacy CLI-based Type 2 JDBC Driver supports one phase data source:
COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource
Requires JDBC driver files: db2java.zip (Note: If you run SQLJ in DB2 Version 8, db2jcc.jar is also
required.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2DataStoreHelper
Does not require a valid authentication alias.
Requires properties:
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
4. DB2 legacy CLI-based Type 2 JDBC Driver (XA)
The DB2 legacy CLI-based Type 2 JDBC Driver (XA) is built on top of DB2 CLI (Call Level Interface).
It uses the DB2 CLI interface to communicate with DB2 UDB servers. For use with Application Server
on Windows, UNIX, or workstation-based LINUX, this provider requires DB2 Connect (which is
available from DB2).
DB2 legacy CLI-based Type 2 JDBC Driver (XA) supports two phase data source:
COM.ibm.db2.jdbc.DB2XADataSource
Requires JDBC driver files: db2java.zip (Note: If you run SQLJ in DB2 Version 8, db2jcc.jar is also
required.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.DB2DataStoreHelper
Does not require a valid authentication alias.
Requires properties:
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.

For more information on DB2 for z/OS, visit the DB2 Web site at: http://www.ibm.com/software/data/db2/.

Cloudscape
1. Cloudscape JDBC Provider
The Cloudscape JDBC Provider provides the JDBC access to the Cloudscape database. This
Cloudscape JDBC driver used the embedded framework. You cannot use any Version 4.0 data sources
with Cloudscape.
Cloudscape JDBC Provider supports one phase data source:
com.ibm.db2j.jdbc.DB2jConnectionPoolDataSource
Requires JDBC driver files: db2j.jar.
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper
Does not require a valid authentication alias.

1432 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Requires properties:
v databaseName The name of the database from which the data source obtains connections. If you
do not specify a fully qualified path name, Application Server uses the default location of
WAS_HOME./cloudscape (or the equivalent default for a UNIX or LINUX environment).
– Example database path name for Windows: c:\temp\sampleDB
– Example database path name for UNIX or LINUX: /tmp/sampleDB
If no database currently exists for the path name you want to specify, simply append ;create=true
to the path name to create a database dynamically. (For example: c:\temp\sampleDB;create=true)
2. Cloudscape JDBC Provider (XA)
The Cloudscape JDBC Provider (XA) provides the XA-compliant JDBC access to the Cloudscape
database. This Cloudscape JDBC driver uses the embedded framework. You cannot use any Version
4.0 data sources with Cloudscape.
Cloudscape JDBC Provider (XA) supports two phase data source:
com.ibm.db2j.jdbc.DB2jXADataSource
Requires JDBC driver files: db2j.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper
Does not require a valid authentication alias.
Requires properties:
v databaseName The name of the database from which the data source obtains connections. If you
do not specify a fully qualified path name, Application Server uses the default location of
WAS_HOME./cloudscape (or the equivalent default for a UNIX or LINUX environment).
– Example database path name for Windows: c:\temp\sampleDB
– Example database path name for UNIX or LINUX: /tmp/sampleDB
If no database currently exists for the path name you want to specify, simply append ;create=true
to the path name to create a database dynamically. (For example: c:\temp\sampleDB;create=true)
3. Cloudscape Network Server using Universal JDBC driver
This Cloudscape driver takes advantage of the Network Server support that the DB2 universal Type 4
JDBC driver provides. You cannot use any Version 4.0 data sources with Cloudscape.
Cloudscape uses the DB2 Universal Driver when using the Network Server. It supports one phase data
source:
com.ibm.db2.jcc.DB2ConnectionPoolDataSource
Requires JDBC driver files:
v db2jcc.jar If you install and run DB2, you must use the db2jcc.jar file that comes with DB2. To do
that, the classpath in the JDBC template for Cloudscape network server is set to be:
<classpath>${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc.jar</classpath>

<classpath>${CLOUDSCAPE_JDBC_DRIVER_PATH}/db2j.jar</classpath>

<classpath>${CLOUDSCAPE51_JDBC_DRIVER_PATH}/db2j.jar</classpath>

<classpath>${UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc.jar</classpath>

which means that the db2jcc.jar from DB2 always takes precedence. Note that this also means that
you must set the DB2 environment variable DB2UNIVERSAL_JDBC_DRIVER_PATH in WebSphere
when you set up your DB2 datasource. This is instead of hard coding the path of the db2jcc.jar for
DB2 datasources.
v db2jcc_license_cu.jar This file is the DB2 Universal JDBC license file that provides access to the
Cloudscape databases using the Network Server framework. Use this file to gain access to the
database. This file ships with WebSphere and is located in ${UNIVERSAL_JDBC_DRIVER_PATH}.

Note: UNIVERSAL_JDBC_DRIVER_PATHis a WebSphere environment variable that is already

defined to the location in Websphere Application Server where the license jar file above is

Chapter 8. Developing WebSphere applications 1433

 located, and will only be used if the DB2UNIVERSAL_JDBC_DRIVER_PATH is not set. DB2
users should ensure that DB2UNIVERSAL_JDBC_DRIVER_PATH is set to avoid loading
multiple vesions of the db2jcc.jar file.

Note: DB2UNIVERSAL_JDBC_DRIVER_PATH is a WebSphere environment variable that you

must set to point to the location of db2jcc.jar file (that comes with DB2). This variable is set
only if you create a db2 provider. See the DB2 section for more information on the
DB2UNIVERSAL_JDBC_DRIVER_PATH path variable.

Note: Cloudscape requires only db2jcc_license_c.jar; however, WebSphere Application Server uses
db2jcc_license_cu.jar because this works for both DB2 UDB and Cloudscape.
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.CloudscapeNetworkServerDataStoreHelper
Note: The administrative console incorrectly lists the DB2UniversalDataStoreHelper as the default
value for the DataStoreHelper class. You must change the default value to
com.ibm.websphere.rsadapter.CloudscapeNetworkServerDataStoreHelper. Also change the custom
properties, using the instructions in the customer property section.
Requires a valid authentication alias.
Requires properties:
v databaseName The name of the database from which the data source obtains connections. If you
do not specify a fully qualified path name, Application Server uses the default location of
WAS_HOME./cloudscape (or the equivalent default for a UNIX or LINUX environment).
– Example database path name for Windows: c:\temp\sampleDB
– Example database path name for UNIX or LINUX: /tmp/sampleDB
If no database currently exists for the path name you want to specify, simply append ;create=true
to the path name to create a database dynamically. (For example: c:\temp\sampleDB;create=true)
v driverType Only the Type 4 driver is allowed.
v serverName The TCP/IP address or the host name for the Distributed Relational Database
Architecture (DRDA) server.
v portNumber The TCP/IP port number where the DRDA server resides. The default value is port
1527.
v retrieveMessagesfromServerOnGetMessage This property is required by WebSphere Application
Server, not the database. The default value is false. You must set the value of this property to true,
to enable text retrieval using the SQLException.getMessage() method.
See the Cloudscape setup instructions for more information on configuring the Cloudscape Network
Server.

For more information on IBM Cloudscape, visit the Cloudscape Web site at:
http://www.ibm.com/software/data/cloudscape/

Informix
1. Informix JDBC Driver
The Informix JDBC Driver is a Type 4 JDBC driver that provides JDBC access to the Informix
database.
Informix JDBC Driver supports one phase data source:
com.informix.jdbcx.IfxConnectionPoolDataSource
Requires JDBC driver files:
ifxjdbc.jar
ifxjdbcx.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.InformixDataStoreHelper
Requires a valid authentication alias.

1434 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Requires properties:
v serverName The name of the Informix instance on the server. Example: ol_myserver.
v portNumber The port on which the instances listen. Example: 1526.
v ifxIFXHOST Either the IP address or the host name of the machine that is running the Informix
database to which you want to connect. Example: myserver.mydomain.com.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
v informixLockModeWait Although not required, this property enables you to set the number of
seconds that Informix software waits for a lock. By default, Informix code throws an exception if it
cannot immediately acquire a lock. Example: 2.
2. Informix JDBC Driver (XA)
The Informix JDBC Driver (XA) is a Type 4 JDBC driver that provides XA-compliant JDBC access to
the Informix database.
Informix JDBC Driver (XA) supports two phase data source:
com.informix.jdbcx.IfxXADataSource
Requires JDBC driver files:
ifxjdbc.jar
ifxjdbcx.jar
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.InformixDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the Informix instance on the server. Example: ol_myserver.
v portNumber The port on which the instances listen. Example: 1526.
v ifxIFXHOST Either the IP address or the host name of the machine that is running the Informix
database to which you want to connect. Example: myserver.mydomain.com.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
v informixLockModeWait Although not required, this property enables you to set the number of
seconds that Informix software waits for a lock. By default, Informix code throws an exception if it
cannot immediately acquire a lock. Example: 2.

For more information on Informix, visit the Informix Web site at: http://www.ibm.com/software/data/informix/

Sybase
1. Sybase JDBC Driver
The Sybase JDBC Driver is a Type 4 JDBC driver that provides JDBC access to the Sybase database.
Sybase JDBC Driver supports one phase data source:
com.sybase.jdbc2.jdbc.SybConnectionPoolDataSource
Requires JDBC driver files: jconn2.jar.
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.SybaseDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the database server. Example: myserver.mydomain.com.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
v portNumber The TCP/IP port number through which all communications to the server take place.
Example: 4100.
v connectionProperties A custom property required for applications containing EJB 2.0 enterprise
beans. Value: SELECT_OPENS_CURSOR=true(Type: java.lang.String)
2. Sybase JDBC Driver (XA)

Chapter 8. Developing WebSphere applications 1435

 The Sybase JDBC Driver (XA) is a Type 4 JDBC driver that provides XA-compliant JDBC access to
the Sybase database.
Sybase JDBC Driver (XA) supports two phase data source:
com.sybase.jdbc2.jdbc.SybXADataSource
Requires JDBC driver files: jconn2.jar.
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.SybaseDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the database server. Example: myserver.mydomain.com
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
v portNumber The TCP/IP port number through which all communications to the server take place.
Example: 4100.
v connectionProperties A custom property required for applications containing EJB 2.0 enterprise
beans. Value: SELECT_OPENS_CURSOR=true(Type: java.lang.String)

For more information on Sybase, visit the Sybase Web site at: http://www.sybase.com/

Oracle
1. Oracle JDBC Driver
The Oracle JDBC Driver provides JDBC access to the Oracle database. This JDBC driver supports
both Type 2 JDBC access and Type 4 JDBC access.
Oracle JDBC Driver supports one phase data source:
oracle.jdbc.pool.OracleConnectionPoolDataSource
Requires JDBC driver files: ojdbc14.jar. (Note: If you require Oracle trace, use ojdbc14_g.jar.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.OracleDataStoreHelper
(Note: If you are running Oracle10g, use com.ibm.websphere.rsadapter.Oracle10gDataStoreHelper.
Requires a valid authentication alias.
Requires properties:
v URL The URL that indicates the database from which the data source obtains connections.
Example: jdbc:oracle:thin:@myServer:1521:myDatabase, where myServer is the server name, 1521
is the port it is using for communication, and myDatabase is the database name.
2. Oracle JDBC Driver (XA)
The Oracle JDBC Driver (XA) provides XA-compliant JDBC access to the Oracle database. This JDBC
driver supports both Type 2 JDBC access and Type 4 JDBC access.
Oracle JDBC Driver (XA) supports two phase data source:
oracle.jdbc.xa.client.OracleXADataSource
Requires JDBC driver files: ojdbc14.jar. (Note: If you require Oracle trace, use ojdbc14_g.jar.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.OracleDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v URL The URL that indicates the database from which the data source obtains connections.
Example: jdbc:oracle:thin:@myServer:1521:myDatabase, where myServer is the server name, 1521
is the port it is using for communication, and myDatabase is the database name.

For more information on Oracle, visit the Oracle Web site at: http://www.oracle.com/

1436 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MS SQL Server
1. DataDirect ConnectJDBC type 4 driver for MS SQL Server
DataDirect ConnectJDBC type 4 driver for MS SQL Server is a Type 4 JDBC driver that provides
JDBC access to the MS SQL Server database. This provider is for use only with the Connect JDBC
driver purchased from DataDirect Technologies.
This JDBC provider supports this data source:
com.ddtek.jdbcx.sqlserver.SQLServerDataSource
Requires JDBC driver files:
sqlserver.jar,
base.jar and util.jar
(The spy.jar file is optional. You need this file to enable spy logging. The spy.jar file is not in the
same directory as the other three jar files. Instead, it is located in the ../spy/ directory.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.ConnectJDBCDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the server in which MS SQL Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that MS SQL Server uses for communication. Port 1433 is the default.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
2. DataDirect ConnectJDBC type 4 driver for MS SQL Server (XA)
DataDirect ConnectJDBC type 4 driver for MS SQL Server (XA) is a Type 4 JDBC driver which
provides XA-compliant JDBC access to the MS SQL Server database. This provider is for use only
with the Connect JDBC driver purchased from DataDirect Technologies.
This JDBC provider supports this data source:
com.ddtek.jdbcx.sqlserver.SQLServerDataSource.
Requires JDBC driver files:
sqlserver.jar,
base.jar and util.jar.
(The spy.jar file is optional. You need this file to enable spy logging. The spy.jar file is not in the
same directory as the other three jar files. Instead, it is located in the ../spy/ directory.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.ConnectJDBCDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the server in which MS SQL Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that MS SQL Server uses for communication. Port 1433 is the default.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
For more information on the DataDirect ConnectJDBC driver, visit the DataDirect Web site at:
http://www.datadirect-technologies.com/
3. WebSphere embedded ConnectJDBC driver for MS SQL Server
WebSphere embedded ConnectJDBC driver for MS SQL Server is a Type 4 JDBC driver that provides
JDBC access to the MS SQL Server database. This JDBC driver ships with WebSphere Application
Server. Only use this provider with the Connect JDBC driver embedded in WebSphere; it cannot be
used with a Connect JDBC driver purchased separately from DataDirect Technologies.
This JDBC provider supports this data source:
com.ibm.websphere.jdbcx.sqlserver.SQLServerDataSource.
Requires JDBC driver files:

Chapter 8. Developing WebSphere applications 1437

 sqlserver.jar
base.jar and
util.jar.
(The spy.jar file is optional. You need this file to enable spy logging. The spy.jar file for the
WebSphere embedded Connect JDBC driver ships with WebSphere Application Server. All the files are
located in the WAS_HOME/lib/ directory.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.WSConnectJDBCDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the server in which MS SQL Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that MS SQL Server uses for communication. Port 1433 is the default.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
4. WebSphere embedded ConnectJDBC driver for MS SQL Server (XA)
WebSphere embedded ConnectJDBC driver for MS SQL Server (XA) is a Type 4 JDBC driver which
provides XA-compliant JDBC access to the MS SQL Server database. This JDBC driver ships with
WebSphere Application Server. Use this provider with the Connect JDBC driver embedded in
WebSphere. Do not use it with a Connect JDBC driver purchased separately from DataDirect
Technologies.
This JDBC provider supports this data source:
com.ibm.websphere.jdbcx.sqlserver.SQLServerDataSource.
Requires JDBC driver files:
sqlserver.jar
base.jar and
util.jar.
(The spy.jar file is optional. You need this file to enable spy logging. The spy.jar file for the
WebSphere embedded Connect JDBC driver ships with WebSphere Application Server. All the files are
located in the WAS_HOME/lib/ directory.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.WSConnectJDBCDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the server in which MS SQL Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that MS SQL Server uses for communication. Port 1433 is the default.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
Whether you need to support one or two phase transactions with the WebSphere embedded Connect
JDBC XA driver, you must install Stored Procedures for the Java Transaction API (JTA) on your
machine that runs Microsoft SQL. The WebSphere Application Server installation disks provide a base
level of Stored Procedures for JTA. (You can find the most current version of the software on the
WebSphere Application Server-embedded DataDirect Technologies product update Web page.) Install
Stored Procedures for JTA by performing the following steps:
a. Determine whether you are running the 32-bit or 64-bit MS SQL Server and select the appropriate
sqljbc.dll and instjdbc.sql files.
b. Stop your MS SQL Server service.
c. Copy the sqljdbc.dll file into your %SQL_SERVER_INSTALL%\Binn\ directory.
d. Restart the MS SQL Server service.
e. Run theinstjdbc.sql script. (The script can be run by the MS SQL Server Query Analyzer or the
ISQL utility).

1438 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 You can download the latest patches and upgrades to the WebSphere embedded Connect JDBC
driver from the following FTP site:
ftp://ftp.software.ibm.com/software/websphere/info/tools/DataDirect/datadirect.htm
5. DataDirect SequeLink type 3 JDBC driver for MS SQL Server -- Deprecated
Because this JDBC provider is deprecated in WebSphere Application Server Version 6.0, it is no longer
an available option in the administrative console. In its place, use one of the Connect JDBC providers,
which are described previously in this section.
DataDirect SequeLink type 3 JDBC driver for MS SQL Server is a type 3 JDBC driver that provides
JDBC access to MS SQL Server via SequeLink server.
This JDBC provider supports this data source:
com.ddtek.jdbcx.sequelink.SequeLinkDataSource
Requires JDBC driver files:
sljc.jar and
spy-sl.jar
(The JDBC driver shipped with WebSphere Application Server requires the sljc.jar and the
spy-sl.jar files. The JDBC driver purchased from DataDirect requires the sljc.jar and the spy.jar
files. The spy.jar and spy-sl.jar files are optional. You need these files to enable spy logging.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.SequeLinkDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the server in which SequeLink Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that SequeLink Server uses for communication. By default, SequeLink
Server uses port 19996.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
6. DataDirect SequeLink type 3 JDBC driver for MS SQL Server (XA) -- Deprecated
Because this JDBC provider is deprecated in WebSphere Application Server Version 6.0, it is no longer
an available option in the administrative console. In its place, use one of the Connect JDBC providers,
which are described previously in this section.
DataDirect SequeLink type 3 JDBC driver for MS SQL Server (XA) is a type 3 JDBC driver that
provides XA-compliant JDBC access to MS SQL Server via the SequeLink server.
This JDBC provider supports this data source:
com.ddtek.jdbcx.sequelink.SequeLinkDataSource
Requires JDBC driver files:
sljc.jar and
spy-sl.jar
(The JDBC driver shipped with WebSphere Application Server requires the sljc.jar and the
spy-sl.jar files. The JDBC driver purchased from DataDirect requires the sljc.jar and the spy.jar
files. The spy.jar and spy-sl.jar files are optional. You need these files to enable spy logging.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.SequeLinkDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the server in which SequeLink Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that SequeLink Server uses for communication. By default, SequeLink
Server uses port 19996.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.

Chapter 8. Developing WebSphere applications 1439

 Both of the WebSphere-embedded SequeLink JDBC drivers require installation of SequeLink Server
on all machines running MS SQL Server. See the readme.html file found in the DataDirect folder on
the WebSphere Application Server CD for instructions on how to install SequeLink Server. (Only install
SequeLink Server from the WebSphere Application Server CD if you are using the SequeLink JDBC
driver embedded in WebSphere. Otherwise, install a copy of SequeLink Server purchased from
DataDirect Technologies.)
From the following FTP site, you can download the latest patches and upgrades for the version of
SequeLink Server that is used with the WebSphere-embedded SequeLink JDBC driver:
ftp://ftp.software.ibm.com/software/websphere/info/tools/DataDirect/datadirect.htm
For more information on the DataDirect SequeLink type 3 JDBC driver, visit the DataDirect Web site at:
http://www.datadirect-technologies.com/
7. Microsoft JDBC driver for MSSQLServer 2000 -- Deprecated
Because this JDBC provider is deprecated in WebSphere Application Server Version 6.0, it is no longer
an available option in the administrative console. In its place, use one of the Connect JDBC providers,
which are described previously in this section.
Microsoft JDBC driver for MSSQLServer 2000 is a type 4 JDBC driver that provides JDBC access to
the MS SQL Server database.
This JDBC provider supports this data source:
com.microsoft.jdbcx.sqlserver.SQLServerDataSource
Requires JDBC driver files:
mssqlserver.jar,
msbase.jar and msutil.jar
(The spy.jar file is optional. You need it to enable spy logging. However, Microsoft does not ship the
spy.jar file. Contact Microsoft about this issue.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.ConnectJDBCDataStoreHelper
Requires a valid authentication alias.
Requires properties:
v serverName The name of the server in which MS SQL Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that MS SQL Server uses for communication. Port 1433 is the default.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.
8. Microsoft JDBC driver for MSSQLServer 2000 (XA) -- Deprecated
Because this JDBC provider is deprecated in WebSphere Application Server Version 6.0, it is no longer
an available option in the administrative console. In its place, use one of the Connect JDBC providers,
which are described previously in this section.
Microsoft JDBC driver for MSSQLServer 2000 (XA) is a type 4 JDBC driver that provides XA-compliant
JDBC access to the MS SQL Server database.
This JDBC provider supports this data source:
com.microsoft.jdbcx.sqlserver.SQLServerDataSource
Requires JDBC driver files:
mssqlserver.jar,
msbase.jar and msutil.jar
(The spy.jar file is optional. You need it to enable spy logging. However, Microsoft does not ship the
spy.jar file. Contact Microsoft about this issue.)
Requires DataStoreHelper class:
com.ibm.websphere.rsadapter.ConnectJDBCDataStoreHelper
Requires a valid authentication alias.
Requires properties:

1440 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 v serverName The name of the server in which MS SQL Server resides. Example:
myserver.mydomain.com
v portNumber The TCP/IP port that MS SQL Server uses for communication. Port 1433 is the default.
v databaseName The name of the database from which the data source obtains connections.
Example: Sample.

For more information on the Microsoft JDBC driver, visit the Microsoft Web site at:
http://www.microsoft.com/sql

Connector modules collection

Use this page to view established connector modules, which are resource adaptor (RAR) files that have
been packaged into deployable components compliant with the J2EE Connector Architecture (JCA).

To view this administrative console page, click Applications >Enterprise Applications > application >
Connector Modules.

You must generate a connector module for every resource adapter (RAR file) in the application. You do
this through an assembly tool, which creates an instance of the connector module object for the RAR file.
To learn more about the process, see the topic ″Assembling resource adapter (connector) modules″ in the
Information Center.

Remove: Removes a module from the deployed application. The module is deleted from the application
in the WebSphere Application Server configuration repository and also from all the nodes where the
application is installed and running (or expected to run). If the application is running on a node when the
module file is deleted from the node as a result of configuration synchronization then the application is
stopped, the module file is deleted from the node’s file system, and then the application is restarted.

Update: Opens a wizard that helps you update module in an application. If a module has the same URI
as a module already existing in the application, the new module replaces the existing module. If the new
module does not exist in the application, it is added to the deployed application. If the application is
running on a node when the module file is updated on the node as a result of configuration
synchronization then the application is stopped, the module file is updated on the node’s file system, and
then the application is restarted.

Remove File: Deletes a file from a module of a deployed application. The file is also deleted from all the
nodes where the module is installed after configuration is synchronized with nodes. If the application is
running on a node when the module file is updated on the node as a result of configuration
synchronization then the application is stopped, the module file is updated on the node’s file system, and
then the application is restarted.

URI:

Specifies the logical path to the resource that will be serviced by the product.

Name:

Specifies the display name of the connector module.

Connector module settings:

Use this page to view the settings of connector modules, which are resource adapter (RAR) files that have
been packaged into deployable components compliant with the J2EE Connector Architecture (JCA).

To view this administrative console page, click Applications > Enterprise Applications > application >
Connector Modules > connector_module.

Chapter 8. Developing WebSphere applications 1441

The following field descriptions refer to properties that are set when you create connector modules using
an assembly tool. To learn more about the process, see the topic ″Assembling resource adapter
(connector) modules″ in the Information Center.

Remove: Removes a module from the deployed application. The module is deleted from the application
in the WebSphere Application Server configuration repository and also from all the nodes where the
application is installed and running (or expected to run). If the application is running on a node when the
module file is deleted from the node as a result of configuration synchronization then the application is
stopped, the module file is deleted from the node’s file system, and then the application is restarted.

Update: Opens a wizard that helps you update module in an application. If a module has the same URI
as a module already existing in the application, the new module replaces the existing module. If the new
module does not exist in the application, it is added to the deployed application. If the application is
running on a node when the module file is updated on the node as a result of configuration
synchronization then the application is stopped, the module file is updated on the node’s file system, and
then the application is restarted.

Remove File: Deletes a file from a module of a deployed application. The file is also deleted from all the
nodes where the module is installed after configuration is synchronized with nodes. If the application is
running on a node when the module file is updated on the node as a result of configuration
synchronization then the application is stopped, the module file is updated on the node’s file system, and
then the application is restarted.

Uri:

Specifies the logical path to the resource that is serviced by WebSphere Application Server.

Data type String

Name:

Specifies the display name of the connector module.

Data type String

altDD:

Specifies the alternate DD of the connector module.

The alternate DD URI for a given module.

Data type String

Starting weight:

Specifies the startup priority of the connector module over others.

When your application contains multiple modules, the starting weight you specify determines this module’s
startup priority over other modules during server startup. Modules with lower startup order are started first.

Data type String

1442 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Messaging resources

Learning about messaging with WebSphere Application Server

Use this topic to learn about the use of asynchronous messaging for enterprise applications with
WebSphere Application Server.

WebSphere Application Server supports asynchronous messaging as a method of communication based

on the Java Message Service (JMS) and Java Connector Architecture (JCA) programming interfaces.
These interfaces provide a common way for Java programs (clients and J2EE applications) to create,
send, receive, and read asynchronous requests, as messages.

Besides using the programming interfaces directly to explicitly poll for messages, WebSphere Application
Server also supports the use of message-driven beans as asynchronous message consumers. A
message-driven bean is invoked by the EJB container when a message arrives at the destination that it is
configured to listen on, without an application having to explicitly poll the destination.

To handle non-JMS requests inbound to WebSphere Application Server from enterprise information
systems, message-driven beans use a Java Connector Architecture (JCA) 1.5 resource adapter written for
that purpose. In the JCA 1.5 specification, such message-driven beans are commonly called message
endpoints or simply endpoints.

Message-driven beans that implement the javax.jms.MessageListener interface can be used for JMS
messaging. For JMS messaging, message-driven beans can use a JMS provider that has a JCA 1.5
resource adapter, such as the default messaging provider that is part of WebSphere Application Server
version 6.

With a JCA 1.5 resource adapter, you deploy EJB 2.1 message-driven beans as JCA resources to use a
J2C activation specification. If a JMS provider does not have a JCA 1.5 resource adapter, such as the V5
Default Messaging and WebSphere MQ, you must configure JMS message-driven beans against a listener
port (as in WebSphere Application Server version 5).

You can use the WebSphere administrative console to administer the WebSphere Application Server
support for asynchronous messaging. For example, you can configure JCA resource adapters, J2C
activation specifications, JMS providers, and JMS resources, and can control the activity of messaging
services.

To learn more about WebSphere messaging support, see the following topics:
v JMS providers
v Styles of messaging in applications
v Using JMS interfaces to explicitly poll for messages
v Using message-driven beans to automatically retrieve messages
v ″Components of JMS support″ in the information center.
v Components of message-driven bean support
v WebSphere Application Server cloning and WebSphere MQ clustering
v Security considerations for asynchronous messaging

JMS providers
This topic provides an overview of the support for JMS providers by WebSphere Application Server.

IBM WebSphere Application Server supports asynchronous messaging through the use of a JMS provider
and its related messaging system. JMS providers must conform to the JMS specification version 1.1. To

Chapter 8. Developing WebSphere applications 1443

use message-driven beans the JMS provider must support the optional Application Server Facility (ASF)
function defined within that specification, or support an inbound resource adapter as defined in the JCA
specification version 1.5.

The service integration technologies of IBM WebSphere Application Server can act as a messaging
system when you have configured a service integration bus that is accessed through the default
messaging provider. This support is installed as part of WebSphere Application Server, administered
through the administrative console, and is fully integrated with the WebSphere Application Server runtime.

WebSphere Application Server also includes support for the following JMS providers:
WebSphere MQ
Provided for use with supported versions of WebSphere MQ.
Generic
Provided for use with any 3rd party messaging system. If you want to use message-driven beans,
the messaging system must support ASF.

For backwards compatibility with earlier releases, WebSphere Application Server also includes support for
the V5 default messaging provider which enables you to configure resources for use with the WebSphere
Application Server version 5 Embedded Messaging system. The V5 default messaging provider can also
be used with a service integration bus.

WebSphere applications can use messaging resources provided by any of these JMS providers. However
the choice of provider is most often dictated by requirements to use or integrate with an existing
messaging system. For example, you may already have a messaging infrastructure based on WebSphere
MQ. In this case you may either connect directly using the included support for WebSphere MQ as a JMS
provider, or configure a service integration bus with links to a WebSphere MQ network and then access
the bus through the default messaging provider.

Styles of messaging in applications

This topic describes the ways that applications can use point-to-point and publish/subscribe messaging.

Applications can use the following styles of asynchronous messaging:

Point-to-Point
Point-to-point applications use queues to pass messages between each other. The applications
are called point-to-point, because a client sends a message to a specific queue and the message
is picked up and processed by a server listening to that queue. It is common for a client to have
all its messages delivered to one queue. Like any generic mailbox, a queue can contain a mixture
of messages of different types.
Publish/subscribe
Publish/subscribe systems provide named collection points for messages, called topics. To send
messages, applications publish messages to topics. To receive messages, applications subscribe
to topics; when a message is published to a topic, it is automatically sent to all the applications
that are subscribers of that topic. By using a topic as an intermediary, message publishers are
kept independent of subscribers.

Both styles of messaging can be used in the same application.

Applications can use asynchronous messaging in the following ways:

One-way
An application sends a message, and does not want a response. This pattern of use is often
referred to as a datagram.
Request / response
An application sends a request to another application and expects to receive a response in return.

1444 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
One-way and forward
An application sends a request to another application, which sends a message to yet another
application.

These messaging techniques can be combined to produce a variety of asynchronous messaging

scenarios.

For more information about how such messaging scenarios are used by WebSphere enterprise
applications, see the following topics:
v An overview of asynchronous messaging with JMS
v An overview of asynchronous messaging with message-driven beans

For more information about these messaging techniques and the Java Message Service (JMS), see Sun’s
Java Message Service (JMS) specification documentation
(http://developer.java.sun.com/developer/technicalArticles/Networking/messaging/).

For more information about message-driven bean and inbound messaging support, see Sun’s Enterprise
JavaBeans specification (http://java.sun.com/products/ejb/docs.html).

For information about JCA inbound messaging processing, see Sun’s J2EE Connector Architecture
specification (http://java.sun.com/j2ee/connector/download.html).

Using JMS interfaces to explicitly poll for messages

This topic provides an overview of applications that use JMS interfaces to explicitly poll for messages on a
destination then retrieve messages for processing by business logic beans (enterprise beans).

WebSphere Application Server supports asynchronous messaging as a method of communication based

on the Java Message Service (JMS) programming interfaces. JMS provides a common way for Java
programs (clients and J2EE applications) to create, send, receive, and read asynchronous requests, as
JMS messages.

The base support for asynchronous messaging using JMS, shown in the following figure, provides the
common set of JMS interfaces and associated semantics that define how a JMS client can access the
facilities of a JMS provider. This enables WebSphere J2EE applications, as JMS clients, to exchange
messages asynchronously with other JMS clients by using JMS destinations (queues or topics).

Applications can use both point-to-point and publish/subscribe messaging (referred to as “messaging
domains” in the JMS specification), while supporting the different semantics of each domain.

WebSphere Application Server supports applications that use JMS 1.1 domain-independent interfaces
(referred to as the “common interfaces” in the JMS specification). With JMS 1.1, the preferred approach for
implementing applications is to use the common interfaces. The JMS 1.1 common interfaces provide a
simpler programming model than domain-specific interfaces. Also, applications can create both queues
and topics in the same session and coordinate their use in the same transaction.

The common interfaces are also parents of domain-specific interfaces. These domain-specific interfaces
(provided for JMS 1.0.2 in WebSphere Application Server version 5) are supported only to provide
inter-operation and backward compatibility with applications that have already been implemented to use
those interfaces.

A WebSphere application can use the JMS interfaces to explicitly poll a JMS destination to retrieve an
incoming message, then pass the message to a business logic bean. The business logic bean uses
standard JMS calls to process the message; for example, to extract data or to send the message on to
another JMS destination.

Chapter 8. Developing WebSphere applications 1445

Figure 8. Asynchronous messaging using JMS. This figure shows an enterprise application polling a JMS destination
to retrieve an incoming message, which it processes with a business logic bean. The business logic bean uses
standard JMS calls to process the message; for example, to extract data or to send the message on to another JMS
destination. For more information, see the text that accompanies this figure.

WebSphere applications can use standard JMS calls to process messages, including any responses or
outbound messaging. Responses can be handled by an enterprise bean acting as a sender bean, or
handled in the enterprise bean that receives the incoming messages. Optionally, this process can use
two-phase commit within the scope of a transaction. This level of functionality for asynchronous messaging
is called bean-managed messaging, and gives an enterprise bean complete control over the messaging
infrastructure; for example, for connection and session pool management. The application server has no
role in bean-managed messaging.

WebSphere applications can also use message-driven beans, as described in related topics.

For more details about JMS, see Sun’s Java Message Service (JMS) specification documentation.

Using message-driven beans to automatically retrieve messages

WebSphere Application Server supports the use of message-driven beans as asynchronous message
consumers.

Messaging with message-driven beans is shown in the figure Messaging with message-driven beans.

A client sends messages to the destination (or endpoint) for which the message-driven bean is deployed
as the message listener. When a message arrives at the destination, the EJB container invokes the
message-driven bean automatically without an application having to explicitly poll the destination. The
message-driven bean implements some business logic to process incoming messages on the destination.

Message-driven beans can be configured as listeners on a Java Connector Architecture (JCA) 1.5
resource adapter or against a listener port (as in WebSphere Application Server version 5). With a JCA 1.5
resource adapter, message-driven beans can handle generic message types, not just JMS messages. This
makes message-driven beans suitable for handling generic requests inbound to WebSphere Application
Server from enterprise information systems through the resource adapter. In the JCA 1.5 specification,
such message-driven beans are commonly called message endpoints or simply endpoints.

1446 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
All message-driven beans must implement the MessageDrivenBean interface. For JMS messaging, a
message-driven bean must also implement the message listener interface, javax.jms.MessageListener.

A message driven bean can be registered with the EJB timer service for time-based event notifications if it
implements the javax.ejb.TimedObject interface in addition to the message listener interface.

You are recommended to develop a message-driven bean to delegate the business processing of
incoming messages to another enterprise bean, to provide clear separation of message handling and
business processing. This also enables the business processing to be invoked by either the arrival of
incoming messages or, for example, from a WebSphere J2EE client.

Messages arriving at a destination being processed by a message-driven bean have no client credentials
associated with them; the messages are anonymous. Security depends on the role specified by the RunAs
Identity for the message-driven bean as an EJB component. For more information about EJB security, see
EJB component security.

For JMS messaging, message-driven beans can use a JMS provider that has a JCA 1.5 resource adapter,
such as the default messaging provider that is part of WebSphere Application Server version 6. With a
JCA 1.5 resource adapter, you deploy EJB 2.1 message-driven beans as JCA 1.5-compliant resources, to
use a J2C activation specification. If the JMS provider does not have a JCA 1.5 resource adapter, such as
the V5 Default Messaging and WebSphere MQ, you must configure JMS message-driven beans against a
listener port (as in WebSphere Application Server version 5).

Message-driven beans - JCA components:

This topic provides an overview of the administrative components that you configure for message-driven
beans as listeners on a Java Connector Architecture (JCA) 1.5 resource adapter.

Components for a JCA resource adapter

To handle non-JMS requests inbound to WebSphere Application Server from enterprise information
systems, message-driven beans use a Java Connector Architecture (JCA) 1.5 resource adapter written for
that purpose.

With a Java Connector Architecture (JCA) 1.5 resource adapter, a message-driven bean acts as a listener
on a specific endpoint. In the JCA 1.5 specification, such message-driven beans are commonly called
message endpoints or simply endpoints.

Each application configuring one or more endpoints must specify the resource adapter that sends
messages to the endpoint.

Chapter 8. Developing WebSphere applications 1447

Figure 9. Message-driven bean components for a JCA resource adapter. This figure shows the main components of
WebSphere support for message-driven beans for use with an external JCA resource adapter.

The administrator creates a J2C activation specification to provide information to the deployer about the
configuration properties of an endpoint instance (message-driven bean) related to the processing of the
inbound messages. Properties specified on an activation specification can be overridden by appropriately
named activation-configuration properties in the deployment descriptor of an associated EJB 2.1
message-driven bean.

When a deployed message-driven bean is installed, it is associated with an activation specification for an
endpoint. When a message arrives on the endpoint, the message is passed to a new instance of a
message-driven bean for processing.

Administered object definitions and classes are provided by a resource adapter when you install it. Using
this information, the administrator can create and configure J2C administered objects with JNDI names
that are then available for applications to use. Some messaging styles may need applications to use
special administered objects for sending and synchronously receiving messages (through connection
objects using programming interfaces specific to a messaging style). Administered objects can also be
used to perform transformations on an asynchronously-received message in a way that is specific to a
message provider. Administered objects can be accessed by a component by using either a message
destination reference (preferred) or a resource environment reference.

Components for a JCA messaging provider

Message-driven beans that implement the javax.jms.MessageListener interface can be used for JMS
messaging. For JMS messaging, message-driven beans can use a JCA-based messaging provider such
as the default messaging provider that is part of WebSphere Application Server and configure
message-driven beans to use a JCA activation specification.

1448 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Figure 10. Message-driven bean components for the default messaging provider. This figure shows the main
components of WebSphere support for message-driven beans for use with the default messaging provider.

With the default messaging provider, a message-driven bean acts as a listener on a specific JMS
destination.

The administrator creates a JMS activation specification to provide information to the deployer about the
configuration properties of a message-driven bean related to the processing of the inbound messages. For
example, a JMS activation specification specifies the name of the service integration bus to connect to,
and includes information about the message acknowledgement modes, message selectors, destination
types, and whether or not durable subscriptions are shared across connections with members of a server
cluster. Properties specified on an activation specification can be overridden by appropriately named
activation-configuration properties in the deployment descriptor of an associated EJB 2.1 message-driven
bean.

The administrator also creates other administered objects that configure the JMS destination and the
associated resources of a service integration bus that are used to implement messaging with that JMS
destination. For more information about JMS resources and service integration, see ″Learning about the
default messaging provider″ in the information center.

J2C activation specification configuration and use:

This topic provides an overview about the configuration and use of J2C activation specifications, used in
the deployment of message-driven beans for JCA 1.5 resources.

J2C activation specifications are part of the configuration of inbound messaging support that can be part of
a JCA 1.5 resource adapter. Each JCA 1.5 resource adapter that supports inbound messaging defines one
or more messagelistener types in its deployment descriptor (ra.xml). The messagelistener type is the
interface that the resource adapter uses to communicate inbound messages to the message endpoint. A
message-driven bean (MDB) is a message endpoint and implements one of the messagelistener-type
interfaces provided by the resource adapter. By allowing multiple message listener types, a resource
adapter can support a variety of different protocols. For example, the interface javax.jms.MessageListener,
is a type of message listener that supports JMS messaging. For each messagelistener-type that a
resource adapter implements, the resource adapter defines an associated activation specification
(activationspec in the ra.xml). The activation specification is used to set configuration properties for a
particular use of the inbound support for the receiving endpoint.

Chapter 8. Developing WebSphere applications 1449

When an application containing a message-driven bean is deployed, the deployer must select a resource
adapter that supports the same messagelistener type that the message-driven bean implements. As part of
the message-driven bean deployment, the deployer needs to specify the properties to set on the J2C
activation specification. Later, during application startup, a J2C activation specification instance is created,
and these properties are set and used to activate the endpoint (that is, to configure the resource adapter‘s
inbound support for the specific message-driven bean).

J2C activation specification configuration options and precedence:

Resource adapter scoped configuration

A J2C activation specification configuration instance can be created and modified under an installed
resource adapter at the cell, node, or server scope. This activation specification configuration is created
based on a particular message listener type for the given resource adapter. Valid properties available for
configuration are determined by introspection of the ActivationSpec class instance provided with the
resource adapter. When created, an ActivationSpec class instance is referenced by its JNDI name. This
activation specification configuration is needed during the deployment of a message-driven bean for the
resource adapter.

Configuring a J2C activation specification instance at the cell, node, or server level offers two distinct
advantages:
v The activation specification configuration information can be share among multiple message-driven
beans across multiple applications.
v Updates to the configuration properties can be made without the need to redeploy the application.

Application-based configuration

Applications with message-driven beans have the option of specifying all, some, or none of the properties
needed by the ActivationSpec class. These properties, specified as activation-config properties in the
application‘s deployment descriptor, are configured when the application is assembled. To change any of
these properties requires redeploying the application. These properties are unique to this applications use
and are not shared with other message-driven beans. Any properties defined in the application’s
deployment descriptor take precedence over those defined by the resource adapter-scoped definition. This
allows application developers to choose the best defaults for their applications.

To deploy and activate a message-driven bean with respect to application specification configuration
properties would be as follows:
1. Use JNDI to look up a J2C activation specification configuration instance, which is based on its
resource adapter-scoped definition.
2. Set the properties needed by the ActivationSpec class to the values defined by the cell, node, or
server definition. If any of the properties are also defined as activation-config properties of the
application, use the value defined by the activation-config property.
3. During application startup, the server activates the MDB endpoint by calling the resource adapter and
passing a configured instance of the ActivationSpec.
4. Note that a resource adapter can specify in its deployment descriptor if a given ActivationSpec property
is required. If it is required, and it is not supplied either by the cell, node or server definition, or an
activation-config property from the applications deployment descriptor, then an exception is raised as
part of the sequence to activate the message-driven bean.

WebSphere activation specification optional binding properties:

J2C authentication alias
If you provide values for user name and password as custom properties on an activation
specification, you may not want to have those values exposed in clear text for security reasons.
WebSphere security allows you to securely define an authentication alias for such cases.

1450 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 Configuration of activation specifications, both as an administrative object and during application
deployment enable you to use the authentication alias instead of providing the user name and
password.
If you set the authentication alias field, then you should not set the user name and password
custom properties fields. Also, authentication alias properties set as part of application deployment
take precedence over properties set on an activation specification administrative object.
Only the authentication alias is ever written to file in an unencrypted form, even for purposes of
transaction recovery logging. The security service is used to protect the real user name and
password.
During application startup, when the activation specification is being initialized as part of endpoint
activation, the server uses the authentication alias to retrieve the real user name and password
from security then set it on the activation specification instance.
Destination JNDI name
For resource adapters that support JMS you need to associate javax.jms.Destinations with an
activation specification, such that the resource adapter can service messages from the JMS
destination. In this case, the administrator configures a J2C Administered Object which implements
the javax.jms.Destination interface and binds it into JNDI.
You can configure a J2C Administered Object to use an ActivationSpec class that implements a
setDestination(javax.jms.Destination) method. In this case, you can specify the destination JNDI
name (that is, the JNDI name for the J2C Administered object that implements the
javax.jms.Destination).
A destination JNDI name set as part of application deployment take precedence over properties
set on an activation specification administrative object.
During application startup, when the activation specification is being initialized as part of endpoint
activation, the server uses the destination JNDI name to look up the destination administered
object then set it on the activation specification instance.

Message-driven beans - transaction support: Message-driven beans can handle messages read from
destinations (or endpoints) within the scope of a transaction. If transaction handling is specified for a
destination, the message-driven bean starts a global transaction before it reads any incoming message
from that destination. When the message-driven bean processing has finished, it commits or rolls back the
transaction (using JTA transaction control).

All messages retrieved from a specific destination have the same transactional behavior.

If messages are queued to be sent within a global transaction they are sent when the transaction is
committed. If the processing of a message causes the transaction to be rolled back, then the message
that caused the bean instance to be invoked is left on the JMS destination.

WebSphere Application Server cloning and WebSphere MQ clustering

This topic provides a summary of information about using WebSphere Application Server horizontal cloning
with WebSphere MQ server clustering support. It describes a scenario that shows how the message
listener service can be configured to take advantage of WebSphere MQ server clustering and provides
some information about how to resolve potential runtime failures in the clustering scenario. The information
in this topic is based on the scenario shown in the figure WebSphere Application Server horizontal cloning
with WebSphere MQ clustered queues.

Note: WebSphere MQ server clustering is only available with the full WebSphere MQ product installed as
a JMS provider.

Each JMS listener is used to retrieve messages from a destination defined to the server. In the following
information the listener configurations are the same for each WebSphere application server. Each
application server host contains a WebSphere application server and an WebSphere MQ server. If a host

Chapter 8. Developing WebSphere applications 1451

is only used to distribute messages, it only contains an WebSphere MQ server. There can be many
servers defined in the configuration, although for simplicity the information in this topic is based on a
scenario containing only three servers as shown in “WebSphere Application Server cloning and
WebSphere MQ clustering” on page 1451.

Figure 11. WebSphere Application Server horizontal cloning with WebSphere MQ clustered queues. This figure shows
two WebSphere Application Server hosts, with horizontal clustering, and a messaging host used to distribute
messages for WebSphere MQ server clustering. For more information, see the text that accompanies this figure.

The scenario shown in “WebSphere Application Server cloning and WebSphere MQ clustering” on page
1451 comprises the following three hosts:
v Server host S1 contains the following servers:
WebSphere MQ server.
The server is defined to have a queue manager, QM1, and a local queue, Q1. The queue
manager belongs to a cluster. The queue is populated by the WebSphere MQ server located on
host M3. Applications can add messages directly to the queue, Q1, but would not be subjected
to the control of the WebSphere MQ cluster.
WebSphere Application Server
This contains a cloned application server, WAS1, which is configured with a JMS listener. The
listener is configured to retrieve messages from JMS destination Q1.
v Server host S2 contains the following servers:
WebSphere MQ server.
The server is defined to have a queue manager, QM2, and a local queue, Q1. The queue
manager belongs to the same cluster as QM1 on host S1. As with QM1, the queue is populated
by the WebSphere MQ server located on host M3. Applications can add messages directly to
the queue, Q1, but would not be subjected to the control of the MQ cluster.
WebSphere Application Server
This contains a cloned application server, WAS2 (identical to WAS1 on host S1), which is
configured with a JMS listener. The listener is configured to retrieve messages from JMS
destination Q1.

1452 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v Messaging host M3 contains the following servers:
WebSphere MQ server.
The server is defined to have a queue manager, QM3, which also belongs to the same cluster
as QM1 and QM2. Applications add messages to the queue manager and queue Q1. The
cluster to which this queue manager belongs causes messages to be distributed to all other
queue managers in the cluster which have queue Q1 defined.

Note: Queue Q1 is not defined as a local queue on this host. If the queue was defined locally,
then messages would remain on the server for local processing; messages would not be
distributed by the queue manager cluster control to the other queue managers in the
cluster that do have the queue defined.
This host does not have a WebSphere application server defined. All message retrieval processing is
performed by the other two application servers on hosts S1 and S2.

Recovery scenarios

There are several failure scenarios that could occur with the clustering configuration; for example:
v WAS server failures.
In this scenario the failure of any single WebSphere application server results in the messages for the
specified destination remaining on the queue, until the server is restarted.
v WebSphere MQ Queue Manager failures.
There are two different failures to consider:
1. Failure of a queue manager on the same host as a WebSphere application server (for example,
failure of QM2 on host S2). In this case messages are delivered to the other available application
servers, until the WebSphere MQ server is back online, when messages are processed as
expected.
2. Failure of the messaging host M3 and its queue manager, QM3. In this case, the result of an outage
is more significant because no messages are delivered to the other queue managers in the cluster.
In a fully-deployed and scaled production system, host M3 would not be designed to be a single
point of failure, and additional messaging servers would be added to the cluster configuration.

Asynchronous messaging - security considerations

This topic describes considerations that you should be aware of if you want to use security for
asynchronous messaging with WebSphere Application Server.

Security for messaging operates as a part of the WebSphere Application Server global security, and is
enabled only when global security is enabled.

When global security is enabled, JMS connections made to the JMS provider are authenticated, and
access to JMS resources owned by the JMS provider are controlled by access authorizations. Also, all
requests to create new connections to the JMS provider must provide a user ID and password for
authentication. The user ID and password do not need to be provided by the application. If authentication
is successful, then the JMS connection is created; if the authentication fails then the connection request is
ended.

Standard J2C authentication is used for a request to create a new connection to the JMS provider. If your
resource authentication (res-auth) is set to Application, set the alias in the Component-managed
Authentication Alias. If the application that tries to create a connection to the JMS provider specifies a user
ID and password, those values are used to authenticate the creation request. If the application does not
specify a user ID and password, the values defined by the Component-managed Authentication Alias are
used. If the connection factory is not configured with a Component-managed Authentication Alias, then you
receive a runtime JMS exception when an attempt is made to connect to the JMS provider.

Restriction:

Chapter 8. Developing WebSphere applications 1453

 1. User IDs longer than 12 characters cannot be used for authentication with the version 5
default messaging provider or WebSphere MQ. For example, the default Windows NT
user ID, Administrator, is not valid for use, because it contains 13 characters.
Therefore, an authentication alias for a WebSphere JMS provider or WebSphere MQ
connection factory must specify a user ID no longer than 12 characters.
2. If you want to use Bindings transport mode for JMS connections to WebSphere MQ, you
set the property Transport type=BINDINGS on the WebSphere MQ Queue Connection
Factory. You must also choose one of the following options:
v To use security credentials, ensure that the user specified is the currently logged on
user for the WebSphere Application Server process. If the user specified is not the
current logged on user for the WebSphere Application Server process, then the
WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid
security authentication supplied for MQQueueManager error.
v Do not specify security credentials. On the WebSphere MQ Connection Factory,
ensure that both the Component-managed Authentication Alias and the
Container-managed Authentication Alias properties are not set.

Authorization to access messages stored by the default messaging provider is controlled by authorization
to access the service integration bus destinations on which the messages are stored. For information
about authorizing permissions for individual bus destinations, see ″Administering destination permissions″
in the information center.

Messaging: Resources for learning

v Sun’s Java Message Service (JMS) specification documentation.
Provides details about the Java Message Service (JMS).
v Sun’s J2EE Connector Architecture specification (http://java.sun.com/j2ee/connector/download.html).
Provides details about inbound messaging processing using the J2EE Connector architecture.
v J2EE specification
Provides details about the J2EE specification, including messaging considerations.
v WebSphere MQ Using Java.
Provides information about using JMS with WebSphere MQ as a messaging provider.
v http://www-3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html
Provides WebSphere MQ messaging platform-specific books.
v WebSphere MQ Event Broker Web site at http://www-4.ibm.com/software/ts/mqseries/platforms/#eventb
Provides books about WebSphere MQ Event Broker as a publish/subscribe messaging broker.
v WebSphere MQ Integrator Web site at http://www-4.ibm.com/software/ts/mqseries/platforms/#integrator
Provides books about WebSphere MQ Integrator as a publish/subscribe messaging broker.
v IBM Publications Center
This Web site provides a wide range of IBM publications, including publications about messaging
products.

Installing and configuring a JMS provider

This topic describes the different ways that you can use JMS providers with WebSphere Application
Server. A JMS provider enables use of the Java Message Service (JMS) and other message resources in
WebSphere Application Server.

IBM WebSphere Application Server supports asynchronous messaging through the use of a JMS provider
and its related messaging system. JMS providers must conform to the JMS specification version 1.1. To
use message-driven beans the JMS provider must support the optional Application Server Facility (ASF)
function defined within that specification, or support an inbound resource adapter as defined in the JCA
specification version 1.5.

1454 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The service integration technologies of IBM WebSphere Application Server can act as a messaging
system when you have configured a service integration bus that is accessed through the default
messaging provider. This support is installed as part of WebSphere Application Server, administered
through the administrative console, and is fully integrated with the WebSphere Application Server runtime.

WebSphere Application Server also includes support for the following JMS providers:
WebSphere MQ
Provided for use with supported versions of WebSphere MQ.
Generic
Provided for use with any 3rd party messaging system. If you want to use message-driven beans,
the messaging system must support ASF.

For more information about the support for JMS providers, see “JMS providers” on page 1443.

For more information about installing and using JMS providers, see the following topics:
v Installing the default messaging provider
v Using WebSphere MQ as a JMS provider. ″Installing WebSphere MQ as a JMS provider.″

Note:
– You can install WebSphere MQ in addition to the default messaging provider. The preferred
solution for publish/subscribe messaging with WebSphere MQ as a JMS provider is a full
message broker such as WebSphere MQ Event Broker.
– If you install WebSphere MQ as a JMS provider, you can use the WebSphere administrative
console to administer the JMS resources provided by WebSphere MQ, such as queue
connection factories. However, you cannot administer MQ security, which is administered
through WebSphere MQ.
For more information about scenarios and considerations for using WebSphere MQ with IBM
WebSphere Application Server, see the White Papers and Red books provided by WebSphere MQ; for
example, through the WebSphere MQ library Web page at http://www-
3.ibm.com/software/ts/mqseries/library/
v Installing another JMS provider, which must conform to the JMS specification and, to use
message-driven beans, support the ASF function. If you want to use a JMS provider other than the
default messaging provider or WebSphere MQ, you should complete the following steps:
1. Installing and configuring the JMS provider and its resources by using the tools and information
provided with the product.
2. Define the JMS provider to WebSphere Application Server as a generic messaging provider.

Note: You can use the WebSphere administrative console to administer JMS connection factories and
destinations (within WebSphere Application Server) for a generic provider, but cannot administer
the JMS provider or its resources outside of WebSphere Application Server.

Installing the default messaging provider

Use this task to install the default messaging provider of IBM WebSphere Application Server.

The default messaging provider is installed as a fully-integrated component of WebSphere Application

Server, and needs no separate installation steps.

However, ensure that there is enough space in the file systems where you want to store messaging data.

You can use the WebSphere administrative console to define JMS resources for the default messaging
provider.

For more information about the default messaging provider, see ″Using the default messaging provider″ in
the information center.

Chapter 8. Developing WebSphere applications 1455

Using asynchronous messaging
These topics describe how to use asynchronous messaging with WebSphere Application Server, to enable
enterprise applications to use JMS resources and message-driven beans.

WebSphere Application Server supports asynchronous messaging as a method of communication based

on the Java Message Service (JMS) programming interface. This JMS support is provided by one or more
JMS providers, and associated services and resources, that you configure for use by enterprise
applications. You can deploy EJB 2.1 applications that use the JMS 1.1 interfaces and EJB 2.0
applications that use the JMS 1.0.2 interfaces.

You can use the WebSphere administrative console to administer the WebSphere Application Server
support for asynchronous messaging. For example, you can configure messaging providers and their
resources, and can control the activity of messaging services.

For more information about implementing WebSphere enterprise applications that use asynchronous
messaging, see the following topics:
v Learning about messaging with WebSphere
v Installing a messaging provider
v Using the default messaging provider
v “Maintaining Version 5 default messaging resources” on page 1532
v “Using JMS resources of WebSphere MQ”
v “Using JMS resources of a generic provider” on page 1524
v “Administering support for message-driven beans” on page 1565
v Programming to use asynchronous messaging
v Troubleshooting WebSphere messaging

Using JMS resources of WebSphere MQ

This topic is the entry-point into a set of topics about enabling WebSphere applications to use JMS
resources provided by WebSphere MQ.

You can install WebSphere MQ as a JMS provider to WebSphere Application Server. WebSphere
applications can use the JMS 1.1 interfaces or JMS 1.0.2 interfaces to access JMS resources provided by
WebSphere MQ, in addition to JMS resources provided by the default messaging provider (or a generic
messaging provider).

You can use the WebSphere administrative console to administer the JMS connection factories and
destinations provided by WebSphere MQ.

In a mixed-version WebSphere Application Server deployment manager cell, you can administer
WebSphere MQ resources on both Version 6 and Version 5 nodes. For Version 5 nodes, the
administrative console presents the subset of resources and properties that are applicable to WebSphere
Application Server Version 5.

For more information about using WebSphere MQ as a messaging provider to WebSphere Application
Server, see the following topics:
v “Installing WebSphere MQ as a JMS provider”
v “Listing JMS resources for WebSphere MQ” on page 1458
v “Configuring JMS resources for the WebSphere MQ messaging provider” on page 1517

Installing WebSphere MQ as a JMS provider

Use this task to install and configure WebSphere MQ with support for the Java Message Service (JMS),
for use as a JMS provider to WebSphere Application Server.

1456 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If you have a messaging infrastructure based on WebSphere MQ, you may either connect directly using
the included support for WebSphere MQ as a JMS provider, or configure a service integration bus with
links to a WebSphere MQ network and then access the bus through the default messaging provider.
v (UNIX platforms only) Before you install WebSphere MQ on a UNIX platform, create and mount a
journalized file system called /var/mqm for your messaging working data. Use a partition strategy with a
separate volume for the WebSphere MQ data. This means that other system activity is not affected if a
large amount of messaging work builds up in /var/mqm. You can also create separate file systems for
your log data (var/mqm/log) and error files (var/mqm/errors). You should store log files on a different
physical volume from the messaging queues (var/mqm). This ensures data integrity in the case of a
hardware failure. If you are creating separate file systems, allow a minimum of 30 MB of storage for
/var/mqm, 20 MB of storage for /var/mqm/log, and 4 MB of storage for /var/mqm/errors.
– The /var file system is used to store all the security logging information for the system, and is used
to store the temporary files for email and printing. Therefore, it is critical that you maintain free space
in /var for these operations. If you do not create a separate file system for messaging data, and /var
fills up, all security logging will be stopped on the system until some free space is available in /var.
Also, email and printing will no longer be possible until some free space is available in /var.
– It is not recommended to install Rational Application Developer and WebSphere Application Server
on the same machine when using WebSphere MQ.
– For more information a security logging issue, see ″Security and WebSphere MQ″ in the information
center.
– For more information about creating file systems for WebSphere MQ, and WebSphere MQ space
requirements for /var file systems, see the section “Preparing for Installation: Creating WebSphere
MQ file systems” in the appropriate WebSphere MQ Quick Beginnings book.
– For other installation prerequisites, see the appropriate WebSphere MQ Quick Beginnings book, as
follows:
- WebSphere MQ for Windows, Quick Beginnings, GC34-6073
- WebSphere MQ for AIX, Quick Beginnings, GC34-6076
- WebSphere MQ for Solaris, Quick Beginnings, GC34-6075
- WebSphere MQ for HP-UX, Quick Beginnings, GC34-6077
- WebSphere MQ for Linux for Intel and Linux for zSeries, Quick Beginnings, GC34-6078
You can get these books from the WebSphere MQ messaging platform-specific books Web page at
http://www-3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html

To install and configure WebSphere MQ for use as a JMS provider to IBM WebSphere Application Server,
complete the following steps:
1. Install a supported version of WebSphere MQ, with the required MQ features, as described in the
installation instructions provided with WebSphere MQ.
To identify the a supported version of WebSphere MQ, see the Supported hardware and software Web
page at http://www.ibm.com/software/webservers/appserv/doc/latest/prereq.html.
For information about installing WebSphere MQ, or migrating to a supported version of WebSphere
MQ from an earlier version, see the appropriate WebSphere MQ Quick Beginnings book, as listed
above.
(RHEL 3.0 and SLES 8) After you install WebSphere MQ on any of the following platforms, but before
you try to accept the license, apply the fix located at: http://l3.hursley.ibm.com/cgi-
bin/ViewPRB.pl?1812. Otherwise, you may see a segmentation fault error when attempting to run the
mqlicense.sh -accept command to accept the WebSphere MQ license agreement. Also, export the
following variable: LD_ASSUME_KERNEL=2.4.19
v Red Hat Enterprise Linux (RHEL) 3.0 on Intel or s390
v SUSE Linux Enterprise Server (SLES) 8 on Intel
2. If you want to use WebSphere MQ - Publish/Subscribe support, you need to provide a
Publish/Subscribe broker.

Chapter 8. Developing WebSphere applications 1457

 For example, you can do this by using either WebSphere MQ Event Broker or WebSphere MQ
Integrator (formerly MQSeries Integrator). For more information about these products, see the following
Web sites:
v WebSphere MQ Event Broker Web site at http://www-
4.ibm.com/software/ts/mqseries/platforms/#eventb
v WebSphere MQ Integrator Web site at http://www-
4.ibm.com/software/ts/mqseries/platforms/#integrator
3. Follow the WebSphere MQ instructions for verifying your installation setup.

4. For AIX, see the WebSphere MQ readme.txt for additional steps.

5. If you want to install IBM WebSphere Application Server on the same host as WebSphere MQ, and
have not yet done so, install IBM WebSphere Application Server.
6. Set the MQJMS_LIB_ROOT environment variable to the directory where WebSphereMQ\Java\lib is
installed. IBM WebSphere Application Server uses the MQJMS_LIB_ROOT to locate the WebSphere
MQ libraries for the WebSphere MQ JMS Provider.

This task has installed WebSphere MQ for use as a JMS provider for WebSphere Application Server.

You can configure JMS resources to be provided by WebSphere MQ, by using the WebSphere
administrative console to define WebSphere MQ resources.

(UNIX platforms only) Restrict access to the messaging errors directories and logging files, by using the
following commands. This is part of the procedure to secure the directories and log files needed for
WebSphere MQ, as described in Securing messaging directories and log files.
1. For the /var/mqm/errors directory:
chmod 3777 /var/mqm/errors
chown mqm:mqm /var/mqm/errors

touch /var/mqm/errors/AMQERR01.LOG
chown mqm:mqm /var/mqm/errors/AMQERR01.LOG
chmod 666 /var/mqm/errors/AMQERR01.LOG

touch /var/mqm/errors/AMQERR02.LOG
chown mqm:mqm /var/mqm/errors/AMQERR02.LOG
chmod 666 /var/mqm/errors/AMQERR02.LOG

touch /var/mqm/errors/AMQERR03.LOG
chown mqm:mqm /var/mqm/errors/AMQERR03.LOG
chmod 666 /var/mqm/errors/AMQERR03.LOG
2. For the /var/mqm/qmgrs/@SYSTEM/errors directory:
chmod 3777 /var/mqm/qmgrs/@SYSTEM/errors
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG

Listing JMS resources for WebSphere MQ

Use this task with the WebSphere administrative console to list the JMS resources provided by
WebSphere MQ as a messaging provider.

1458 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
You can use the WebSphere administrative console to display lists of the following types of JMS resources
provided by WebSphere MQ. You can use the panels displayed to select JMS resources to administer, or
to create or delete JMS resources (where appropriate).

To display administrative lists of JMS resources for WebSphere MQ, complete the following general steps:
1. Start the WebSphere administrative console.
2. In the navigation pane, click Resources → JMS Providers → WebSphere MQ
3. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
4. In the content pane, under Additional Resources, click the link for the type of JMS resource. This
displays a list of any existing resources of the selected type. For more information about the settings
panels displayed for resources, see the related reference topics.

WebSphere MQ connection factory collection:

The unified JMS connection factories configured in the WebSphere MQ messaging provider, for both
point-to-point and publish/subscribe messaging.

This panel shows a list of the WebSphere MQ unified JMS connection factories with a summary of their
configuration properties. In a deployment manager cell, these connection factories are not available for
Version 5 nodes.

This type of connection factory is sometimes called a “unified” or “domain-independent” JMS connection
factory, and supports the JMS 1.1 domain-independent interfaces (referred to as the ″common interfaces″
in the JMS specification). This enables applications to use the same, common, interfaces for both
point-to-point and publish/subscribe messaging. A unified JMS connection factory also supports the
domain-specific (queue and topic) interfaces, as used in JMS 1.0.2, so applications can still use those
interfaces.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. In the content pane, ensure that the scope is set to cell scope or to node or server scope for a Version
6 node.
3. In the content pane, under Additional Resources, click WebSphere MQ connection factories. This
displays a list of any existing JMS queue connection factories.

To define a new connection factory, click New.

To view or change the properties of a queue connection factory, click its name in the list displayed.

To act on one or more of the connection factories listed, select the check boxes next to the names of the
objects that you want to act on, then use the buttons provided.

WebSphere MQ connection factory settings:

Use this panel to view or change the configuration properties of the selected JMS connection factory for
use with WebSphere MQ as a JMS provider. These configuration properties control how connections are
created to associated JMS queues and topics.

This type of connection factory is sometimes called a “unified” or “domain-independent” JMS connection
factory, and supports the JMS 1.1 domain-independent interfaces (referred to as the ″common interfaces″
in the JMS specification). This enables applications to use the same, common, interfaces for both

Chapter 8. Developing WebSphere applications 1459

point-to-point and publish/subscribe messaging. A unified JMS connection factory also supports the
domain-specific (queue and topic) interfaces, as used in JMS 1.0.2, so applications can still use those
interfaces.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. In the content pane, ensure that the scope is set to cell scope, or to node or server scope for a
Version 6 node.
3. In the content pane, under Additional Resources, click WebSphere MQ connection factories.
4. Click the name of the JMS connection factory that you want to work with.

A unified JMS connection factory for the WebSphere MQ JMS provider has the following properties.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ for JMS resources. For more information about configuring WebSphere MQ JMS
resources, see the WebSphere MQ Using Java book. and the WebSphere MQ System
Administration book, SC33-1873, which are available from the WebSphere MQ messaging
platform-specific books Web page at http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications
Center, or from the WebSphere MQ collection kit, SK2T-0730.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.
v For more information about setting SSL properties for WebSphere MQ, see the section SSL
properties in the WebSphere MQ Using Java book.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which this JMS connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the JMS connection factories across the
WebSphere administrative domain.

Data type String

JNDI name:

The JNDI name that is used to bind the connection factory into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

1460 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

Category:

A category used to classify or group this connection factory, for your IBM WebSphere Application Server
administrative records.

Data type String

Authentication mechanism preference:

The authentication mechanism to be used for connections to WebSphere MQ created by this connection
factory.

If WebSphere MQ is not configured to support the authentication mechanism preference, it is ignored.

Data type Enum

Default BASIC PASSWORD
Range
BASIC PASSWORD
Authentication is performed based on a user ID
and password provided by an authentication
alias. The authentication alias used is obtained
from one of the following properties:
v Component-managed Authentication Alias, for
application-managed authentication.
v Container-managed Authentication Alias, for
container-managed authentication.
KerbV5
Authentication is performed based on SSL
certificates.

Component-managed authentication alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
application-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

Chapter 8. Developing WebSphere applications 1461

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Restriction:
1. User IDs longer than 12 characters cannot be used for authentication with WebSphere
MQ. For example, the default Windows user ID, Administrator, is not valid because it
contains 13 characters. Therefore, an authentication alias for a WebSphere MQ queue
connection factory must specify a user ID no longer than 12 characters.
2. If you want to use Bindings transport mode on JMS queue connections to WebSphere
MQ, you set the Transport type property to BINDINGS on the WebSphere MQ Queue
Connection Factory. You must also choose one of the following options:
v To use security credentials, ensure that the user specified is the currently logged on
user for the WebSphere Application Server process. If the user specified is not the
current logged on user for the WebSphere Application Server process, then the
WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid
security authentication supplied for MQQueueManager.
v Do not specify security credentials. On the WebSphere MQ Connection Factory,
ensure that both the Component-managed Authentication Alias and the
Container-managed Authentication Alias properties are not set.

Container-managed authentication alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
container-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Restriction:
1. User IDs longer than 12 characters cannot be used for authentication with WebSphere
MQ. For example, the default Windows user ID, Administrator, is not valid because it
contains 13 characters. Therefore, an authentication alias for a WebSphere MQ queue
connection factory must specify a user ID no longer than 12 characters.
2. If you want to use Bindings transport mode on JMS queue connections to WebSphere
MQ, you set the Transport type property to BINDINGS on the WebSphere MQ Queue
Connection Factory. You must also choose one of the following options:
v To use security credentials, ensure that the user specified is the currently logged on
user for the WebSphere Application Server process. If the user specified is not the
current logged on user for the WebSphere Application Server process, then the
WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid
security authentication supplied for MQQueueManager.
v Do not specify security credentials. On the WebSphere MQ Connection Factory,
ensure that both the Component-managed Authentication Alias and the
Container-managed Authentication Alias properties are not set.

Mapping-configuration alias:

1462 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The module used to map authentication aliases.

This field provides a list of the modules that have been configured on the Security → JAAS Configuration
→ Application Logins Configuration property. For more information about the mapping configurations,
see Java Authentication and Authorization service configuration entry settings.

Data type Enum

Default Null
Range ClientContainer
The client container maps authentication aliases.
WSLogin
The WSLogin module maps authentication
aliases.
DefaultPrincipalMapping
The JAAS configuration maps an authentication
alias to its userid and password.

Manage cached handles:

Whether or not cached handles (held in inst vars in a bean) should be tracked by the container.

Tracking handles can cause a large performance overhead if used at runtime; however, for debugging
purposes it can be useful to enable handle management.

Data type Check box

Default Cleared
Range
Cleared
Cached handles are not tracked by the container.
Selected
Cached handles are tracked by the container.
You should select this option only for debugging
purposes, because this can cause a large
performance overhead.

Log missing transaction contexts:

Whether or not the container logs when there is a missing transaction context at the time that a connection
is created.

Data type Check box

Default Selected
Range
Selected
When a connection is created, any missing
transaction contexts are logged in the activity log.
Cleared
Missing transaction contexts are not logged.

Queue manager:

The name of the WebSphere MQ queue manager for this connection factory. Connections created by this
factory connect to that queue manager.

Data type String

Default Null

Chapter 8. Developing WebSphere applications 1463

Range A valid WebSphere MQ queue manager name, as 1
through 48 ASCII characters

Host:

The name of the host on which the WebSphere MQ queue manager runs, for client connection only.

Data type String

Default Null
Range A valid TCP/IP hostname

Port:

The TCP/IP port number used for connection to the WebSphere MQ queue manager, for client connection
only.

This port must be configured on the WebSphere MQ queue manager.

Data type Integer

Default Null
Range A valid TCP/IP port number, configured on the WebSphere
MQ queue manager.

Channel:

The name of the channel used for connection to the WebSphere MQ queue manager, for client connection
only.

Data type String

Default Null
Range 1 through 20 ASCII characters

Transport type:

Specifies whether to use the WebSphere MQ client connection or JNI bindings for connection to the
WebSphere MQ queue manager. WebSphere MQ as the JMS provider controls the communication
protocols between JMS clients and JMS servers. Tune the transport type when you are using non-ASF
nonpersistent, non-durable, non-transactional messaging or when you want to satisfy security issues and
the client is local to the queue manager node.

Data type Enum

Units Not applicable
Default BINDINGS
Range BINDINGS
JNI bindings are used to connect to the queue
manager. BINDINGS is a shared memory
protocol and can only be used when the queue
manager is on the same node as the JMS client
and comes at some security risks that should be
addressed through the use of EJB roles.
CLIENT
WebSphere MQ client connection is used to
connect to the queue manager. CLIENT is a
typical TCP-based protocol.

1464 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Recommended BINDINGS is faster by 30% or more, but it lacks security.
When you have security concerns, CLIENT is more
desirable than BINDINGS.

Model queue definition:

The name of the model queue definition that can be used by the queue manager to create temporary
queues if a queue requested does not already exist.

Data type String

Default Null
Range 1 through 48 ASCII characters

Client ID:

The JMS client identifier used for connections to the WebSphere MQ queue manager.

Data type String

Default Null

CCSID:

The coded character set identifier for use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

Data type String

Units Integer
Default Null
Range 1 through 65535

For more information about supported CCSIDs, and about converting between message data from one
coded character set to another, see the WebSphere MQ System Administration and the WebSphere MQ
Application Programming Reference books. These are available from the WebSphere MQ messaging
multiplatform and platform-specific books Web pages; for example, at http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications Center, or
from the WebSphere MQ collection kit, SK2T-0730.

Enable message retention:

Whether or not unwanted messages are left on the queue. If this option is not enabled, unwanted
messages are dealt with according to their disposition options.

Data type Check box

Default Cleared
Range Selected
Unwanted messages are left on the queue.
Cleared
Unwanted messages are dealt with according to
their disposition options.

XA enabled:

Chapter 8. Developing WebSphere applications 1465

Specifies whether the connection factory is for XA or non-XA coordination of messages and controls if the
application server uses XA QCF/TCF. Enable XA if multiple resources are not used in the same
transaction.

If you clear this property, the JMS session is still enlisted in a transaction, but uses the resource manager
local transaction calls (session.commit and session.rollback) instead of XA calls. This can lead to an
improvement in performance. However, this means that only a single resource can be enlisted in a
transaction in WebSphere Application Server.

Last participant support enables you to enlist one non-XA resource with other XA-capable resources.

Data type Check box

Units Not applicable
Default Selected (XA enabled)
Range Selected
The connection factory is for XA-coordination of
messages
Cleared
The connection factory is for non-XA coordination
of messages
Recommended Do not enable XA when the message queue received is
the only resource in the transaction. Enable XA when
other resources, including other queues or topics, are
involved.

Enable return methods during shutdown:

Whether or not applications return from a method call if the queue manager has entered a controlled
shutdown.

Data type Checkbox

Default Selected
Range Selected
Applications return from a method call if the
queue manager has entered a controlled
shutdown.
Cleared
Applications do not return from a method call if
the queue manager has entered a controlled
shutdown.

Local server address:

The range of local ports to be used when making a connection to a WebSphere MQ queue manager

If a JMS application attempts to connect to a WebSphere MQ queue manager in client mode, a firewall
might allow only those connections that originate from specified ports or a range of ports. In this situation,
you can use this property to specify a port, or a range of points, that the application can bind to.

Data type String

Default Null

1466 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range A string in the format:
[ip-addr][(low-port[,high-port])]

For example:
v 9.20.4.98
The channel binds to address 9.20.4.98 locally
v 9.20.4.98(1000)
The channel binds to address 9.20.4.98 locally and
uses port 1000
v 9.20.4.98(1000,2000)
The channel binds to address 9.20.4.98 locally and
uses a port in the range 1000 to 2000
v (1000)
The channel binds to port 1000 locally
v (1000,2000)
The channel binds to a port in the range 1000 to 2000
locally

You can specify a host name instead of an IP address.

For direct connections, this property applies only when

multicast is used and the value of the property must not
contain a port number. If it does contain a port number,
the connection is rejected. Therefore, the only valid values
of the property are null, an IP address, or a host name.

Polling interval:

The interval, in milliseconds, between scans of all receivers during asynchronous message delivery

Data type Integer

Units milliseconds
Default 5000
Range 1 through 2147483647

Rescan interval:

The interval in milliseconds between which a topic is scanned to look for messages that have been added
to a topic out of order.

This interval controls the scanning for messages that have been added to a topic out of order with respect
to a WebSphere MQ browse cursor.

Data type Integer

Units milliseconds
Default 5000
Range 1 through 2147483647

SSL cipher suite:

The cipher suite to use for SSL connection to WebSphere MQ.

Set this property to a valid cipher suite provided by your JSSE provider; it must match the CipherSpec
named on the SVRCONN channel named by the Channel property.

Chapter 8. Developing WebSphere applications 1467

You must set this property if the SSL Peer Name property is to be set.

SSL CRL:

A list of zero or more Certificate Revocation List (CRL) servers used to check for SSL certificate
revocation. (Use of this property requires a WebSphere MQ JVM at Java 2 version 1.4.)

The value is a space-delimited list of entries of the form:

ldap://hostname:[port]

optionally followed by a single / (forward slash). If port is omitted, the default LDAP port of 389 is
assumed. At connect-time, the SSL certificate presented by the server is checked against the specified
CRL servers. For more information about CRL security, see the section “Working with Certificate
Revocation Lists” in the WebSphere MQ Security book; for example at:
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas012w.htm#IDX2254.

SSL peer name:

For SSL, a distinguished name skeleton that must match the name provided by the WebSphere MQ queue
manager. The distinguished name is used to check the identifying certificate presented by the server at
connect-time.

The SSL Peer Name property is ignored if SSL cipher suite property is not specified.

This property is a list of attribute name and value pairs separated by commas or semicolons. For example:
CN=QMGR.*, OU=IBM, OU=WEBSPHERE

The example given checks the identifying certificate presented by the server at connect-time. For the
connection to succeed, the certificate must have a Common Name beginning QMGR., and must have at
least two Organizational Unit names, the first of which is IBM and the second WEBSPHERE. Checking is
not case-sensitive.

For more details about distinguished names and their use with WebSphere MQ, see the WebSphere MQ
Security book; for example, the section “Distinguished Names” at
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas010p.htm#HDRDCDN.

Temporary queue prefix:

The prefix that is used for names of temporary JMS queues created by applications that use this
connection factory.

Data type String

Default Null

Enable MQ connection pooling:

Whether or not to use WebSphere MQ connection pooling.

Data type Checkbox

Default Selected

1468 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range
Selected Cleared
The connection factory uses The connection factory does
WebSphere MQ connection not use WebSphere MQ
pooling. When a connection connection pooling. When a
is no longer required, instead connection is no longer
of destroying it, it can be required, it is destroyed. To
pooled, and later reused. use the same queue
This can provide a manager a new connection is
substantial performance created.
enhancement for repeated
connections to the same
queue manager.

Broker control queue:

The name of the publish/subscribe broker’s control queue, to which publisher and subscriber applications
send all command messages (except publications and requests to delete publications).

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker queue manager:

The name of the WebSphere MQ queue manager that provides the publish/subscribe message broker.

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker publication queue:

The name of the broker’s input queue (stream queue) that receives all publication messages for the
default stream. Applications can also send requests to delete publications on the default stream to this
queue.

Data type String

Units En_US ASCII characters
Default Null
Range 1 through 48 ASCII characters

Broker subscription queue:

The name of the broker’s queue from which non-durable subscription messages are retrieved. The
subscriber specifies the name of the queue when it registers a subscription.

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker CC subscription queue:

Chapter 8. Developing WebSphere applications 1469

The name of the broker’s queue from which non-durable subscription messages are retrieved for a
ConnectionConsumer. This property applies only for use of the Web container.

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker version:

Whether the message broker is provided by the WebSphere MQ MA0C Supportpac or newer versions of
WebSphere message broker products.

Data type Enum

Default Advanced
Range Advanced
The message broker is provided by newer
versions of WebSphere message broker
products, such as WebsSphere MQ Integrator
and Event Broker.
Basic The message broker is provided by the
WebSphere MQ MA0C SupportPac (MQSeries -
Publish/Subscribe) or MQSI working in MA0C
compatibility mode.

Publish/subscribe cleanup level:

The level of cleanup provided by the Publish/subscribe cleanup utility

To avoid the problems associated with non-graceful closure of subscriber objects, WebSphere MQ as a
JMS provider provides a Publish/Subscribe cleanup utility that attempts to detect any earlier JMS
publish/subscribe problems. If a large number of problems are detected, some performance degradation
may be observed while resources are cleaned up. This utility runs transparently on a background thread
and should not affect other WebSphere MQ operations.

Data type Enum

Default SAFE

1470 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range
SAFE The Cleanup thread attempts to remove
unconsumed subscription messages, or
temporary queues, for failed subscriptions. This
mode of cleanup does not interfere with the
operation of other JMS applications.
ASPROP
The style of cleanup to use is determined by the
system property com.ibm.mq.jms.cleanup, which
is queried at JVM startup. This property can be
set on the java command-line using the -D
option, and should be set to NONE, SAFE or
STRONG. Any other value causes an exception.
If not set, the property defaults to SAFE. This
allows easy JVM-wide change to the Cleanup
level without needing to update every topic
connection factory used by the system.
NONE In this special mode, no cleanup is performed;
and no cleanup thread exists. Additionally, if the
application is using the single-queue approach,
unconsumed messages can be left on the queue.
This option can be useful if the application is
distant from the queue manager, and especially if
it only publishes rather than subscribes. However,
some application should perform cleanup on the
queue manager to deal with any unconsumed
messages - this could be a JMS application with
CLEANUP(SAFE) or CLEANUP(STRONG), or
the WebSphere MQ manual cleanup utility.
STRONG
The cleanup thread performs as
CLEANUP(SAFE), but also clears the
SYSTEM.JMS.REPORT.QUEUE of any
unrecognized messages.

Publish/subscribe cleanup interval:

The interval, in milliseconds, between background executions of the publish/subscribe cleanup utility.

Data type Integer

Default 60000
Range 1 through 2147483647

Message selection:

Whether message selection is done at the broker or client.

Data type Enum

Default BROKER
Range
BROKER
Message selection is done at the broker.
CLIENT
Message selection is done at the client.

Chapter 8. Developing WebSphere applications 1471

Publish acknowledgement interval:

The interval, in number of messages, between publish requests that require acknowledgement from the
broker.

Data type Integer

Default 25
Range 1 through 2147483647

Enable sparse subscriptions:

Select this option to support subscriptions that receive infrequent matching messages.

Data type Checkbox

Default Cleared
Range
Selected
Subscriptions can receive infrequent matching
messages. This value requires that the
subscription queue can be opened for browse.
Cleared
Sparse subscriptions are not supported.
Subscriptions receive frequent matching
messages.

Publish/subscribe status interval:

The interval, in milliseconds, between transactions to refresh publish/subscribe status.

Data type Integer

Default 60000
Range 1 through 2147483647

Persistent subscriptions store:

Where WebSphere MQ stores persistent data relating to active JMS subscriptions.

Data type Enum

Default MIGRATE

1472 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range
MIGRATE
This option dynamically selects the queue-based
or broker-based subscription store based on the
levels of queue manager and publish/subscribe
broker installed. If both queue manager and
broker are capable of supporting
SUBSTORE(BROKER), this behaves as
SUBSTORE(BROKER); otherwise it behaves as
SUBSTORE(QUEUE). Additionally,
SUBSTORE(MIGRATE) transfers durable
subscription information from the queue-based
subscription store to the broker-based store.
QUEUE
Subscription information is stored on
SYSTEM.JMS.ADMIN.QUEUE and
SYSTEM.JMS.PS.STATUS.QUEUE on the local
queue manager.
BROKER
Subscription information is stored by the
publish/subscribe broker used by the application.
This option requires recent levels of queue
manager and publish/subscribe broker. This
subscription store requires recent levels of both
queue manager and publish/subscribe broker. It
is designed to provide improved resilience.

Enable multicast transport:

Whether or not this connection factory uses multicast transport.

With multicast, messages are delivered to all consumers. This is useful in environments where there are a
large number of clients that all want to receive the same messages, because with multicast only one copy
of each message is sent. Multicast reduces the total amount of network traffic. Reliable multicast is
standard multicast with a reliability layer added.

Data type Enum

Default NOTUSED
Range
NOTUSED
This connection factory does not use multicast
transport.
ENABLED
This connection factory uses multicast transport,
but does not provide a reliable multicast
connection.
ENABLED_IF_AVAILABLE
This connection factory uses multicast transport if
the message broker supports it.
ENABLED_RELIABLE
This connection factory uses reliable multicast
transport
ENABLED_RELIABLE_IF_AVAILABLE
This connection factory uses reliable multicast
transport if the message broker supports it.

Chapter 8. Developing WebSphere applications 1473

Enable clone support:

Select this check box to enable clone support to allow the same durable subscription across topic clones.

Data type check box

Default Cleared
Range Selected
Clone support is enabled.
Cleared
Clone support is disabled.

If you select this property, you must also specify a value for the Client ID property.

Direct broker authentication:

Whether the broker uses basic or certificate-based authentication for direct connections.

This property selects the authentication on a direct connections (if the TRANSPORT property is set to
DIRECT).

Data type Enum

Default NONE
Range
NONE Direct broker authentication is not used.
PASSWORD
Password-based authentication is used for direct
connections. Authentication is performed based
on a user ID and password provided by an
authentication alias. The authentication alias
used is obtained from one of the following
properties:
v Component-managed Authentication Alias, for
application-managed authentication.
v Container-managed Authentication Alias, for
container-managed authentication.
CERTIFICATE
Certificate-based authentication is used for direct
connections. The SSLPEERNAME and SSLCRL
properties are used to perform the authentication
checks.
You can use certificate-based authentication
when connecting directly to a WebSphere
Business Integration Event Broker or WebSphere
Business Integration Message Broker broker.

Proxy host name:

Host name of the Web Scale proxy host.

A direct connection is made to the proxy server, which forwards the connection request to the message
broker.

If the TRANSPORT property is set to DIRECT, the type of connection to the message broker depends on
the value of this property, according to the following rules:

1474 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v If this property is set to the empty string, a direct connection is made to the broker identified by the
HOSTNAME and PORT.
v If this property is set to a value other than the empty string, a direct connection is made to the broker
through the proxy server identified by this property and the PROXYPORT property.

Data type String

Default Null

Proxy port:

Port number of the Web Scale proxy port.

A direct connection is made to this port on the proxy server identified by the PROXYHOSTNAME property,
which forwards the connection request to the message broker. For more information, see the description of
the PROXYHOSTNAME property.

Data type Integer

Default 0

Connection pool:

Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Session pools:

An optional set of session pool settings.

This link provides a panel of optional connection pool properties, common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

Custom properties:

An optional set of name and value pairs for custom properties passed to WebSphere MQ.

WebSphere MQ queue connection factory collection:

The queue connection factories configured in the WebSphere MQ messaging provider, for point-to-point
messaging with JMS queues.

This panel shows a list of the WebSphere MQ queue connection factories with a summary of their
configuration properties.

Chapter 8. Developing WebSphere applications 1475

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Queue Connection Factory.
This displays a list of any existing JMS queue connection factories.

To view or change the properties of a queue connection factory, click its name in the list displayed.

To act on one or more of the connection factories listed, select the check boxes next to the names of the
objects that you want to act on, then use the buttons provided.

WebSphere MQ queue connection factory settings:

Use this panel to view or change the configuration properties of the selected queue connection factory for
use with the WebSphere MQ JMS provider. These configuration properties control how connections are
created to the associated JMS queue destination.

A WebSphere MQ queue connection factory is used to create JMS connections to queues provided by
WebSphere MQ for point-to-point messaging.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Queue Connection Factories.
This displays a list of any existing JMS queue connection factories.
4. Click the name of the JMS connection factory that you want to work with.

A queue connection factory for the WebSphere MQ JMS provider has the following properties.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ for JMS resources. For more information about configuring WebSphere MQ for
JMS resources, see the WebSphere MQ Using Java book. and the WebSphere MQ System
Administration book, SC33-1873, which are available from the WebSphere MQ messaging
platform-specific books Web page at http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications
Center, or from the WebSphere MQ collection kit, SK2T-0730.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

1476 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type String

Name:

The name by which this queue connection factory is known for administrative purposes within IBM
WebSphere Application Server.

Data type String

JNDI name:

The JNDI name that is used to bind the connection factory into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

Category:

A category used to classify or group this connection factory, for your IBM WebSphere Application Server
administrative records.

Data type String

Component-managed authentication alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
application-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Restriction:

Chapter 8. Developing WebSphere applications 1477

 1. User IDs longer than 12 characters cannot be used for authentication with WebSphere
MQ. For example, the default Windows user ID, Administrator, is not valid because it
contains 13 characters. Therefore, an authentication alias for a WebSphere MQ queue
connection factory must specify a user ID no longer than 12 characters.
2. If you want to use Bindings transport mode on JMS queue connections to WebSphere
MQ, you set the Transport type property to BINDINGS on the WebSphere MQ Queue
Connection Factory. You must also choose one of the following options:
v To use security credentials, ensure that the user specified is the currently logged on
user for the WebSphere Application Server process. If the user specified is not the
current logged on user for the WebSphere Application Server process, then the
WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid
security authentication supplied for MQQueueManager.
v Do not specify security credentials. On the WebSphere MQ Connection Factory,
ensure that both the Component-managed Authentication Alias and the
Container-managed Authentication Alias properties are not set.

Container-managed authentication alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
container-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Restriction:
1. User IDs longer than 12 characters cannot be used for authentication with WebSphere
MQ. For example, the default Windows user ID, Administrator, is not valid because it
contains 13 characters. Therefore, an authentication alias for a WebSphere MQ queue
connection factory must specify a user ID no longer than 12 characters.
2. If you want to use Bindings transport mode on JMS queue connections to WebSphere
MQ, you set the Transport type property to BINDINGS on the WebSphere MQ Queue
Connection Factory. You must also choose one of the following options:
v To use security credentials, ensure that the user specified is the currently logged on
user for the WebSphere Application Server process. If the user specified is not the
current logged on user for the WebSphere Application Server process, then the
WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid
security authentication supplied for MQQueueManager.
v Do not specify security credentials. On the WebSphere MQ Connection Factory,
ensure that both the Component-managed Authentication Alias and the
Container-managed Authentication Alias properties are not set.

Mapping-configuration alias:

The module used to map authentication aliases.

This field provides a list of the modules that have been configured on the Security → JAAS Configuration
→ Application Logins Configuration property. For more information about the mapping configurations,
see Java Authentication and Authorization service configuration entry settings.

1478 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Enum
Default Null
Range ClientContainer
The client container maps authentication aliases.
WSLogin
The WSLogin module maps authentication
aliases.
DefaultPrincipalMapping
The JAAS configuration maps an authentication
alias to its userid and password.

Host:

The name of the host on which the WebSphere MQ queue manager runs, for client connection only.

Data type String

Default Null
Range A valid TCP/IP hostname

Port:

The TCP/IP port number used for connection to the WebSphere MQ queue manager, for client connection
only.

This port must be configured on the WebSphere MQ queue manager.

Data type Integer

Default 0
Range A valid TCP/IP port number, configured on the WebSphere
MQ queue manager.

Transport type:

Whether the WebSphere MQ client connection or JNI bindings are used for connection to the WebSphere
MQ queue manager.

WebSphere MQ, as the messaging provider, controls the communication protocols between JMS clients
and JMS servers. Tune the transport type when you are using non-ASF non-persistent, non-durable,
non-transactional messaging or when you want to satisfy security issues and the client is local to the
queue manager node.

Data type Enum

Units Not applicable
Default BINDINGS
Range BINDINGS
JNI bindings are used to connect to the queue
manager. BINDINGS is a shared memory
protocol and can only be used when the queue
manager is on the same node as the JMS client
and comes at some security risks that should be
addressed through the use of EJB roles.
CLIENT
WebSphere MQ client connection is used to
connect to the queue manager. CLIENT is a
typical TCP-based protocol.

Chapter 8. Developing WebSphere applications 1479

Recommended BINDINGS is faster by 30% or more, but it lacks security.
When you have security concerns, BINDINGS is more
desirable than CLIENT.

Channel:

The name of the channel used for connection to the WebSphere MQ queue manager, for client connection
only.

Data type String

Default Null
Range 1 through 20 ASCII characters

Queue manager:

The name of the WebSphere MQ queue manager for this connection factory. Connections created by this
factory connect to that queue manager.

Data type String

Default Null
Range A valid WebSphere MQ queue manager name, as 1
through 48 ASCII characters

Model queue definition:

The name of the model queue definition that can be used by the queue manager to create temporary
queues if a queue requested does not already exist.

Data type String

Default Null
Range 1 through 48 ASCII characters

Client ID:

The JMS client identifier used for connections to WebSphere MQ.

Data type String

Range A valid JMS client ID, as ASCII characters

CCSID:

The coded character set identifier for use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

Data type String

Units Integer
Default Null
Range 1 through 65535

For more information about supported CCSIDs, and about converting between message data from one
coded character set to another, see the WebSphere MQ System Administration and the WebSphere MQ
Application Programming Reference books. These are available from the WebSphere MQ messaging

1480 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
multi-platform and platform-specific books Web pages; for example, at http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications Center, or
from the WebSphere MQ collection kit, SK2T-0730.

Enable message retention:

Whether or not unwanted messages are left on the queue. If this option is not enabled, unwanted
messages are dealt with according to their disposition options.

Data type Enum

Default Selected
Range Selected
Unwanted messages are left on the queue.
Cleared
Unwanted messages are dealt with according to
their disposition options.

XA enabled:

Specifies whether the connection factory is for XA or non-XA coordination of messages and controls if the
application server uses XA. Enable XA if multiple resources are not used in the same transaction.

If you clear this property (non-XA), the JMS session is still enlisted in a transaction, but uses the resource
manager local transaction calls (session.commit and session.rollback) instead of XA calls. This can lead to
an improvement in performance. However, this means that only a single resource can be enlisted in a
transaction in WebSphere Application Server.

Last participant support enables you to enlist one non-XA resource with other XA-capable resources.

Data type Checkbox

Default Selected
Range Selected
The connection factory is for XA-coordination of
messages
Cleared
The connection factory is for non-XA coordination
of messages
Recommended Do not select to enable XA when the message queue
received is the only resource in the transaction. Enable
XA if transactions involve other resources, including other
queues or topics.

Enable return methods during shutdown:

Whether or not applications return from a method call if the queue manager has entered a controlled
shutdown.

Data type Checkbox

Default Selected
Range Selected
Applications return from a method call if the
queue manager has entered a controlled
shutdown.
Cleared
Applications do not return from a method call if
the queue manager has entered a controlled
shutdown.

Chapter 8. Developing WebSphere applications 1481

Local server address:

The local server address

If a JMS application attempts to connect to a WebSphere MQ queue manager in client mode, a firewall
might allow only those connections that originate from specified ports or a range of ports. In this situation,
you can use this property to specify a port, or a range of points, that the application can bind to.

Data type String

Default Null
Range A string in the format:
[ip-addr][(low-port[,high-port])]

For example:
v 9.20.4.98
The channel binds to address 9.20.4.98 locally
v 9.20.4.98(1000)
The channel binds to address 9.20.4.98 locally and
uses port 1000
v 9.20.4.98(1000,2000)
The channel binds to address 9.20.4.98 locally and
uses a port in the range 1000 to 2000
v (1000)
The channel binds to port 1000 locally
v (1000,2000)
The channel binds to a port in the range 1000 to 2000
locally

You can specify a host name instead of an IP address.

For direct connections, this property applies only when

multicast is used and the value of the property must not
contain a port number. If it does contain a port number,
the connection is rejected. Therefore, the only valid values
of the property are null, an IP address, or a host name.

Polling interval:

The interval, in milliseconds, between scans of all receivers during asynchronous message delivery

Data type Integer

Units milliseconds
Default 5000
Range 1 through 2147483647

Rescan interval:

The interval in milliseconds between which a queue is scanned to look for messages that have been
added to a queue out of order.

This interval controls the scanning for messages that have been added to a queue out of order with
respect to a WebSphere WebSphere MQ browse cursor.

1482 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Integer
Units milliseconds
Default 5000
Range 1 through 2147483647

SSL Cipher Suite:

The cipher suite to use for SSL connection to WebSphere MQ.

Set this property to a valid cipher suite provided by your JSSE provider; it must match the CipherSpec
named on the SVRCONN channel named by the Channel property.

You must set this property if the SSL Peer Name property is to be set.

SSL CRL:

A list of zero or more Certificate Revocation List (CRL) servers used to check for SSL certificate
revocation. (Use of this property requires a WebSphere MQ JVM at Java 2 version 1.4.)

The value is a space-delimited list of entries of the form:

ldap://hostname:[port]

optionally followed by a single / (forward slash). If port is omitted, the default LDAP port of 389 is
assumed. At connect-time, the SSL certificate presented by the server is checked against the specified
CRL servers. For more information about CRL security, see the section “Working with Certificate
Revocation Lists” in the WebSphere MQ Security book; for example at:
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas012w.htm#IDX2254.

SSL Peer Name:

For SSL, a distinguished name skeleton that must match the name provided by the WebSphere MQ queue
manager. The distinguished name is used to check the identifying certificate presented by the server at
connect-time.

The SSL Peer Name property is ignored if SSL Cipher Suite property is not specified.

This property is a list of attribute name and value pairs separated by commas or semicolons. For example:
CN=QMGR.*, OU=IBM, OU=WEBSPHERE

The example given checks the identifying certificate presented by the server at connect-time. For the
connection to succeed, the certificate must have a Common Name beginning QMGR., and must have at
least two Organizational Unit names, the first of which is IBM and the second WEBSPHERE. Checking is
not case-sensitive.

For more details about distinguished names and their use with WebSphere MQ, see the WebSphere MQ
Security book; for example, the section “Distinguished Names” at
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas010p.htm#HDRDCDN.

Temporary queue prefix:

The prefix that is used for names of temporary JMS queues created by applications that use this
connection factory.

Data type String

Default Null

Chapter 8. Developing WebSphere applications 1483

Use connection pooling:

Whether or not to use WebSphere MQ connection pooling.

Data type Checkbox

Default Selected
Range
Selected Cleared
The connection factory uses The connection factory does
WebSphere MQ connection not use WebSphere MQ
pooling. When a connection connection pooling. When a
is no longer required, instead connection is no longer
of destroying it, it can be required, it is destroyed. To
pooled, and later reused. use the same queue
This can provide a manager a new connection is
substantial performance created.
enhancement for repeated
connections to the same
queue manager.

Connection pool:

An optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Session pool:

An optional set of session pool settings.

This link provides a panel of optional connection pool properties, common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

WebSphere MQ topic connection factory collection:

The topic connection factories configured in the WebSphere MQ messaging provider for publish/subscribe
messaging with JMS topics.

This panel shows a list of the WebSphere MQ topic connection factories with a summary of their
configuration properties.

To view this administrative console page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.

1484 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Topic Connection Factory.
This displays a list of any existing queue connection factories.

To view or change the properties of a connection factory, click its name in the list displayed.

To act on one or more of the connection factories listed, select the check boxes next to the names of the
objects that you want to act on, then use the buttons provided.

WebSphere MQ topic connection factory settings:

Use this panel to view or change the configuration properties of the selected topic connection factory for
use with the WebSphere MQ as a JMS provider. These configuration properties control how connections
are created to the associated JMS topic destination.

A WebSphere MQ topic connection factory is used to create JMS connections to topic destinations
provided by WebSphere MQ for publish/subscribe messaging.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Topic Connection Factories.
This displays a list of any existing JMS topic connection factories.
4. Click the name of the JMS connection factory that you want to work with.

A WebSphere MQ topic connection factory has the following properties.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ for JMS resources. For more information about configuring WebSphere MQ for
JMS resources, see the WebSphere MQ Using Java book.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.
v For more information about setting the SSL properties for WebSphere MQ, see the section SSL
properties in the WebSphere MQ Using Java book.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

Chapter 8. Developing WebSphere applications 1485

The name by which this topic connection factory is known for administrative purposes within IBM
WebSphere Application Server.

Data type String

JNDI name:

The JNDI name that is used to bind the topic connection factory into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of this topic connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

Category:

A category used to classify or group this topic connection factory, for your IBM WebSphere Application
Server administrative records.

Data type String

Component-managed authentication alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
application-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Restriction:
1. User IDs longer than 12 characters cannot be used for authentication with WebSphere
MQ. For example, the default Windows user ID, Administrator, is not valid because it
contains 13 characters. Therefore, an authentication alias for a WebSphere MQ queue
connection factory must specify a user ID no longer than 12 characters.

1486 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 2. If you want to use Bindings transport mode on JMS queue connections to WebSphere
MQ, you set the Transport type property to BINDINGS on the WebSphere MQ Queue
Connection Factory. You must also choose one of the following options:
v To use security credentials, ensure that the user specified is the currently logged on
user for the WebSphere Application Server process. If the user specified is not the
current logged on user for the WebSphere Application Server process, then the
WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid
security authentication supplied for MQQueueManager.
v Do not specify security credentials. On the WebSphere MQ Connection Factory,
ensure that both the Component-managed Authentication Alias and the
Container-managed Authentication Alias properties are not set.

Container-managed authentication alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
container-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Restriction:
1. User IDs longer than 12 characters cannot be used for authentication with WebSphere
MQ. For example, the default Windows user ID, Administrator, is not valid because it
contains 13 characters. Therefore, an authentication alias for a WebSphere MQ queue
connection factory must specify a user ID no longer than 12 characters.
2. If you want to use Bindings transport mode on JMS queue connections to WebSphere
MQ, you set the Transport type property to BINDINGS on the WebSphere MQ Queue
Connection Factory. You must also choose one of the following options:
v To use security credentials, ensure that the user specified is the currently logged on
user for the WebSphere Application Server process. If the user specified is not the
current logged on user for the WebSphere Application Server process, then the
WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid
security authentication supplied for MQQueueManager.
v Do not specify security credentials. On the WebSphere MQ Connection Factory,
ensure that both the Component-managed Authentication Alias and the
Container-managed Authentication Alias properties are not set.

Mapping-configuration alias:

The module used to map authentication aliases.

This field provides a list of the modules that have been configured on the Security → JAAS Configuration
→ Application Logins Configuration property. For more information about the mapping configurations,
see Java Authentication and Authorization service configuration entry settings.

Data type Enum

Default Null

Chapter 8. Developing WebSphere applications 1487

Range ClientContainer
The client container maps authentication aliases.
WSLogin
The WSLogin module maps authentication aliases.
DefaultPrincipalMapping
The JAAS configuration maps an authentication alias to its userid
and password.

Host:

The name of the host on which the WebSphere MQ queue manager runs, for client connection only.

Data type String

Default Null
Range A valid TCP/IP hostname

Port:

The TCP/IP port number used for connection to the WebSphere MQ queue manager, for client connection
only.

This port must be configured on the WebSphere MQ queue manager.

Data type Integer

Default Null
Range A valid TCP/IP port number, configured on the WebSphere MQ queue
manager.

Transport type:

Specifies whether to use the WebSphere MQ client connection or JNI bindings for connection to the
WebSphere MQ queue manager. WebSphere MQ as the JMS provider controls the communication
protocols between JMS clients and JMS servers. Tune the transport type when you are using non-ASF
nonpersistent, non-durable, non-transactional messaging or when you want to satisfy security issues and
the client is local to the queue manager node.

Data type Enum

Units Not applicable
Default BINDINGS

1488 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range BINDINGS
JNI bindings are used to connect to the queue manager. BINDINGS
is a shared memory protocol and can only be used when the queue
manager is on the same node as the JMS client and comes at some
security risks that should be addressed through the use of EJB roles.
CLIENT
WebSphere MQ client connection is used to connect to the queue
manager. CLIENT is a typical TCP-based protocol.
DIRECT
For a WebSphere MQ message broker using DIRECT mode.
DIRECT is a lightweight sockets protocol used in non-transactional,
non-durable and non-persistent Publish/Subscribe messaging.
DIRECT works only for clients and message-driven beans using the
non-ASF protocol.
The type of connection to the message broker depends on the value
of the PROXYHOSTNAME property, according to the following rules:
v If the PROXYHOSTNAME property is set to the empty string, a
direct connection is made to the broker identified by the
HOSTNAME and PORT.
v If the PROXYHOSTNAME property is set to a value other than the
empty string, a direct connection is made to the broker through
the proxy server identified by this property and the PROXYPORT
property.

Recommended DIRECT is the fastest transport type and should be used where possible. Use
BINDINGS when you want to satisfy additional security tasks and the queue
manager is local to the JMS client. QUEUED is fallback for all other cases.
Note: WebSphere MQ 5.3 before CSD2 with the DIRECT setting can lose
messages when used with message-driven beans and under load. This also
happens with client-side based applications unless the broker’s
maxClientQueueSize is set to 0. You can set this to 0 with the command
#wempschangeproperties WAS_nodeName_server1 -e default -o
DynamicSubscriptionEngine -n maxClientQueueSize -v 0 -x
executionGroupUUID, where executionGroupUUID can be found by starting the
broker and looking in the Event Log/Applications for event 2201. This value is
usually ffffffff-0000-0000-000000000000.

Channel:

The name of the channel used for connection to the WebSphere MQ queue manager, for client connection
only.

Data type String

Default Null
Range 1 through 20 ASCII characters

Queue manager:

The name of the WebSphere MQ queue manager for this connection factory. Connections created by this
factory connect to that queue manager.

Data type String

Default Null
Range A valid WebSphere MQ queue manager name, as 1 through 48 ASCII
characters

Chapter 8. Developing WebSphere applications 1489

Broker control queue:

The name of the publish/subscribe broker’s control queue, to which publisher and subscriber applications
send all command messages (except publications and requests to delete publications).

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker queue manager:

The name of the WebSphere MQ queue manager that provides the publish/subscribe message broker.

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker publication queue:

The name of the broker’s input queue (stream queue) that receives all publication messages for the
default stream. Applications can also send requests to delete publications on the default stream to this
queue.

Data type String

Units En_US ASCII characters
Default Null
Range 1 through 48 ASCII characters

Broker subscription queue:

The name of the broker’s queue from which non-durable subscription messages are retrieved. The
subscriber specifies the name of the queue when it registers a subscription.

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker CC subscription queue:

The name of the broker’s queue from which non-durable subscription messages are retrieved for a
ConnectionConsumer. This property applies only for use of the Web container.

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker version:

Whether the message broker is provided by the WebSphere MQ MA0C Supportpac or newer versions of
WebSphere message broker products.

Data type Enum

Default Advanced

1490 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range Advanced
The message broker is provided by newer versions of WebSphere
message broker products, such as WebSphere Business Integration
Message Broker and Event Broker.
Basic The message broker is provided by the WebSphere MQ MA0C
SupportPac (MQSeries - Publish/Subscribe) or MQSI working in
MA0C compatibility mode.

Model queue definition:

The name of the model queue definition that the broker can use to create dynamic queues for non-default
streams if the stream queue does not already exist

The name of the model queue definition that the broker can use to create dynamic queues to receive
publications for streams other than the default stream. This is only used if the stream queue does not
already exist. If this model queue definition does not exist, all stream queues must be defined by the
administrator.

Data type String

Default Null
Range 1 through 48 ASCII characters

Enable clone support:

Select this check box to enable clone support to allow the same durable subscription across topic clones.

Data type Check box

Default Cleared
Range Selected
Clone support is enabled.
Cleared
Clone support is disabled.

If you select this property, you must also specify a value for the Client ID property.

Client ID:

The JMS client identifier used for connections to WebSphere MQ.

Data type String

Range A valid JMS client ID, as ASCII characters

CCSID:

The coded character set identifier for use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

Data type String

Units Integer
Default Null
Range 1 through 65535

Chapter 8. Developing WebSphere applications 1491

For more information about supported CCSIDs, and about converting between message data from one
coded character set to another, see the WebSphere MQ System Administration and the WebSphere MQ
Application Programming Reference books. These are available from the WebSphere MQ messaging
multiplatform and platform-specific books Web pages; for example, at http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications Center, or
from the WebSphere MQ collection kit, SK2T-0730.

XA Enabled:

Specifies whether the connection factory is for XA or non-XA coordination of messages and controls if the
application server uses XA. Enable XA if multiple resources are not used in the same transaction.

If you clear this property (non-XA), the JMS session is still enlisted in a transaction, but uses the resource
manager local transaction calls (session.commit and session.rollback) instead of XA calls. This can lead to
an improvement in performance. However, this means that only a single resource can be enlisted in a
transaction in WebSphere Application Server.

Last participant support enables you to enlist one non-XA resource with other XA-capable resources.

Data type Checkbox

Default Selected
Range Selected
The connection factory is for XA-coordination of messages
Cleared
The connection factory is for non-XA coordination of messages
Recommended Do not select to enable XA when the message queue received is the only
resource in the transaction. Enable XA if transactions involve other resources,
including other queues or topics.

Publish/subscribe cleanup level:

The level of cleanup provided by the Publish/subscribe cleanup utility

To avoid the problems associated with non-graceful closure of subscriber objects, WebSphere MQ as a
JMS provider provides a Publish/Subscribe cleanup utility that attempts to detect any earlier JMS
publish/subscribe problems. If a large number of problems are detected, some performance degradation
may be observed while resources are cleaned up. This utility runs transparently on a background thread
and should not affect other WebSphere MQ operations.

Data type Enum

Default SAFE

1492 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range
SAFE The Cleanup thread attempts to remove unconsumed subscription
messages, or temporary queues, for failed subscriptions. This mode
of cleanup does not interfere with the operation of other JMS
applications.
ASPROP
The style of cleanup to use is determined by the system property
com.ibm.mq.jms.cleanup, which is queried at JVM startup. This
property can be set on the java command-line using the -D option,
and should be set to NONE, SAFE or STRONG. Any other value
causes an exception. If not set, the property defaults to SAFE. This
allows easy JVM-wide change to the Cleanup level without needing
to update every topic connection factory used by the system.
NONE In this special mode, no cleanup is performed; and no cleanup
thread exists. Additionally, if the application is using the single-queue
approach, unconsumed messages can be left on the queue.
This option can be useful if the application is distant from the queue
manager, and especially if it only publishes rather than subscribes.
However, some application should perform cleanup on the queue
manager to deal with any unconsumed messages - this could be a
JMS application with CLEANUP(SAFE) or CLEANUP(STRONG), or
the WebSphere MQ manual cleanup utility.
STRONG
The cleanup thread performs as CLEANUP(SAFE), but also clears
the SYSTEM.JMS.REPORT.QUEUE of any unrecognized messages.

Publish/subscribe cleanup interval:

The interval, in milliseconds, between background executions of the publish/subscribe cleanup utility.

Data type Integer

Default 60000
Range 1 through 2147483647

Message selection:

Whether message selection is done at the broker or client.

Data type Enum

Default BROKER
Range
BROKER
Message selection is done at the broker.
CLIENT
Message selection is done at the client.

Publish acknowledgement interval:

The interval, in number of messages, between publish requests that require acknowledgement from the
broker.

Data type Integer

Default 25
Range 1 through 2147483647

Chapter 8. Developing WebSphere applications 1493

Enable sparse subscriptions:

Select this option to support subscriptions that receive infrequent matching messages.

Data type Checkbox

Default Cleared
Range
Selected
Subscriptions can receive infrequent matching messages. This value
requires that the subscription queue can be opened for browse.
Cleared
Sparse subscriptions are not supported. Subscriptions receive
frequent matching messages.

Publish/subscribe status interval:

The interval, in milliseconds, between transactions to refresh publish/subscribe status.

Data type Integer

Default 60000
Range 1 through 2147483647

Persistent subscriptions store:

Where WebSphere MQ stores persistent data relating to active JMS subscriptions.

Data type Enum

Default MIGRATE
Range
MIGRATE
This option dynamically selects the queue-based or broker-based
subscription store based on the levels of queue manager and
publish/subscribe broker installed. If both queue manager and broker
are capable of supporting SUBSTORE(BROKER), this behaves as
SUBSTORE(BROKER); otherwise it behaves as
SUBSTORE(QUEUE). Additionally, SUBSTORE(MIGRATE) transfers
durable subscription information from the queue-based subscription
store to the broker-based store.
QUEUE
Subscription information is stored on SYSTEM.JMS.ADMIN.QUEUE
and SYSTEM.JMS.PS.STATUS.QUEUE on the local queue manager.
BROKER
Subscription information is stored by the publish/subscribe broker
used by the application. This option requires recent levels of queue
manager and publish/subscribe broker. This subscription store
requires recent levels of both queue manager and publish/subscribe
broker. It is designed to provide improved resilience.

Enable multicast transport:

Whether or not this connection factory uses multicast transport.

With multicast, messages are delivered to all consumers. This is useful in environments where there are a
large number of clients that all want to receive the same messages, because with multicast only one copy
of each message is sent. Multicast reduces the total amount of network traffic. Reliable multicast is
standard multicast with a reliability layer added.

1494 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Enum
Default NOTUSED
Range
NOTUSED
This connection factory does not use multicast transport.
ENABLED
This connection factory uses multicast transport, but does not
provide a reliable multicast connection.
ENABLED_IF_AVAILABLE
This connection factory uses multicast transport if the message
broker supports it.
ENABLED_RELIABLE
This connection factory uses reliable multicast transport
ENABLED_RELIABLE_IF_AVAILABLE
This connection factory uses reliable multicast transport if the
message broker supports it.

Direct broker authentication:

Whether the broker uses basic or certificate-based authentication for direct connections.

This property selects the authentication on a direct connections (if the TRANSPORT property is set to
DIRECT).

Data type Enum

Default NONE
Range
NONE Direct broker authentication is not used.
PASSWORD
Password-based authentication is used for direct connections.
Authentication is performed based on a user ID and password
provided by an authentication alias. The authentication alias used is
obtained from one of the following properties:
v Component-managed Authentication Alias, for
application-managed authentication.
v Container-managed Authentication Alias, for container-managed
authentication.
CERTIFICATE
Certificate-based authentication is used for direct connections. The
SSLPEERNAME and SSLCRL properties are used to perform the
authentication checks.
You can use certificate-based authentication when connecting
directly to a WebSphere Business Integration Event Broker or
WebSphere Business Integration Message Broker broker.

Proxy host name:

Host name of the Web Scale proxy host.

A direct connection is made to the proxy server, which forwards the connection request to the message
broker.

If the TRANSPORT property is set to DIRECT, the type of connection to the message broker depends on
the value of this property, according to the following rules:

Chapter 8. Developing WebSphere applications 1495

v If this property is set to the empty string, a direct connection is made to the broker identified by the
HOSTNAME and PORT.
v If this property is set to a value other than the empty string, a direct connection is made to the broker
through the proxy server identified by this property and the PROXYPORT property.

Data type String

Default Null

Proxy port:

Port number of the Web Scale proxy port.

A direct connection is made to this port on the proxy server identified by the PROXYHOSTNAME property,
which forwards the connection request to the message broker. For more information, see the description of
the PROXYHOSTNAME property.

Data type Integer

Default 0

Enable return methods during shutdown:

Whether or not applications return from a method call if the queue manager has entered a controlled
shutdown.

Data type Checkbox

Default Selected
Range Selected
Applications return from a method call if the
queue manager has entered a controlled
shutdown.
Cleared
Applications do not return from a method call if
the queue manager has entered a controlled
shutdown.

Local server address:

The range of local ports to be used when making a connection to a WebSphere MQ queue manager

If a JMS application attempts to connect to a WebSphere MQ queue manager in client mode, a firewall
might allow only those connections that originate from specified ports or a range of ports. In this situation,
you can use this property to specify a port, or a range of points, that the application can bind to.

Data type String

Default Null

1496 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range A string in the format:
[ip-addr][(low-port[,high-port])]

For example:
v 9.20.4.98
The channel binds to address 9.20.4.98 locally
v 9.20.4.98(1000)
The channel binds to address 9.20.4.98 locally and uses port 1000
v 9.20.4.98(1000,2000)
The channel binds to address 9.20.4.98 locally and uses a port in the
range 1000 to 2000
v (1000)
The channel binds to port 1000 locally
v (1000,2000)
The channel binds to a port in the range 1000 to 2000 locally

You can specify a host name instead of an IP address.

For direct connections, this property applies only when multicast is used and
the value of the property must not contain a port number. If it does contain a
port number, the connection is rejected. Therefore, the only valid values of the
property are null, an IP address, or a host name.

Polling interval:

The interval, in milliseconds, between scans of all receivers during asynchronous message delivery

Data type Integer

Units milliseconds
Default 5000
Range 1 through 2147483647

Rescan interval:

The interval in milliseconds between which a topic is scanned to look for messages that have been added
to a topic out of order.

This interval controls the scanning for messages that have been added to a topic out of order with respect
to a WebSphere MQ browse cursor.

Data type Integer

Units milliseconds
Default 5000
Range 1 through 2147483647

SSL cipher suite:

The cipher suite to use for SSL connection to WebSphere MQ.

Set this property to a valid cipher suite provided by your JSSE provider; it must match the CipherSpec
named on the SVRCONN channel named by the Channel property.

You must set this property if the SSL Peer Name property is to be set.

Chapter 8. Developing WebSphere applications 1497

SSL CRL:

A list of zero or more Certificate Revocation List (CRL) servers used to check for SSL certificate
revocation. (Use of this property requires a WebSphere MQ JVM at Java 2 version 1.4.)

The value is a space-delimited list of entries of the form:

ldap://hostname:[port]

optionally followed by a single / (forward slash). If port is omitted, the default LDAP port of 389 is
assumed. At connect-time, the SSL certificate presented by the server is checked against the specified
CRL servers. For more information about CRL security, see the section “Working with Certificate
Revocation Lists” in the WebSphere MQ Security book; for example at:
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas012w.htm#IDX2254.

SSL peer name:

For SSL, a distinguished name skeleton that must match the name provided by the WebSphere MQ queue
manager. The distinguished name is used to check the identifying certificate presented by the server at
connect-time.

The SSL Peer Name property is ignored if SSL Cipher Suite property is not specified.

This property is a list of attribute name and value pairs separated by commas or semicolons. For example:
CN=QMGR.*, OU=IBM, OU=WEBSPHERE

The example given checks the identifying certificate presented by the server at connect-time. For the
connection to succeed, the certificate must have a Common Name beginning QMGR., and must have at
least two Organizational Unit names, the first of which is IBM and the second WEBSPHERE. Checking is
not case-sensitive.

For more details about distinguished names and their use with WebSphere MQ, see the WebSphere MQ
Security book; for example, the section “Distinguished Names” at
http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas010p.htm#HDRDCDN.

Enable MQ Connection Pooling:

Whether or not to use WebSphere MQ connection pooling.

Data type Checkbox

Default Selected
Range
Selected Cleared
The connection factory uses WebSphere MQ The connection
connection pooling. When a connection is no factory does not
longer required, instead of destroying it, it can use WebSphere
be pooled, and later reused. This can provide a MQ connection
substantial performance enhancement for pooling. When a
repeated connections to the same queue connection is no
manager. longer required, it is
destroyed. To use
the same queue
manager a new
connection is
created.

Connection pool:

1498 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Session pools:

An optional set of session pool settings.

This link provides a panel of optional connection pool properties, common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance.
This is independent from any WebSphere MQ connection pooling. You need to configure the connection
and session pool properties appropriately for your applications, otherwise you may not get the connection
and session behavior that you want.

WebSphere MQ queue destination collection:

The queue destinations configured in the WebSphere MQ messaging provider for point-to-point messaging
with JMS queues.

This panel shows a list of the WebSphere MQ queue destinations with a summary of their configuration
properties.

To view this administrative console page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Queue Destinations. This
displays a list of any existing JMS queue destinations.

To create a new queue destination, click New.

To browse or change the properties of a queue destination, select its name in the list displayed.

To act on one or more of the queue destinations listed, click the check box next to the name of the queue,
then use the buttons provided.

WebSphere MQ queue settings:

Use this panel to browse or change the configuration properties of the selected JMS queue destination for
point-to-point messaging with WebSphere MQ as a messaging provider.

A WebSphere MQ queue destination is used to configure the properties of a JMS queue. Connections to
the queue are created by the associated JMS queue connection factory for WebSphere MQ as a
messaging provider.

To view this page, use the administrative console to complete the following steps:

Chapter 8. Developing WebSphere applications 1499

1. In the navigation pane, expand Resources → Messaging Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Queue Destinations. This
displays a list of any existing JMS queue destinations.
4. Click the name of the JMS queue destination that you want to work with.

A queue for use with the WebSphere MQ JMS provider has the following properties.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ for JMS resources. For more information about configuring WebSphere MQ for
JMS resources, see the WebSphere MQ Using Java book.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which the queue is known for administrative purposes within IBM WebSphere Application
Server.

Data type String

JNDI name:

The JNDI name that is used to bind the queue into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of the queue, for administrative purposes

1500 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type String
Default Null

Category:

A category used to classify or group this queue, for your IBM WebSphere Application Server administrative
records.

Data type String

Persistence:

Whether all messages sent to the destination are persistent, non-persistent, or have their persistence
defined by the application

Data type Enum

Default Application defined
Range Application defined
Messages on the destination have their
persistence defined by the application that put
them onto the queue.
Queue defined
Messages on the destination have their
persistence defined by the WebSphere MQ
queue definition properties.
Persistent
Messages on the destination are persistent.
Non persistent
Messages on the destination are not persistent.

Priority:

Whether the message priority for this destination is defined by the application or the Specified priority
property

Data type Enum

Default Application defined
Range Application defined
The priority of messages on this destination is
defined by the application that put them onto the
destination.
Queue defined
Messages on the destination have their
persistence defined by the WebSphere MQ
destination definition properties.
Specified
The priority of messages on this destination is
defined by the Specified priority property.If you
select this option, you must define a priority you
must define a priority on the Specified Priority
property.

Specified priority:

Chapter 8. Developing WebSphere applications 1501

If the Priority property is set to Specified, type here the message priority for this destination, in the range
0 (lowest) through 9 (highest)

Data type Integer

Units Message priority level
Default 0
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Whether the expiry timeout for this destination is defined by the application or the Specified Expiry
property, or messages on the destination never expire (have an unlimited expiry timeout)

Data type Enum

Default APPLICATION DEFINED
Range APPLICATION DEFINED
The expiry timeout for messages on this
destination is defined by the application that put
them onto the destination.
SPECIFIED
The expiry timeout for messages on this
destination is defined by the Specified Expiry
property.If you select this option, you must define
a timeout on the Specified Expiry property.
UNLIMITED
Messages on this destination have no expiry
timeout, so those messages never expire.

Specified expiry:

If the Expiry Timeout property is set to Specified, type here the number of milliseconds (greater than 0)
after which messages on this destination expire.

Data type Integer

Units Milliseconds
Default 0
Range Greater than or equal to 0
v 0 indicates that messages never timeout
v Other values are an integer number of milliseconds

Base queue name:

The name of the queue to which messages are sent, on the queue manager specified by the Base Queue
Manager Name property.

Data type String

Default Null
Range 1 through 48 ASCII characters

Base queue manager name:

The name of the WebSphere MQ queue manager to which messages are sent

1502 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
This queue manager provides the queue specified by the Base Queue Name property.

Data type String

Units En_US ASCII characters
Default Null
Range A valid WebSphere MQ Queue Manager name, as 1
through 48 ASCII characters

CCSID:

The coded character set identifier for use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

Data type String

Units Integer
Default Null
Range 1 through 65535

For more information about supported CCSIDs, and about converting between message data from one
coded character set to another, see the WebSphere MQ System Administration and the WebSphere MQ
Application Programming Reference books. These are available from the WebSphere MQ messaging
multiplatform and platform-specific books Web pages; for example, at
http://www.ibm.com/software/ts/mqseries/library/ manualsa/manuals/platspecific.html, the IBM Publications
Center, or from the WebSphere MQ collection kit, SK2T-0730.

Use native encoding:

Whether or not the destination should use native encoding (appropriate encoding values for the Java
platform).

Data type Check box

Default Cleared
Range Cleared
Native encoding is not used, so specify the
properties below for integer, decimal, and floating
point encoding.
Selected
Native encoding is used (to provide appropriate
encoding values for the Java platform).

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Integer encoding:

If native encoding is not enabled, select whether integer encoding is normal or reversed.

Data type Enum

Default NORMAL

Chapter 8. Developing WebSphere applications 1503

Range NORMAL
Normal integer encoding is used.
REVERSED
Reversed integer encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Decimal encoding:

If native encoding is not enabled, select whether decimal encoding is normal or reversed.

Data type Enum

Units Not applicable
Default NORMAL
Range NORMAL
Normal decimal encoding is used.
REVERSED
Reversed decimal encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Floating point encoding:

If native encoding is not enabled, select the type of floating point encoding.

Data type Enum

Default IEEENORMAL
Range IEEENORMAL
IEEE normal floating point encoding is used.
IEEEREVERSED
IEEE reversed floating point encoding is used.
S390 S390 floating point encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Target client:

Whether the receiving application is JMS-compliant or is a traditional WebSphere MQ application

Data type Enum

Default JMS
Range JMS The target is a JMS-compliant application.
MQ The target is a non-JMS, traditional WebSphere
MQ application.

Queue manager host:

The name of host for the queue manager on which the queue destination is created.

Data type String

Default Null
Range A valid TCP/IP hostname

1504 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Queue manager port:

The number of the port used by the queue manager on which this queue is defined.

Data type String

Units A valid TCP/IP port number.
Default Null
Range A valid TCP/IP port number. This port must be configured
on the WebSphere MQ queue manager.

Server connection channel name:

The name of the channel used for connection to the WebSphere MQ queue manager.

Data type String

Default Null
Range 1 through 20 ASCII characters

User name:

The user ID used, with the Password property, for authentication when connecting to the queue manager
to define the queue destination.

If you specify a value for the User name property, you must also specify a value for the Password
property.

Data type String

Default Null

Password:

The password, used with the User name property, for authentication when connecting to the queue
manager to define the queue destination.

If you specify a value for the User name property, you must also specify a value for the Password
property.

Data type String

Default Null

WebSphere MQ queue settings (MQ Config):

Use this panel to browse or change the configuration properties defined to WebSphere MQ for the
selected queue destination.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Queue Destinations. This
displays a list of any existing JMS queue destinations.
4. Click the name of the JMS queue destination that you want to work with.
5. Under Additional Resources, click MQ Config.

Chapter 8. Developing WebSphere applications 1505

A WebSphere MQ queue destination is used to configure the properties of a JMS queue. A queue for use
with the WebSphere MQ JMS provider has the following extra properties defined to WebSphere MQ.

Notes

Note:
v To be able to browse or change these MQ Config properties, the WebSphere MQ Queue
Manager on which the queue resides must be configured for remote administration and be
running. You must also have installed the WebSphere MQ client. If you have not done this, the
administrative console displays messages like the following:
The WMQQueueDefiner MBean has encountered an error.
WMSG0331E: The MQ Client is required for this functionality, but it is not installed.
v These MQ Config properties can be used only to view or change the properties of local queues.
You cannot use MQ Config to administer alias or remote queues.
v Some properties displayed are read-only and cannot be changed.
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ JMS resources. For more information about configuring WebSphere MQ JMS
resources, see the WebSphere MQ: Using Java book; for example from the WebSphere MQ
multiplatform library Web page at
http://www.ibm.com/software/ts/mqseries/library/manualsa/manuals/crosslatest.html.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.

Base Queue Name:

The name of the local queue to which messages are sent, on the queue manager specified by the Base
Queue Manager Name property.

Data type String

Base Queue Manager Name:

The name of the WebSphere MQ queue manager to which messages are sent.

This queue manager provides the queue specified by the Base Queue Name property.

Data type String

Queue Manager Host:

The name of host for the queue manager on which the queue destination is created.

Data type String

Queue Manager Port:

The number of the port used by the queue manager on which this queue is defined.

Data type Integer

Range A valid TCP/IP port number. This port must be configured
on the WebSphere MQ queue manager.

Server Connection Channel Name:

1506 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The name of the channel used for connection to the WebSphere MQ queue manager.

Data type String

Range 1 through 20 ASCII characters

User ID:

The user ID used, with the Password property, for authentication when connecting to the queue manager
to define the queue destination.

If you specify a value for the User ID property, you must also specify a value for the Password property.

Data type String

Password:

The password, used with the User ID property, for authentication when connecting to the queue manager
to define the queue destination.

If you specify a value for the User ID property, you must also specify a value for the Password property.

Data type String

Description:

The WebSphere MQ queue description, for administrative purposes within WebSphere MQ.

Data type String

Default Null
Range 1 through 64 ASCII characters.

Inhibit Put:

Whether or not put operations are allowed for this queue.

Data type Enum

Default Put Inhibited
Range Put Allowed
Put operations are allowed for this queue.
Put Inhibited
Put operations are not allowed for this queue.

Persistence:

Whether messages on the queue are persistent or non-persistent.

Data type Enum

Default Persistent
Range Persistent
Messages on the queue are persistent.
Non persistent
Messages on the queue are not persistent.

Chapter 8. Developing WebSphere applications 1507

Cluster Name:

The name of the cluster to which the WebSphere MQ queue manager belongs.

If you specify a value for Cluster Name, you should not specify a value for Cluster Name List. Cluster
names must conform to the rules described in the WebSphere MQ MQSC Command Reference book.

Data type String

Default Null
Range A valid WebSphere MQ name for a queue manager
cluster, as 1 through 48 ASCII characters

Cluster Name List:

The name of the cluster namelist to which the WebSphere MQ queue manager belongs.

If you specify a value for Cluster Name, you should not specify a value for Cluster Name List. Cluster
names must conform to the rules described in the WebSphere MQ MQSC Command Reference book.

Data type String

Default Null
Range A valid WebSphere MQ name for a list of queue manager
clusters, as 1 through 48 ASCII characters

Default Binding:

The default binding to be used when the queue is defined as a cluster queue.

Data type Enum

Default On Open
Range On Open
The queue handle is bound to a specific instance
of the cluster queue when the queue is opened.
Not Fixed
The queue handle is not bound to any particular
instance of the cluster queue. This allows the
queue manager to select a specific queue
instance when the message is put, and to
change that selection subsequently should the
need arise.

Inhibit Get:

Whether or not get operations are allowed for this queue.

Data type Enum

Default Get Inhibited
Range Get Inhibited
Get operations are not allowed for this queue.
Get Allowed
Get operations are allowed for this queue.

Maximum Queue Depth:

The maximum number of messages allowed on the queue.

1508 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Integer
Units Number of messages
Default 0
Range A value greater than or equal to zero, and less than or
equal to 640 000.

For more information about the maximum value allowed,

see the WebSphere MQ MQSC Command Reference.

If this value is reduced, any messages that are already on

the queue are not affected, even if the number of
messages exceeds the new maximum.

Maximum Message Length:

The maximum length, in bytes, of messages on this queue.

Data type Integer

Units Number of bytes
Default 0
Range A value greater than or equal to zero, and less than or
equal to the maximum message length for the queue
manager and WebSphere MQ platform. For more
information about the maximum value allowed, see the
WebSphere MQ MQSC Command Reference.

If this value is reduced, any message that is already on

the queue are not affected, even if the message length
exceeds the new maximum.

Shareability:

Whether multiple applications can get messages from this queue.

Data type Enum

Default Shareable
Range Shareable
More than one application instance can get
messages from the queue.
Not Shareable
Only one application instance can get messages
from the queue.

Input Open Option:

The default share option for applications opening this queue for input

Data type Enum

Default Exclusive
Range Exclusive
The open request is for exclusive input from the
queue.
Shared
The open request is for shared input from the
queue.

Chapter 8. Developing WebSphere applications 1509

Message Delivery Sequence:

The order in which messages are delivered from the queue in response to get requests.

Data type Enum

Default FIFO
Range FIFO Messages are delivered in first in first out (FIFO)
order. Priority is ignored for messages on this
queue.
Priority
Messages are delivered in first-in-first-out (FIFO)
order within priority. This is the default supplied
with WebSphere MQ, but your installation might
have changed it.

Backout Threshold:

The maximum number of times that a message can be backed out. If this threshold is reached, the
message is requeued on the backout queue specified by the Backout Requeue Name property.

The WebSphere MQ queue manager keeps a record of the number of times that each message has been
backed out. When this number reaches a configurable threshold, the connection consumer requeues the
message on a named backout queue. If this requeue fails for any reason, the message is removed from
the queue and either requeued to the dead-letter queue, or discarded.

Data type Integer

Default 0
Range 0 Never requeue messages
1 or more
The number of times that a message has been
backed, at which the message is requeued on a
named backout queue.

Backout Requeue Name:

The name of the backout queue to which messages are requeued if they have been backed out more than
the backout threshold.

The WebSphere MQ queue manager keeps a record of the number of times that each message has been
backed out. When this number reaches a configurable threshold, the connection consumer requeues the
message on a named backout queue. If this requeue fails for any reason, the message is removed from
the queue and either requeued to the dead-letter queue, or discarded.

Data type String

Default Null
Range 1 through 48 characters.

Harden Get Backout:

Whether hardening should be used to ensure that the count of the number of times that a message has
been backed out is accurate.

Data type Enum

Default Hardened

1510 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range Hardened
The count is hardened.
Not Hardened
The count is not hardened. This is the default
supplied with WebSphere MQ, but your
installation might have changed it.

Default Priority:

The default message priority for this destination, used if no priority is provided with a message.

Data type Integer

Default 0
Range 0 (lowest priority) through 9 (highest priority)

WebSphere MQ topic destination collection:

The JMS topic destinations configured in the WebSphere MQ messaging provider for point-to-point
messaging with JMS topics. Use this panel to create or delete topic destinations, or to select a topic
destination to view or change its configuration properties.

This panel shows a list of JMS topic destinations with a summary of their configuration properties.

To view this administrative console page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Topic Destinations. This
displays a list of any existing JMS topic destinations.

To create a new topic destination, click New.

To view or change the properties of a topic destination, select its name in the list displayed.

To act on one or more of the topic destinations listed, click the check box next to the name of the topic,
then use the buttons provided.

WebSphere MQ topic settings:

Use this panel to browse or change the configuration properties of the selected JMS topic destination for
publish/subscribe messaging with WebSphere MQ as a messaging provider.

A WebSphere MQ topic destination is used to configure the properties of a JMS topic for WebSphere MQ
as a messaging provider. Connections to the topic are created by the associated topic connection factory.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → WebSphere MQ.
2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the
scope is set to node or server scope for a Version 5 node, the administrative console presents the
subset of resources and properties that are applicable to WebSphere Application Server Version 5.
3. In the content pane, under Additional Resources, click WebSphere MQ Topic Destinations. This
displays a list of any existing JMS topic destinations.
4. Click the name of the JMS topic destination that you want to work with.

Chapter 8. Developing WebSphere applications 1511

A WebSphere MQ topic has the following properties.

Note:
v The property values that you specify must match the values that you specified when configuring
WebSphere MQ for JMS resources. For more information about configuring WebSphere MQ for
JMS resources, see the WebSphere MQ Using Java book.
v In WebSphere MQ, names can have a maximum of 48 characters, with the exception of
channels which have a maximum of 20 characters.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which the topic is known for administrative purposes within IBM WebSphere Application
Server.

Data type String

JNDI name:

The JNDI name that is used to bind the topic into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of the topic, for administrative purposes within IBM WebSphere Application Server.

Data type String

Default Null

Category:

A category used to classify or group this topic, for your IBM WebSphere Application Server administrative
records.

1512 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type String

Persistence:

Whether all messages sent to the destination are persistent, non-persistent, or have their persistence
defined by the application

Data type Enum

Default APPLICATION DEFINED
Range APPLICATION DEFINED
Messages on the destination have their
persistence defined by the application that put
them onto the destination.
QUEUE DEFINED
Messages on the destination have their
persistence defined by the WebSphere MQ
destination definition properties.
PERSISTENT
Messages on the destination are persistent.
NON PERSISTENT
Messages on the destination are not persistent.

Priority:

Whether the message priority for this destination is defined by the application or the Specified Priority
property

Data type Enum

Default APPLICATION DEFINED
Range APPLICATION DEFINED
The priority of messages on this destination is
defined by the application that put them onto the
destination.
QUEUE DEFINED
Messages on the destination have their
persistence defined by the WebSphere MQ
queue definition properties.
SPECIFIED
The priority of messages on this destination is
defined by the Specified Priority property. If you
select this option, you must define a priority on
the Specified Priority property.

Specified priority:

If the Priority property is set to Specified, type here the message priority for this destination, in the range
0 (lowest) through 9 (highest)

Data type Integer

Units Message priority level
Default 0
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Chapter 8. Developing WebSphere applications 1513

Whether the expiry timeout for this destination is defined by the application or the Specified Expiry
property, or messages on the queue never expire (have an unlimited expiry timeout)

Data type Enum

Default APPLICATION DEFINED
Range APPLICATION DEFINED
The expiry timeout for messages on this
destination is defined by the application that put
them onto the destination.
SPECIFIED
The expiry timeout for messages on this
destination is defined by the Specified Expiry
property. If you select this option, you must
define a timeout on the Specified Expiry
property.
UNLIMITED
Messages on this destination have no expiry
timeout, so those messages never expire.

Specified expiry:

If the Expiry Timeout property is set to Specified, type here the number of milliseconds (greater than 0)
after which messages on this destination expire.

Data type Integer

Units Milliseconds
Default 0
Range Greater than or equal to 0
v 0 indicates that messages never timeout
v Other values are an integer number of milliseconds

Base topic name:

The name of the WebSphere MQ topic to which messages are sent.

Data type String

Range Depends on the broker used. For details, see the
documentation for your broker; for example the
WebSphere MQ Event Broker library at
http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/wsmqebv21.html.

CCSID:

The coded character set identifier for use with WebSphere MQ.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

Data type String

Units Integer
Default Null
Range 1 through 65535

For more information about supported CCSIDs, and about converting between message data from one
coded character set to another, see the WebSphere MQ System Administration and the WebSphere MQ

1514 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Application Programming Reference books. These are available from the WebSphere MQ messaging
multiplatform and platform-specific books Web pages; for example, at http://www-
3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications Center, or
from the WebSphere MQ collection kit, SK2T-0730.

Use native encoding:

Whether or not the destination should use native encoding (appropriate encoding values for the Java
platform).

Data type Check box

Units Not applicable
Default Cleared
Range Cleared
Native encoding is not used, so specify the
properties below for integer, decimal, and floating
point encoding.
Selected
Native encoding is used (to provide appropriate
encoding values for the Java platform).

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Integer encoding:

If native encoding is not enabled, select whether integer encoding is normal or reversed.

Data type Enum

Default NORMAL
Range NORMAL
Normal integer encoding is used.
REVERSED
Reversed integer encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Decimal encoding:

If native encoding is not enabled, select whether decimal encoding is normal or reversed.

Data type Enum

Default NORMAL
Range NORMAL
Normal decimal encoding is used.
REVERSED
Reversed decimal encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Floating point encoding:

If native encoding is not enabled, select the type of floating point encoding.

Data type Enum

Chapter 8. Developing WebSphere applications 1515

Default IEEENORMAL
Range IEEENORMAL
IEEE normal floating point encoding is used.
IEEEREVERSED
IEEE reversed floating point encoding is used.
S390 S390 floating point encoding is used.

For more information about encoding properties, see the

WebSphere MQ Using Java document.

Target client:

Whether the receiving application is JMS-compliant or is a traditional WebSphere MQ application

Data type Enum

Default JMS
Range JMS The target is a JMS-compliant application.
MQ The target is a non-JMS, traditional WebSphere
MQ application.

Broker durable subscription queue:

The name of the broker’s queue from which durable subscription messages are retrieved

The subscriber specifies the name of the queue when it registers a subscription.

Data type String

Default Null
Range 1 through 48 ASCII characters

Broker CC durable subscription queue:

The name of the broker’s queue from which durable subscription messages are retrieved for a
ConnectionConsumer. This property applies only for use of the Web container.

Data type String

Default Null
Range 1 through 48 ASCII characters

Enable multicast:

Whether or not this topic destination uses multicast transport.

With multicast, messages are delivered to all consumers. This is useful in environments where there are a
large number of clients that all want to receive the same messages, because with multicast only one copy
of each message is sent. Multicast reduces the total amount of network traffic. Reliable multicast is
standard multicast with a reliability layer added.

Data type Enum

Default NOTUSED

1516 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range
NOTUSED
This destination does not use multicast transport.
ENABLED
This destination uses multicast transport, but
does not provide a reliable multicast connection.
ENABLED_IF_AVAILABLE
This destination uses multicast transport if the
message broker supports it.
ENABLED_RELIABLE
This destination uses reliable multicast transport
ENABLED_RELIABLE_IF_AVAILABLE
This destination uses reliable multicast transport
if the message broker supports it.

Configuring JMS resources for the WebSphere MQ messaging provider

Use the following tasks to configure the connection factories and destinations for the WebSphere MQ JMS
provider.

You only need to complete these tasks if WebSphere Application Server supports enterprise applications
that use JMS resources provided by WebSphere MQ. To enable use of resources provider by WebSphere
MQ, you must have installed and configured WebSphere MQ JMS support, as described in ″Installing and
configuring WebSphere MQ as the JMS provider″ in the information center.

You can use the WebSphere administrative console to configure JMS connections factories, JMS queues,
and JMS topics for WebSphere MQ as the messaging provider.

Using the administrative console, if you set the scope of the WebSphere MQ messaging provider to cell
scope or to node scope for a WebSphere Application Server version 6 node, you can configure JMS 1.1
resources and properties. This includes unified JMS connection factories for use by both point-to-point and
publish/subscribe JMS 1.1 applications. With JMS 1.1, this approach is preferred to the domain-specific
queue connection factory and topic connection factory. If you set the scope to a WebSphere Application
Server Version 5 node, you can only configure domain-specific JMS resources, and the subset of
properties that apply to WebSphere Application Server Version 5.

For more information about configuring JMS resources for the WebSphere MQ messaging provider, see
the following topics. These topics include optional steps for you to create a new JMS resource.

Configuring resources for WebSphere Application Server version 6:

v Configuring a unified JMS connection factory
v Configuring a JMS queue connection factory
v Configuring a JMS topic connection factory
v Configuring a JMS queue
v Configuring a JMS topic
v Enabling WebSphere MQ JMS connection pooling

Configuring a unified JMS connection factory, for WebSphere MQ:

Use this task to browse or configure a unified JMS connection factory for use with WebSphere MQ as a
messaging provider. This task contains an optional step for you to create a new unified JMS connection
factory.

This topic describes how to configure a unified JMS connection factory for WebSphere MQ as a
messaging provider on an Application Server version 6 node. With JMS 1.1, this approach is preferred to
the domain-specific JMS queue connection factory and JMS topic connection factory.
Chapter 8. Developing WebSphere applications 1517
If you want to configure a JMS queue connection factory or topic factory, see the related tasks.

To browse or configure a unified JMS connection factory for use with WebSphere MQ as a messaging
provider, use the administrative console to complete the following steps:
1. Display the WebSphere MQ messaging provider. In the navigation pane, expand Resources → JMS
Providers → WebSphere MQ.
2. Optional: Change the Scope setting to the level at which the connection factory is visible to
applications.
3. In the contents pane, under Additional Properties, click WebSphere MQ Connection Factories This
displays a table listing any existing unified JMS connection factories, with a summary of their
properties.
4. To browse or change the properties of an existing unified JMS connection factory, click its name in the
list. Otherwise, to create a new connection factory, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this connection factory is known for administrative purposes within IBM
WebSphere Application Server.
JNDI name
The JNDI name that is used to bind the connection factory into the name space.
CCSID
The coded character set identifier for use with the WebSphere MQ queue manager; for
example: 850.
c. Click Apply. This defines the JMS connection factory to WebSphere Application Server, and
enables you to browse or change additional properties.
5. Optional: Change properties for the unified JMS connection factory, according to your needs.
6. Optional: Change connection pool properties and session pool properties, according to your needs.
7. Click OK.
8. Save any changes to the master configuration.
9. To have the changed configuration take effect, stop then restart the application server.

Configuring a JMS queue connection factory, for WebSphere MQ:

Use this task to browse or change a JMS queue connection factory for use with WebSphere MQ as a
messaging provider. This task contains an optional step for you to create a new JMS queue connection
factory.

With JMS 1.1, the preferred approach is to use unified JMS connection factories instead of the
domain-specific JMS queue connection factory and JMS topic connection factory. If you want to configure
a unified JMS connection factory, see “Configuring a unified JMS connection factory, for WebSphere MQ”
on page 1517.

To browse or configure a JMS queue connection factory for use with WebSphere MQ as a messaging
provider, use the administrative console to complete the following steps:
1. Display the WebSphere MQ messaging provider. In the navigation pane, expand Resources → JMS
Providers → WebSphere MQ.
2. Optional: Change the Scope setting to the level at which the connection factory is visible to
applications.
3. In the contents pane, under Additional Properties, click WebSphere MQ Queue Connection Factories
This displays a table listing any existing JMS queue connection factories, with a summary of their
properties.

1518 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
4. To browse or change an existing JMS queue connection factory, click its name in the list. Otherwise, to
create a new connection factory, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this connection factory is known for administrative purposes within IBM
WebSphere Application Server.
JNDI name
The JNDI name that is used to bind the connection factory into the name space.
CCSID
The coded character set identifier for use with the WebSphere MQ queue manager; for
example: 850.
c. Click Apply. This defines the connection factory to WebSphere Application Server, and enables
you to browse or change additional properties.
5. Optional: Change properties for the queue connection factory, according to your needs.
6. Optional: Change connection pool properties and session pool properties, according to your needs.
7. Click OK.
8. Save any changes to the master configuration.
9. To have the changed configuration take effect, stop then restart the application server.

Configuring a JMS topic connection factory, for WebSphere MQ:

Use this task to browse or configure a JMS topic connection factory for publish/subscribe messaging with
WebSphere MQ as a messaging provider. This task contains an optional step for you to create a new JMS
topic connection factory.

With JMS 1.1, the preferred approach is to use unified JMS connection factories instead of the
domain-specific JMS queue connection factory and JMS topic connection factory. If you want to configure
a unified JMS connection factory, see “Configuring a unified JMS connection factory, for WebSphere MQ”
on page 1517.

To configure a topic connection factory for use with the WebSphere MQ as a messaging provider, use the
administrative console to complete the following steps:
1. Display the WebSphere MQ messaging provider. In the navigation pane, expand Resources → JMS
Providers → WebSphere MQ.
2. Optional: Change the Scope setting to the level at which the connection factory is visible to
applications.
3. In the contents pane, under Additional Properties, click WebSphere MQ Topic Connection Factories
This displays a table listing any existing JMS topic connection factories, with a summary of their
properties.
4. To browse or change an existing JMS topic connection factory, click its name in the list. Otherwise, to
create a new connection factory, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this destination is known for administrative purposes within IBM
WebSphere Application Server.
JNDI Name
The JNDI name that is used to bind the destination into the name space.

Chapter 8. Developing WebSphere applications 1519

 CCSID
The coded character set identifier for use with the WebSphere MQ queue manager; for
example: 850.
c. Click Apply. This defines the destination to WebSphere Application Server, and enables you to
browse or change additional properties.
5. Optional: Change properties for the topic connection factory, according to your needs.
6. Optional: Change connection pool properties and session pool properties, according to your needs.
7. Click OK.
8. Save any changes to the master configuration.
9. To have the changed configuration take effect, stop then restart the application server.

Configuring a JMS queue destination, for WebSphere MQ:

Use this task to browse or change a JMS queue destination for point-to-point messaging with WebSphere
MQ as a messaging provider. This task contains an optional step for you to create a new JMS queue
destination.

To browse or configure a JMS queue destination for use with WebSphere MQ as a messaging provider,
use the administrative console to complete the following steps:
1. Display the WebSphere MQ messaging provider. In the navigation pane, expand Resources → JMS
Providers → WebSphere MQ.
2. Optional: Change the Scope setting to the level at which the JMS destination is visible to applications.
3. In the contents pane, under Additional Properties, click WebSphere MQ queue destinations This
displays a table listing any existing JMS queue destinations, with a summary of their properties.
4. To browse or change the properties of an existing JMS queue destination, click its name in the list.
Otherwise, to create a new queue, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this queue destination is known for administrative purposes within IBM
WebSphere Application Server.
JNDI name
The JNDI name that is used to bind the queue destination into the name space.
Base Queue Name
The name of the queue to which messages are sent, on the queue manager specified by
the Base Queue Manager Name property.
CCSID
The coded character set identifier for use with the WebSphere MQ queue manager; for
example: 850.
c. Click Apply. This defines the queue destination to WebSphere Application Server, and enables you
to browse or change additional properties.
5. Optional: Change properties for the queue destination, according to your needs.
6. Optional: If you want WebSphere Application Server to try to use the WebSphere MQ queue
manager’s remote administration utilities to create the queue, configure the WebSphere MQ Queue
Connection properties.
If you have already created your underlying queue in WebSphere MQ using its administration tools
(such as runmqsc or MQ Explorer), you do not need to configure any of the WebSphere MQ Queue
Connection properties. You only need to configure these properties if you want WebSphere Application
Server to try to use the WebSphere MQ queue manager’s remote administration utilities to create the
queue.

1520 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 To be able to browse or change these MQ Config properties, you must have installed the WebSphere
MQ client. If you have not done this, the administrative console displays messages like the following:
The WMQQueueDefiner MBean has encountered an error.
WMSG0331E: The MQ Client is required for this functionality, but it is not installed.

Note: For any changes to these properties to take effect on the queue manager, the WebSphere MQ
Queue Manager on which the queue resides (or will reside) must be configured for remote
administration and be running.
For more details about these properties, see WebSphere MQ config properties for the queue
destination.
7. Click OK.
8. Save any changes to the master configuration.
9. To have the changed configuration take effect, stop then restart the application server.

Configuring a JMS topic destination, for WebSphere MQ:

Use this task to browse or change a JMS topic destination for publish/subscribe messaging with
WebSphere MQ as a messaging provider. This task contains an optional step for you to create a new JMS
topic destination.

To configure a JMS topic destination for use with WebSphere MQ as a messaging provider, use the
administrative console to complete the following steps:
1. Display the WebSphere MQ messaging provider. In the navigation pane, expand Resources → JMS
Providers → WebSphere MQ.
2. Optional: Change the Scope setting to the level at which the JMS destination is visible to applications.
3. In the contents pane, under Additional Properties, click WebSphere MQ topic destinations This
displays a table listing any existing JMS topic destinations, with a summary of their properties.
4. To browse or change an existing JMS topic destination, click its name in the list. Otherwise, to create a
new topic destination, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this connection factory is known for administrative purposes within IBM
WebSphere Application Server.
JNDI Name
The JNDI name that is used to bind the connection factory into the name space.
Base Topic Name
The name of the WebSphere MQ topic to which messages are sent.
CCSID
The coded character set identifier for use with the WebSphere MQ queue manager; for
example: 850.
c. Click Apply. This defines the topic destination to WebSphere Application Server, and enables you
to browse or change additional properties.
5. Optional: Change properties for the topic destination, according to your needs.
6. Click OK.
7. Save any changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the application server.

Configuring WebSphere MQ connection pooling:

Chapter 8. Developing WebSphere applications 1521

Use this task to browse or change properties of WebSphere MQ connection pooling for JMS connections
from an application server to WebSphere MQ as a JMS provider.

To enable WebSphere MQ connection pooling for an application server, use the administrative console to
complete the following steps:
1. Display the Message Listener Service properties for the application server
a. In the navigation pane, click Servers → Application Servers
b. In the content pane, click the name of the application server.
c. Under Additional Properties, click Message Listener Service properties.
2. Select Custom Properties, to enable WebSphere MQ connection pooling, add the following custom
properties:
mqjms.pooling.threshold
The maximum number of unused connections in the pool.
mqjms.pooling.timeout
The timeout in milliseconds for unused connections in the pool.
3. Click OK.
4. Save any changes to the master configuration.
5. To have the changed configuration take effect, stop then restart the application server.

WebSphere MQ JMS connection pooling: To improve the overall performance of JMS within the system,
the message listener service enables the connection pooling facility provided by the WebSphere MQ JMS
implementation. This support does not affect the performance of a message listener, because it retains its
connections while listening on a destination, but does affect the overall JMS system performance. When a
connection is no longer required, WebSphere MQ can pool the connection then reuse it later instead of
destroying it.

Note: This support is only available for use with WebSphere MQ as a JMS provider.

To enable WebSphere MQ connection pooling and configure the characteristics of the WebSphere MQ
connection pool, see Enabling WebSphere MQ JMS connection pooling.

Securing WebSphere MQ messaging directories and log files

Use this task to restrict access to the /var/mqm directories and log files needed for WebSphere MQ as a
JMS provider.

You need to set the permissions described in this topic, to reduce the risk of severe security exposures.

Note: The /var file system is used to store all the security logging information for the system, and is used
to store the temporary files for email and printing. Therefore, it is critical that you maintain free
space in /var for these operations and prevent unauthorized access to the file system. If you do not
create a separate file system for messaging data, and /var fills up, all security logging will be
stopped on the system until some free space is available in /var. Also, email and printing will no
longer be possible until some free space is available in /var.

This procedure involves steps that you complete at different stages of installing and using IBM WebSphere
Application Server, as described below. The steps are also described at appropriate points in other tasks,
but are collected here for completeness.

This procedure applies only to the ordinary UNIX file system. If your site uses access-control lists,
secure the files by using that mechanism. Any site-specific requirements can affect the desired owner,
group and corresponding privileges. For example, on AIX, complete the following steps:
1. Before installing WebSphere MQ, create and mount a journalized file system called /var/mqm. Use a
partition strategy with a separate volume for the messaging data. This means that other system activity
is not affected if a large amount of messaging work builds up in /var/mqm.

1522 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Install WebSphere MQ as a messaging provider.
As part of this stage, the installation program creates the /var/mqm/errors and
/var/mqm/qmgrs/@SYSTEM/errors directories used to hold messaging logging files.
3. Restrict access to the /var/mqm/errors directory and the logging files, by using the following
commands:
chmod 3777 /var/mqm/errors
chown mqm:mqm /var/mqm/errors

touch /var/mqm/errors/AMQERR01.LOG
chown mqm:mqm /var/mqm/errors/AMQERR01.LOG
chmod 666 /var/mqm/errors/AMQERR01.LOG

touch /var/mqm/errors/AMQERR02.LOG
chown mqm:mqm /var/mqm/errors/AMQERR02.LOG
chmod 666 /var/mqm/errors/AMQERR02.LOG

touch /var/mqm/errors/AMQERR03.LOG
chown mqm:mqm /var/mqm/errors/AMQERR03.LOG
chmod 666 /var/mqm/errors/AMQERR03.LOG
4. Restrict access to the /var/mqm/qmgrs/@SYSTEM/errors directory and the logging files, by using the
following commands:
chmod 3777 /var/mqm/qmgrs/@SYSTEM/errors
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG
5. For each application server that uses JMS resources provided by WebSphere MQ, restrict access to
the server’s /var/mqm/qmgrs/long_server_name/errors directory and its messaging logging files. You
should restrict access to the server’s directory and logging files, as soon after creating the application
server as possible.
To restrict access to the server’s directory and logging files, use the following commands:
chmod 3775 /var/mqm/qmgrs/long_server_name/errors
chown mqm:mqm /var/mqm/qmgrs/long_server_name/errors

touch /var/mqm/qmgrs/long_server_name/errors/AMQERR01.LOG
chown mqm:mqm /var/mqm/qmgrs/long_server_name/errors/AMQERR01.LOG
chmod 666 /var/mqm/qmgrs/long_server_name/errors/AMQERR01.LOG

touch /var/mqm/qmgrs/long_server_name/errors/AMQERR02.LOG
chown mqm:mqm /var/mqm/qmgrs/long_server_name/errors/AMQERR02.LOG
chmod 666 /var/mqm/qmgrs/long_server_name/errors/AMQERR02.LOG

touch /var/mqm/qmgrs/long_server_name/errors/AMQERR03.LOG
chown mqm:mqm /var/mqm/qmgrs/long_server_name/errors/AMQERR03.LOG
chmod 666 /var/mqm/qmgrs/long_server_name/errors/AMQERR03.LOG
Where long_server_name is the long name assigned to the server, in the following form:
WAS_nodename_server_name. For example, if you created an application server called server1 to run on
the node called appnode1, the long server name would be: WAS_appnode1_server1.

This task has restricted access to the /var/mqm directories and log files needed for WebSphere MQ as a
JMS provider, such that only the user ID mqm or members of the mqm user group have write access.

Chapter 8. Developing WebSphere applications 1523

Using JMS resources of a generic provider
This topic is the entry-point into a set of topics about enabling WebSphere applications to use JMS
resources provided by a generic messaging provider (other than a WebSphere default messaging provider
or WebSphere MQ).

You can install a messaging provider other than the default messaging provider or WebSphere MQ.
WebSphere applications can use the JMS 1.1 interfaces or JMS 1.0.2 interfaces to access JMS resources
provided by the generic messaging provider, in addition to JMS resources provided by the default
messaging provider or WebSphere MQ (if installed).

You can use the WebSphere administrative console to administer the JMS connection factories and
destinations provided by generic messaging providers.

In a mixed-version WebSphere Application Server deployment manager cell, you can administer generic
messaging resources on both Version 6 and Version 5 nodes. For Version 5 nodes, the administrative
console presents the subset of resources and properties that are applicable to WebSphere Application
Server Version 5.

For more information about using a generic messaging provider to WebSphere Application Server, see the
following topics:
v Defining a generic messaging provider
v “Displaying administrative lists of generic messaging resources” on page 1525
v “Configuring JMS resources for a generic messaging provider” on page 1531

Defining a generic messaging provider

Use this task to define a new messaging provider to WebSphere Application Server, for use instead of the
default messaging provider or a WebSphere MQ as a messaging provider.

Before starting this task, you should have installed and configured the messaging provider and its
resources by using the tools and information provided with the messaging provider.

To define a new generic messaging provider to WebSphere Application Server, use the administrative
console to complete the following steps:
1. In the navigation pane, click JMS Providers → Generic. This displays the existing generic messaging
providers in the content pane.
2. To define a new generic messaging provider, click New in the content pane. Otherwise, to change the
definition of an existing messaging provider, click the name of the provider. This displays the properties
used to define the messaging provider in the content pane.
3. Specify the following required properties. You can specify other properties, as described in a later step.
Name The name by which this messaging provider is known for administrative purposes within IBM
WebSphere Application Server.
External initial context factory
The Java classname of the initial context factory for the JMS provider.
External provider URL
The JMS provider URL for external JNDI lookups.
4. Optional: Click Apply. This enables you to specify additional properties.
5. Optional: Specify other properties for the messaging provider.
Under Additional Properties, you can use the Custom Properties link to specify custom properties for
your initial context factory, in the form of standard javax.naming properties.
6. Click OK.
7. Save the changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the application server.

1524 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
You can now configure JMS resources for the generic messaging provider, as described in “Configuring
JMS resources for a generic messaging provider” on page 1531.

Displaying administrative lists of generic messaging resources

Use this task with the WebSphere administrative console to display administrative lists of JMS resources
provided by a messaging provider other than the default messaging provider or WebSphere MQ.

You can use the WebSphere administrative console to display lists of the following types of JMS resources
provided by a generic messaging provider. You can use the panels displayed to select JMS resources to
administer, or to create or delete JMS resources (where appropriate).

To display administrative lists of JMS resources for a generic messaging provider, complete the following
general steps:
1. Start the WebSphere administrative console.
2. In the navigation pane, click Resources → JMS Providers → Generic
3. If appropriate, in the content pane, change the scope of the generic messaging provider. If the scope is
set to node or server scope for a Version 5 node, the administrative console presents the subset of
resources and properties that are applicable to WebSphere Application Server Version 5.
4. In the content pane, under Additional Resources, click the link for the type of JMS resource. This
displays a list of any existing resources of the selected type. For more information about the settings
panels displayed for resources, see the related reference topics.

JMS provider collection:

Use this panel to list JMS providers, or to select a JMS provider to view or change its configuration
properties.

To view this administrative console page, click Resources → JMS providers → Generic

To view or change the properties of a JMS provider or its resources, select its name in the list displayed.

To define a new generic JMS provider, click New.

To act on one or more of the JMS providers listed, click the check boxes next to the names of the objects
that you want to act on, then use the buttons provided.
Name The name by which this JMS provider is known for administrative purposes.
Description
A description of this JMS provider for administrative purposes.

Generic JMS connection factory collection:

The JMS connection factories configured in the associated generic messaging provider for both
point-to-point and publish/subscribe messaging. Use this panel to create or delete JMS connection
factories, or to select a connection factory to browse or change its configuration properties.

This panel shows a list of the generic JMS connection factories with a summary of their configuration
properties.

To view this administrative console page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → Generic.
2. In the content pane, click the name of the generic messaging provider that you want to support the
JMS connection factory.
3. Under Additional Properties, click JMS connection factories.

To define a new JMS connection factory, click New.

Chapter 8. Developing WebSphere applications 1525

To view or change the properties of a JMS connection factory, select its name in the list displayed.

To act on one or more of the JMS connection factories listed, click the check boxes next to the names of
the objects that you want to act on, then use the buttons provided.

Generic JMS connection factory settings:

Use this panel to browse or change the configuration properties of the selected JMS connection factory for
use with the associated generic JMS provider. These configuration properties control how connections are
created to the JMS destinations on the provider.

A JMS connection factory is used to create connections to JMS destinations. The JMS connection factory
is created by the associated JMS provider.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, expand Resources → JMS Providers → Generic.
2. In the content pane, click the name of the messaging provider that you want to support the JMS
connection factory.
3. If appropriate, in the content pane, change the scope of the generic messaging provider.
4. Under Additional Properties, click JMS connection factories.
5. Click the name of the JMS connection factory that you want to work with.

A JMS connection factory for a generic JMS provider (other than the default messaging provider or
WebSphere MQ as a JMS provider) has the following properties:

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which this JMS connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the associated messaging provider.

Data type String

Type:

Whether this connection factory is for creating JMS queue destinations or JMS topic destinations.

Select one of the following options:

QUEUE
A JMS queue connection factory for point-to-point messaging.
TOPIC
A JMS topic connection factory for publish/subscribe messaging.

1526 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
JNDI name:

The JNDI name that is used to bind the connection factory into the WebSphere Application Server name
space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

Category:

A category used to classify or group this connection factory, for your IBM WebSphere Application Server
administrative records.

Data type String

External JNDI name:

The JNDI name that is used to bind the connection factory into the name space of the generic messaging
provider.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Component-managed Authentication Alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
application-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use

Chapter 8. Developing WebSphere applications 1527

of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Container-managed Authentication Alias:

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for
container-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Mapping-Configuration Alias:

The module used to map authentication aliases.

This field provides a list of the modules that have been configured on the Global Security → JAAS
Configuration → Application Logins Configuration property. For more information about the mapping
configurations, see Java Authentication and Authorization service configuration entry settings.

Data type Enum

Default Null
Range ClientContainer
The client container maps authentication aliases.
WSLogin
The WSLogin module maps authentication
aliases.
DefaultPrincipalMapping
The JAAS configuration maps an authentication
alias to its userid and password.

Connection pool:

Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the messaging provider to improve
performance. You need to configure the connection and session pool properties appropriately for your
applications, otherwise you may not get the connection and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Session pool:

An optional set of session pool settings.

This link provides a panel of optional connection pool properties, common to all J2C connectors.

1528 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The application server pools connections and sessions with the messaging provider to improve
performance. You need to configure the connection and session pool properties appropriately for your
applications, otherwise you may not get the connection and session behavior that you want.

Custom properties:

An optional set of name and value pairs for custom properties passed to the messaging provider.

Generic JMS destination collection:

The JMS destinations configured in the associated messaging provider for point-to-point and
publish/subscribe messaging. Use this panel to create or delete JMS destinations, or to select a JMS
destination to browse or change its configuration properties.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → Generic.
2. In the content pane, click the name of the messaging provider that you want to support the JMS
destination.
3. Under Additional Properties, click JMS destinations.

To define a new JMS destination, click New.

To view or change the properties of a JMS destination, select its name in the list displayed.

To act on one or more of the JMS destinations listed, click the check boxes next to the names of the
objects that you want to act on, then use the buttons provided.

Generic JMS destination settings:

Use this panel to browse or change the configuration properties of the selected JMS destination for use
with the associated JMS provider.

A JMS destination is used to configure the properties of a JMS destination for the associated generic
messaging provider (not the default messaging provider or WebSphere MQ). Connections to the JMS
destination are created by the associated JMS connection factory.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → Generic.
2. In the content pane, click the name of the messaging provider that you want to support the JMS
destination.
3. Under Additional Properties, click JMS destinations.
4. Click the name of the JMS destination that you want to work with.

A JMS destination for use with a generic messaging provider has the following properties.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Chapter 8. Developing WebSphere applications 1529

Data type String

Name:

The name by which the queue is known for administrative purposes within IBM WebSphere Application
Server.

Data type String

Type:

Whether this JMS destination is a queue (for point-to-point) or topic (for publish/subscribe).

Select one of the following options:

Queue
A JMS queue destination for point-to-point messaging.
Topic A JMS topic destination for publish/subscribe messaging.

JNDI name:

The JNDI name that is used to bind the queue into the application server’s name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of the queue, for administrative purposes

Data type String

Category:

A category used to classify or group this queue, for your IBM WebSphere Application Server administrative
records.

Data type String

External JNDI name:

The JNDI name that is used to bind the queue into the application server’s name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the

1530 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
platform.

Data type String

Configuring JMS resources for a generic messaging provider

Use the following tasks to configure the JMS connection factories and destinations for a generic
messaging provider (not the default messaging provider or WebSphere MQ).

You only need to complete these tasks if your WebSphere Application Server environment uses a
messaging provider other than the default messaging provider or WebSphere MQ to support enterprise
applications that use JMS. To enable use of such a generic messaging provider, you must have installed
and configured the messaging provider, as described in ″Defining a new JMS provider to WebSphere
Application Server″ in the information center.

To configure JMS resources for a generic messaging provider, complete the following tasks:
v Configuring a JMS connection factory
v Configuring a JMS destination

Configuring a JMS connection factory, generic JMS provider:

Use this task to browse or change the properties of a JMS connection factory for use with a generic JMS
provider (other than the default messaging provider or WebSphere MQ).

To configure a JMS connection factory for use with a generic JMS provider, use the administrative console
to complete the following steps:
1. Display the generic messaging provider. In the navigation pane, expand Resources → JMS Providers
→ Generic.
2. Optional: Change the Scope setting to the level at which the connection factory is visible to
applications.
3. In the content pane, under Additional Properties, click JMS connection factories This displays a table
listing any existing JMS connection factories, with a summary of their properties.
4. To browse or change an existing JMS connection factory, click its name in the list. Otherwise, to create
a new connection factory, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this JMS connection factory is known for administrative purposes
within IBM WebSphere Application Server.
Type Select whether the connection factory is for JMS queues (QUEUE) or JMS topics (TOPIC).
JNDI Name
The JNDI name that is used to bind the JMS connection factory into the WebSphere
Application Server name space.
External JNDI Name
The JNDI name that is used to bind the JMS connection factory into the name space of the
messaging provider.
c. Click Apply. This defines the JMS connection factory to WebSphere Application Server, and
enables you to browse or change additional properties.
5. Optional: Change properties for the JMS connection factory, according to your needs.
6. Click OK.
7. Save any changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the application server.

Chapter 8. Developing WebSphere applications 1531

Configuring a JMS destination, a generic JMS provider:

Use this task to browse or change the properties of a JMS destination for use with a generic JMS provider
(other than the default messaging provider or WebSphere MQ).

To configure a JMS destination for use with a generic JMS provider, use the administrative console to
complete the following steps:
1. Display the generic messaging provider. In the navigation pane, expand Resources → JMS Providers
→ Generic.
2. Optional: Change the Scope setting to the level at which the connection factory is visible to
applications.
3. In the content pane, under Additional Properties, click JMS destinations This displays a table listing
any existing JMS destinations, with a summary of their properties.
4. To browse or change an existing JMS destination, click its name in the list. Otherwise, to create a new
destination, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this JMS destination is known for administrative purposes within IBM
WebSphere Application Server.
Type Select whether the destination is for JMS queues (QUEUE) or JMS topics (TOPIC).
JNDI Name
The JNDI name that is used to bind the JMS destination into the WebSphere Application
Server name space.
External JNDI Name
The JNDI name that is used to bind the JMS destination into the name space of the
messaging provider.
c. Click Apply. This defines the JMS destination to WebSphere Application Server, and enables you
to browse or change additional properties.
5. Optional: Change properties for the JMS destination, according to your needs.
6. Click OK.
7. Save any changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the application server.

Maintaining Version 5 default messaging resources

This topic is the entry-point into a set of topics about maintaining messaging resources provided for
WebSphere Application Server version 5 applications by the default messaging provider.

WebSphere application server version 5 applications can use JMS resources provided by the default
messaging provider of WebSphere application server version 6. You can use the WebSphere
administrative console to manage the JMS connection factories and destinations for WebSphere
Application Server version 5 applications. Such JMS resources are maintained as V5 Default Messaging
resources.

In a deployment manager cell, you can use V5 Default Messaging resources to maintain Version 5 default
messaging resources for both version 6 and version 5 nodes in the cell.
v V5 Default Messaging configured against a version 6 node provides a JMS transport to a messaging
engine of a service integration bus that supports the version 6 default messaging provider. The
messaging engine emulates the service of a version 5 JMS server.

1532 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
v V5 Default Messaging configured against a version 5 node provides a JMS transport to a version 5 JMS
server.

You can also use the administrative console to manage a JMS server on a Version 5 node.

For more information about maintaining Version 5 default messaging resources, see the following topics:
v “Listing version 5 default messaging resources”
v “Configuring Version 5 default JMS resources” on page 1556
v “Managing Version 5 JMS servers in a deployment manager cell” on page 1559
v “Configuring authorization security for a Version 5 default messaging provider” on page 1560

Listing version 5 default messaging resources

Complete this task to display administrative lists of JMS resources for use by WebSphere application
server version 5 applications.

You can use the WebSphere administrative console to display lists of the following types of JMS resources
for use by WebSphere application server version 5 applications. You can use the panels displayed to
select JMS resources to configure, administer, create, or delete (where appropriate).

To display administrative lists of Version 5 default JMS resources, complete the following general steps:
1. Start the WebSphere administrative console.
2. Display the version 5 default messaging provider. In the navigation pane, expand Resources → JMS
Providers → V5 Default Messaging.
3. Optional: Change the Scope setting to the level at which the JMS queue connection factory is visible
to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the cell can
look up and use that JMS resource. However, the JMS resource has only the subset of properties that
apply to WebSphere Application Server Version 5. If you want to define a JMS resource at Cell level
for use on non-Version 5 nodes, you should define the JMS resource for the Version 6 default
messaging provider.
4. In the content pane, under Additional Resources, click the link for the type of JMS resource. This
displays a list of any existing resources of the selected type. For more information about the settings
panels displayed for resources, see the related reference topics.

JMS provider settings:

Use this panel to view the configuration properties of the selected JMS provider. You cannot change these
properties.

To view this page, use the administrative console to complete one of the following steps:
v In the navigation pane, click Resources → JMS Providers → WebSphere MQ.
v In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
v In the navigation pane, click Resources → JMS Providers → Generic → provider_name.

If you want to browse or change JMS resources of the JMS provider, complete the following steps:
1. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications.
2. Under Additional Properties, click the link for the type of resource . For more information about the
administrative console panels for the types of JMS resources, see the related topics.

Scope:

The level to which this resource definition is visible; the cell, node, or server level.

Chapter 8. Developing WebSphere applications 1533

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

When JMS resources are created for this messaging provider, they are always created into the provider
scope selected in this panel. To browse or change resources in other scopes, select the required level
option, then click Apply, before clicking the link for the type of resource.

Note that no matter what the scope of a defined resource, the resource’s properties only apply at an
individual server level. For example, if you define the scope of a data source at the Cell level, all users in
that Cell can look up and use that data source, which is unique within that Cell. However, resource
property settings are local to each server in the Cell.
Cell The most general scope. Resources defined at the Cell scope are visible from all Nodes and
servers, unless they are overridden. To view resources defined in the cell scope, do not specify a
server or a node name in the scope selection form.
Node The default scope for most resource types. Resources defined at the Node scope override any
duplicates defined at the Cell scope and are visible to all servers on the same node, unless they
are overridden at a server scope on that node. To view resources defined in a node scope, do not
specify a server, but select a node name in the scope selection form.
Server
The most specific scope for defining resources. Resources defined at the Server scope override
any duplicate resource definitions defined at the Cell scope or parent Node scope and are visible
only to a specific server. To view resources defined in a server scope, specify a server name as
well as a node name in the scope selection form.

Data type String

Name:

The name by which the JMS provider is known for administrative purposes.

Data type String

Default WebSphereJMSProvider

Description:

A description of the JMS provider, for administrative purposes within IBM WebSphere Application Server.

Data type String

Classpath:

The Java classpath for WebSphere MQ as a JMS provider. The list of paths or JAR file names that
together form the location for the JMS provider classes.

[JMS Providers > WebSphere MQ and JMS Providers > Generic only]

Data type String

Default [WebSphere MQ] $MQJMS_LIB_ROOT

Native Library Path:

The native library path for WebSphere MQ as a JMS provider. An optional path to any native libraries
needed by the JMS provider.

1534 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
[JMS Providers > WebSphere MQ and JMS Providers > Generic only]

Data type String

Default [WebSphere MQ] $MQJMS_LIB_ROOT

The Native Library Path property is set to the directory where the WebSphere MQ Java feature is installed.

External initial context factory:

The Java classname of the initial context factory for the JMS provider.

[JMS Providers > Generic only]

For example, for an LDAP service provider the value has the form: com.sun.jndi.ldap.LdapCtxFactory.

Data type String

Default Null

External provider URL:

The JMS provider URL for external JNDI lookups.

[JMS Providers > Generic only]

For example, an LDAP URL for a messaging provider has the form:
ldap://hostname.company.com/contextName.

Data type String

Default Null

Version 5 JMS server collection:

On a WebSphere Application Server Version 5 node, a JMS server provides the functions of the JMS
provider. Use this panel to list JMS servers on WebSphere Application Server Version 5 nodes within the
administration domain, or to select a JMS server to view or change its configuration properties.

There can be at most one JMS server on each Version 5 node in the administration domain, and any
application server within the domain can access JMS resources served by any JMS server on any node in
the domain.

To view this page, use the administrative console to complete the following step:
1. In the navigation pane, select Servers → Version 5 JMS Servers.

To browse or change the properties of a JMS server, select its name in the list displayed.

To act on one or more of the JMS servers listed, click the check box next to the server name, then use the
buttons provided.

version 5 JMS server settings:

The JMS functions on a version 5 node within a deployment manager cell are served by a JMS server.
Use this panel to view or change the configuration properties of the selected JMS server.

JMS servers are supported only to aid migration of WebSphere Application Server version 5 nodes to
WebSphere Application Server version 6.
Chapter 8. Developing WebSphere applications 1535
You can use this panel to configure a general set of JMS server properties, which add to the default
values of properties configured automatically for the version 5 default messaging provider.

Note: JMS servers make use of WebSphere MQ properties and, in general, the default values of those
properties are adequate. However, if you are running high messaging loads, you may need to
change some WebSphere MQ properties; for example, properties for log file locations, file pages,
and buffer pages. For more information about configuring WebSphere MQ properties, see the
WebSphere MQ System Administration book, SC33-1873, which is available from the IBM
Publications Center or from the WebSphere MQ collection kit, SK2T-0730.

Name:

The name by which the JMS server is known for administrative purposes within IBM WebSphere
Application Server.

This name should not be changed.

Data type String

Units Not applicable
Default WebSphere Internal JMS Server
Range Not applicable

Description:

A description of the JMS server, for administrative purposes within IBM WebSphere Application Server.

This string should not be changed.

Data type String

Default WebSphere Internal JMS Server

Number of threads:

The number of concurrent threads to be used by the publish/subscribe matching engine

The number of concurrent threads should only be set to a small number.

Data type Integer

Units Threads
Default 1
Range Greater than or equal to 1.

Queue Names:

The names of the queues hosted by this JMS server. Each queue name must be added on a separate
line.

Each queue listed in this field must have a separate queue administrative object with the same
administrative name. To make a queue available to applications, define a WebSphere queue and add its
name to this field on the JMS Server panel for the host on which you want the queue to be hosted.

Data type String

Units Queue name

1536 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range Each entry in this field is a queue name of up to 45
characters, which must match exactly (including use of
upper- and lowercase characters) the WebSphere queue
administrative object defined for the queue.

Initial State:

The state that you want the JMS server to have when it is next restarted.

Data type Enum

Default Started
Range Started
The JMS server is started automatically.
Stopped
The JMS server is not started automatically. If
any deployed enterprise applications are to use
JMS server functions provided by the JMS
server, the system administrator must start the
JMS server manually or select the Started value
of this property then restart the JMS server.

To restart a JMS server on a version 5 node, stop then

restart that JMS server.

Version 5 WebSphere Queue connection factory collection:

Use this panel to list JMS queue connection factories for point-to-point messaging, for use by WebSphere
Application Server version 5 applications. These configuration properties control how connections are
created between the JMS provider and the default messaging system that it uses.

This panel shows a list of the JMS queue connection factories with a summary of their configuration
properties.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the
cell can look up and use that JMS resource. However, the JMS resource has only the subset of
properties that apply to WebSphere Application Server Version 5. If you want to define a JMS resource
at Cell level for use on non-Version 5 nodes, you should define the JMS resource for the Version 6
default messaging provider.
3. Under Additional Resources, click WebSphere queue connection factories. This displays a list of any
existing JMS queue connection factories.

To define a new JMS queue connection factory, click New.

To browse or change the properties of a connection factory, select its name in the list displayed.

To act on one or more of the connection factories listed, click the check box next to the name of the
connection factory, then use the buttons provided.

Version 5 WebSphere queue connection factory settings:

Use this panel to browse or change the configuration properties of the selected JMS queue connection
factory for point-to-point messaging for use by WebSphere Application Server version 5 applications.

Chapter 8. Developing WebSphere applications 1537

A WebSphere queue connection factory is used to create JMS connections to the default messaging
provider for use by WebSphere Application Server version 5 applications.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the
cell can look up and use that JMS resource.
3. Under Additional Resources, click WebSphere queue connection factories. This displays a list of any
existing JMS queue connection factories.
4. Click the name of the JMS queue connection factory that you want to work with.

A queue connection factory for the embedded WebSphere JMS provider has the following properties:

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which this JMS queue connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the JMS connection factories across the
WebSphere administrative domain.

Data type String

Default Null

JNDI name:

The JNDI name that is used to bind the JMS connection factory into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of this connection factory for administrative purposes within IBM WebSphere Application
Server.

1538 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type String
Default Null

Category:

A category used to classify or group this connection factory, for your IBM WebSphere Application Server
administrative records.

Data type String

Node:

The WebSphere node name of the administrative node where the JMS server runs for this connection
factory. Connections created by this factory connect to that JMS server.

Data type Enum

Default Null
Range Pull-down list of Version 5 nodes in the WebSphere
administrative domain.

Component-managed Authentication Alias:

This alias specifies a user ID and password to be used to authenticate connection to the messaging
provider for application-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the messaging provider.
The use of this alias depends on the resource authentication (res-auth) setting declared in the connection
factory resource reference of an application component’s deployment descriptors.

Note: User IDs longer than 12 characters cannot be used for authentication with the Version 5 default
messaging provider. For example, the default Windows NT user ID, Administrator, is not valid
because it contains 13 characters. Therefore, an authentication alias for a WebSphere queue
connection factory must specify a user ID no longer than 12 characters.

Container-managed Authentication Alias:

This alias specifies a user ID and password to be used to authenticate connection to the messaging
provider for container-managed authentication.

This field is deprecated in 6.0. The specification of a login configuration and associated properties on the
component resource reference determines the container-managed authentication strategy when the
res-auth value is Container. If the ’DefaultPrincipalMapping’ login configuration is used, the associated
property is a container-managed authentication alias. This field is used only in the absence of a
loginConfiguration on the component resource reference. To define a new alias, see the related item J2EE
Connector Architecture (J2C) authentication data entries.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

Chapter 8. Developing WebSphere applications 1539

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the messaging provider.
The use of this alias depends on the resource authentication (res-auth) setting declared in the connection
factory resource reference of an application component’s deployment descriptors.

Note: User IDs longer than 12 characters cannot be used for authentication with the Version 5 default
messaging provider. For example, the default Windows NT user ID, Administrator, is not valid
because it contains 13 characters. Therefore, an authentication alias for a WebSphere topic
connection factory must specify a user ID no longer than 12 characters.

Mapping-Configuration Alias:

The module used to map authentication aliases.

This field is deprecated in 6.0. The specification of a login configuration and associated properties on the
component resource reference determines the container-managed authentication strategy when the
res-auth value is Container. This field is used only in the absence of a loginConfiguration on the
component resource reference.

This field provides a list of the modules that have been configured on the Security → JAAS Configuration
→ Application Logins Configuration property. For more information about the mapping configurations,
see Java Authentication and Authorization service configuration entry settings.

Data type Enum

Default Null
Range ClientContainer
The client container maps authentication aliases.
WSLogin
The WSLogin module maps authentication
aliases.
DefaultPrincipalMapping
The JAAS configuration maps an authentication
alias to its userid and password.

XA Enabled:

Specifies whether the connection factory is for XA or non-XA coordination of messages and controls if the
application server uses XA QCF/TCF. Enable XA if multiple resources are not used in the same
transaction.

If you clear this checkbox property (for non-XA coordination), the JMS session is still enlisted in a
transaction, but uses the resource manager local transaction calls (session.commit and session.rollback)
instead of XA calls. This can lead to an improvement in performance. However, this means that only a
single resource can be enlisted in a transaction in WebSphere Application Server.

Last participant support enables you to enlist one non-XA resource with other XA-capable resources.

For a WebSphere Topic Connection Factory with the Port property set to DIRECT this property does not
apply, and always adopts non-XA coordination.

Data type Checkbox

Default Selected (enabled for XA coordination)

1540 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range Selected
The connection factory is enabled for
XA-coordination of messages
Cleared
The connection factory is not enabled for XA
coordination of messages
Recommended Do not enable XA coordination when the message queue
or topic received is the only resource in the transaction.
Enable XA coordination when other resources, including
other queues or topics, are involved.

Connection pool:

Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the messaging provider to improve
performance. You need to configure the connection and session pool properties appropriately for your
applications, otherwise you may not get the connection and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Session pool:

An optional set of session pool settings.

This link provides a panel of optional connection pool properties, common to all J2C connectors.

The application server pools connections and sessions with the messaging provider to improve
performance. You need to configure the connection and session pool properties appropriately for your
applications, otherwise you may not get the connection and session behavior that you want.

Session pool settings:

Use this page to configure session pool settings.

This administrative console page is common to a range of resource types; for example, JMS queue
connection factories. To view this page, the path depends on the type of resource, but generally you select
an instance of the resource provider, then an instance of the resource type, then click Session pools. For
example: click Resources → JMS Providers → V5 Default Messaging → WebSphere queue connection
factories → connection_factory → Session pools.

Connection Timeout:

Specifies the interval, in seconds, after which a connection request times out and a
ConnectionWaitTimeoutException is thrown.

The wait is necessary when the maximum value of connections (Max Connections) to a particular
connection pool is reached . For example, if Connection Timeout is set to 300 and the maximum number
of connections is reached, the Pool Manager waits for 300 seconds for an available physical connection. If
a physical connection is not available within this time, the Pool Manager throws a
ConnectionWaitTimeoutException. It usually does not make sense to retry the getConnection() method,
because if a longer wait time is required, you should set the Connection Timeout setting to a higher

Chapter 8. Developing WebSphere applications 1541

value. Therefore, if this exception is caught by the application, the administrator should review the
expected usage of the application and tune the connection pool and the database accordingly.

If Connection Timeout is set to 0, the Pool Manager waits as long as necessary until a connection is
allocated (which happens when the number of connections falls below the value of Max Connections).

If Max Connections is set to 0, which enables an infinite number of physical connections, then the
Connection Timeout value is ignored.

Data type Integer

Units Seconds
Default 180
Range 0 to max int

Max Connections:

Specifies the maximum number of physical connections that you can create in this pool.

These are the physical connections to the backend resource. Once this number is reached, no new
physical connections are created and the requester waits until a physical connection that is currently in
use returns to the pool, or a ConnectionWaitTimeoutException is thrown.

For example, if the Max Connections value is set to 5, and there are five physical connections in use, the
pool manager waits for the amount of time specified in Connection Timeout for a physical connection to
become free.

If Max Connections is set to 0, the Connection Timeout value is ignored.

For better performance, set the value for the connection pool lower than the value for the Max
Connections option in the Web container. Lower settings, such as 10-30 connections, perform better than
higher settings, such as 100.

If clones are used, one data pool exists for each clone. Knowing the number of data pools is important
when configuring the database maximum connections.

You can use the Tivoli Performance Viewer to find the optimal number of connections in a pool. If the
number of concurrent waiters is greater than 0, but the CPU load is not close to 100%, consider increasing
the connection pool size. If the Percent Used value is consistently low under normal workload, consider
decreasing the number of connections in the pool.

Data type Integer

Default 10
Range 0 to max int

Min Connections:

Specifies the minimum number of physical connections to maintain.

Until this number is reached, the pool maintenance thread does not discard physical connections.
However, no attempt is made to bring the number of connections up to this number. If you set a value for
Aged Timeout, the minimum is not maintained. All connections with an expired age are discarded.

For example if the Min Connections value is set to 3, and one physical connection is created, the Unused
Timeout thread does not discard that connection. By the same token, the thread does not automatically
create two additional physical connections to reach the Min Connections setting.

1542 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Integer
Default 1
Range 0 to max int

Reap Time:

Specifies the interval, in seconds, between runs of the pool maintenance thread.

For example, if Reap Time is set to 60, the pool maintenance thread runs every 60 seconds. The Reap
Time interval affects the accuracy of the Unused Timeout and Aged Timeout settings. The smaller the
interval, the greater the accuracy. If the pool maintenance thread is enabled, set the Reap Time value less
than the values of Unused Timeout and Aged Timeout. When the pool maintenance thread runs, it
discards any connections remaining unused for longer than the time value specified in Unused Timeout,
until it reaches the number of connections specified in Min Connections. The pool maintenance thread
also discards any connections that remain active longer than the time value specified in Aged Timeout.

The Reap Time interval also affects performance. Smaller intervals mean that the pool maintenance thread
runs more often and degrades performance.

To disable the pool maintenance thread set Reap Time to 0, or set both Unused Timeout and Aged
Timeout to 0. The recommended way to disable the pool maintenance thread is to set Reap Time to 0, in
which case Unused Timeout and Aged Timeout are ignored. However, if Unused Timeout and Aged
Timeout are set to 0, the pool maintenance thread runs, but only physical connections which timeout due
to non-zero timeout values are discarded.

Data type Integer

Units Seconds
Default 180
Range 0 to max int

Unused Timeout:

Specifies the interval in seconds after which an unused or idle connection is discarded.

Set the Unused Timeout value higher than the Reap Timeout value for optimal performance. Unused
physical connections are only discarded if the current number of connections not in use exceeds the Min
Connections setting. For example, if the unused timeout value is set to 120, and the pool maintenance
thread is enabled (Reap Time is not 0), any physical connection that remains unused for two minutes is
discarded. Note that accuracy of this timeout, as well as performance, is affected by the Reap Time value.
For more information, see Reap Time.

Data type Integer

Units Seconds
Default 1800
Range 0 to max int

Aged Timeout:

Specifies the interval in seconds before a physical connection is discarded.

Setting Aged Timeout to 0 supports active physical connections remaining in the pool indefinitely. Set the
Aged Timeout value higher than the Reap Timeout value for optimal performance. For example, if the
Aged Timeout value is set to 1200, and the Reap Time value is not 0, any physical connection that
remains in existence for 1200 seconds (20 minutes) is discarded from the pool. Note that accuracy of this

Chapter 8. Developing WebSphere applications 1543

timeout, as well as performance, are affected by the Reap Time value. For more information, see Reap
Time.

Data type Integer

Units Seconds
Default 0
Range 0 to max int

Purge Policy:

Specifies how to purge connections when a stale connection or fatal connection error is detected.

Valid values are EntirePool and FailingConnectionOnly. JCA data sources can have either option.
WebSphere Version 4.0 data sources always have a purge policy of EntirePool.

Data type String

Default FailingConnectionOnly
Range
EntirePool
All connections in the pool are marked stale. Any
connection not in use is immediately closed. A
connection in use is closed and throws a
StaleConnectionException during the next
operation on that connection. Subsequent
getConnection requests from the application
result in new connections to the database
opening. When using this purge policy, there is a
slight possibility that some connections in the
pool are closed unnecessarily when they are not
stale. However, this is a rare occurrence. In most
cases, a purge policy of EntirePool is the best
choice.
FailingConnectionOnly
Only the connection that caused the
StaleConnectionException is closed. Although
this setting eliminates the possibility that valid
connections are closed unnecessarily, it makes
recovery from an application perspective more
complicated. Because only the currently failing
connection is closed, there is a good possibility
that the next getConnection request from the
application can return a connection from the pool
that is also stale, resulting in more stale
connection exceptions.

Version 5 WebSphere topic connection factory collection:

Use this panel to list JMS topic connection factories for publish/subscribe messaging, for use by
WebSphere Application Server version 5 applications. These configuration properties control how
connections are created between the JMS provider and the default messaging system that it uses.

This panel shows a list of JMS topic connection factories with a summary of their configuration properties.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the

1544 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 cell can look up and use that JMS resource. However, the JMS resource has only the subset of
properties that apply to WebSphere Application Server Version 5. If you want to define a JMS resource
at Cell level for use on non-Version 5 nodes, you should define the JMS resource for the Version 6
default messaging provider.
3. Under Additional Resources, click WebSphere topic connection factories. This displays a list of any
existing JMS topic connection factories.

To define a new JMS topic connection factory, click New.

To view or change the properties of a connection factory, select its name in the list displayed.

To act on one or more of the connection factories listed, click the check box next to the name of the
connection factory, then use the buttons provided.

WebSphere topic connection factory settings:

Use this panel to browse or change the configuration properties of the selected JMS topic connection
factory for publish/subscribe messaging by WebSphere Application Server version 5 applications.

A WebSphere topic connection factory is used to create JMS connections to the default messaging
provider for use by WebSphere Application Server version 5 applications.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the
cell can look up and use that JMS resource.
3. Under Additional Resources, click WebSphere topic connection factories. This displays a list of any
existing JMS topic connection factories.
4. Click the name of the JMS topic connection factory that you want to work with.

A JMS topic connection factory for use with the Version 5 default messaging provider has the following
properties.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which this JMS topic connection factory is known for administrative purposes within IBM
WebSphere Application Server. The name must be unique within the JMS connection factories across the
WebSphere administrative domain.

Data type String

Default Null

Chapter 8. Developing WebSphere applications 1545

JNDI name:

The JNDI name that is used to bind the topic connection factory into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of this topic connection factory for administrative purposes within IBM WebSphere Application
Server.

Data type String

Default Null

Category:

A category used to classify or group this topic connection factory, for your IBM WebSphere Application
Server administrative records.

Data type String

Node:

The WebSphere node name of the administrative node where the JMS server runs for this connection
factory. Connections created by this factory connect to that JMS server.

Data type Enum

Default Null
Range Pull-down list of nodes in the WebSphere administrative
domain.

Port:

Which of the two ports that connections use to connect to the JMS server. The QUEUED port is for
full-function JMS publish/subscribe support, the DIRECT port is for non-persistent, non-transactional,
non-durable subscriptions only.

Note: Message-driven beans cannot use the direct listener port for publish/subscribe support. Therefore,
any topic connection factory configured with Port set to Direct cannot be used with
message-driven beans.

Data type Enum

Units Not applicable
Default QUEUED

1546 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range QUEUED
The listener port used for full-function
JMS-compliant, publish/subscribe support.
DIRECT
The listener port used for direct TCP/IP
connection (non-transactional, non-persistent,
and non-durable subscriptions only) for
publish/subscribe support.

Component-managed Authentication Alias:

This alias specifies a user ID and password to be used to authenticate connection to the messaging
provider for application-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the messaging provider.
The use of this alias depends on the resource authentication (res-auth) setting declared in the connection
factory resource reference of an application component’s deployment descriptors.

Note: User IDs longer than 12 characters cannot be used for authentication with the Version 5 default
messaging provider. For example, the default Windows NT user ID, Administrator, is not valid
because it contains 13 characters. Therefore, an authentication alias for a WebSphere topic
connection factory must specify a user ID no longer than 12 characters.

Container-managed Authentication Alias:

This alias specifies a user ID and password to be used to authenticate connection to the messaging
provider for container-managed authentication.

This field is deprecated in 6.0. The specification of a login configuration and associated properties on the
component resource reference determines the container-managed authentication strategy when the
res-auth value is Container. If the ’DefaultPrincipalMapping’ login configuration is used, the associated
property is a container-managed authentication alias. This field is used only in the absence of a
loginConfiguration on the component resource reference. To define a new alias, see the related item J2EE
Connector Architecture (J2C) authentication data entries.

This property provides a list of the J2C authentication data entry aliases that have been defined to
WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of
a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the
user ID and password used to authenticate the creation of a new connection to the JMS provider. The use
of this alias depends on the resource authentication (res-auth) setting declared in the connection factory
resource reference of an application component’s deployment descriptors.

Note: User IDs longer than 12 characters cannot be used for authentication with the embedded
WebSphere JMS provider. For example, the default Windows NT user ID, Administrator, is not
valid for use with embedded WebSphere messaging, because it contains 13 characters. Therefore,
an authentication alias for a WebSphere JMS provider connection factory must specify a user ID no
longer than 12 characters.

Mapping-Configuration Alias:

Chapter 8. Developing WebSphere applications 1547

The module used to map authentication aliases.

This field is deprecated in 6.0. The specification of a login configuration and associated properties on the
component resource reference determines the container-managed authentication strategy when the
res-auth value is Container. This field is used only in the absence of a loginConfiguration on the
component resource reference.

This field provides a list of the modules that have been configured on the Security → JAAS Configuration
→ Application Logins Configuration property. For more information about the mapping configurations,
see Java Authentication and Authorization service configuration entry settings.

Data type Enum

Default Null
Range ClientContainer
The client container maps authentication aliases.
WSLogin
The WSLogin module maps authentication
aliases.
DefaultPrincipalMapping
The JAAS configuration maps an authentication
alias to its userid and password.

Clone Support:

Select this checkbox to enable clone support to allow the same durable subscription across topic clones.

Data type Enum

Default Cleared
Range Selected
Clone support is enabled.
Cleared
Clone support is disabled.

If you select this property, you must also specify a value for the Client ID property.

Client ID:

The JMS client identifier used for connections to the queue manager.

Data type String

Range A valid JMS client ID

XA Enabled:

Specifies whether the connection factory is for XA or non-XA coordination of messages and controls if the
application server uses XA QCF/TCF. Enable XA if multiple resources are not used in the same
transaction.

If you clear this checkbox property (for non-XA coordination), the JMS session is still enlisted in a
transaction, but uses the resource manager local transaction calls (session.commit and session.rollback)
instead of XA calls. This can lead to an improvement in performance. However, this means that only a
single resource can be enlisted in a transaction in WebSphere Application Server.

Last participant support enables you to enlist one non-XA resource with other XA-capable resources.

1548 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
For a WebSphere Topic Connection Factory with the Port property set to DIRECT this property does not
apply, and always adopts non-XA coordination.

Data type Checkbox

Default Selected (enabled for XA coordination)
Range Selected
The connection factory is enabled for
XA-coordination of messages
Cleared
The connection factory is not enabled for XA
coordination of messages
Recommended Do not enable XA coordination when the message queue
or topic received is the only resource in the transaction.
Enable XA coordination when other resources, including
other queues or topics, are involved.

Connection pool:

Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the messaging provider to improve
performance. You need to configure the connection and session pool properties appropriately for your
applications, otherwise you may not get the connection and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the
default value. The size of the connection pool is set on a per queue or topic basis.

Session pool:

An optional set of session pool settings.

This link provides a panel of optional connection pool properties, common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance. You
need to configure the connection and session pool properties appropriately for your applications, otherwise
you may not get the connection and session behavior that you want.

Version 5 WebSphere queue destination collection:

Use this panel to list JMS queue for point-to-point messaging for use by WebSphere Application Server
version 5 applications.

This panel shows a list of the JMS queue destinations with a summary of their configuration properties.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the
cell can look up and use that JMS resource. However, the JMS resource has only the subset of
properties that apply to WebSphere Application Server Version 5. If you want to define a JMS resource
at Cell level for use on non-Version 5 nodes, you should define the JMS resource for the Version 6
default messaging provider.
3. Under Additional Resources, click WebSphere queue destinations. This displays a list of any existing
JMS queue destinations.

Chapter 8. Developing WebSphere applications 1549

To define a new JMS queue destination, click New.

To view or change the properties of a queue destination, select its name in the list displayed.

To act on one or more of the queue destinations listed, click the check box next to the name of the queue,
then use the buttons provided.

Version 5 WebSphere queue destination settings:

Use this panel to view or change the configuration properties of the selected JMS queue destination for
point-to-point messaging by WebSphere Application Server version 5 applications.

A queue destination is used to configure a JMS queue of the default messaging provider for use by
WebSphere Application Server version 5 applications. Connections to the queue are created by the
associated V5 Default Messaging WebSphere queue connection factory.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the
cell can look up and use that JMS resource. However, the JMS resource has only the subset of
properties that apply to WebSphere Application Server Version 5. If you want to define a JMS resource
at Cell level for use on non-Version 5 nodes, you should define the JMS resource for the Version 6
default messaging provider.
3. Under Additional Resources, click WebSphere queue destinations. This displays a list of any existing
JMS queue destinations.
4. Click the name of the JMS queue destination that you want to work with.

A JMS queue for use with the internal WebSphere JMS provider has the following properties.

Scope:

Specifies the level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which the queue is known for administrative purposes within IBM WebSphere Application
Server.

To enable applications to use this queue, you must add the queue name to the Queue Names field on the
panel for the JMS server that hosts the queue.

Data type String

JNDI name:

1550 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The JNDI name that is used to bind the queue into the application server’s name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of the queue, for administrative purposes

Data type String

Default Null

Category:

A category used to classify or group this queue, for your IBM WebSphere Application Server administrative
records.

Data type String

Persistence:

Whether all messages sent to the destination are persistent, non-persistent, or have their persistence
defined by the application

Data type Enum

Default APPLICATION DEFINED
Range APPLICATION DEFINED
Messages on the destination have their
persistence defined by the application that put
them onto the queue.
NON PERSISTENT
Messages on the destination are not persistent.
PERSISTENT
Messages on the destination are persistent.
When a persistent message is put to a queue, all
of the message data is written to the messaging
log (under the embedded_messaging_install\log
directory) to make recovery of the message
possible.

Priority:

Whether the message priority for this destination is defined by the application or the Specified priority
property

Data type Enum

Default APPLICATION DEFINED

Chapter 8. Developing WebSphere applications 1551

Range APPLICATION DEFINED
The priority of messages on this destination is
defined by the application that put them onto the
destination.
QUEUE DEFINED
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
SPECIFIED
The priority of messages on this destination is
defined by the Specified priority property.If you
select this option, you must define a priority on
the Specified priority property.

Specified priority:

If the Priority property is set to Specified, type here the message priority for this queue, in the range 0
(lowest) through 9 (highest)

If the Priority property is set to Specified, messages sent to this queue have the priority value specified
by this property.

Data type Integer

Units Message priority level
Default 0
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Whether the expiry timeout for this queue is defined by the application or the Specified expiry property, or
messages on the queue never expire (have an unlimited expiry timeout)

Data type Enum

Default APPLICATION DEFINED
Range APPLICATION DEFINED
The expiry timeout for messages on this queue is
defined by the application that put them onto the
queue.
UNLIMITED
Messages on this queue have no expiry timeout,
so those messages never expire.
SPECIFIED
The expiry timeout for messages on this queue is
defined by the Specified expiry property.If you
select this option, you must define a timeout on
the Specified expiry property.

Specified expiry:

If the Expiry timeout property is set to Specified, type here the number of milliseconds (greater than 0)
after which messages on this queue expire

Data type Integer

Units Milliseconds
Default 0

1552 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Range Greater than or equal to 0
v 0 indicates that messages never timeout
v Other values are an integer number of milliseconds

Version 5 WebSphere topic destination collection:

Use this panel to list JMS topic destinations for publish/subscribe messaging with the default messaging
provider on a Version 5 node in the deployment manager cell.

This panel shows a list of JMS topic destinations with a summary of their configuration properties.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the
cell can look up and use that JMS resource. However, the JMS resource has only the subset of
properties that apply to WebSphere Application Server Version 5. If you want to define a JMS resource
at Cell level for use on non-Version 5 nodes, you should define the JMS resource for the Version 6
default messaging provider.
3. Under Additional Resources, click WebSphere topic destinations. This displays a list of any existing
JMS topic destinations.

To define a new JMS topic connection factory, click New.

To browse or change the properties of a topic destination, select its name in the list displayed.

To act on one or more of the topic destinations listed, click the check box next to the name of the topic,
then use the buttons provided.

Version 5 WebSphere topic destination settings:

Use this panel to browse or change the configuration properties of the selected JMS topic destination for
publish/subscribe messaging by WebSphere application server version 5 applications.

A WebSphere topic destination is used to configure the properties of a JMS topic for the default
messaging provider on a Version 5 node in the deployment manager cell. Connections to the topic are
created by the associated topic connection factory.

To view this page, use the administrative console to complete the following steps:
1. In the navigation pane, click Resources → JMS Providers → V5 Default Messaging.
2. (Optional) In the content pane, change the Scope setting to the level at which JMS resources are
visible to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the
cell can look up and use that JMS resource. However, the JMS resource has only the subset of
properties that apply to WebSphere Application Server Version 5. If you want to define a JMS resource
at Cell level for use on non-Version 5 nodes, you should define the JMS resource for the Version 6
default messaging provider.
3. Under Additional Resources, click WebSphere topic destinations. This displays a list of any existing
JMS topic destinations.
4. Click the name of the JMS topic destination that you want to work with.

A JMS topic destination for use with the Version 5 default messaging provider has the following properties.

Scope:

Specifies the level to which this resource definition is visible to applications.

Chapter 8. Developing WebSphere applications 1553

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at
multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at
more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse
or change this resource (or other resources) at a different scope, change the scope on the messaging
provider settings panel, then click Apply, before clicking the link for the type of resource.

Data type String

Name:

The name by which the topic is known for administrative purposes within IBM WebSphere Application
Server.

Data type String

JNDI name:

The JNDI name that is used to bind the topic into the application server’s name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the
logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined
by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the
platform.

Data type String

Description:

A description of the topic, for administrative purposes within IBM WebSphere Application Server.

Data type String

Default Null

Category:

A category used to classify or group this topic, for your IBM WebSphere Application Server administrative
records.

Data type String

Topic:

The name of the topic as defined to the JMS provider.

Data type String

Default Null
Range The topic value can be dot notation and include wildcard
characters.

1554 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Persistence:

Whether all messages sent to the destination are persistent, non-persistent, or have their persistence
defined by the application

Data type Enum

Default APPLICATION DEFINED
Range APPLICATION DEFINED
Messages on the destination have their
persistence defined by the application that put
them onto the queue.
NON-PERSISTENT
Messages on the destination are not persistent.
PERSISTENT
Messages on the destination are persistent.

Priority:

Whether the message priority for this destination is defined by the application or the Specified priority
property

Data type Enum

Units Not applicable
Default APPLICATION DEFINED
Range APPLICATION DEFINED
The priority of messages on this destination is
defined by the application that put them onto the
destination.
QUEUE DEFINED
[WebSphere MQ destination only] Messages on
the destination have their persistence defined by
the WebSphere MQ queue definition properties.
SPECIFIED
The priority of messages on this destination is
defined by the Specified priority property. If you
select this option, you must define a priority on
the Specified priority property.

Specified priority:

If the Priority property is set to Specified, type here the message priority for this queue, in the range 0
(lowest) through 9 (highest)

If the Priority property is set to Specified, messages sent to this queue have the priority value specified
by this property.

Data type Integer

Units Message priority level
Default 0
Range 0 (lowest priority) through 9 (highest priority)

Expiry:

Whether the expiry timeout for this queue is defined by the application or the Specified expiry property, or
messages on the queue never expire (have an unlimited expiry timeout)

Chapter 8. Developing WebSphere applications 1555

Data type Enum
Units Not applicable
Default APPLICATION DEFINED
Range APPLICATION DEFINED
The expiry timeout for messages on this queue is
defined by the application that put them onto the
queue.
UNLIMITED
Messages on this queue have no expiry timeout,
so those messages never expire.
SPECIFIED
The expiry timeout for messages on this queue is
defined by the Specified expiry property. If you
select this option, you must define a timeout on
the Specified expiry property.

Specified expiry:

If the Expiry timeout property is set to Specified, type here the number of milliseconds (greater than 0)
after which messages on this queue expire

Data type Integer

Units Milliseconds
Default 0
Range Greater than or equal to 0
v 0 indicates that messages never timeout
v Other values are an integer number of milliseconds

Configuring Version 5 default JMS resources

Use the following tasks to configure the JMS connection factories and destinations WebSphere application
server version 5 applications.

You only need to complete these tasks if you have WebSphere application server version 5 applications
that need to use JMS resources provided by the default messaging provider. Such JMS resources are
maintained as V5 Default Messaging resources.

In a deployment manager cell, you can use V5 Default Messaging resources to maintain Version 5 default
messaging resources for both version 6 and version 5 nodes in the cell.
v Configuring a Version 5 default JMS queue connection factory
v Configuring a Version 5 default JMS topic connection factory
v Configuring a Version 5 default JMS queue destination
v Configuring a Version 5 default JMS topic destination

Configuring a Version 5 queue connection factory:

Use this task to browse or change the properties of a JMS queue connection factory for point-to-point
messaging with the default messaging provider on a Version 5 node in the deployment manager cell. This
task contains an optional step for you to create a new JMS queue connection factory.

To configure a JMS queue connection factory for use by WebSphere application server version 5
applications, use the administrative console to complete the following steps:
1. Display the version 5 default messaging provider. In the navigation pane, expand Resources → JMS
Providers → V5 Default Messaging.

1556 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Optional: Change the Scope setting to the level at which the JMS queue connection factory is visible
to applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the cell can
look up and use that JMS resource.
3. In the content pane, under Additional Properties, click WebSphere queue connection factories This
displays any existing JMS queue connection factories for the Version 5 messaging provider in the
content pane.
4. To browse or change an existing JMS queue connection factory, click its name in the list. Otherwise, to
create a new connection factory, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this JMS queue connection factory is known for administrative
purposes within IBM WebSphere Application Server.
JNDI Name
The JNDI name that is used to bind the JMS queue connection factory into the name
space.
c. Click Apply. This defines the JMS queue connection factory to WebSphere Application Server, and
enables you to browse or change additional properties.
5. Optional: Change properties for the queue connection factory, according to your needs.
6. Click OK.
7. Save any changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the application server.

Configuring a Version 5 JMS topic connection factory:

Use this task to browse or change a JMS topic connection factory for publish/subscribe messaging by
WebSphere application server version 5 applications.

To configure a JMS topic connection factory for use by WebSphere application server version 5
applications, use the administrative console to complete the following steps:
1. Display the version 5 default messaging provider. In the navigation pane, expand Resources → JMS
Providers → V5 Default Messaging.
2. Optional: Change the Scope setting to the level at which the JMS topic connection factory is visible to
applications. If you define a Version 5 JMS resource at the Cell scope level, all users in the cell can
look up and use that JMS resource.
3. In the content pane, under Additional Properties, click WebSphere topic connection factories This
displays any existing JMS topic connection factories for the Version 5 messaging provider in the
content pane.
4. To browse or change an existing JMS topic connection factory, click its name in the list. Otherwise, to
create a new connection factory, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this JMS topic connection factory is known for administrative purposes
within IBM WebSphere Application Server.
JNDI Name
The JNDI name that is used to bind the JMS topic connection factory into the name space.
c. Click Apply. This defines the JMS topic connection factory to WebSphere Application Server, and
enables you to browse or change additional properties.
5. Optional: Change properties for the topic connection factory, according to your needs.

Chapter 8. Developing WebSphere applications 1557

6. Click OK.
7. Save any changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the application server.

Configuring a Version 5 WebSphere queue destination:

Use this task to browse or change the properties of a JMS queue destination for point-to-point messaging
by WebSphere Application Server version 5 applications. This task contains an optional step for you to
create a new topic destination.

To configure a JMS queue destination for use by WebSphere application server version 5 applications, use
the administrative console to complete the following steps:
1. Display the version 5 default messaging provider. In the navigation pane, expand Resources → JMS
Providers → V5 Default Messaging.
2. Optional: Change the Scope setting to the level at which the JMS destination is visible to applications.
If you define a Version 5 JMS resource at the Cell scope level, all users in the cell can look up and
use that JMS resource.
3. In the content pane, under Additional Properties, click WebSphere queue destinations This displays
any existing queue destinations for the Version 5 default messaging provider in the content pane.
4. To browse or change an existing JMS queue destination, click its name in the list. Otherwise, to create
a new queue destination, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this queue destination is known for administrative purposes within IBM
WebSphere Application Server.
JNDI Name
The JNDI name that is used to bind the queue destination into the name space.
c. Click Apply. This defines the queue destination to WebSphere Application Server, and enables you
to browse or change additional properties.
5. Optional: Change properties for the queue destination, according to your needs.
6. Click OK.
7. Save any changes to the master configuration.
8. To make a queue destination available to applications, you need to host the queue on a JMS server.
To add a new queue to a JMS server or to change an existing queue on a JMS server, you define the
administrative name of the queue to the JMS server, as described in Managing Version 5 JMS servers
in a deployment manager cell.
9. To have the changed configuration take effect, stop then restart the application server.

Configuring a version 5 WebSphere topic destination:

Use this task to browse or change the properties of a JMS topic destination for publish/subscribe
messaging by WebSphere application server version 5 applications.. This task contains an optional step
for you to create a new topic destination.

To configure a JMS topic destination for use WebSphere application server version 5 applications, use the
administrative console to complete the following steps:
1. Display the version 5 default messaging provider. In the navigation pane, expand Resources → JMS
Providers → V5 Default Messaging.

1558 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
2. Optional: Change the Scope setting to the level at which the JMS destination is visible to applications.
If you define a Version 5 JMS resource at the Cell scope level, all users in the cell can look up and
use that JMS resource.
3. In the content pane, under Additional Properties, click WebSphere topic destinations This displays
any existing JMS topic destinations for the Version 5 default messaging provider in the content pane.
4. To browse or change an existing JMS topic destination, click its name in the list. Otherwise, to create a
new topic destination, complete the following steps:
a. Click New in the content pane.
b. Specify the following required properties. You can specify other properties, as described in a later
step.
Name The name by which this topic destination is known for administrative purposes within IBM
WebSphere Application Server.
JNDI Name
The JNDI name that is used to bind the topic destination into the name space.
Topic The name of the topic in the default messaging provider, to which messages are sent.
c. Click Apply. This defines the topic destination to WebSphere Application Server, and enables you
to browse or change additional properties.
5. Optional: Change properties for the topic destination, according to your needs.
6. Click OK.
7. Save any changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the application server.

Managing Version 5 JMS servers in a deployment manager cell

Use this task to manage JMS servers on WebSphere Application Server version 5 nodes in a deployment
manager cell.

The use of JMS servers is only intended to support migration from WebSphere Application Server version
5 nodes to WebSphere Application Server version 6.

In a WebSphere Application Server deployment manager cell, each Version 5 node can have at most one
JMS server, and any Version 5 application server within the cell can use JMS resources served by any of
those JMS servers. Applications on WebSphere Application Server version 6 can also use JMS resources
served by any of those JMS servers.

You can use the WebSphere administrative console to display a list of all version 5 JMS servers, to show
and control their runtime status. You can also configure a general set of JMS server properties, which add
to the default values of properties configured automatically for the version 5 default messaging provider.

Note: In general, the default values of properties for the version 5 default messaging provider are
adequate for JMS servers. However, if you are running high messaging loads, you may need to
change some WebSphere MQ properties; for example, WebSphere MQ properties for log file
locations, file pages, and buffer pages. For more information about configuring WebSphere MQ
properties, see the WebSphere MQ System Administration book, SC33-1873, which is available
from the IBM Publications Center or from the WebSphere MQ collection kit, SK2T-0730.

To manage a version 5 JMS server, use the administrative console to complete the following steps:
1. In the navigation pane, select Servers → JMS Servers This displays a table of the JMS servers,
showing their runtime status.
2. Optional: If you want to change the runtime status of a JMS server, complete the following steps:
a. In the table of JMS servers, select the JMS servers that you want to act on.
v To act on one or more specific JMS servers, select the check box next to the JMS server name.
v To act on all JMS servers, select the check box next to the JMS servers title of the table.
Chapter 8. Developing WebSphere applications 1559
 b. Click one of the actions displayed to change the status of the JMS servers; for example, click Stop
to stop a JMS server.
The status of the JMS servers that you have acted on is updated to show the result of your actions.
3. Optional: If you want to change the properties of a JMS server, complete the following steps:
a. Click the name of the server
b. Set one or more of the following configuration properties:
Initial state
If you want the JMS server to be started automatically when the application server is next
started, set this property to Started.
Number of threads
Set the number of concurrent threads to be used by the publish/subscribe matching
engine. The number of concurrent threads should only be set to a small number.
4. Optional: If you want the JMS server to host a new JMS queue, add the queue name to the Queue
Names field.
The name must match the name of a JMS Queue administrative object, including the use of upper-
and lowercase.
5. Optional: If you want to stop the JMS server hosting a JMS queue, remove the queue name from the
Queue Names field.
6. Click OK.
7. Save your changes to the master configuration.
8. To have the changed configuration take effect, stop then restart the JMS server.

Configuring authorization security for a Version 5 default messaging provider

Use this task to configure authorization security for the default messaging provider on a WebSphere
Application Server version 5 node in a deployment manager cell.

To configure authorization security for the version 5 default messaging provider complete the following
steps.

Note: Security for the version 5 default messaging provider is enabled when you enable global security
for WebSphere Application Server on the version 5 node. For more information about enabling
global security, see Managing secured applications.
1. Configure authorization settings to access JMS resources owned by the embedded WebSphere JMS
provider. Authorization to access JMS resources owned by the embedded WebSphere JMS provider is
controlled by settings in the WAS_install_root\config\cells\your_cell_name\integral-jms-
authorizations.xml file.
The settings grant or deny authenticated userids access to internal JMS provider resources (queues or
topics). As supplied, the integral-jms-authorisations.xml file grants the following permissions:
v Read and write permissions to all queues.
v Pub, sub, and persist to all topics.
To configure authorization settings, edit the integral-jms-authorisations.xml file according to the
information in this topic and in that file. Please note the file is in Unicode, which requires a binary FTP
to the host from a workstation.
2. Edit the queue-admin-userids element to create a list of userids with administrative access to all
queues. Administrative access is needed to create queues and perform other administrative activities
on queues. For example, consider the following queue-admin-userids section:
<queue-admin-userids>
<userid>adminid1</userid>
<userid>adminid2</userid>
</queue-admin-userids>

1560 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 In this example the userids adminid1 and adminid2 are defined to have administrative access to all
queues.
3. Edit the queue-default-permissions element to define the default queue access permissions. These
permissions are used for queues for which you do not define specific permissions (in queue sections).
If this section is not specified, then access permissions exist only for those queues for which you have
specifically created queue elements.
For example, consider the following queue-default-permissions element:
<queue-default-permissions>
<permission>write</permission>
</queue-default-permissions>
In this example the default access permission for all queues is write. This can be overridden for a
specific queue by creating a queue element that sets its access permission to read.
4. If you want to define specific access permissions for a queue, create a queue element, then define the
following elements:
For example, consider the following queue element:
<queue>
<name>q1</name>
<public>
</public>
<authorize>
<userid>useridr</userid>
<permission>read</permission>
</authorize>
<authorize>
<userid>useridw</userid>
<permission>write</permission>
</authorize>
<authorize>
<userid>useridrw</userid>
<permission>read</permission>
<permission>write</permission>
</authorize>
</queue>
In this example for the queue q1, the userid useridr has read permission, the userid useridw has write
permission, the userid useridrw has both read and write permissions, and all other userids have no
access permissions (<public></public>).
5. Edit topic elements to define the access permissions for publish/subscribe topic destinations.
For topics, you can grant and deny access permissions. Full permission inheritance is supported on
topics. If you do not define specific access permissions for a userid on a specific topic then
permissions are inherited first from the public permissions on that topic then from the parent topic. The
inheritance of access permissions continues until the root topic from which the root permissions are
assumed.
a. If you want to define default access permissions for the root topic, edit a topic element with an
empty name element. If you omit such a topic section, topics have no default topic permissions
other than those defined by specific topic elements. For example, consider the following topic
element for the root topic:
<topic>
<name></name>
<public>
<permission>+pub</permission>
</public>
</topic>
In this example, the default access permission for all topics is set to publish. This can be
overridden by other topic elements for specific topic names.
b. If you want to define access permissions for a specific topic, create a topic element with the name
for the topic then define the access permissions in the public and authorize elements of the topic
element. For example, consider the following topic section:

Chapter 8. Developing WebSphere applications 1561

 <topic>
<name>a/b/c</name>
<public>
<permission>+sub</permission>
</public>
<authorize>
<userid>useridpub</userid>
<permission>+pub</permission>
</authorize>
</topic>
In this example, the subscribe permission is granted to anyone accessing any topic whose name
starts with a/b/c. Also, the userid useridpub is granted publish permission for any topic whose
name starts with a/b/c.
6. Save the integral-jms-authorizations.xml file.

If the dynamic update setting is selected, changes to the integral-jms-authorizations.xml file become active
when the changed file is saved, so there is no need to stop and restarted the JMS server. If the dynamic
update setting is not selected, you need to stop and restart the JMS server to make changes active.

Authorization settings for Version 5 default JMS resources:

Use the integral-jms-authorisations.xml file to view or change the authorization settings for JMS resources
owned by the default messaging provider on WebSphere Application Server version 5 nodes.

Authorization to access default JMS resources owned by the default messaging provider on WebSphere
Application Server nodes is controlled by the following settings in the
was_install\config\cells\your_cell_name\integral-jms-authorisations.xml file.

This structure of the settings in integral-jms-authorisations.xml is shown in the following example.

Descriptions of these settings are provided after the example. To configure authorization settings, follow
the instructions provided in Configuring authorization security for the Version 5 JMS providers
<integral-jms-authorizations>

<dynamic-update>true</dynamic-update>

<queue-admin-userids>
<userid>adminid1</userid>
<userid>adminid2</userid>
</queue-admin-userids>

<queue-default-permissions>
<permission>write</permission>
</queue-default-permissions>

<queue>
<name>q1</name>
<public>
</public>
<authorize>
<userid>useridr</userid>
<permission>read</permission>
</authorize>
<authorize>
<userid>useridw</userid>
<permission>write</permission>
</authorize>
</queue>

<queue>
<name>q2</name>
<public>
<permission>write</permission>

1562 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 </public>
<authorize>
<userid>useridr</userid>
<permission>read</permission>
</authorize>
</queue>

<topic>
<name></name>
<public>
<permission>+pub</permission>
</public>
</topic>

<topic>
<name>a/b/c</name>
<public>
<permission>+sub</permission>
</public>
<authorize>
<userid>useridpub</userid>
<permission>+pub</permission>
</authorize>
</topic>

</integral-jms-authorizations>

dynamic-update: Controls whether or not the JMS Server checks dynamically for updates to this file.
true (Default) Enables dynamic update support.
false Disables dynamic update checking and improves authorization performance.

queue-admin-userids: This element lists those userids with administrative access to all Version 5 default
queue destinations. Administrative access is needed to create queues and perform other administrative
activities on queues. You define each userid within a separate userid sub element:
<userid>adminid</userid>
Where adminid is a user ID that can be authenticated by IBM WebSphere Application Server.

queue-default-permissions: This element defines the default queue access permissions that are assumed
if no permissions are specified for a specific queue name. These permissions are used for queues for
which you do not define specific permissions (in queue elements). If this element is not specified, then no
access permissions exist unless explicitly authorized for individual queues.

You define the default permission within a separate permission sub element:
<permission>read-write</permission>
Where read-write is one of the following keywords:
read By default, userids have read access to Version 5 default queue destinations.
write By default, userids have write access to Version 5 default queue destinations.

queue: This element contains the following authorization settings for a single queue destination:
name The name of the queue.
public The default public access permissions for the queue. This is used only for those userids that have
no specific authorize element. If you leave this element empty, or do not define it at all, only those
userids with authorize elements can access the queue.
You define each default permission within a separate permission element.
authorize
The access permissions for a specific userid. Within each authorize element, you define the
following elements:
userid The userid that you want to assign a specific access permission.
permission
An access permission for the associated userid.

Chapter 8. Developing WebSphere applications 1563

 You define each permission within a separate permission element. Each permission
element can contain the keyword read or write to define the access permission.

For example, consider the following queue element:

<queue>
<name>q1</name>
<public>
</public>
<authorize>
<userid>useridr</userid>
<permission>read</permission>
</authorize>
<authorize>
<userid>useridw</userid>
<permission>write</permission>
</authorize>
<authorize>
<userid>useridrw</userid>
<permission>read</permission>
<permission>write</permission>
</authorize>
</queue>

topic: This element contains the following authorization settings for a single topic destination:

Each topic element has the following sub elements:

name The name of the topic, without wildcards or other substitution characters.
public The default public access permissions for the topic. This is used only for those userids that have
no specific authorize element. If you leave this element empty, or do not define it at all, only those
userids with authorize elements can access the topic.
You define each default permission within a separate permission element.
authorize
The access permissions for a specific userid. Within each authorize element, you define the
following elements:
userid The userid that you want to assign a specific access permission.
permission
An access permission for the associated userid.
You define each permission within a separate permission element. Each permission
element can contain one of the following keywords to define the access permission:
+pub Grant publish permission
+sub Grant subscribe permission
+persist
Grant persist permission
-pub Deny publish permission
-sub Deny subscribe permission
-persist
Deny persist permission

JMS components on version 5 nodes

To provide messaging support on a WebSphere Application Server version 5 node, there is at most one
JMS server and some number of JMS resources configured for the default messaging JMS provider on
that node.

A JMS server on a version 5 node serves the JMS resources (connection factories and destinations) for
that node. The JMS server is managed as a separate process to application servers on the same node.
Any application server within the domain can access JMS resources served by any JMS server on any
node in the domain.

1564 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
A connection factory encapsulates the configuration properties used to create connections with the JMS
provider, to enable applications to access JMS destinations.

Administering support for message-driven beans

Use these tasks to manage resources used to support message-driven beans. These tasks are in addition
to the tasks for administering resource adapters, JMS providers and the resources they provide.

You can use the WebSphere administrative console to configure the following resources for
message-driven beans:
v J2C activation specifications for JCA 1.5-compliant message-driven beans. Activation specifications
must be provided when the application’s resources are configured using the default messaging provider
or any generic J2C Resource Adapter that supports inbound messaging.
v The message listener service, listener ports, and listeners for EJB 2.0 message-driven beans deployed
against listener ports. Listener ports must be provided when using the JMS providers: V5 Default
Messaging, WebSphere MQ, or Generic.

You can update the configuration data at any time, but some updates only take effect when the
appropriate server is next started.

For information about administering support for message-driven beans, see the following topics:
v Configuring JMS activation specifications, default messaging provider
v “Configuring a J2C activation specification”
v “Configuring a J2C administered object” on page 1568
v Configuring message listener resources for EJB 2.0 message-driven beans

For other information about administering JMS providers and the messaging resources they provide, see
the list of related topics.

Configuring a J2C activation specification

Use this task to configure a J2C activation specification used to deploy message-driven beans with an
external resource adapter.

Use this task if you want to use a message-driven bean as a listener on a Java Connector Architecture
(JCA) 1.5 resource adapter other than the default messaging JMS provider.

To configure a J2C activation specification for an external resource adapter, use the administrative console
to complete the following steps. This task contains an optional step for you to create a new activation
specification.
1. Display the external resource adapter. In the navigation pane, click Resources → Resource Adapters
→ adapter_name. This displays in the content pane a table of properties for the external resource
adapter, including links to the types of J2C resources that it provides.
2. Optional: Change the Scope setting to the scope level at which the activation specification is to be
visible to applications, according to your needs.
3. In the content pane, under the Activation specifications heading, click J2C Activation Specifications.
This lists any existing J2C activation specifications for the external resource adapter in the content
pane.
4. Display the properties of the J2C activation specification. If you want to display an existing J2C
activation specification, click one of the names listed.
Alternatively, if you want to create a new J2C activation specification, click New, then specify the
following required properties:
Name Type the name by which the activation specification is known for administrative purposes. The
JNDI name is automatically generated based on the value for the Name property.

Chapter 8. Developing WebSphere applications 1565

 Message listener type
Select the message listener type that this activation specification instance should support. This
list is based on the deployment descriptor of the external resource adapter.
Depending on the external resource adapter, there can be additional required properties that need to
be supplied. To provide values for these properties, click Custom properties. When creating a new
activation specification, you may need to click Apply before this custom property selection is available.
5. Specify properties for the activation specification, according to your needs .
6. Click OK.
7. Save your changes to the master configuration.

J2C Activation Specifications collection:

This page contains a list of J2C activation specifications for a resource adapter configuration and is used
to create new J2C activation specifications, to select J2C activation specifications for configuration
changes, or to delete J2C activation specifications.

Activation specification definitions and classes are provided by a resource adapter when it is installed.
Using this information, the administrator can create and configure J2C activation specifications with JNDI
names that are then available for applications to use. The resource adapter uses a J2C activation
specification to configure a specific endpoint instance. Each application configuring one or more endpoints
must specify the resource adapter that sends messages to the endpoint. The application must use the
activation specification to provide the configuration properties related to the processing of the inbound
messages.

To view this administrative console page, click Resources >Resource Adapters > resource_adapter >
J2C Activation Specifications.

Name:

Specifies the display name of the J2C activation specification instance.

A string with no spaces meant to be a meaningful text identifier for the J2C activation specification.

Data type String

JNDI name:

Specifies the Java Naming and Directory Interface (JNDI) name for the J2C activation specification
instance.

Data type String

Description:

A free-form text string to describe the J2C activation specification instance.

Data type String

Message Listener Type:

The Message Listener Type that is used by this activation specification.

1566 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
The list of available classes is provided by the resource adapter.

Data type String

J2C Activation Specifications settings:

Use this page to specify the settings for a J2C activation specification.

The resource adapter uses a J2C activation specification to configure a specific endpoint instance. Each
application configuring one or more endpoints must specify the resource adapter that sends messages to
the endpoint. The application must use the activation specification to provide the configuration properties
related to the processing of the inbound messages.

To view this administrative console page, click Resources >Resource Adapters > resource_adapter >
J2C Activation Specifications > activation_specification.

Name:

Specifies the display name of the J2C activation specification instance.

A string with no spaces meant to be a meaningful text identifier for the J2C activation specification. Name
is required

Data type String

JNDI name:

Specifies the Java Naming and Directory Interface (JNDI) name for the J2C activation specification
instance.

The JNDI name is required. If you do not specify one, it is created from the Name field. If not specified,
the JNDI name defaults to eis/[name]

Data type String

Description:

A free-form text string to describe the J2C activation specification instance.

Data type String

Authentication alias:

This optional field is used to bind the J2C activation specification to an authentication alias (configured
through the security JAAS screens).

This alias is used to access a user name and password that are set on the configured J2C activation
specification. This field is only meaningful if the J2C activation specification you are configuring has a
UserName and Password field.

Data type Text

Message Listener Type:

Chapter 8. Developing WebSphere applications 1567

The Message Listener Type used by this activation specification.

For new objects, the list of available classes is provided by the resource adapter in a drop-down list. After
you create the activation specification, the field is a read only text field.

Data type Drop-down list or text

Destination JNDIName:

The destination JNDIName field only appears when a message of type javax.jms.Destination with name
Destination is received.

Configuring a J2C administered object

Use this task to configure a J2C administered object used to configure objects with an external resource
adapter.

Use this task if you want to use a message-driven bean as a listener on a Java Connector Architecture
(JCA) 1.5 resource adapter other than the default messaging JMS provider.

To configure a J2C administered object for an external resource adapter, use the administrative console to
complete the following steps. This task contains an optional step for you to create a new administered
object.
1. Display the external resource adapter. In the navigation pane, click Resources → Resource Adapters
→ adapter_name. This displays in the content pane a table of properties for the external resource
adapter, including links to the types of J2C resources that it provides.
2. Optional: Change the Scope setting to the scope level at which the activation specification is to be
visible to applications, according to your needs.
3. In the content pane, under the Activation specifications heading, click J2C Administered Objects. This
lists any existing J2C administered objects for the external resource adapter in the content pane.
4. Display the properties of the J2C administered object. If you want to display an existing J2C
administered object, click one of the names listed.
Alternatively, if you want to create a new J2C administered object, click New, then specify the following
required properties:
Name Type the name by which the J2C administered object is known for administrative purposes.
The JNDI name is automatically generated based on the value for the Name property.
Administered object class
Select the administered object class that this instance should support. This list is based on the
deployment descriptor of the external resource adapter.
Depending on the external resource adapter, there can be additional required properties that need to
be supplied. To provide values for these properties, click Custom properties. When creating a new
administered object, you may need to click Apply before this custom property selection is available.
5. Specify properties for the activation specification, according to your needs .
6. Click OK.
7. Save your changes to the master configuration.

J2C Administered Objects collection:

Use this page to specify administered object settings for a Resource Adapter.

Administered object definitions and classes are provided by a resource adapter when you install it. Using
this information, the administrator can create and configure J2C administered objects with JNDI names
that are then available for applications to use. Some messaging styles may need applications to use

1568 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
special administered objects for sending and synchronously receiving messages (through connection
objects using messaging style specific APIs). It is also possible that administered objects may be used to
perform transformations on an asynchronously received message in a message provider-specific way.
Administered objects can be accessed by a component by using either a resource environment reference
or a message destination reference (preferred).

To view this administered console page, click Resources >Resource Adapters > resource_adapter > J2C
Administered Objects.

JNDI Name:

Specifies the JNDI name of the administered object.

Data type String

Name:

Specifies display name assigned to this administered object.

Data type String

Description:

Specifies a description for the administered object.

Data type String

Administered Object Class:

Specifies the Administered Object class that is associated with this administered object. This class must be
one that is provided by the resource adapter.

Data type String

J2C Administered Object settings:

Use this page to specify the settings for an administered object.

Administered object definitions and classes are provided by a resource adapter when you install it. Using
this information, the administrator can create and configure J2C administered objects with JNDI names
that are then available for applications to use. Some messaging styles may need applications to use
special administered objects for sending and synchronously receiving messages (through connection
objects using messaging style specific APIs). It is also possible that administered objects may be used to
perform transformations on an asynchronously received message in a message provider-specific way.
Administered objects can be accessed by a component by using either a resource environment reference
or a message destination reference (preferred).

To view this administrative console page, click Resources >Resource Adapters > resource_adapter >
J2C Administered Objects > administered_object.

Name:

Specifies the name of the J2C administered object instance.

Chapter 8. Developing WebSphere applications 1569

A string with no spaces meant to be a meaningful text identifier for the administered object. This name is
required.

Data type String

JNDI name:

Specifies the Java Naming and Directory Interface (JNDI) name that this administered object is bound
under.

The JNDI name is required. If you do not specify one, it is created from the Name field. If not specified,
the JNDI name defaults to eis/[name]

Data type String

Description:

Specifies a text description of the J2C administered object instance.

Data type String

Administered Object Class:

For new objects, the list of available classes is provided by the resource adapter in a drop-down list. You
can only select classes from this list.

After you create the administered object, you cannot modify the Administered Object Class; it is read only.

Data type Drop-down list or Text

Configuring message listener resources for message-driven beans

Use the following tasks to configure resources needed by the message listener service to support
message-driven beans for use with a JMS provider that does not have a JCA 1.5 resource adapter.

For JMS messaging, message-driven beans can use a JMS provider that has a JCA 1.5 resource adapter,
such as the default messaging provider that is part of WebSphere Application Server version 6. With a
JCA 1.5 resource adapter, you deploy EJB 2.1 message-driven beans as JCA resources to use a J2C
activation specification. If the JMS provider does not have a JCA 1.5 resource adapter, such as the V5
Default Messaging and WebSphere MQ, you must configure JMS message-driven beans against a listener
port (as in WebSphere Application Server version 5).

If you want to deploy an enterprise application to use JMS message-driven beans with a JMS provider that
does not have a JCA 1.5 resource adapter, use the following task descriptions:
v Configuring the message listener service
v Adding a new listener port
v Configuring a listener port
v Deleting a listener port
v Configuring security for EJB 2.0 message-driven beans
v Administering listener ports

Configuring the message listener service:

Use this task to configure the properties of the message listener service for an application server, to
support message-driven beans deployed against listener ports.

1570 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
If the JMS provider does not have a JCA 1.5 resource adapter, such as the V5 Default Messaging and
WebSphere MQ, you must configure JMS message-driven beans against a listener port (as in WebSphere
Application Server version 5).

If you want to deploy an enterprise application to use message-driven beans with listener ports, you can
use this task to browse or change the configuration of the message listener service for an application
server.

To configure the message listener service for an application server, use the administrative console to
complete the following steps:
1. Display the listener service settings page:
a. In the navigation pane, select Servers → Application Servers
b. In the content pane, click the name of the application server.
c. Under Communications, click Messaging → Message Listener Service
2. Optional: Browse or change the value of properties for the message-driven bean thread pool.
a. Click Thread Pool
b. Change the following properties, to suit your needs:
Minimum size
The minimum number of threads to allow in the pool.
Maximum size
The maximum number of threads to allow in the pool.
Thread inactivity timeout
The number of milliseconds of inactivity that should elapse before a thread is reclaimed. A
value of 0 indicates not to wait and a negative value (less than 0) means to wait forever.

Note: The administrative console does not allow you to set the inactivity timeout to a
negative number. To do this you must modify the value directly in the config.xml file.
Allow thread allocation beyond maximum thread size
Select this check box to enable the number of threads to increase beyond the maximum
size configured for the thread pool.
c. Click OK.
3. Optional: Specify any of the following optional properties that you need, as Custom properties of the
message listener service:
NON.ASF.RECEIVE.TIMEOUT, MQJMS.POOLING.TIMEOUT, MQJMS.POOLING.THRESHOLD,
MAX.RECOVERY.RETRIES, and RECOVERY.RETRY.INTERVAL.
For more information about these custom properties, see Custom Properties.
To browse or change the properties, complete the following steps:
a. Click Custom properties
b. For each custom property, specify a value to suit your needs.
If you have not specified a property before:
1) Click New.
2) Type the name of the property.
3) Type the value of the property.
4) Click OK.
4. Save your changes to the master configuration.
5. To have the changed configuration take effect, stop then restart the Application Server.

Message listener service:

Chapter 8. Developing WebSphere applications 1571

The message listener service is an extension to the JMS functions of the JMS provider. It provides a
listener manager that controls and monitors one or more JMS listeners, which each monitor a JMS
destination on behalf of a deployed message-driven bean.

This panel displays links to the Additional Properties pages for Listener Ports, Thread Pool, and Custom
Properties for the message listener service.

To view this administrative console page, click Servers → Application Servers → application_server →
[Communications] Messaging → Message Listener Service

Custom Properties:

An optional set of name and value pairs for custom properties of the message listener service.

You can use the Custom properties page to define the following properties for use by the message listener
service.
v NON.ASF.RECEIVE.TIMEOUT
v MQJMS.POOLING.TIMEOUT
v MQJMS.POOLING.THRESHOLD
v MAX.RECOVERY.RETRIES
v RECOVERY.RETRY.INTERVAL

Message listener port collection:

The message listener ports configured in the administrative domain

This panel displays a list of the message listener ports configured in the administrative domain. Each
listener port is used with a message-driven bean to automatically receive messages from an associated
JMS destination. You can use this panel to add new listener ports or to change the properties of existing
listener ports. For more information about the property fields for listener ports, see Listener port properties.

To view this administrative console page, click Servers → Application Servers → application_server →
[Messaging] Message Listener Service → Listener Ports

Listener port settings:

A listener port is used to simplify administration of the association between a connection factory,
destination, and deployed message-driven bean.

Use this panel to view or change the configuration properties of the selected listener port.

To view this administrative console page, click Servers → Application Servers → application_server →
[Communications] Messaging → Message Listener Service → Listener Ports → listener_port

Name:

The name by which the listener port is known for administrative purposes.

Data type String

Default Null

Initial state:

The state that you want the listener port to have when the application server is next restarted

1572 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Data type Enum
Units Not applicable
Default Started
Range Started
When the application server is next started, the
listener port is started automatically.
Stopped
When the application server is next started, the
listener port is not started automatically. If
message-driven beans are to use this listener
port on the application server, the system
administrator must start the port manually or
select the Started value of this property then
restart the application server.

Description:

A description of the listener port, for administrative purposes within IBM WebSphere Application Server.

Data type String

Default Null

Connection factory JNDI name:

The JNDI name for the JMS connection factory to be used by the listener port; for example,
jms/connFactory1.

Data type String

Default Null

Destination JNDI name:

The JNDI name for the destination to be used by the listener port; for example, jms/destn1.

You cannot use a temporary destination for late responses.

Data type String

Default Null

Maximum sessions:

Specifies the maximum number of concurrent sessions that a listener can have with the JMS server to
process messages.

Each session corresponds to a separate listener thread and therefore controls the number of concurrently
processed messages. Adjust this parameter when the server does not fully use the available capacity of
the machine and if you do not need to process messages in a specific message order.

Data type Integer

Units Sessions
Default 1
Range 1 through 2147483647

Chapter 8. Developing WebSphere applications 1573

Recommended v If you want to process messages in a strict message
order, set the value to 1, so only one thread is ever
processing messages.
v If you want to process multiple messages
simultaneously (known as “message concurrency”), set
this property to a value greater than 1. Keep this value
as low as possible to prevent overloading client
applications. A good starting point for a 100% JMS
workload with short transaction times is 2 to 4 sessions
per processor. If longer running transactions exist, you
may need more sessions, which should be determined
by experimentation.

Maximum retries:

The maximum number of times that the listener tries to deliver a message before the listener is stopped, in
the range 0 through 2147483647.

The maximum number of times that the listener tries to deliver a message to a message-driven bean
instance before the listener is stopped.

Data type Integer

Units Retry attempts
Default 0 (no retries)
Range 0 (no retries) through 2147483647

Maximum messages:

The maximum number of messages that the listener can process in one transaction.

If the queue is empty, the listener processes each message when it arrives. Each message is processed
within a separate transaction.

For the WebSphere V5 default messaging provider or WebSphere MQ as the JMS provider, if messages
start accumulating on the queue then the listener can start processing messages in batches. For generic
JMS providers, this property value is passed to the JMS provider but the effect depends on the JMS
provider.

Data type Integer

Units Number of messages
Default 1
Range 1 through 2147483647

1574 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Recommended For the WebSphere default messaging providers or
WebSphere MQ as the JMS provider, if you want to
process multiple messages in a single transaction, then
set this value to more than 1. If messages start
accumulating on the queue, then a value greater than 1
enables multiple messages to be batch-processed into a
single transaction, and eliminates much of the overhead of
transactions on JMS messages.
Note:
v If one message in the batch fails processing with an
exception, the entire batch of messages is put back on
the queue for processing.
v Any resource lock held by any of the interactions for the
individual messages are held for the duration of the
entire batch.
v Depending on the amount of processing that messages
need, and if XA transactions are being used, setting a
value greater than 1 can cause the transaction to time
out. If an XA transaction does time out routinely
because processing multiple messages exceeds the
transaction timeout, reduce this property to 1 (to limit
processing to one message per transaction) or increase
your transaction timeout.

Message listener service custom properties:

Use this panel to view or change an optional set of name and value pairs for custom properties of the
message listener service.

To view this administrative console page, click Servers → Application Servers → application_server →
[Communications] Messaging → Message Listener Service → Custom Properties

You can use the Custom properties page to define the following properties for use by the message listener
service.
v NON.ASF.RECEIVE.TIMEOUT
v MQJMS.POOLING.TIMEOUT
v MQJMS.POOLING.THRESHOLD
v MAX.RECOVERY.RETRIES
v RECOVERY.RETRY.INTERVAL

NON.ASF.RECEIVE.TIMEOUT:

The timeout in milliseconds for synchronous message receives performed by message-driven bean listener
sessions in the non-ASF mode of operation.

You should set this property to a non-zero value only if you want to enable the non-ASF mode of operation
for all message-driven bean listeners on the application server.

The message listener service has two modes of operation, Application Server Facilities (ASF) and
non-Application Server Facilities (non-ASF).
v The ASF mode is meant to provide concurrency and transactional support for applications. For
publish/subscribe message-drive beans, the ASF mode provides better throughput and concurrency,
because in the non-ASF mode the listener is single-threaded.

Chapter 8. Developing WebSphere applications 1575

v The non-ASF mode is mainly for use with generic JMS providers that do not support JMS ASF, which is
an optional extension to the JMS specification. The non-ASF mode is also transactional but, because
the path length is shorter than the ASF mode, usually provides improved performance.
Use non-ASF if:
– Your generic JMS provider does not provide JMS ASF support
– You are using message-driven beans with WebSphere topic connections with the DIRECT port,
because the embedded publish/subscribe broker using that port does not support XA transactions or
JMS ASF.
– Message order is a strict requirement

Data type Integer

Units Milliseconds
Default ASF mode (custom property not created)
Range 0 or greater milliseconds
0 non-ASF mode is disabled
1 or more
The timeout in milliseconds for non-ASF
message-driven bean listener synchronous
session receives
Recommended If a transaction timeout occurs, the message must recycle
causing extra work. If you want to use the non-ASF mode,
set this property to lower than the transaction timeout, but
leave spare at least the maximum duration of your
message-driven bean’s onMessage() method. For
example, if your message-driven bean’s onMessage()
method typically takes a maximum of 10 seconds, and the
transaction timeout is set to 120 seconds, you might set
the NON.ASF.RECEIVE.TIMEOUT property to no more
than 110000 (110000 milliseconds, that is 110 seconds).

MQJMS.POOLING.TIMEOUT:

The number of milliseconds after which a connection in the pool is destroyed if it has not been used.

An MQSimpleConnectionManager allocates connections on a most-recently-used basis, and destroys

connections on a least-recently-used basis. By default, a connection is destroyed if it has not been used
for five minutes.

Data type Integer

Units Milliseconds
Default 5 minutes
Range

MQJMS.POOLING.THRESHOLD:

The maximum number of unused connections in the pool.

An MQSimpleConnectionManager allocates connections on a most-recently-used basis, and destroys

connections on a least-recently-used basis. By default, a connection is destroyed if there are more than
ten unused connections in the pool.

Data type Integer

Units Number of connections
Default 10
Range

1576 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
MAX.RECOVERY.RETRIES:

The maximum number of times that the listener service tries to get a message from a listener port before
the associated listener is stopped, in the range 0 through 2147483647.

Data type Integer

Units Retry attempts
Default 0 (no retries)
Range 0 (no retries) through 2147483647

RECOVERY.RETRY.INTERVAL:

The time in seconds between retry attempts by the listener service to get a message from a listener port.

Data type Integer

Units Seconds
Default 10
Range 1 through 2147483647

Creating a new listener port:

Use this task to create a new listener port for the message listener service, so that message-driven beans
can be associated with the port to retrieve messages.

Although you can continue to deploy an EJB 2.0 message-driven bean against a listener port (as in
WebSphere Application Server version 5), you are recommended to deploy such beans as JCA
1.5-compliant resources and to upgrade them to be EJB 2.1 message-driven beans.

If you want to deploy an enterprise application to use EJB 2.0 message-driven beans with listener ports,
use this task to create a new listener port for a message-driven bean to retrieve messages from.

To create a new listener port, use the administrative console to complete the following steps:
1. Display the collection list of listener ports:
a. In the navigation pane, select Servers → Application Servers
b. In the content pane, click the name of the application server.
c. Under Additional Properties, click Message Listener Service
d. Click Listener Ports.
2. Click New.
3. Specify the following required properties:
Name The name by which the listener port is known for administrative purposes.
Connection factory JNDI name
The JNDI name for the JMS connection factory to be used by the listener port; for example,
jms/connFactory1
Destination JNDI name
The JNDI name for the destination to be used by the listener port; for example, jms/destn1.
4. Optional: Change other properties for the listener port, according to your needs.
5. Click OK.
6. Save your changes to the master configuration.
7. To have the changed configuration take effect, stop then restart the application server.

Chapter 8. Developing WebSphere applications 1577

If enabled, the listener port is started automatically when a message-driven bean associated with that port
is installed.

Configuring a listener port:

Use this task to browse or change the properties of an existing listener port, used by message-driven
beans associated with the port to retrieve messages.

Although you can continue to deploy an EJB 2.0 message-driven bean against a listener port (as in
WebSphere Application Server version 5), you are recommended to deploy such beans as JCA
1.5-compliant resources and to upgrade them to be EJB 2.1 message-driven beans.

If you have deployed an enterprise application to use EJB 2.0 message-driven beans with listener ports,
use this task to browse or change the configuration of a listener port that a message-driven bean retrieves
messages from.

To configure the properties of a listener port, use the administrative console to complete the following
steps:
1. Display the collection list of listener ports:
a. In the navigation pane, select Servers → Application Servers
b. In the content pane, click the name of the application server.
c. Under Additional Properties, click Message Listener Service
d. Click Listener Ports.
2. Click the name of the listener port that you want to work with. This displays the properties of the
listener port in the content pane.
3. Optional: Change properties for the listener port, according to your needs.
4. Click OK.
5. Save any changes to the master configuration.
6. To have a changed configuration take effect, stop then restart the application server.

Deleting a listener port:

Use this task to delete a listener port from the message listener service, to prevent message-driven beans
associated with the port from retrieving messages.

To delete a listener port, use the administrative console to complete the following steps:
1. In the navigation pane, select Servers-> Application Servers This displays a table of the application
servers in the administrative domain.
2. In the content pane, click the name of the application server. This displays the properties of the
application server in the content pane.
3. Under Communications, click Messaging → Message Listener Service This displays the Message
Listener Service properties in the content pane.
4. In the content pane, click Listener Ports. This displays a list of the listener ports.
5. In the content pane, select the check box for the listener port that you want to delete.
6. Click Delete. This action stops the port (needed to allow the port to be deleted) then deletes the port.
7. To save your configuration, click Save on the task bar of the Administrative console window.
8. To have the changed configuration take effect, stop then restart the application server.

Configuring security for message-driven beans that use listener ports:

Use this task to configure resource security and security permissions for EJB 2.0 message-driven beans
deployed to use listener ports.

1578 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Messages arriving at a listener port have no client credentials associated with them. The messages are
anonymous.

To call secure enterprise beans from a message-driven bean, the message-driven bean needs to be
configured with a RunAs Identity deployment descriptor. Security depends on the role specified by the
RunAs Identity for the message-driven bean as an EJB component.

For more information about EJB security, see EJB component security. For more information about
configuring security for your application, see Assembling secured applications.

JMS connections used by message-driven beans can benefit from the added security of using J2C
container-managed authentication. To enable the use of J2C container authentication aliases and mapping,
define a J2C container-managed alias on the JMS connection factory definition that the message-driven
bean is using to listen upon (defined by the Connection factory JNDI name property of the listener port).
If defined, the listener uses the container-managed authentication alias for its JMSConnection security
credentials instead of any application-managed alias. To set the container-managed alias, use the
administrative console to complete the following steps:
1. To display the listener port settings, click Servers → Application Servers → application_server →
[Communications] Messaging → Message Listener Service → Listener Ports → listener_port
2. To get the name of the JMS connection factory, look at the Connection factory JNDI name property.
3. Display the JMS connection factory properties. For example, to display the properties of a WebSphere
queue connection factory provided by the default messaging provider, click Resources → JMS
Providers → Default Messaging Provider → → [Content pane] WebSphere Queue Connection
Factories → connection_factory
4. Set the Authentication alias property.
5. Click OK

Administering listener ports:

Use the following tasks to administer listener ports, which each define the association between a
connection factory, a destination, and a message-driven bean.

You can use the WebSphere administrative console to administer listener ports, as described in the
following tasks.
v Adding a new listener port
Use this task to create a new listener port, to specify a new association between a connection factory, a
destination, and a message-driven bean. This enables deployed message-driven beans associated with
the port to retrieve messages from the destination.
v Configuring a listener port
Use this task to browse or change the configuration properties of a listener port.
v Starting a listener port
Use this task to start a listener port manually.
v Stopping a listener port
Use this task to stop a listener port manually.

Note: If configured as enabled, a listener port is started automatically when a message-driven bean
associated with that port is installed. You do not normally need to start or stop a listener port
manually.

Starting a listener port:

Use this task to start a listener port on an application server, to enable the listeners for message-driven
beans associated with the port to retrieve messages.

Chapter 8. Developing WebSphere applications 1579

A listener is active, that is able to receive messages from a destination, if the deployed message-driven
bean, listener port, and message listener service are all started. Although you can start these components
in any order, they must all be in a started state before the listener can retrieve messages.

If configured as enabled, a listener port is started automatically when a message-driven bean associated
with that port is installed. However, you can start a listener port manually, as described in this topic.

When a listener port is started, the listener manager tries to start the listeners for each message-driven
bean associated with the port. If a message-driven bean is stopped, the port is started but the listener is
not started, and remains stopped. If you start a message-driven bean, the related listener is started.

To start a listener port on an application server, use the administrative console to complete the following
steps:
1. If you want the listener for a deployed message-driven bean to be able to receive messages at the
port, check that the message-driven bean has been started.
2. Display the collection list of listener ports:
a. In the navigation pane, select Servers → Application Servers
b. In the content pane, click the name of the application server.
c. Under Additional Properties, click Message Listener Service
d. Click Listener Ports.
3. Select the check box for the listener port that you want to start.
4. Click Start.
5. Save your changes to the master configuration.

Stopping a listener port:

Use this task to stop a listener port on an application server, to prevent the listeners for message-driven
beans associated with the port from retrieving messages.

When you stop a listener port as described in this topic, the listener manager stops the listeners for all
message-driven beans associated with the port.

To stop a listener port on an application server, use the administrative console to complete the following
steps:
1. Display the collection list of listener ports:
a. In the navigation pane, select Servers → Application Servers
b. In the content pane, click the name of the application server.
c. Under Additional Properties, click Message Listener Service
d. Click Listener Ports.
2. Select the check box for the listener port that you want to stop.
3. Click Stop.
4. Save your changes to the master configuration.
5. To have the changed configuration take effect, stop then restart the application server.

Message-driven beans - listener port components: The WebSphere Application Server support for
message-driven beans deployed against listener ports is based on JMS message listeners and the
message listener service, and builds on the base support for JMS. The main components of WebSphere
Application Server support for message-driven beans are described below:

The message listener service is an extension to the JMS functions of the JMS provider and provides a
listener manager, which controls and monitors one or more JMS listeners.

1580 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Each listener monitors either a JMS queue destination (for point-to-point messaging) or a JMS topic
destination (for publish/subscribe messaging).

A connection factory is used to create connections with the JMS provider for a specific JMS queue or topic
destination. Each connection factory encapsulates the configuration parameters needed to create a
connection to a JMS destination.

A listener port defines the association between a connection factory, a destination, and a deployed
message-driven bean. Listener ports are used to simplify the administration of the associations between
these resources.

When a deployed message-driven bean is installed, it is associated with a listener port and the listener for
a destination. When a message arrives on the destination, the listener passes the message to a new
instance of a message-driven bean for processing.

When an application server is started, it initializes the listener manager based on the configuration data.
The listener manager creates a dynamic session thread pool for use by listeners, creates and starts
listeners, and during server termination controls the cleanup of listener message service resources. Each
listener completes several steps for the JMS destination that it is to monitor, including:
v Creating a JMS server session pool, and allocating JMS server sessions and session threads for
incoming messages.
v Interfacing with JMS ASF to create JMS connection consumers to listen for incoming messages.
v If specified, starting a transaction and requesting that it is committed (or rolled back) when the EJB
method has completed.
v Processing incoming messages by invoking the onMessage() method of the specified enterprise bean.

Important file for message-driven beans

The following file in the WAS_HOME/temp directory is important for the operation of the WebSphere
Application Server messaging service, so should not be deleted. If you do need to delete the
WAS_HOME/temp directory or other files in it, ensure that you preserve the following file:
server_name-durableSubscriptions.ser
You should not delete this file, because the messaging service uses it to keep track of durable
subscriptions for message-driven beans. If you uninstall an application that contains a
message-driven bean, this file is used to unsubscribe the durable subscription.

Mail, URLs, and other J2EE resources

Using mail
Using the JavaMail API, a code segment can be embedded in any Java 2 Enterprise Edition (J2EE)
application component, such as an EJB or a servlet, allowing the application to send a message and save
a copy of the mail to the Sent folder.

The following is a code sample that you would embed in a J2EE application:
javax.naming.InitialContext ctx = new javax.naming.InitialContext();

javax.mail.Session mail_session = (javax.mail.Session)

ctx.lookup("java:comp/env/mail/MailSession3");
MimeMessage msg = new MimeMessage(mail_session);

msg.setRecipients(Message.RecipientType.TO,
InternetAddress.parse("[email protected]"));

msg.setFrom(new InternetAddress("[email protected]"));

msg.setSubject("Important message from eEdge.com");

Chapter 8. Developing WebSphere applications 1581

 msg.setText(msg_text);

Transport.send(msg);

Store store = mail_session.getStore();

store.connect();

Folder f = store.getFolder("Sent");

if (!f.exists()) f.create(Folder.HOLDS_MESSAGES);

f.appendMessages(new Message[] {msg});

J2EE applications can use JavaMail APIs by looking up references to logically named mail connection
factories through the java:comp/env/mail subcontext that is declared in the application deployment
descriptor and mapped to installation specific mail session resources. As in the case of other J2EE
resources, this can be done in order to eliminate the need for the application to hard code references to
external resources.
1. Locate a resource through Java Naming and Directory Interface (JNDI). The J2EE specification
considers a mail session instance as a resource, or a factory from which mail transport and store
connections can be obtained. Do not hard code mail sessions (namely, fill up a Properties object, then
use it to create a javax.mai.Session object). Instead, you must follow the J2EE programming model of
configuring resources through the system facilities and then locating them through JNDI lookups.
In the previous sample code, the line javax.mail.Session mail_session = (javax.mail.Session)
ctx.lookup(″java:comp/env/mail/MailSession3″); is an example of not hard coding a mail session
and using a resource name located through JNDI. You can consider the lookup name,
mail/MailSession3, as a soft link to the real resource.
2. Define resource references while assembling your application. See ″Assembling applications″ in the
information center. You must define a resource reference for the mail resource in the deployment
descriptor of the component, because a mail session is referenced in the JNDI lookup. Typically, you
can use an assembly tool shipped with WebSphere Application Server.
When you create this reference, be sure that the name of the reference matches the name used in the
code. For example, the previous code uses java:comp/env/mail/MailSession3 in its lookup. Therefore
the name of this reference must be mail/Session3, and the type of the resource must be
javax.mail.Session. After configuration, the deployment descriptor contains the following entry for the
mail resource reference:
<resource-reference>
<description>description</description>
<res-ref-name>mail/MailSession3</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
3. Configure mail providers and sessions. The sample code references a mail resource, the deployment
descriptor declares the reference, but the resource itself does not exist yet. Now you need to configure
the mail resource that is referenced by your application component. Notice that the mail session you
configure must have both its transport and mail access portions defined; the former required because
the code is sending a message, the latter because it also saves a copy to the local mail store. When
you configure the mail session, you need to specify a JNDI name. This is an important name for
installing your application and linking up the resource references in your application with the real
resources that you configure.
4. Install your application. You can install your application using either the administrative console or the
scripting tool. During installation, WebSphere Application Server inspects all resource references and
requires you to supply a JNDI name for each of them. This is not an arbitrary JNDI name, but the JNDI
name given to a particular, configured resource that is the target of the reference.

1582 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
5. Manage existing mail providers and sessions. You can update and remove mail providers and
sessions.
To update mail providers and sessions:
a. Open the administrative console.
b. Click Resources > Mail Providers in the console navigation tree. Then, click Mail Provider >
mail_provider > Mail Session.
c. Click the mail_provider or mail_session that you want to modify. To remove a mail provider or mail
session, click Remove after making your selection.
d. Click Apply or OK.
e. Save the configuration.
6. Enable debugger for a mail session.

If your application has a client, you can update mail providers and mail sessions using the Application
Client Resource Configuration Tool (ACRCT).

JavaMail API
The JavaMail APIs provide a platform and protocol-independent framework for building Java-based mail
client applications.

WebSphere Application Server supports the JavaMail API, Version 1.2, and the JavaBeans Activation
Framework (JAF) Version 1.0. In WebSphere Application Server, the JavaMail API is supported in all Web
application components, namely:
v Servlets
v JavaServer Pages (JSP) files
v Enterprise beans
v Application clients

The JavaMail APIs are generic for sending and reading mail. They require service providers, known in
WebSphere Application Server as protocol providers, to interact with mail servers that run on pertaining
protocols.

For example, Simple Mail Transfer Protocol (SMTP) is a popular transport protocol for sending mail.
JavaMail applications can connect to an SMTP server and send mail through it by using this SMTP
protocol provider.

In addition to service providers, the JavaMail API requires the Java Application Framework (JAF) to handle
mail content that is not plain text, including Multipurpose Internet Mail Extensions (MIME), URL pages, and
file attachments.

The JavaMail APIs, the JAF, the service providers and the protocols are shipped as part of WebSphere
Application Server using the following Sun licensed packages:
v mail.jar - Contains the JavaMail APIs, and the SMTP, IMAP, and POP3 service providers.
v activation.jar - Contains the JavaBeans Activation Framework.

Mail providers and mail sessions

A JavaMail service provider is a driver that supports JavaMail interaction with mail servers using a
particular mail protocol. WebSphere Application Server includes service providers, also known as protocol
providers, for mail protocols including Simple Mail Transfer Protocol (SMTP), Internet Message Access
Protocol (IMAP), and Post Office Protocol 3 (POP3).

A mail provider encapsulates a collection of protocol providers. For example, WebSphere Application
Server has a built-in mail provider that encompasses the three protocol providers: SMTP, IMAP and POP3.
These protocol providers are installed as the default and suffice for most applications.

Chapter 8. Developing WebSphere applications 1583

If you have a particular application that requires custom protocol providers, you must first follow the steps
outlined in the ″JavaMail API Design Specification, V1.2, Chapter 5 - The Mail Session″ to install your own
protocol providers. See the article, Mail: Resources for learning, for a link to this documentation.

Mail sessions are represented by the javax.mail.Session class. A mail Session object authenticates
users, and controls users’ access to messaging systems.

To create platform-independent applications, use a resource factory reference to create a JavaMail

session. A resource factory is an object that provides access to resources in the deployed environment of
a program using the naming conventions defined by the Java Naming and Directory Interface (JNDI).

Ensure that every mail session is defined under a parent mail provider. Select a mail provider first and
then create your new mail session.

Mail migration tip

Parts of the JavaServer Page (JSP) 1.2 specification change the way the EmailBean class works with
Email.jsp.

The specifications state that the JSP container creates a JSP page implementation class for each JSP
page. The name of the JSP page implementation class is implementation-dependent. The JSP page
implementation object belongs to an implementation-dependent named package which can vary between
one JSP and another; therefore minimal assumptions should be made. The unnamed package should not
be used without explicit import of the class.

Following these specifications, you should place EmailBean.class in a package referred to it by the fully
qualified packageName in Email.jsp. Otherwise, Email.jsp is unable to find EmailBean.class.

JavaMail security permissions best practices

In many of its activities, the JavaMail API needs to access certain configuration files. The JavaMail and
JavaBeans Activation Framework binary packages themselves already contain the necessary configuration
files. However, the JavaMail API allows the user to define user-specific and installation-specific
configuration files to meet special requirements.

The two locations where such configuration files can exist are <user.home>and <java.home>/lib. For
example, if the JavaMail API needs to access a file named mailcap when sending a message, it first tries
to access <user.home>/.mailcap. If that attempt fails, either due to lack of security permission or a
nonexistent file, the API continues to try<java.home> /lib/mailcap. If that attempts also fails, it tries
META-INF/mailcap in the class path, which actually leads to the configuration files contained in the
mail.jar and activation.jar files. WebSphere Application Server uses the general-purpose JavaMail
configuration files contained in the mail.jar and activation.jar files and does not put any mail
configuration files in <user.home>and <java.home>/lib. File read permission for both the mail.jar and
activation.jar files is granted to all applications to ensure proper functioning of the JavaMail API, as
shown in the following segment of the app.policy file:
grant codeBase "file:${application}" {
// The following are required by Java mail
permission java.io.FilePermission "${was.install.root}${/}java${/}jre${/}lib${/}ext${/}mail.jar", "read";
permission java.io.FilePermission "${was.install.root}${/}java${/}jre${/}lib${/}ext${/}activation.jar", "read";
};

JavaMail code attempts to access configuration files at <user.home>and <java.home>/lib causing

AccessControlExceptions to be thrown, since there is no file read permission granted for those two
locations by default. This activity does not affect the proper functioning of the JavaMail API, but you might
see a large amount of JavaMail-related security exceptions reported in the system log, which might swamp
harmful errors that you are looking for. If this situation is a problem, consider adding two more permission
lines to the permission block above. This should eliminate most, if not all, JavaMail-related harmless
security exceptions from the log file. The application permission block in the app.policy file now looks like:

1584 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
 grant codeBase "file:${application}" {
// The following are required by Java mail
permission java.io.FilePermission "${was.install.root}${/}java${/}jre${/}lib${/}ext${/}mail.jar", "read";
permission java.io.FilePermission "${was.install.root}${/}java${/}jre${/}lib${/}ext${/}activation.jar", "read";
permission java.io.FilePermission "${user.home}${/}.mailcap", "read";
permission java.io.FilePermission "${java.home}${/}lib${/}mailcap", "read";
};

Mail: Resources for learning

Use the following links to find relevant supplemental information about the JavaMail API. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of the
information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

Programming model and decisions

v JavaMail documentation

Programming specifications
v JavaMail 1.3 API documentation (Sun Java specifications)

JavaMail support for IPv6

WebSphere Application Server Version 6.0 and its JavaMail component support Internet Protocol Version
6.0 (IPv6), meaning that:
v Both can run on a pure IPv4 network, a pure IPv6 network, or a mixed IPv4 and IPv6 network.
v On either the pure IPv6 network or the mixed network, the JavaMail component works with mail servers
(such as the SMTP mail transfer agent, and the IMAP and POP3 mail stores) that are also IPv6
compatible. Additionally, a JavaMail component that is run on the mixed IPv4 and IPv6 network can
communicate with mail servers using IPv4.

Use of brackets with IPv6 addresses

When you configure a mail session, you can specify the mail server hosts (also known as mail transport
and mail store hosts) with domain-qualified host names or numerical IP addresses. Using host names is
generally the preferred method. If you use IP addresses, however, consider enclosing IPv6 addresses in
square brackets to prevent parsing inaccuracies. See the following example:
[fe80::202:57ff:fec4:2334]

The JavaMail API requires a combination of many host names or IP addresses with a port number, using
the host:port number syntax . This extra colon can cause the port number to be read as part of an IPv6
address. Using brackets prevents your JavaMail implementation from processing the extra characters
erroneously.

Using URL resources within an application

Java 2 Enterprise Edition (J2EE) applications can use Uniform Resource Locators (URLs) by looking up
references to logically named URL connection factories through the java:comp/env/url subcontext, which
is declared in the application deployment descriptor and mapped to installation specific URL resources. As
in the case of other J2EE resources, this can be done in order to eliminate the need for the application to
hard code references to external resources. The process is the same used with other J2EE resources,
such as JDBC objects and JavaMail sessions.
1. Develop an application that relies on naming features.

Chapter 8. Developing WebSphere applications 1585

2. Define resource references while assembling your application. See ″Assembling applications″ in the
information center. A URL resource that uses a built-in protocol, such as HTTP, FTP, or file, can use
the default URL provider. URL resources that use other protocols need to use a custom URL provider.
3. Configure your URL resources within an application.
a. Open the administrative console.
b. Click Resources>URL Providers in the console navigation tree.
c. Click URL_provider>URLs.
4. Optional: Configure URL providers and URLs within an application client using the Application Client
Resource Configuration Tool (ACRCT).
5. Manage URL providers and URL resources used by the deployed application. To update or remove
existing URL configurations:
a. Open the administrative console.
b. Click Resources > URL Providers in the console navigation tree.
c. Click URL Provider > URLs.
d. Select the URL to modify.
e. Modify the URL properties.
f. Click Apply or OK.
To remove URL providers and URLs, after step 2, Click URL_provider > URLs. Select the URL you
want to remove and click Delete. Then, click Apply or OK.

URLs
A Uniform Resource Locator (URL) is an identifier that points to an electronically accessible resource, such
as a directory file on a machine in a network, or a document stored in a database.

URLs appear in the format scheme:scheme_information.

You can represent a scheme as HTTP, FTP, file, or another term that identifies the type of resource and
the mechanism by which you can access the resource.

In a World Wide Web browser location or address box, a URL for a file available using HyperText Transfer
Protocol (HTTP) starts with http:. An example is http://www.ibm.com. Files available using File Transfer
Protocol (FTP) start with ftp:. Files available locally start with file:.

The scheme_information commonly identifies the Internet machine making a resource available, the path
to that resource, and the resource name. The scheme_information for HTTP, FTP and file generally starts
with two slashes (//), then provides the Internet address separated from the resource path name with one
slash (/). For example,

http://www-4.ibm.com/software/webservers/appserv/library.html.

For HTTP and FTP, the path name ends in a slash when the URL points to a directory. In such cases, the
server generally returns the default index for the directory.

URL provider collection

Use this page to create new URL providers to handle URL protocols that are not supported by the IBM
Developer Kit For the Java™ Platform. You also have the option of selecting the default URL provider,
which uses the URL support provided by the kit. Any URL resource with protocols based on Java 2
Standard Edition 1.3.1, such as HyperText Transfer Protocol (HTTP) or File Transfer Protocol (FTP), can
use the default URL provider.

To view this administrative console page, click Resources > URL Providers.

Name:

1586 IBM WebSphere Application Server Network Deployment, Version 6: Administering applications and their environment
Specifies the administrative name for the URL provider.

Description:

Describes the URL provider for your administrative records.

URL provider settings

Use this page create new URL providers.

To view this administrative console page, click Resources > URL Providers > URL_provider.

Name:

Specifies the administrative name for the URL provider.

Description:

Describes the URL provider, for your administrative records.

Class path:

Specifies paths or JAR file names which together form the location for the resource provider classes.

Stream handler class name:

Specifies fully qualified name of a user-defined Java class that extends the java.net.URLStreamHandler
class for a particular URL protocol, such as FTP.

Protocol:

Specifies the protocol supported by this stream handler. For example, NNTP, SMTP, FTP.

URL configuration collection

Use this page to view existing Uniform Resource Locator (URL) configurations, as well as begin
configuring new URLs that point to electronically accessible resources (such as directory files on a
machine in a network, or a document stored in a database).

To view this administrative console page, click Resources > URL Providers > URL_provider > URLs.

Name:

Specifies the display name for the resource.

JNDI Name:

Specifies the JNDI name.

Description:

Specifies the description of the resource.

Category:

Specifies the category string, which you can use to classify or group the resource.

Chapter 8. Developing WebSphere applications 1587

URL configuration settings
Use this page to configure Uniform Resource Locators (URLs) that point to electronically accessible
resources, such as a directory file on a machine in a network, or a document stored in a database.

To view this administrative console page, click Resources > URL Providers > URL_provider > URLs >
URL.

Name:

Specifies the display name for the resource.

JNDI Name:

Specifies the JNDI name.

Description:

Specifies the description of the resource.

Category:

Specifies the category string, which you can use to classify or group the resource.

Spec:

Specifies the string from which to form a URL.

URLs: Resources for learning

Use the following links to find relevant supplemental information about URLs. The information resides on
IBM and non-IBM Internet sites, whose sponsors control the technical accuracy of the information.

These links are provided for convenience. Often, the information is not specific to the IBM WebSphere
Application Server product, but is useful all or in part for understanding the product. When possible, links
are provided to technical papers and Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.

Programming specifications
v W3C Architecture - Naming and Addressing: URIs, URLs
v URL API documentation

Resource environment entries

This topic provides instructions on configuring new resource environment entries, which define
environment resources that are the binding targets for resource-environment-references in an application’s
deployment descriptor.
1. Configure a resource environment provider, which is a library that provides the implementation for a
environment resource factory. Begin by clicking Resources >Resource Environment Providers >
New. (See the New Resource Environment Provider topic for more information.)
2. After saving your resource environment provider, go to the Additional Properties heading and click
Resource environment entries. Click New to define a new resource environment entry. Refer to the
“Resource environment entry settings” on page 1591 to