IBM SDK For Java: Diagnostics Guide Java Jdk1.5

User Manual:

Open the PDF directly: View PDF .
Page Count: 498

Download
Open PDF In Browser	View PDF

IBM Developer Kit and Runtime Environment, Java
Technology Edition, Version 5.0
Version 5 Release 0

Diagnostics Guide




IBM Developer Kit and Runtime Environment, Java
Technology Edition, Version 5.0
Version 5 Release 0

Diagnostics Guide




Note
Before using this information and the product it supports, read the information in “Notices” on page 463.

Twelfth Edition (November 2009)
This edition applies to all the platforms that are included in the IBM Developer Kit and Runtime Environment, Java
2 Technology Edition, Version 5.0 and to all subsequent releases and modifications until otherwise indicated in new
editions. Technical changes made for all the editions of this book are indicated by vertical bars to the left of the
changes.
© Copyright IBM Corporation 2003, 2010.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Figures . . . . . . . . . . . . . . . ix
Tables . . . . . . . . . . . . . . . xi
About the Diagnostics Guide . . . . . xiii
What does the "Java Virtual Machine (JVM)"
Who should read this book . . . . . .
Using this book. . . . . . . . . .
Other sources of information . . . . .
Reporting problems . . . . . . . .
Conventions and terminology . . . . .
How to send your comments . . . . .
Contributors . . . . . . . . . . .
Summary of changes . . . . . . . .

mean? xiii
. . . xiv
. . . xiv
. . . xv
. . . xv
. . . xv
. . . xvi
. . . xvi
. . . xvi

Tilt ratio . . . . . . . . . . . .
How to do heap sizing . . . . . . . .
Initial and maximum heap sizes . . . .
Using verbose:gc . . . . . . . . .
Using fine tuning options. . . . . . .
Interaction of the Garbage Collector with
applications . . . . . . . . . . . .
How to coexist with the Garbage Collector . .
Root set . . . . . . . . . . . .
Thread local heap . . . . . . . . .
Bug reports . . . . . . . . . . .
Finalizers . . . . . . . . . . . .
Manually starting the Garbage Collector. .
Frequently asked questions about the Garbage
Collector . . . . . . . . . . . . .

.
.
.
.
.

.
.
.
.
.

20
21
21
21
22

.
.
.
.
.
.
.

.
.
.
.
.
.
.

22
23
23
23
23
24
25

.

. 26

Part 1. Understanding the IBM
Software Developers Kit (SDK) for
Java . . . . . . . . . . . . . . . . 1

Chapter 3. Class loading . . . . . . . 29

Chapter 1. The building blocks of the
IBM Virtual Machine for Java. . . . . . 3

Chapter 4. Class data sharing . . . . . 33

Java application stack . . . . . . . . .
Components of the IBM Virtual Machine for Java
JVM Application Programming Interface (API)
Diagnostics component . . . . . . . .
Memory management . . . . . . . .
Class loader . . . . . . . . . . .
Interpreter . . . . . . . . . . . .
Platform port layer . . . . . . . . .

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

4
4
5
5
5
6
6
6

Chapter 2. Memory management . . . . 7
Overview of memory management . . . . . . . 7
Object allocation . . . . . . . . . . . . 7
Reachable objects . . . . . . . . . . . . 8
Garbage collection . . . . . . . . . . . 8
Heap sizing problems . . . . . . . . . . 8
Allocation . . . . . . . . . . . . . . . 9
Heap lock allocation . . . . . . . . . . . 9
Cache allocation . . . . . . . . . . . . 9
Large Object Area . . . . . . . . . . . 10
Detailed description of garbage collection . . . . 11
Mark phase . . . . . . . . . . . . . 11
Sweep phase . . . . . . . . . . . . . 14
Compaction phase . . . . . . . . . . . 15
Subpool (AIX, Linux PPC and zSeries, z/OS and
i5/OS only) . . . . . . . . . . . . . 16
Reference objects . . . . . . . . . . . 16
Final reference processing . . . . . . . . 17
JNI weak reference . . . . . . . . . . . 17
Heap expansion . . . . . . . . . . . . 17
Heap shrinkage . . . . . . . . . . . . 18
Generational Concurrent Garbage Collector. . . . 19
Tenure age. . . . . . . . . . . . . . 20
© Copyright IBM Corp. 2003, 2010

The parent-delegation model . . .
Namespaces and the runtime package
Custom class loaders . . . . . .

.
.
.

.
.
.

.
.
.

.
.
.

. 29
. 30
. 31

Chapter 5. The JIT compiler. . . . . . 35
JIT compiler overview . . . . . . . . . .
How the JIT compiler optimizes code. . . . .
Phase 1 - inlining . . . . . . . . . .
Phase 2 - local optimizations . . . . . .
Phase 3 - control flow optimizations . . . .
Phase 4 - global optimizations . . . . . .
Phase 5 - native code generation . . . . .
Frequently asked questions about the JIT compliler

.
.
.
.
.
.
.

35
36
36
36
37
37
37
37

Chapter 6. Java Remote Method
Invocation . . . . . . . . . . . . . 39
The RMI implementation . . . . . . .
Thread pooling for RMI connection handlers
Understanding distributed garbage collection
Debugging applications involving RMI . .

.
.
.
.

.
.
.
.

.
.
.
.

39
40
40
41

Chapter 7. The ORB . . . . . . . . . 43
CORBA. . . . . . . . . . . . . .
RMI and RMI-IIOP . . . . . . . . . .
Java IDL or RMI-IIOP? . . . . . . . .
RMI-IIOP limitations . . . . . . . . .
Further reading . . . . . . . . . . .
Examples of client–server applications . . .
Interfaces . . . . . . . . . . . .
Remote object implementation (or servant) .
Stubs and ties generation . . . . . . .
Server code . . . . . . . . . . .
Summary of major differences between RMI
(JRMP) and RMI-IIOP . . . . . . . .
Using the ORB . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

43
44
44
44
45
45
45
45
46
47

.
.

. 50
. 51

iii

How the ORB works . . . .
The client side . . . . .
The server side . . . . .
Additional features of the ORB .
Portable object adapter . .
Fragmentation . . . . .
Portable interceptors . . .
Interoperable Naming Service

. .
. .
. .
. .
. .
. .
. .
(INS)

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

54
54
59
61
61
63
63
66

Chapter 8. The Java Native Interface
(JNI) . . . . . . . . . . . . . . . . 69
Overview of JNI . . . . . . . . . . . . .
The JNI and the Garbage Collector . . . . . .
Overview of JNI object references . . . . . .
JNI transitions . . . . . . . . . . . .
Copying and pinning . . . . . . . . . . .
Using the isCopy flag . . . . . . . . . .
Using the mode flag . . . . . . . . . .
A generic way to use the isCopy and mode flags
Handling exceptions . . . . . . . . . . .
Synchronization . . . . . . . . . . . . .
Debugging the JNI . . . . . . . . . . . .
JNI checklist . . . . . . . . . . . . . .

Part 2. Submitting problem reports

69
70
70
73
75
75
76
76
76
77
78
79

81

Part 3. Problem determination . . . 83
Chapter 9. First steps in problem
determination . . . . . . . . . . . . 85
Chapter 10. AIX problem determination 87
Setting up and checking your AIX environment
Enabling full AIX core files . . . . . .
General debugging techniques . . . . . .
AIX debugging commands . . . . . .
DBX Plug-in . . . . . . . . . . .
Diagnosing crashes . . . . . . . . .
Documents to gather . . . . . . . .
Locating the point of failure . . . . .
Debugging hangs . . . . . . . . . .
AIX deadlocks . . . . . . . . . .
AIX busy hangs . . . . . . . . .
Poor performance on AIX . . . . . .
Understanding memory usage. . . . . .
32- and 64-bit JVMs . . . . . . . .
The 32-bit AIX Virtual Memory Model . .
The 64-bit AIX Virtual Memory Model . .
Changing the Memory Model (32-bit JVM)
The native and Java heaps . . . . . .
The AIX 32-bit JVM default memory models
Monitoring the native heap. . . . . .
Native heap usage. . . . . . . . .
Specifying MALLOCTYPE . . . . . .
Monitoring the Java heap . . . . . .
Receiving OutOfMemoryError exceptions .
Is the Java or native heap exhausted? . .
Java heap exhaustion . . . . . . . .
Native heap exhaustion . . . . . . .

iv

IBM SDK for Java: Diagnostics Guide

.
.
.
.
.

. 87
. 88
. 89
. 90
. 99
. . 100
. . 100
. . 101
. . 102
. . 102
. . 102
. . 105
. . 105
. . 105
. . 105
. . 106
. . 107
. . 107
108
. . 108
. . 109
. . 110
. . 110
. . 110
. . 111
. . 111
. . 111

AIX fragmentation problems . .
Submitting a bug report . . . .
Debugging performance problems .
Finding the bottleneck . . . .
CPU bottlenecks . . . . . .
Memory bottlenecks . . . . .
I/O bottlenecks. . . . . . .
JVM heap sizing . . . . . .
JIT compilation and performance .
Application profiling . . . . .
MustGather information for AIX . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

112
113
113
113
114
118
118
118
119
119
119

Chapter 11. Linux problem
determination . . . . . . . . . . . 121
Setting up and checking your Linux environment
General debugging techniques. . . . . . .
Using system dump tools . . . . . . .
Examining process information . . . . .
ldd . . . . . . . . . . . . . . .
Tracing tools . . . . . . . . . . .
Debugging with gdb . . . . . . . . .
Diagnosing crashes . . . . . . . . . .
Debugging hangs . . . . . . . . . . .
Debugging memory leaks . . . . . . . .
Debugging performance problems . . . . .
Finding the bottleneck . . . . . . . .
CPU usage . . . . . . . . . . . .
Memory usage . . . . . . . . . . .
Network problems . . . . . . . . .
JVM heap sizing . . . . . . . . . .
JIT compilation and performance . . . . .
Application profiling . . . . . . . . .
MustGather information for Linux . . . . .
Known limitations on Linux . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

121
123
123
124
126
126
127
129
130
131
131
131
131
132
132
133
133
133
134
136

Chapter 12. Windows problem
determination . . . . . . . . . . . 139
Setting up and checking your Windows
environment. . . . . . . . . . . . .
Windows 32-bit large address aware support
General debugging techniques. . . . . . .
System dump . . . . . . . . . . .
Diagnosing crashes in Windows . . . . . .
Data to send to IBM . . . . . . . . .
Debugging hangs . . . . . . . . . . .
Getting a dump from a hung JVM . . . .
Analyzing deadlocks . . . . . . . . .
Debugging memory leaks . . . . . . . .
The Windows memory model . . . . . .
Classifying leaks . . . . . . . . . .
Tracing leaks . . . . . . . . . . .
Using Heapdump to debug memory leaks. .
OutOfMemoryError creating a thread . . . .
Debugging performance problems . . . . .
Finding the bottleneck . . . . . . . .
Windows systems resource usage. . . . .
JVM heap sizing . . . . . . . . . .
JIT compilation and performance . . . . .
Application profiling . . . . . . . . .
MustGather information for Windows . . . .

. 139
140
. 141
. 141
. 142
. 142
. 143
. 143
. 143
. 143
. 143
. 144
. 144
. 145
. 145
. 145
. 145
. 146
. 146
. 146
. 146
. 146

Chapter 13. z/OS problem
determination . . . . . . . . . . . 149
Setting up and checking your z/OS environment
Maintenance. . . . . . . . . . . .
LE settings . . . . . . . . . . . .
Environment variables . . . . . . . .
Private storage usage . . . . . . . . .
Setting up dumps . . . . . . . . . .
General debugging techniques. . . . . . .
Using IPCS commands . . . . . . . .
Using dbx . . . . . . . . . . . .
Interpreting error message IDs . . . . .
Diagnosing crashes . . . . . . . . . .
Documents to gather . . . . . . . . .
Determining the failing function . . . . .
Working with TDUMPs using IPCS . . . .
Debugging hangs . . . . . . . . . . .
The process is deadlocked . . . . . . .
The process is looping . . . . . . . .
The process is performing badly . . . . .
Understanding Memory Usage . . . . . .
Allocations to LE HEAP . . . . . . . .
z/OS virtual storage . . . . . . . . .
OutOfMemoryError exceptions . . . . .
Debugging performance problems . . . . .
Finding the bottleneck . . . . . . . .
z/OS systems resource usage . . . . . .
JVM heap sizing . . . . . . . . . .
JIT compilation and performance . . . . .
Application profiling . . . . . . . . .
MustGather information for z/OS . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

149
149
149
149
149
150
151
152
152
152
153
153
154
156
159
160
160
161
161
161
161
162
163
163
164
164
164
164
164

Chapter 14. IBM i problem
determination . . . . . . . . . . . 167
Determining which VM is in use . . . . . .
Setting up your IBM Technology for Java
Environment . . . . . . . . . . . .
Required Software and Licensing . . . . .
Configuring JAVA_HOME . . . . . . .
Enabling i5/OS PASE core files . . . . .
Setting environment variables for i5/OS PASE
or QShell . . . . . . . . . . . . .
Determining the home directory for a user .
Setting default Java command-line options .
General debugging techniques. . . . . . .
Diagnosing problems at the command line . .
IBM i debugging commands . . . . . . .
Work with Active Jobs (WRKACTJOB) . . .
Work with Job (WRKJOB) . . . . . . .
Work with System Status (WRKSYSSTS) . .
Work with Disk Status (WRKDSKSTS) . . .
Process Status (ps). . . . . . . . . .
Debugger (dbx). . . . . . . . . . .
Debugging performance problems . . . . .
Analyzing CPU bottlenecks. . . . . . .
Analyzing memory problems . . . . . .
Analyzing I/O problems . . . . . . .
Diagnosing crashes . . . . . . . . . .
Checking the system environment . . . .
Finding out about the Java environment . .

. 167
.
.
.
.

167
168
168
169

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

170
171
172
173
173
174
174
174
174
174
175
175
175
176
178
179
182
182
182

Detailed crash diagnosis . . . . . . . .
Diagnosing hangs . . . . . . . . . . .
i5/OS deadlocks . . . . . . . . . .
i5/OS busy hangs . . . . . . . . . .
Understanding memory usage. . . . . . .
The 32-bit i5/OS PASE Virtual memory model
The process and garbage-collected heaps . .
Monitoring the garbage-collected heap . . .
Process heap usage . . . . . . . . .
OutOfMemoryError exceptions . . . . .
Garbage-collected heap exhaustion . . . .
Submitting a bug report . . . . . . . .
Using dbx . . . . . . . . . . . . .
Using the DBX Plug-in for Java . . . . .
Important dbx usage notes and warnings . .
Using dbx to investigate a Java system dump
Starting dbx on a system dump
(core.{date}.{time}.{pid}.dmp) . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.

182
182
183
183
183
183
184
184
184
185
185
185
186
186
187
188

. 188

Chapter 15. Sun Solaris problem
determination . . . . . . . . . . . 189
Chapter 16. Hewlett-Packard SDK
problem determination . . . . . . . 191
Chapter 17. ORB problem
determination . . . . . . . . . . . 193
Identifying an ORB problem . . . . . . .
Debug properties . . . . . . . . . . .
ORB exceptions . . . . . . . . . . .
Completion status and minor codes . . . . .
Java security permissions for the ORB . . . .
Interpreting the stack trace . . . . . . . .
Description string . . . . . . . . . .
Interpreting ORB traces . . . . . . . . .
Message trace . . . . . . . . . . .
Comm traces . . . . . . . . . . .
Client or server. . . . . . . . . . .
Service contexts . . . . . . . . . .
Common problems . . . . . . . . . .
ORB application hangs . . . . . . . .
Running the client without the server running
before the client is started . . . . . . .
Client and server are running, but not naming
service. . . . . . . . . . . . . .
Running the client with MACHINE2 (client)
unplugged from the network . . . . . .
IBM ORB service: collecting data . . . . . .
Preliminary tests . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.

193
194
195
196
197
198
199
199
199
200
201
202
202
202

. 203
. 204
. 204
. 205
. 205

Chapter 18. NLS problem
determination . . . . . . . . . . . 207
Overview of fonts . . . . . . . . . .
Font utilities. . . . . . . . . . . .
Common NLS problem and possible causes .

.
.
.

. 207
. 208
. 209

| Chapter 19. Attach API problem
| determination . . . . . . . . . . . 211

Contents

v

Part 4. Using diagnostic tools . . . 215
Chapter 20. Overview of the available
diagnostics . . . . . . . . . . . . 217
Categorizing the problem . . .
Summary of diagnostic information
Summary of cross-platform tooling
Heapdump analysis tooling .
Cross-platform dump viewer .
JVMTI tools . . . . . . .
JVMPI tools . . . . . . .
JPDA tools . . . . . . .
DTFJ . . . . . . . . .
Trace formatting . . . . .
JVMRI. . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

217
217
219
219
219
219
220
220
220
220
221

Chapter 21. Using dump agents . . . 223
Using the -Xdump option . . . . . .
Merging -Xdump agents. . . . . .
Dump agents . . . . . . . . . .
Console dumps. . . . . . . . .
System dumps . . . . . . . . .
Stack dumps . . . . . . . . .
LE CEEDUMPs. . . . . . . . .
Tool option . . . . . . . . . .
Javadumps . . . . . . . . . .
Heapdumps . . . . . . . . . .
Snap traces . . . . . . . . . .
Dump events . . . . . . . . . .
Advanced control of dump agents . . .
exec option . . . . . . . . . .
file option . . . . . . . . . .
filter option . . . . . . . . . .
opts option . . . . . . . . . .
Priority option . . . . . . . . .
range option. . . . . . . . . .
request option . . . . . . . . .
defaults option . . . . . . . . .
Dump agent tokens . . . . . . . .
Default dump agents . . . . . . . .
Removing dump agents . . . . . . .
Dump agent environment variables . . .
Signal mappings . . . . . . . . .
Windows, Linux, AIX, and i5/OS specifics
z/OS specifics . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

223
225
227
228
228
229
229
230
231
231
232
232
233
233
234
234
235
236
236
237
237
238
238
239
239
241
241
242

Chapter 22. Using Javadump. . . . . 245
Enabling a Javadump. . . . . . . .
Triggering a Javadump . . . . . . .
Interpreting a Javadump . . . . . .
Javadump tags . . . . . . . . .
TITLE, GPINFO, and ENVINFO sections
Storage Management (MEMINFO) . .
Locks, monitors, and deadlocks (LOCKS)
Threads and stack trace (THREADS) .
Classloaders and Classes (CLASSES) .
Environment variables and Javadump . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

245
245
247
247
248
250
252
253
255
256

Chapter 23. Using Heapdump . . . . 257
vi

IBM SDK for Java: Diagnostics Guide

Information for users of previous releases of
Heapdump . . . . . . . . . . . . .
Getting Heapdumps . . . . . . . . . .
Enabling text formatted ("classic") Heapdumps
Available tools for processing Heapdumps . .
Using -Xverbose:gc to obtain heap information .
Environment variables and Heapdump . . . .
Text (classic) Heapdump file format . . . . .

. 257
. 257
258
. 258
. 258
. 258
. 259

Chapter 24. Using system dumps and
the dump viewer . . . . . . . . . . 263
Overview of system dumps . . .
System dump defaults . . . . .
Overview of the dump viewer. . .
Using the dump extractor, jextract
Using the dump viewer, jdmpview
Dump viewer commands . . . .
General commands . . . . .
Working with locks . . . . .
Showing details of a dump . . .
Analyzing the memory . . . .
Working with classes . . . . .
Working with objects . . . . .
Generating Heapdumps . . . .
Working with trace . . . . .
Example session . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

263
264
264
264
266
267
267
269
269
269
270
271
271
272
273

Chapter 25. Tracing Java applications
and the JVM . . . . . . . . . . . . 283
What can be traced? . . . . . . . . .
Types of tracepoint . . . . . . . . .
Default tracing . . . . . . . . . . .
Where does the data go? . . . . . . .
Writing trace data to memory buffers . .
Writing trace data to a file . . . . . .
External tracing . . . . . . . . .
Tracing to stderr . . . . . . . . .
Trace combinations . . . . . . . .
Controlling the trace . . . . . . . . .
Specifying trace options . . . . . . .
Detailed descriptions of trace options . .
Using the Java API . . . . . . . .
Using the trace formatter . . . . . . .
Determining the tracepoint ID of a tracepoint
Application trace . . . . . . . . . .
Implementing application trace . . . .
Using application trace at run time . . .
Using method trace . . . . . . . . .
Running with method trace . . . . .
Untraceable methods . . . . . . . .
Examples of use . . . . . . . . .
Example of method trace output . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

283
284
284
285
286
286
287
287
287
287
288
288
303
304
305
306
306
308
309
309
311
313
314

Chapter 26. JIT problem determination 317
Diagnosing a JIT problem . . . . . .
Disabling the JIT compiler . . . . .
Selectively disabling the JIT compiler .
Locating the failing method . . . .
Identifying JIT compilation failures . .
Performance of short-running applications

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

317
317
318
319
320
321

JVM behavior during idle periods

.

.

.

.

.

. 321

Chapter 27. The Diagnostics Collector 323
Introduction to the Diagnostics Collector . . . .
Using the Diagnostics Collector . . . . . . .
Collecting diagnostics from Java runtime problems
Verifying your Java diagnostics configuration. . .
Configuring the Diagnostics Collector . . . . .
Diagnostics Collector settings . . . . . . .
Known limitations. . . . . . . . . . . .

323
323
323
325
325
325
327

Chapter 28. Garbage Collector
diagnostics . . . . . . . . . . . . 329
How do the garbage collectors work? . . .
Common causes of perceived leaks . . . .
Listeners . . . . . . . . . . . .
Hash tables . . . . . . . . . . .
Static class data . . . . . . . . .
JNI references . . . . . . . . . .
Objects with finalizers . . . . . . .
-verbose:gc logging . . . . . . . . .
Global collections . . . . . . . . .
Garbage collection triggered by System.gc()
Allocation failures . . . . . . . . .
Scavenger collections . . . . . . . .
Concurrent garbage collection . . . . .
Timing problems during garbage collection
-Xtgc tracing . . . . . . . . . . .
-Xtgc:backtrace . . . . . . . . . .
-Xtgc:compaction . . . . . . . . .
-Xtgc:concurrent . . . . . . . . .
-Xtgc:dump . . . . . . . . . . .
-Xtgc:excessiveGC . . . . . . . . .
-Xtgc:freelist . . . . . . . . . . .
-Xtgc:parallel . . . . . . . . . .
-Xtgc:references. . . . . . . . . .
-Xtgc:scavenger. . . . . . . . . .
-Xtgc:terse . . . . . . . . . . .
Finding which methods allocated large objects

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.

. 347
. 347
. 348

Chapter 29. Class-loader diagnostics
Class-loader command-line options .
Class-loader runtime diagnostics . .
Loading from native code . . . .

.
.
.

.
.
.

.
.
.

329
329
329
330
330
330
330
330
331
332
333
334
335
339
340
340
341
341
341
342
342
343
343
343
344
344

347

Chapter 30. Shared classes
diagnostics . . . . . . . . . . . . 351
Deploying shared classes . . . . . . .
Cache naming . . . . . . . . . .
Cache access . . . . . . . . . .
Cache housekeeping . . . . . . . .
Cache performance . . . . . . . .
Compatibility between service releases . .
Nonpersistent shared cache cleanup . . .
Dealing with runtime bytecode modification .
Potential problems with runtime bytecode
modification . . . . . . . . . . .
Modification contexts. . . . . . . .
SharedClassHelper partitions . . . . .
Using the safemode option . . . . . .

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

351
351
352
352
353
354
355
356

.
.
.
.

.
.
.
.

356
357
357
357

Further considerations for runtime bytecode
modification . . . . . . . . . . . . .
Understanding dynamic updates . . . . . . .
Using the Java Helper API . . . . . . . . .
SharedClassHelper API . . . . . . . . .
Understanding shared classes diagnostics output
Verbose output . . . . . . . . . . . .
VerboseIO output . . . . . . . . . . .
VerboseHelper output . . . . . . . . .
printStats utility . . . . . . . . . . .
printAllStats utility . . . . . . . . . .
Debugging problems with shared classes . . . .
Using shared classes trace . . . . . . . .
Why classes in the cache might not be found or
stored . . . . . . . . . . . . . . .
Dealing with initialization problems . . . . .
Dealing with verification problems . . . . .
Dealing with cache problems . . . . . . .
Class sharing with OSGi ClassLoading framework

358
358
361
362
363
363
363
364
364
365
366
366
366
367
369
369
370

Chapter 31. Using the Reliability,
Availability, and Serviceability
Interface . . . . . . . . . . . . . 371
Preparing to use JVMRI . .
Writing an agent . . .
Registering a trace listener
Changing trace options .
Starting the agent . . .
Building the agent. . .
Agent design . . . .
JVMRI functions . . . .
API calls provided by JVMRI
CreateThread . . . .
DumpDeregister . . .
DumpRegister . . . .
DynamicVerbosegc . .
GenerateHeapdump . .
GenerateJavacore . . .
GetComponentDataArea.
GetRasInfo . . . . .
InitiateSystemDump . .
InjectOutOfMemory . .
InjectSigSegv . . . .
NotifySignal . . . . .
ReleaseRasInfo . . . .
RunDumpRoutine . . .
SetOutOfMemoryHook .
TraceDeregister . . . .
TraceDeregister50 . . .
TraceRegister . . . .
TraceRegister50 . . . .
TraceResume . . . .
TraceResumeThis . . .
TraceSet . . . . . .
TraceSnap . . . . .
TraceSuspend . . . .
TraceSuspendThis . . .
RasInfo structure . . . .
RasInfo request types. . .
Intercepting trace data . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Contents

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

371
371
372
373
373
373
374
374
375
375
375
375
376
376
376
376
377
377
377
377
378
378
378
379
379
379
379
380
380
380
381
381
381
381
382
382
382

vii

The -Xtrace:external=.
Calling external trace . . . .
Formatting . . . . . . . .

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

. 382
. 383
. 383

Chapter 32. Using the HPROF Profiler

385

Explanation of the HPROF output file .

. 386

.

.

.

Setting an environment variable
Separating values in a list . .
JVM environment settings . .
z/OS environment variables .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

DUMP messages .
J9VM messages. .
SHRC messages .

Chapter 34. Using the Diagnostic Tool
Framework for Java . . . . . . . . 393

Appendix D. Command-line options

.
.

.
.

.
.

.
.

.
.

.
.

.
.

. 393
. 397

Chapter 35. Using JConsole . . . . . 401
Chapter 36. Using the IBM Monitoring
and Diagnostic Tools for Java - Health
Center . . . . . . . . . . . . . . 405

Part 5. Appendixes . . . . . . . . 407
Appendix A. CORBA minor codes

. . 409

Appendix B. Environment variables
Displaying the current environment .

viii

.

IBM SDK for Java: Diagnostics Guide

.

.

413
.

. 413

.
.
.
.

413
414
414
418

Appendix C. Messages . . . . . . . 419

Chapter 33. Using the JVMTI . . . . . 391

Using the DTFJ interface .
DTFJ example application .

.
.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

Specifying command-line options. . .
General command-line options . . .
System property command-line options
JVM command-line options. . . . .
-XX command-line options . . . .
JIT command-line options . . . . .
Garbage Collector command-line options

.
.
.

.
.
.
.
.
.
.

.
.
.

.
.
.
.
.
.
.

.
.
.

. 420
. 424
. 427

.
.
.
.
.
.
.

.
.
.
.
.
.
.

439
439
440
442
444
452
452
453

Appendix E. Default settings for the
JVM . . . . . . . . . . . . . . . 461
Notices . . . . . . . . . . . . . . 463
Trademarks .

.

.

.

.

.

.

.

.

.

.

.

.

. 464

Index . . . . . . . . . . . . . . . 467

Figures
1.

Screenshot of ReportEnv tool .

© Copyright IBM Corp. 2003, 2010

.

.

.

.

. 140

2.

DTFJ interface diagram .

.

.

.

.

.

.

. 396

ix

x

IBM SDK for Java: Diagnostics Guide

Tables
1.

Java subcomponents .

.

© Copyright IBM Corp. 2003, 2010

.

.

.

.

.

.

. 293

xi

xii

IBM SDK for Java: Diagnostics Guide

About the Diagnostics Guide
The Diagnostics Guide tells you about how the IBM® Virtual Machine for Java™
works, debugging techniques, and the diagnostic tools that are available to help
you solve problems with JVMs. It also gives guidance on how to submit problems
to IBM.

What does the "Java Virtual Machine (JVM)" mean?
The Java Virtual machine (JVM) is the application that executes a Java program
and it is included in the Java package.
The installable Java package supplied by IBM comes in two versions on Linux®
and Windows® platforms:
v The Java Runtime Environment (JRE)
v The Java Software Development Kit (SDK)
The AIX®, z/OS®, and IBM i platforms ship only the SDK.
Note: IBM i is the integrated operating environment formerly referred to as IBM
i5/OS®. The documentation might refer to IBM i as i5/OS.
The JRE provides runtime support for Java applications. The SDK provides the
Java compiler and other development tools. The SDK includes the JRE.
The JRE (and, therefore, the SDK) includes a JVM. This is the application that
executes a Java program. A Java program requires a JVM to run on a particular
platform, such as Linux, z/OS, or Windows.
The IBM SDK, Version 5.0 contains a different implementation of the JVM and the
Just-In-Time compiler (JIT) from most earlier releases of the IBM SDK, apart from
the version 1.4.2 implementation on z/OS 64-bit and on AMD64/EM64T platforms.
You can identify this implementation in the output from the java -version
command, which gives these strings for the different implementations:
Implementation

Output

7

IBM J9 VM (build 2.6, JRE 1.7.0 IBM...

6

IBM J9 VM (build 2.4, J2RE 1.6.0 IBM...

5.0

IBM J9 VM (build 2.3, J2RE 1.5.0 IBM...

1.4.2 'classic'

Classic VM (build 1.4.2, J2RE 1.4.2 IBM...

1.4.2 on z/OS 64-bit and
AMD64/EM64T platforms

IBM J9SE VM (build 2.2, J2RE 1.4.2 IBM...

i5/OS 'classic' 1.3.1

java version "1.3.1"
Java(TM) 2 Runtime Environment, Standard Edition (build ...)
Classic VM (build 1.3, build JDK-1.3, native threads, jitc_de)

i5/OS 'classic' 1.4.2

java version "1.4.2"
Java(TM) 2 Runtime Environment, Standard Edition (build ...)
Classic VM (build 1.4, build JDK-1.4, native threads, jitc_de)

i5/OS 'classic' 1.5.0

java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build ...)
Classic VM (build 1.5, build JDK-1.5, native threads, jitc_de)

© Copyright IBM Corp. 2003, 2010

xiii

Implementation

Output

i5/OS 'classic' 1.6.0

java version "1.6.0"
Java(TM) SE Runtime Environment (build ...)
Classic VM (build 1.6, build JDK-1.6, native threads, jitc_de)

For Diagnostics Guides that describe earlier IBM SDKs, see http://www.ibm.com/
developerworks/java/jdk/diagnosis/. For earlier versions of the i5/OS Classic
JVM, see the iSeries® Information Center at http://publib.boulder.ibm.com/
infocenter/iseries/v5r4/.

Who should read this book
This book is for anyone who is responsible for solving problems with Java.

Using this book
Before you can use this book, you must have a good understanding of Software
Developer Kits and the Runtime Environment.
This book is to be used with the IBM SDK and Runtime Environment Version 5.0.
Check the full version of your installed JVM. If you do not know how to do this,
see Chapter 9, “First steps in problem determination,” on page 85. Some of the
diagnostic tools described in this book do not apply to earlier versions.
You can use this book in three ways:
v As an overview of how the IBM Virtual Machine for Java operates, with
emphasis on the interaction with Java. Part 1, “Understanding the IBM Software
Developers Kit (SDK) for Java,” on page 1 of the book provides this information.
You might find this information helpful when you are designing your
application.
v As straightforward guide to determining a problem type, collecting the
necessary diagnostic data, and sending it to IBM. Part 2, “Submitting problem
reports,” on page 81 and Part 3, “Problem determination,” on page 83 of the
book provide this information.
v As the reference guide to all the diagnostic tools that are available in the IBM
Virtual Machine for Java. This information is given in Part 4, “Using diagnostic
tools,” on page 215 of the book.
The parts overlap in some ways. For example, Part 3, “Problem determination,” on
page 83 refers to chapters that are in Part 4, “Using diagnostic tools,” on page 215
when those chapters describe the diagnostics data that is required. You will be able
to more easily understand some of the diagnostics that are in Part 4, “Using
diagnostic tools,” on page 215 if you read the appropriate chapter in Part 1,
“Understanding the IBM Software Developers Kit (SDK) for Java,” on page 1.
The appendixes provide supporting reference information that is gathered into
convenient tables and lists.

xiv

IBM SDK for Java: Diagnostics Guide

Other sources of information
You can obtain additional information about the latest tools, Java documentation,
and the IBM SDKs by following the links.
v For the IBM SDKs, see the downloads at:
http://www.ibm.com/developerworks/java/jdk/index.html
v For articles, tutorials and other technical resources about Java Technology, see
IBM developerWorks® at:
http://www.ibm.com/developerworks/java/
v For Java documentation produced by Sun Microsystems, see:
http://java.sun.com/reference/docs/index.html

Reporting problems
Use the problem determination section to help diagnose your problem, and learn
about available workarounds. If you need to contact IBM service, you might need
to collect some data.
The problem determination section provides guidance on diagnosing and
correcting problems, including known workarounds. See Part 3, “Problem
determination,” on page 83. If you cannot resolve the issue on your own, this
section also tells you what data IBM service needs you to collect. Collect the data
and send a problem report and associated data to IBM service, as described in
Part 2, “Submitting problem reports,” on page 81.

Conventions and terminology
Specific conventions are used to describe methods and classes, and command-line
options.
Methods and classes are shown in normal font:
v The serviceCall() method
v The StreamRemoteCall class
Command-line options are shown in bold. For example:
v -Xgcthreads
Options shown with values in braces signify that one of the values must be
chosen. For example:
-Xverify:{remote | all | none}
with the default underscored.
Options shown with values in brackets signify that the values are optional. For
example:
-Xrunhprof[:help][=...]
In this information, any reference to Sun is intended as a reference to Sun
Microsystems, Inc.
About the Diagnostics Guide

xv

How to send your comments
Your feedback is important in helping to provide accurate and useful information.
If you have any comments about this Diagnostics Guide, you can send them by
e-mail to jvmcookbook@uk.ibm.com. Include the name of the Diagnostics Guide, the
platform you are using, the version of your JVM, and, if applicable, the specific
location of the text you are commenting on (for example, the title of the page).
Do not use this method for sending in bug reports on the JVM. For these, use the
usual methods, as described in Part 2, “Submitting problem reports,” on page 81.

Contributors
This Diagnostics Guide has been put together by members of the Java Technology
Center IBM development and service departments in Hursley, Bangalore, Austin,
Toronto, Ottawa, and Rochester.

Summary of changes
This topic introduces what's new for this Version 5.0 Diagnostics Guide. This
Version 5.0 Diagnostics Guide is based on the Diagnostics Guide for z/OS64 and
AMD64 platforms for the IBM Developer Kit and Runtime Environment, Java 2
Technology Edition, Version 1.4.2, SC34-6359-02.
For Version 5, additional platforms and new diagnostics features have been added.
To help people migrating from Version 1.4.2 or earlier, technical changes made for
the first edition are still indicated by revision bars to the left of the changes.

For the Eleventh edition
The significant changes in this edition are:
v Description of -Dcom.ibm.tools.attach.enable=yes in “System property
command-line options” on page 442.
v Description of Chapter 27, “The Diagnostics Collector,” on page 323 and the
-Xdiagnosticscollector[:settings=] option in “JVM command-line
options” on page 444.

For the tenth edition
The significant changes in this edition are:
v Description of a new dump agent event, called allocation that can be triggered
when a Java object is allocated with a specified size. For more information about
this event, see “Dump events” on page 232.
v Description of
-Dcom.ibm.nio.DirectByteBuffer.AggressiveMemoryManagement=true in
“System property command-line options” on page 442.
v Logging of data now occurs both to the console and to stderr or stdout.

For the ninth edition
The significant changes in this edition are:

xvi

IBM SDK for Java: Diagnostics Guide

v Addition of the JavaReference class to the DTFJ overview diagram, “Using the
DTFJ interface” on page 393.

For the eighth edition
The significant changes in this edition are:
v Description of -Xmxcl in “JVM command-line options” on page 444 and of the
problem it can resolve in “OutOfMemoryError exception when using delegated
class loaders” on page 30.
v Description of -Dsun.timezone.ids.oldmapping in “System property
command-line options” on page 442.

For the seventh edition
The significant changes in this edition are:
v Clarification of the use of jextract and jdmpview on z/OS in “Using the dump
viewer, jdmpview” on page 266
v Correction to the state flags in “Threads and stack trace (THREADS)” on page
253

For the sixth edition
The significant changes for this edition are:
v The addition of -Xdump:events=systhrow in “Dump events” on page 232.
v A clarification of the JVM behavior during idle periods in “JVM behavior during
idle periods” on page 321.
v A clarification of the results of setting the JIT parameter count=0 in “Selectively
disabling the JIT compiler” on page 318.

For the fifth edition
The significant changes for this edition are:
v Error information about va_list for z/OS, in “Debugging the JNI” on page 78.
v A new section, “Text (classic) Heapdump file format” on page 259.

For the fourth edition
The fourth edition was based on the third edition, the Diagnostics Guide for Java 2
Technology Edition Version 5.0, SC34-6650-02. Technical changes made for this
edition are indicated by revision bars to the left of the changes.
The significant changes for the fourth edition are:
v Reorganization of chapters in Part 4, “Using diagnostic tools,” on page 215.

For the third edition
The significant changes for the third edition are:
v A new chapter, Chapter 14, “IBM i problem determination,” on page 167.

For the second edition
The significant changes for the second edition are:
v Improved information about debugging performance problems
About the Diagnostics Guide

xvii

v A new section, “Generational Concurrent Garbage Collector” on page 19
v Reviews of the AIX, Linux, Windows, and z/OS chapters in Part 3, “Problem
determination,” on page 83
v Inclusion of Chapter 15, “Sun Solaris problem determination,” on page 189
v Inclusion of Chapter 16, “Hewlett-Packard SDK problem determination,” on
page 191
v A new section, “Deploying shared classes” on page 351
v A new chapter, Chapter 34, “Using the Diagnostic Tool Framework for Java,” on
page 393

For the first edition
The most significant changes are:
v New chapters:
– Chapter 4, “Class data sharing,” on page 33
– Chapter 10, “AIX problem determination,” on page 87, based on the AIX(R)
chapter in the Diagnostics Guide for the IBM Developer Kit and Runtime
Environment, Java 2 Technology Edition, Version 1.4.2, SC34-6358-02. Revision
bars indicate changes from that chapter.
– Chapter 30, “Shared classes diagnostics,” on page 351
– Chapter 32, “Using the HPROF Profiler,” on page 385
– Chapter 33, “Using the JVMTI,” on page 391
– Appendix C, “Messages,” on page 419
v Much changed chapters:
– Chapter 2, “Memory management,” on page 7
– Part 4, “Using diagnostic tools,” on page 215
– Chapter 22, “Using Javadump,” on page 245
– Chapter 28, “Garbage Collector diagnostics,” on page 329

xviii

IBM SDK for Java: Diagnostics Guide

Part 1. Understanding the IBM Software Developers Kit (SDK)
for Java
The information in this section of the Information Center will give you a basic
understanding of the SDK.
The content provides:
v Background information to explain why some diagnostics work the way they do
v Useful information for application designers
v An explanation of some parts of the JVM
v A set of topics on Garbage collection techniques, which are typically complex
Other sections provide a summary, especially where guidelines about the use of
the SDK are appropriate. This content is not intended as a description of the
design of the SDK, except that it might influence application design or promote an
understanding of why things are done the way that they are.
A section that describes the IBM Object Request Broker (ORB) component is also
available.
The sections in this part are:
v Chapter 1, “The building blocks of the IBM Virtual Machine for Java,” on page 3
v Chapter 2, “Memory management,” on page 7
v Chapter 3, “Class loading,” on page 29
v Chapter 4, “Class data sharing,” on page 33
v Chapter 5, “The JIT compiler,” on page 35
v Chapter 6, “Java Remote Method Invocation,” on page 39
v Chapter 7, “The ORB,” on page 43
v Chapter 8, “The Java Native Interface (JNI),” on page 69

© Copyright IBM Corp. 2003, 2010

1

2

IBM SDK for Java: Diagnostics Guide

Chapter 1. The building blocks of the IBM Virtual Machine for
Java
The IBM Virtual Machine for Java (JVM) is a core component of the Java Runtime
Environment (JRE) from IBM. The JVM is a virtualized computing machine that
follows a well-defined specification for the runtime requirements of the Java
programming language.
The JVM is called "virtual" because it provides a machine interface that does not
depend on the underlying operating system and machine hardware architecture.
This independence from hardware and operating system is a cornerstone of the
write-once run-anywhere value of Java programs. Java programs are compiled into
"bytecodes" that target the abstract virtual machine; the JVM is responsible for
executing the bytecodes on the specific operating system and hardware
combinations.
The JVM specification also defines several other runtime characteristics.
All JVMs:
v Execute code that is defined by a standard known as the class file format
v Provide fundamental runtime security such as bytecode verification
v Provide intrinsic operations such as performing arithmetic and allocating new
objects
JVMs that implement the specification completely and correctly are called
“compliant”. The IBM Virtual Machine for Java is certified as compliant. Not all
compliant JVMs are identical. JVM implementers have a wide degree of freedom to
define characteristics that are beyond the scope of the specification. For example,
implementers might choose to favour performance or memory footprint; they
might design the JVM for rapid deployment on new platforms or for various
degrees of serviceability.
All the JVMs that are currently used commercially come with a supplementary
compiler that takes bytecodes and produces platform-dependent machine code.
This compiler works with the JVM to select parts of the Java program that could
benefit from the compilation of bytecode, and replaces the JVM's virtualized
interpretation of these areas of bytecode with concrete code. This is called
just-in-time (JIT) compilation. IBM's JIT compiler is described in Chapter 5, “The
JIT compiler,” on page 35.
The IBM Virtual Machine for Java contains a number of private and proprietary
technologies that distinguish it from other implementations of the JVM. In this
release, IBM has made a significant change to the JVM and JIT compiler that were
provided in earlier releases, while retaining full Java compliance. When you read
this Diagnostics Guide, bear in mind that the particular unspecified behavior of this
release of the JVM might be different to the behavior that you experienced in
previous releases. Java programmers should not rely on the unspecified behavior
of a particular JRE for this reason.
The diagnostic information in this guide discusses the characteristics of the IBM
JRE that might affect the non-functional behavior of your Java program. This guide
also provides information to assist you with tracking down problems and offers
© Copyright IBM Corp. 2003, 2010

3

advice, from the point of view of the JVM implementer, on how you can tune your
applications. There are many other sources for good advice about Java
performance, descriptions of the semantics of the Java runtime libraries, and tools
to profile and analyze in detail the execution of applications.

Java application stack
A Java application uses the Java class libraries that are provided by the JRE to
implement the application-specific logic. The class libraries, in turn, are
implemented in terms of other class libraries and, eventually, in terms of primitive
native operations that are provided directly by the JVM. In addition, some
applications must access native code directly.
The following diagram shows the components of a typical Java Application Stack
and the IBM JRE.

Java Code

Java Application Stack
Java Application

Java Class
Extensions
Class Libraries

ORB

Native Code

Native Libraries
IBM JVM

NativeOpt.
Packages

User
Native
Exts.

Others

Platform
The JVM facilitates the invocation of native functions by Java applications and a
number of well-defined Java Native Interface functions for manipulating Java from
native code (for more information, see Chapter 8, “The Java Native Interface (JNI),”
on page 69).

Components of the IBM Virtual Machine for Java
The IBM Virtual Machine for Java technology comprises a set of components.
The following diagram shows component structure of the IBM Virtual Machine for
Java:

4

IBM SDK for Java: Diagnostics Guide

JVM API

Diagnostics

Memory
management

Class loader

Interpreter

Platform port layer

JVM Application Programming Interface (API)
The JVM API encapsulates all the interaction between external programs and the
JVM.
Examples of this interaction include:
v Creation and initialization of the JVM through the invocation APIs.
v Interaction with the standard Java launchers, including handling command-line
directives.
v Presentation of public JVM APIs such as JNI and JVMTI.
v Presentation and implementation of private JVM APIs used by core Java classes.

Diagnostics component
The diagnostics component provides Reliability, Availability, and Serviceability
(RAS) facilities to the JVM.
The IBM Virtual Machine for Java is distinguished by its extensive RAS
capabilities. The JVM is designed to be deployed in business-critical operations and
includes several trace and debug utilities to assist with problem determination.
If a problem occurs in the field, it is possible to use the capabilities of the
diagnostics component to trace the runtime function of the JVM and help to
identify the cause of the problem. The diagnostics component can produce output
selectively from various parts of the JVM and the JIT. Part 4, “Using diagnostic
tools,” on page 215 describes various uses of the diagnostics component.

Memory management
The memory management component is responsible for the efficient use of system
memory by a Java application.
Java programs run in a managed execution environment. When a Java program
requires storage, the memory management component allocates the application a
discrete region of unused memory. After the application no longer refers to the

Chapter 1. The building blocks of the IBM Virtual Machine for Java

5

storage, the memory management component must recognize that the storage is
unused and reclaim the memory for subsequent reuse by the application or return
it to the operating system.
The memory management component has several policy options that you can
specify when you deploy the application. Chapter 2, “Memory management,” on
page 7 discusses memory management in the IBM Virtual Machine for Java.

Class loader
The class loader component is responsible for supporting Java's dynamic code
loading facilities.
The dynamic code loading facilities include:
v Reading standard Java .class files.
v Resolving class definitions in the context of the current runtime environment.
v Verifying the bytecodes defined by the class file to determine whether the
bytecodes are language-legal.
v Initializing the class definition after it is accepted into the managed runtime
environment.
v Various reflection APIs for introspection on the class and its defined members.

Interpreter
The interpreter is the implementation of the stack-based bytecode machine that is
defined in the JVM specification. Each bytecode affects the state of the machine
and, as a whole, the bytecodes define the logic of the application.
The interpreter executes bytecodes on the operand stack, calls native functions,
contains and defines the interface to the JIT compiler, and provides support for
intrinsic operations such as arithmetic and the creation of new instances of Java
classes.
The interpreter is designed to execute bytecodes very efficiently. It can switch
between running bytecodes and handing control to the platform-specific
machine-code produced by the JIT compiler. The JIT compiler is described in
Chapter 5, “The JIT compiler,” on page 35.

Platform port layer
The ability to reuse the code for the JVM for numerous operating systems and
processor architectures is made possible by the platform port layer.
The platform port layer is an abstraction of the native platform functions that are
required by the JVM. Other components of the JVM are written in terms of the
platform-neutral platform port layer functions. Further porting of the JVM requires
the provision of implementations of the platform port layer facilities.

6

IBM SDK for Java: Diagnostics Guide

Chapter 2. Memory management
This description of the Garbage Collector and Allocator provides background
information to help you diagnose problems with memory management.
Memory management is explained under these headings:
v “Overview of memory management”
v “Allocation” on page 9
v
v
v
v
v
v

“Detailed description of garbage collection” on page 11
“Generational Concurrent Garbage Collector” on page 19
“How to do heap sizing” on page 21
“Interaction of the Garbage Collector with applications” on page 22
“How to coexist with the Garbage Collector” on page 23
“Frequently asked questions about the Garbage Collector” on page 26

For detailed information about diagnosing Garbage Collector problems, see
Chapter 28, “Garbage Collector diagnostics,” on page 329.
See also the reference information in “Garbage Collector command-line options” on
page 453.

Overview of memory management
Memory management contains the Garbage Collector and the Allocator. It is
responsible for allocating memory in addition to collecting garbage. Because the
task of memory allocation is small, compared to that of garbage collection, the
term “garbage collection” usually also means “memory management”.
This section includes:
v A summary of some of the diagnostic techniques related to memory
management.
v An understanding of the way that the Garbage Collector works, so that you can
design applications accordingly.
The Garbage Collector allocates areas of storage in the heap. These areas of storage
define Java objects. When allocated, an object continues to be live while a reference
(pointer) to it exists somewhere in the JVM; therefore the object is reachable. When
an object ceases to be referenced from the active state, it becomes garbage and can
be reclaimed for reuse. When this reclamation occurs, the Garbage Collector must
process a possible finalizer and also ensure that any internal JVM resources that
are associated with the object are returned to the pool of such resources.

Object allocation
Object allocation is driven by requests by applications, class libraries, and the JVM
for storage of Java objects, which can vary in size and require different handling.
Every allocation requires a heap lock to be acquired to prevent concurrent thread
access. To optimize this allocation, particular areas of the heap are dedicated to a
thread, known as the TLH (thread local heap), and that thread can allocate from its
TLH without having to lock out other threads. This technique delivers the best
© Copyright IBM Corp. 2003, 2010

7

possible allocation performance for small objects. Objects are allocated directly
from a thread local heap. A new object is allocated from this cache without
needing to grab the heap lock. All objects less than 512 bytes (768 bytes on 64-bit
JVMs) are allocated from the cache. Larger objects are allocated from the cache if
they can be contained in the existing cache. This cache is often referred to as the
thread local heap or TLH.

Reachable objects
Reachable objects are found using frames on the thread stack, roots and references.
The active state of the JVM is made up of the set of stacks that represents the
threads, the static fields that are inside Java classes, and the set of local and global
JNI references. All functions that are called inside the JVM itself cause a frame to
be created on the thread stack. This information is used to find the roots. A root is
an object which has a reference to it from outside the heap. These roots are then
used to find references to other objects. This process is repeated until all reachable
objects are found.

Garbage collection
When the JVM cannot allocate an object from the heap because of lack of
contiguous space, a memory allocation fault occurs, and the Garbage Collector is
called.
The first task of the Garbage Collector is to collect all the garbage that is in the
heap. This process starts when any thread calls the Garbage Collector either
indirectly as a result of allocation failure, or directly by a specific call to
System.gc(). The first step is to acquire exclusive control on the virtual machine to
prevent any further Java operations. Garbage collection can then begin.

Heap sizing problems
If the operation of the heap, using the default settings, does not give the best
results for your application, there are actions that you can take.
For the majority of applications, the default settings work well. The heap expands
until it reaches a steady state, then remains in that state, which should give a heap
occupancy (the amount of live data on the heap at any given time) of 70%. At this
level, the frequency and pause time of garbage collection should be acceptable.
For some applications, the default settings might not give the best results. Listed
here are some problems that might occur, and some suggested actions that you can
take. Use verbose:gc to help you monitor the heap.
The frequency of garbage collections is too high until the heap reaches a steady
state.
Use verbose:gc to determine the size of the heap at a steady state and set -Xms
to this value.
The heap is fully expanded and the occupancy level is greater than 70%.
Increase the -Xmx value so that the heap is not more than 70% occupied. The
maximum heap size should, if possible, be able to be contained in physical
memory to avoid paging. For the best performance, try to ensure that the heap
never pages.
At 70% occupancy the frequency of garbage collections is too great.
Change the setting of -Xminf. The default is 0.3, which tries to maintain 30%

8

IBM SDK for Java: Diagnostics Guide

free space by expanding the heap. A setting of 0.4, for example, increases this
free space target to 40%, and reduces the frequency of garbage collections.
Pause times are too long.
Try using -Xgcpolicy:optavgpause. This reduces the pause times and makes
them more consistent when the heap occupancy rises. It does, however, reduce
throughput by approximately 5%, although this value varies with different
applications.
Here are some useful tips:
v Ensure that the heap never pages; that is, the maximum heap size must be able
to be contained in physical memory.
v Avoid finalizers. You cannot guarantee when a finalizer will run, and often they
cause problems. If you do use finalizers, try to avoid allocating objects in the
finalizer method. A verbose:gc trace shows whether finalizers are being called.
v Avoid compaction. A verbose:gc trace shows whether compaction is occurring.
Compaction is usually caused by requests for large memory allocations. Analyze
requests for large memory allocations and avoid them if possible. If they are
large arrays, for example, try to split them into smaller arrays.

Allocation
The Allocator is a component of memory management that is responsible for
allocating areas of memory for the JVM. The task of memory allocation is small,
compared to that of garbage collection.

Heap lock allocation
Heap lock allocation occurs when the allocation request cannot be satisfied in the
existing cache.
For a description of cache allocation, when the request cannot be satisfied, see
“Cache allocation.” As its name implies, heap lock allocation requires a lock and is
therefore avoided, if possible, by using the cache.
If the Garbage Collector cannot find a big enough chunk of free storage, allocation
fails and the Garbage Collector must perform a garbage collection. After a garbage
collection cycle, if the Garbage Collector created enough free storage, it searches
the freelist again and picks up a free chunk. The heap lock is released either after
the object has been allocated, or if not enough free space is found. If the Garbage
Collector does not find enough free storage, it returns OutOfMemoryError.

Cache allocation
Cache allocation is specifically designed to deliver the best possible allocation
performance for small objects.
Objects are allocated directly from a thread local allocation buffer that the thread
has previously allocated from the heap. A new object is allocated from this cache
without the need to grab the heap lock; therefore, cache allocation is very efficient.
All objects less than 512 bytes (768 bytes on 64-bit JVMs) are allocated from the
cache. Larger objects are allocated from the cache if they can be contained in the
existing cache; if not a locked heap allocation is performed.

Chapter 2. Memory management

9

The cache block is sometimes called a thread local heap (TLH). The size of the
TLH varies from 2 KB to 128 KB, depending on the allocation rate of the thread.
Threads which allocate lots of objects are given larger TLHs to further reduce
contention on the heap lock.

Large Object Area
The Large Object Areas (LOA) is an area of the tenure area of the heap set used
solely to satisfy allocations for large objects. The LOA is used when the allocation
request cannot be satisfied in the main area (also known as the small object area
(SOA)) of the tenure heap.
As objects are allocated and freed, the heap can become fragmented in such a way
that allocation can be met only by time-consuming compactions. This problem is
more pronounced if an application allocates large objects. In an attempt to alleviate
this problem, the large object area (LOA) is allocated. A large object in this context
is considered to be any object 64 KB or greater in size. Allocations for new TLH
objects are not considered to be large objects. The large object area is allocated by
default for all GC polices except -Xgcpolicy:subpool (for AIX, Linux PPC and
zSeries®, z/OS, and i5/OS) but, if it is not used, it is shrunk to zero after a few
collections. It can be disabled explicitly by specifying the -Xnoloa command-line
option.

Initialization and the LOA
The LOA boundary is calculated when the heap is initialized, and recalculated
after every garbage collection. The size of the LOA can be controlled using
command-line options: -Xloainitial and -Xloamaximum.
The options take values between 0 and 0.95 (0% thru 95% of the current tenure
heap size). The defaults are:
v -Xloainitial0.05 (5%)
v -Xloamaximum0.5 (50%)

Expansion and shrinkage of the LOA
The Garbage Collector expands or shrinks the LOA, depending on usage.
The Garbage Collector uses the following algorithm:
v If an allocation failure occurs in the SOA:
– If the current size of the LOA is greater than its initial size and if the amount
of free space in the LOA is greater than 70%, reduce by 1% the percentage of
space that is allocated to the LOA.
– If the current size of the LOA is equal to or less than its initial size, and if the
amount of free space in the LOA is greater than 90%:
- If the current size of the LOA is greater than 1% of the heap, reduce by 1%
the percentage of space that is allocated to the LOA.
- If the current size of the LOA is 1% or less of the heap, reduce by 0.1%, the
percentage of space that is allocated to the LOA.
v If an allocation failure occurs on the LOA:
– If the size of the allocation request is greater than 20% of the current size of
the LOA, increase the LOA by 1%.
– If the current size of the LOA is less than its initial size, and if the amount of
free space in the LOA is less than 50%, increase the LOA by 1%.

10

IBM SDK for Java: Diagnostics Guide

– If the current size of the LOA is equal to or greater than its initial size, and if
the amount of free space in the LOA is less than 30%, increase the LOA by
1%.

Allocation in the LOA
The size of the request determines where the object is allocated.
When allocating an object, the allocation is first attempted in the Small Object Area
(SOA). If it is not possible to find a free entry of sufficient size to satisfy the
allocation, and the size of the request is equal to or greater than 64 KB, the
allocation is tried in the LOA again. If the size of the request is less than 64 KB or
insufficient contiguous space exists in the LOA, an allocation failure is triggered.

Detailed description of garbage collection
Garbage collection is performed when an allocation failure occurs in heap lock
allocation, or if a specific call to System.gc() occurs. The thread that has the
allocation failure or the System.gc() call takes control and performs the garbage
collection.
The first step in garbage collection is to acquire exclusive control on the Virtual
machine to prevent any further Java operations. Garbage collection then goes
through the three phases: mark, sweep, and, if required, compaction. The IBM
Garbage Collector (GC) is a stop-the-world (STW) operation, because all
application threads are stopped while the garbage is collected.

Mark phase
In mark phase, all the live objects are marked. Because unreachable objects cannot
be identified singly, all the reachable objects must be identified. Therefore,
everything else must be garbage. The process of marking all reachable objects is
also known as tracing.
The mark phase uses:
v A pool of structures called work packets. Each work packet contains a mark stack.
A mark stack contains references to live objects that have not yet been traced.
Each marking thread refers to two work packets;
1. An input packet from which references are popped.
2. An output packet to which unmarked objects that have just been discovered
are pushed.
References are marked when they are pushed onto the output packet. When the
input packet becomes empty, it is added to a list of empty packets and replaced
by a non-empty packet. When the output packet becomes full it is added to a
list of non-empty packets and replaced by a packet from the empty list.
v A bit vector called the mark bit array identifies the objects that are reachable and
have been visited. This bit array, also known as the mark map, is allocated by the
JVM at startup based on the maximum heap size (-Xmx).The mark bit array
contains one bit for each 8 bytes of heap space. The bit that corresponds to the
start address for each reachable object is set when it is first visited.
The first stage of tracing is the identification of root objects. The active state of the
JVM consists of:
v The saved registers for each thread
v The set of stacks that represent the threads
Chapter 2. Memory management

11

v The static fields that are in Java classes
v The set of local and global JNI references.
All functions that are called in the JVM itself cause a frame on the C stack. This
frame might contain references to objects as a result of either an assignment to a
local variable, or a parameter that is sent from the caller. All these references are
treated equally by the tracing routines.
All the mark bits for all root objects are set and references to the roots pushed to
the output work packet. Tracing then proceeds by iteratively popping a reference
off the marking thread's input work packet and then scanning the referenced object
for references to other objects. If the mark bit is off, there are references to
unmarked objects. The object is marked by setting the appropriate bit in the mark
bit array. The reference is then pushed to the output work packet of the marking
thread. This process continues until all the work packets are on the empty list, at
which point all the reachable objects have been identified.

Mark stack overflow
Because the set of work packets has a finite size, it can overflow and the Garbage
Collector (GC) then performs a series of actions.
If an overflow occurs, the GC empties one of the work packets by popping its
references one at a time, and chaining the referenced objects off their owning class
by using the class pointer field in the object header. All classes with overflow
objects are also chained together. Tracing can then continue as before. If a further
mark stack overflow occurs, more packets are emptied in the same way.
When a marking thread asks for a new non-empty packet and all work packets are
empty, the GC checks the list of overflow classes. If the list is not empty, the GC
traverses this list and repopulates a work packet with the references to the objects
on the overflow lists. These packets are then processed as described above. Tracing
is complete when all the work packets are empty and the overflow list is empty.

Parallel mark
The goal of parallel mark is to increase typical mark performance on a
multiprocessor system, while not degrading mark performance on a uniprocessor
system.
The performance of object marking is increased through the addition of helper
threads that share the use of the pool of work packets. For example, full output
packets that are returned to the pool by one thread can be picked up as new input
packets by another thread.
Parallel mark still requires the participation of one application thread that is used
as the master coordinating agent. The helper threads assist both in the
identification of the root pointers for the collection and in the tracing of these
roots. Mark bits are updated by using host machine atomic primitives that require
no additional lock.
By default, a platform with n processors also has n-1 new helper threads. The
helper threads work with the master thread to complete the marking phase of
garbage collection. You can override the default number of threads by using the
-Xgcthreads option. If you specify a value of 1, the helper threads are not added.
The -Xgcthreads option accepts any value greater than 0, but you gain nothing by
setting it to more than n-1.

12

IBM SDK for Java: Diagnostics Guide

Concurrent mark
Concurrent mark gives reduced and consistent garbage collection pause times
when heap sizes increase.
The GC starts a concurrent marking phase before the heap is full. In the concurrent
phase, the GC scans the roots, i.e. stacks, JNI references, class static fields, and so
on. The stacks are scanned by asking each thread to scan its own stack. These roots
are then used to trace live objects concurrently. Tracing is done by a low-priority
background thread and by each application thread when it does a heap lock
allocation.
While the GC is marking live objects concurrently with application threads
running, it has to record any changes to objects that are already traced. It uses a
write barrier that is run every time a reference in an object is updated. The write
barrier flags when an object reference update has occurred, to force a re-scan of
part of the heap. The heap is divided into 512-byte sections and each section is
allocated a one-byte card in the card table. Whenever a reference to an object is
updated, the card that corresponds to the start address of the object that has been
updated with the new object reference is marked with 0x01. A byte is used instead
of a bit to eliminate contention; it allows marking of the cards using non-atomic
operations. A stop-the-world (STW) collection is started when one of the following
occurs:
v An allocation failure
v A System.gc
v Concurrent mark completes all the marking that it can do
The GC tries to start the concurrent mark phase so that it completes at the same
time as the heap is exhausted. The GC does this by constant tuning of the
parameters that govern the concurrent mark time. In the STW phase, the GC
re-scans all roots and uses the marked cards to see what else must be retraced, and
then sweeps as normal. It is guaranteed that all objects that were unreachable at
the start of the concurrent phase are collected. It is not guaranteed that objects that
become unreachable during the concurrent phase are collected. Objects which
become unreachable during the concurrent phase are referred to as "floating
garbage".
Reduced and consistent pause times are the benefits of concurrent mark, but they
come at a cost. Application threads must do some tracing when they are requesting
a heap lock allocation. The processor usage needed varies depending on how
much idle CPU time is available for the background thread. Also, the write barrier
requires additional processor usage.
The -Xgcpolicy command-line parameter is used to enable and disable concurrent
mark:
-Xgcpolicy: 
The -Xgcpolicy options have these effects:
optthruput
Disables concurrent mark. If you do not have pause time problems (as seen
by erratic application response times), you get the best throughput with
this option. Optthruput is the default setting.
optavgpause
Enables concurrent mark with its default values. If you are having
Chapter 2. Memory management

13

problems with erratic application response times that are caused by normal
garbage collections, you can reduce those problems at the cost of some
throughput, by using the optavgpause option.
gencon
Requests the combined use of concurrent and generational GC to help
minimize the time that is spent in any garbage collection pause.
subpool
Disables concurrent mark. It uses an improved object allocation algorithm
to achieve better performance when allocating objects on the heap. This
option might improve performance on SMP systems with 16 or more
processors. The subpool option is available only on AIX, Linux PPC and
zSeries, z/OS, and i5/OS.

Sweep phase
On completion of the mark phase the mark bit vector identifies the location of all
the live objects in the heap. The sweep phase uses this to identify those chunks of
heap storage that can be reclaimed for future allocations; these chunks are added
to the pool of free space.
A free chunk is identified by examining the mark bit vector looking for sequences
of zeros, which identify possible free space. GC ignores any sequences of zeros that
correspond to a length less than the minimum free size. When a sequence of
sufficient length is found, the GC checks the length of the object at the start of the
sequence to determine the actual amount of free space that can be reclaimed. If this
amount is greater than or equal to the minimum size for a free chunk, it is
reclaimed and added to the free space pool. The minimum size for a free chunk is
currently defined as 512 bytes on 32-bit platforms, and 768 bytes on 64-bit
platforms.
The small areas of storage that are not on the freelist are known as "dark matter",
and they are recovered when the objects that are next to them become free, or
when the heap is compacted. It is not necessary to free the individual objects in the
free chunk, because it is known that the whole chunk is free storage. When a
chunk is freed, the GC has no knowledge of the objects that were in it.

Parallel bitwise sweep
Parallel bitwise sweep improves the sweep time by using available processors. In
parallel bitwise sweep, the Garbage Collector uses the same helper threads that are
used in parallel mark, so the default number of helper threads is also the same and
can be changed with the -Xgcthreads option.
The heap is divided into sections of 256 KB and each thread (helper or master)
takes a section at a time and scans it, performing a modified bitwise sweep. The
results of this scan are stored for each section. When all sections have been
scanned, the freelist is built.

Concurrent sweep
Like concurrent mark, concurrent sweep gives reduced garbage collection pause
times when heap sizes increase. Concurrent sweep starts immediately after a
stop-the-world (STW) collection, and must at least finish a certain subset of its
work before concurrent mark is allowed to kick off, because the mark map used
for concurrent mark is also used for sweeping.
The concurrent sweep process is split into two types of operations:

14

IBM SDK for Java: Diagnostics Guide

v Sweep analysis: Sections of data in the mark map (mark bit array) are analyzed
for ranges of free or potentially free memory.
v Connection: The analyzed sections of the heap are connected into the free list.
Heap sections are calculated in the same way as for parallel bitwise sweep.
An STW collection initially performs a minimal sweep operation that searches for
and finds a free entry large enough to satisfy the current allocation failure. The
remaining unprocessed portion of the heap and mark map are left to concurrent
sweep to be both analyzed and connected. This work is accomplished by Java
threads through the allocation process. For a successful allocation, an amount of
heap relative to the size of the allocation is analyzed, and is performed outside the
allocation lock. In an allocation, if the current free list cannot satisfy the request,
sections of analyzed heap are found and connected into the free list. If sections
exist but are not analyzed, the allocating thread must also analyze them before
connecting.
Because the sweep is incomplete at the end of the STW collection, the amount of
free memory reported (through verbose garbage collection or the API) is an
estimate based on past heap occupancy and the ratio of unprocessed heap size
against total heap size. In addition, the mechanics of compaction require that a
sweep is completed before a compaction can occur. Consequently, an STW
collection that compacts does not have concurrent sweep active during the next
round of execution.
To enable concurrent sweep, use the -Xgcpolicy: parameter optavgpause. It
becomes active along with concurrent mark. The modes optthruput, gencon, and
subpool do not support concurrent sweep.

Compaction phase
When the garbage has been removed from the heap, the Garbage Collector can
consider compacting the resulting set of objects to remove the spaces that are
between them. The process of compaction is complicated because, if any object is
moved, the GC must change all the references that exist to it. The default is not to
compact.
The following analogy might help you understand the compaction process. Think
of the heap as a warehouse that is partly full of pieces of furniture of different
sizes. The free space is the gaps between the furniture. The free list contains only
gaps that are above a particular size. Compaction pushes everything in one
direction and closes all the gaps. It starts with the object that is closest to the wall,
and puts that object against the wall. Then it takes the second object in line and
puts that against the first. Then it takes the third and puts it against the second,
and so on. At the end, all the furniture is at one end of the warehouse and all the
free space is at the other.
To keep compaction times to a minimum, the helper threads are used again.
Compaction occurs if any one of the following is true and -Xnocompactgc has not
been specified:
v -Xcompactgc has been specified.
v Following the sweep phase, not enough free space is available to satisfy the
allocation request.
v A System.gc() has been requested and the last allocation failure garbage
collection did not compact or -Xcompactexplicitgc has been specified.
Chapter 2. Memory management

15

v At least half the previously available memory has been consumed by TLH
allocations (ensuring an accurate sample) and the average TLH size falls below
1024 bytes
v Less than 5% of the active heap is free.
v Less than 128 KB of the heap is free.

Subpool (AIX, Linux PPC and zSeries, z/OS and i5/OS only)
Subpool is an improved GC policy for object allocation that is specifically targeted
at improving the performance of object allocation on SMP systems with 16 or more
processors. You start it with the -Xgcpolicy:subpool command-line option.
The subpool algorithm uses multiple free lists rather than the single free list used
by optavgpause and optthruput. It tries to predict the size of future allocation
requests based on earlier allocation requests. It recreates free lists at the end of
each GC based on these predictions. While allocating objects on the heap, free
chunks are chosen using a "best fit" method, as against the "first fit" method used
in other algorithms. It also tries to minimize the amount of time for which a lock is
held on the Java heap, thus reducing contention among allocator threads.
Concurrent mark is disabled when subpool policy is used. Also, subpool policy
uses a new algorithm for managing the Large Object Area (LOA). Hence, the
subpool option might provide additional throughput optimization for some
applications.

Reference objects
When a reference object is created, it is added to a list of reference objects of the
same type. The referent is the object to which the reference object points.
Instances of SoftReference, WeakReference, and PhantomReference are created by
the user and cannot be changed; they cannot be made to refer to objects other than
the object that they referenced on creation.
If an object has a class that defines a finalize method, a pointer to that object is
added to a list of objects that require finalization.
During garbage collection, immediately following the mark phase, these lists are
processed in a specific order:
1. Soft
2. Weak
3. Final
4. Phantom

Soft, weak, and phantom reference processing
The Garbage Collector (GC) determines if a reference object is a candidate for
collection and, if so, performs a collection process that differs for each reference
type. Soft references are collected if their referent has not been marked for the
previous 32 garbage collection cycles. Weak and phantom references are always
collected if their referent is not marked.
For each element on a list, GC determines if the reference object is eligible for
processing and then if it is eligible for collection.
An element is eligible for processing if it is marked and has a non-null referent
field. If this is not the case, the reference object is removed from the reference list,
resulting in it being freed during the sweep phase.

16

IBM SDK for Java: Diagnostics Guide

If an element is determined to be eligible for processing, GC must determine if it is
eligible for collection. The first criterion here is simple. Is the referent marked? If it
is marked, the reference object is not eligible for collection and GC moves onto the
next element of the list.
If the referent is not marked, GC has a candidate for collection. At this point the
process differs for each reference type. Soft references are collected if their referent
has not been marked for the previous 32 garbage collection cycles. You adjust the
frequency of collection with the -Xsoftrefthreshold option. If there is a shortage of
available storage, all soft references are cleared. All soft references are guaranteed
to have been cleared before the OutOfMemoryError is thrown.
Weak and phantom references are always collected if their referent is not marked.
When a phantom reference is processed, its referent is marked so it will persist
until the following garbage collection cycle or until the phantom reference is
processed if it is associated with a reference queue. When it is determined that a
reference is eligible for collection, it is either queued to its associated reference
queue or removed from the reference list.

Final reference processing
The processing of objects that require finalization is more straightforward.
1. The list of objects is processed. Any element that is not marked is processed by:
a. Marking and tracing the object
b. Creating an entry on the finalizable object list for the object
2. The GC removes the element from the unfinalized object list.
3. The final method for the object is run at an undetermined point in the future
by the reference handler thread.

JNI weak reference
JNI weak references provide the same capability as that of WeakReference objects,
but the processing is very different. A JNI routine can create a JNI Weak reference
to an object and later delete that reference. The Garbage Collector clears any weak
reference where the referent is unmarked, but no equivalent of the queuing
mechanism exists.
Failure to delete a JNI Weak reference causes a memory leak in the table and
performance problems. This also applies to JNI global references. The processing of
JNI weak references is handled last in the reference handling process. The result is
that a JNI weak reference can exist for an object that has already been finalized
and had a phantom reference queued and processed.

Heap expansion
Heap expansion occurs after garbage collection while exclusive access of the virtual
machine is still held. The heap is expanded in a set of specific situations.
The active part of the heap is expanded up to the maximum if one of three
conditions is true:
v The Garbage Collector (GC) did not free enough storage to satisfy the allocation
request.
v Free space is less than the minimum free space, which you can set by using the
-Xminf parameter. The default is 30%.

Chapter 2. Memory management

17

v More than the maximum time threshold is being spent in garbage collection, set
using the -Xmaxt parameter. The default is 13%.
The amount to expand the heap is calculated as follows:
1. The -Xminf option specifies the minimum percentage of heap to be left free
after a garbage collection. If the heap is being expanded to satisfy this value,
the GC calculates how much heap expansion is required.
You can set the maximum expansion amount using the -Xmaxe parameter. The
default value is 0, which means there is no maximum expansion limit. If the
calculated required heap expansion is greater than the non-zero value of
-Xmaxe, the required heap expansion is reduced to the value of -Xmaxe.
You can set the minimum expansion amount using the -Xmine parameter. The
default value is 1 MB. If the calculated required heap expansion is less than the
value of -Xmine, the required heap expansion is increased to the value of
-Xmine.
2. If the heap is expanding and the JVM is spending more than the maximum
time threshold, the GC calculates how much heap expansion is needed to
provide 17% free space. The expansion is adjusted as described in the previous
step, depending on -Xmaxe and -Xmine.
3. If garbage collection did not free enough storage, the GC ensures that the heap
is expanded by at least the value of the allocation request.
All calculated expansion amounts are rounded to the nearest 512-byte boundary on
32-bit JVMs or a 1024-byte boundary on 64-bit JVMs.

Heap shrinkage
Heap shrinkage occurs after garbage collection while exclusive access of the virtual
machine is still held. Shrinkage does not occur in a set of specific situations. Also,
there is a situation where a compaction occurs before the shrink.
Shrinkage does not occur if any of the following are true:
v The Garbage Collector (GC) did not free enough space to satisfy the allocation
request.
v The maximum free space, which can be set by the -Xmaxf parameter (default is
60%), is set to 100%.
v The heap has been expanded in the last three garbage collections.
v This is a System.gc() and the amount of free space at the beginning of the
garbage collection was less than -Xminf (default is 30%) of the live part of the
heap.
v If none of the above is true and more than -Xmaxf free space exists, the GC
must calculate how much to shrink the heap to get it to -Xmaxf free space,
without going below the initial (-Xms) value. This figure is rounded down to a
512-byte boundary on 32-bit JVMs or a 1024-byte boundary on 64-bit JVMs.
A compaction occurs before the shrink if all the following are true:
v A compaction was not done on this garbage collection cycle.
v No free chunk is at the end of the heap, or the size of the free chunk that is at
the end of the heap is less than 10% of the required shrinkage amount.
v The GC did not shrink and compact on the last garbage collection cycle.
On initialization, the JVM allocates the whole heap in a single contiguous area of
virtual storage. The amount that is allocated is determined by the setting of the

18

IBM SDK for Java: Diagnostics Guide

-Xmx parameter. No virtual space from the heap is ever freed back to the native
operating system. When the heap shrinks, it shrinks inside the original virtual
space.
Whether any physical memory is released depends on the ability of the native
operating system. If it supports paging; the ability of the native operating system to
commit and decommit physical storage to the virtual storage; the GC uses this
function. In this case, physical memory can be decommitted on a heap shrinkage.
You never see the amount of virtual storage that is used by the JVM decrease. You
might see physical memory free size increase after a heap shrinkage. The native
operating system determines what it does with decommitted pages.
Where paging is supported, the GC allocates physical memory to the initial heap
to the amount that is specified by the -Xms parameter. Additional memory is
committed as the heap grows.

Generational Concurrent Garbage Collector
The Generational Concurrent Garbage Collector has been introduced in Java 5.0
from IBM. A generational garbage collection strategy is well suited to an
application that creates many short-lived objects, as is typical of many transactional
applications.
You activate the Generational Concurrent Garbage Collector with the
-Xgcpolicy:gencon command-line option.
The Java heap is split into two areas, a new (or nursery) area and an old (or
tenured) area. Objects are created in the new area and, if they continue to be
reachable for long enough, they are moved into the old area. Objects are moved
when they have been reachable for enough garbage collections (known as the
tenure age).

New Area (nursery)

Allocate Space

Survivor Space

Old Area

Tenured Space

The new area is split into two logical spaces: allocate and survivor. Objects are
allocated into the Allocate Space. When that space is filled, a garbage collection
process called scavenge is triggered. During a scavenge, reachable objects are
copied either into the Survivor Space or into the Tenured Space if they have
reached the tenured age. Objects in the new area that are not reachable remain
untouched. When all the reachable objects have been copied, the spaces in the new
area switch roles. The new Survivor Space is now entirely empty of reachable
objects and is available for the next scavenge.

Chapter 2. Memory management

19

Free Space
Occupied Space

Before Scavenge
Allocate Space

Survivor Space

Tenured Space

Allocate Space

Tenured Space

After Scavenge

Survivor Space

This diagram illustrates what happens during a scavenge. When the Allocate Space
is full, a garbage collection is triggered. Reachable objects are then traced and
copied into the Survivor Space. Objects that have reached the tenure age (have
already been copied inside the new area a number of times) are promoted into
Tenured Space. As the name Generational Concurrent implies, the policy has a
concurrent aspect to it. The Tenured Space is concurrently traced with a similar
approach to the one used for –Xgcpolicy:optavgpause. With this approach, the
pause time incurred from Tenured Space collections is reduced.

Tenure age
Tenure age is a measure of the object age at which it should be promoted to the
tenure area. This age is dynamically adjusted by the JVM and reaches a maximum
value of 14. An object’s age is incremented on each scavenge. A tenure age of x
means that an object is promoted to the tenure area after it has survived x flips
between survivor and allocate space. The threshold is adaptive and adjusts the
tenure age based on the percentage of space used in the new area.

Tilt ratio
The size of the allocate space in the new area is maximized by a technique called
tilting. Tilting controls the relative sizes of the allocate and survivor spaces. Based
on the amount of data that survives the scavenge, the ratio is adjusted to maximize
the amount of time between scavenges.
For example, if the initial total new area size is 500 MB, the allocate and survivor
spaces start with 250 MB each (a 50% split). As the application runs and a
scavenge GC event is triggered, only 50 MB survives. In this situation, the survivor
space is decreased, allowing more space for the allocate space. A larger allocate
area means that it takes longer for a garbage collection to occur. This diagram
illustrates how the boundary between allocate and survivor space is affected by the
tilt ratio.

Allocate Space

Survivor Space

50%

20

IBM SDK for Java: Diagnostics Guide

Allocate Space

Survivor Space

90%

How to do heap sizing
You can do heap sizing to suit your requirements.
Generally:
v Do not start with a minimum heap size that is the same as the maximum heap
size.
v Use -verbose:gc to tailor the minimum and maximum settings.
v Investigate the use of fine-tuning options.

Initial and maximum heap sizes
Understanding the operations of the Garbage Collector (GC) helps you set initial
and maximum heap sizes for efficient management of the heap.
When you have established the maximum heap size that you need, you might
want to set the minimum heap size to the same value; for example, -Xms512M
-Xmx512M. However, using the same values is typically not a good idea, because it
delays the start of garbage collection until the heap is full. Therefore, the first time
that the GC runs, the process can take longer. Also, the heap is more likely to be
fragmented and require a heap compaction. You are advised to start your
application with the minimum heap size that your application requires. When the
GC starts up, it will run frequently and efficiently, because the heap is small.
If the GC cannot find enough garbage, it runs compaction. If the GC finds enough
garbage, or any of the other conditions for heap expansion are met (see “Heap
expansion” on page 17), the GC expands the heap.
Therefore, an application typically runs until the heap is full. Then, successive
garbage collection cycles recover garbage. When the heap is full of live objects, the
GC compacts the heap. If sufficient garbage is still not recovered, the GC expands
the heap.
From the earlier description, you can see that the GC compacts the heap as the
needs of the application rise, so that as the heap expands, it expands with a set of
compacted objects in the bottom of the original heap. This process is an efficient
way to manage the heap, because compaction runs on the smallest-possible heap
size at the time that compaction is found to be necessary. Compaction is performed
with the minimum heap sizes as the heap grows. Some evidence exists that an
application's initial set of objects tends to be the key or root set, so that compacting
them early frees the remainder of the heap for more short-lived objects.
Eventually, the JVM has the heap at maximum size with all long-lived objects
compacted at the bottom of the heap. The compaction occurred when compaction
was in its least expensive phase. The amount of processing and memory usage
required to expand the heap is almost trivial compared to the cost of collecting and
compacting a very large fragmented heap.

Using verbose:gc
You can use -verbose:gc when running your application with no load, and again
under stress, to help you set the initial and maximum heap sizes.
The -verbose:gc output is fully described in Chapter 28, “Garbage Collector
diagnostics,” on page 329. Switch on -verbose:gc and run up the application with
no load. Check the heap size at this stage. This provides a rough guide to the start
Chapter 2. Memory management

21

size of the heap (-Xms option) that is needed. If this value is much larger than the
defaults (see Appendix E, “Default settings for the JVM,” on page 461), think about
reducing this value a little to get efficient and rapid compaction up to this value,
as described in “Initial and maximum heap sizes” on page 21.
By running an application under stress, you can determine a maximum heap size.
Use this to set your max heap (-Xmx) value.

Using fine tuning options
You can change the minimum and maximum vales of the free space after garbage
collection, the expansion amount, and the garbage collection time threshold, to fine
tune the management of the heap.
Consider the description of the following command-line parameters and consider
applying them to fine tune the way the heap is managed:
-Xminf and -Xmaxf
Minimum and maximum free space after garbage collection.
-Xmine and -Xmaxe
Minimum and maximum expansion amount.
-Xmint and -Xmaxt
Minimum and maximum garbage collection time threshold.
These are also described in “Heap expansion” on page 17 and “Heap shrinkage”
on page 18.

Interaction of the Garbage Collector with applications
Understanding the way the Garbage Collector works helps you to understand its
relationship with your applications.
The Garbage Collector behaves in these ways:
1. The Garbage Collector will collect some (but not necessarily all) unreachable
objects.
2. The Garbage Collector will not collect reachable objects
3. The Garbage Collector will stop all threads when it is running.
4. The Garbage Collector will start in these ways:
a. The Garbage Collector is triggered when an allocation failure occurs, but
will otherwise not run itself.
b. The Garbage Collector will accept manual calls unless the
-Xdisableexplicitgc parameter is specified. A manual call to the Garbage
Collector (for example, through the System.gc() call) suggests that a garbage
collection cycle will run. In fact, the call is interpreted as a request for full
garbage collection scan unless a garbage collection cycle is already running
or explicit garbage collection is disabled by specifying -Xdisableexplicitgc.
5. The Garbage Collector will collect garbage at its own sequence and timing,
subject to item 4b.
6. The Garbage Collector accepts all command-line variables and environment
variables.
7. Note these points about finalizers:
a. They are not run in any particular sequence.
b. They are not run at any particular time.

22

IBM SDK for Java: Diagnostics Guide

c. They are not guaranteed to run at all.
d. They will run asynchronously to the Garbage Collector.

How to coexist with the Garbage Collector
Use this background information to help you diagnose problems in the coexistence
of your applications with the Garbage Collector (GC).
Do not try to control the GC or to predict what will happen in a given garbage
collection cycle. This unpredictability is handled, and the GC is designed to run
well and efficiently inside these conditions.
Set up the initial conditions that you want and let the GC run. It will behave as
described in “Interaction of the Garbage Collector with applications” on page 22,
which is in the JVM specification.

Root set
The root set is an internally derived set of references to the contents of the stacks
and registers of the JVM threads and other internal data structures at the time that
the Garbage Collector was called.
This composition of the root set means that the graph of reachable objects that the
Garbage Collector constructs in any given cycle is nearly always different from that
traced in another cycle (see list item 5 in “Interaction of the Garbage Collector with
applications” on page 22). This difference has significant consequences for
finalizers (list item 7), which are described more fully in “Finalizers” on page 24.

Thread local heap
The Garbage Collector (GC) maintains areas of the heap for fast object allocation.
The heap is subject to concurrent access by all the threads that are running in the
JVM. Therefore, it must be protected by a resource lock so that one thread can
complete updates to the heap before another thread is allowed in. Access to the
heap is therefore single-threaded. However, the GC also maintains areas of the
heap as thread caches or thread local heap (TLH). These TLHs are areas of the
heap that are allocated as a single large object, marked non-collectable, and
allocated to a thread. The thread can now sub allocate from the TLH objects that
are below a defined size. No heap lock is needed which means that allocation is
very fast and efficient. When a cache becomes full, a thread returns the TLH to the
main heap and grabs another chunk for a new cache.
A TLH is not subject to a garbage collection cycle; it is a reference that is dedicated
to a thread.

Bug reports
Attempts to predict the behavior of the Garbage Collector (GC) are frequent
underlying causes of bug reports.
Here is an example of a regular bug report to Java service of the "Hello World"
variety. A simple program allocates an object or objects, clears references to these
objects, and then initiates a garbage collection cycle. The objects are not seen as
collected. Typically, the objects are not collected because the application has
attached a finalizer that does not run immediately.

Chapter 2. Memory management

23

It is clear from the way that the GC works that more than one valid reason exists
for the objects not being seen as collected:
v An object reference exists in the thread stack or registers, and the objects are
retained garbage.
v The GC has not chosen to run a finalizer cycle at this time.
See list item 1 in “Interaction of the Garbage Collector with applications” on page
22. Real garbage is always found eventually, but it is not possible to predict when
as stated in list item 5.

Finalizers
The Java service team recommends that applications avoid the use of finalizers if
possible. The JVM specification states that finalizers are for emergency clear-up of,
for example, hardware resources. The service team recommends that you use
finalizers for this purpose only. Do not use them to clean up Java software
resources or for closedown processing of transactions.
The reasons for this recommendation are partly because of the nature of finalizers
and the permanent linkage to garbage collection, and partly because of the way
garbage collection works as described in “Interaction of the Garbage Collector with
applications” on page 22.

Nature of finalizers
The JVM specification does not describe finalizers, except to state that they are
final in nature. It does not state when, how, or whether a finalizer is run. Final, in
terms of a finalizer, means that the object is known not to be in use any more.
The object is definitely not in use only when it is not reachable. Only the Garbage
Collector (GC) can determine that an object is not reachable. Therefore, when the
GC runs, it determines which are the unreachable objects that have a finalizer
method attached. Normally, such objects are collected, and the GC can satisfy the
memory allocation fault. Finalized garbage must have its finalizer run before it can
be collected, so no finalized garbage can be collected in the cycle that finds it.
Therefore, finalizers make a garbage collection cycle longer (the cycle has to detect
and process the objects) and less productive. Finalizers use more of the processor
and resources on top of regular garbage collection. Because garbage collection is a
stop-the-world operation, it is sensible to reduce the processor and resource usage
as much as possible.
The GC cannot run finalizers itself when it finds them, because a finalizer might
run an operation that takes a long time. The GC cannot risk locking out the
application while this operation is running. Therefore, finalizers must be collected
into a separate thread for processing. This task adds more processor usage into the
garbage collection cycle.

Finalizers and garbage collection
The behavior of the Garbage Collector (GC) affects the interaction between the GC
and finalizers.
The way finalizers work, described in list item 7 in “Interaction of the Garbage
Collector with applications” on page 22, indicates the non-predictable behavior of
the GC. The significant results are:
v The graph of objects that the GC finds cannot be reliably predicted by your
application. Therefore, the sequence in which finalized objects are located has no
relationship to either

24

IBM SDK for Java: Diagnostics Guide

– the sequence in which the finalized objects are created
– the sequence in which the finalized objects become garbage.
The sequence in which finalizers are run cannot be predicted by your
application.
v The GC does not know what is in a finalizer, or how many finalizers exist.
Therefore, the GC tries to satisfy an allocation without processing finalizers. If a
garbage collection cycle cannot produce enough normal garbage, it might decide
to process finalized objects. Therefore, it is not possible to predict when a
finalizer is run.
v Because a finalized object might be garbage that is retained, a finalizer might not
run at all.

How finalizers are run
When the Garbage Collector (GC) decides to process unreachable finalized objects,
those objects are placed onto a queue that is used as input to a separate finalizer
thread.
When the GC has ended and the threads are unblocked, this finalizer thread starts.
It runs as a high-priority thread and runs down the queue, running the finalizer of
each object in turn. When the finalizer has run, the finalizer thread marks the
object as collectable and the object is probably collected in the next garbage
collection cycle. See list item 7d in “Interaction of the Garbage Collector with
applications” on page 22. If you are running with a large heap, the next garbage
collection cycle might not happen for some time.

Summary and alternative approach
When you understand the characteristics and use of finalizers, consider an
alternative approach to tidying Java resources.
Finalizers are an expensive use of computer resources and they are not
dependable.
The Java service team does not recommend that you use finalizers for process
control or for tidying Java resources. In fact, use finalizers as little as possible.
For tidying Java resources, consider the use of a cleanup routine. When you have
finished with an object, call the routine to null out all references, deregister
listeners, clear out hash tables, and other cleanup operation. Such a routine is far
more efficient than using a finalizer and has the useful side-benefit of speeding up
garbage collection. The Garbage Collector does not have so many object references
to chase in the next garbage collection cycle.

Manually starting the Garbage Collector
Manually starting the Garbage Collector (GC) can degrade JVM performance.
See list item 4b in “Interaction of the Garbage Collector with applications” on page
22. The GC can honor a manual call; for example, through the System.gc() call.
This call nearly always starts a garbage collection cycle, which is a heavy use of
computer resources.
The Java service team recommends that this call is not used, or, if it is, it is
enclosed in conditional statements that block its use in an application runtime
environment. The GC is carefully adjusted to deliver maximum performance to the
JVM. If you force it to run, you severely degrade JVM performance
Chapter 2. Memory management

25

The previous topics indicate that it is not sensible to try to force the GC to do
something predictable, such as collecting your new garbage or running a finalizer.
You cannot predict when the GC will act. Let the GC run inside the parameters
that an application selects at startup time. This method nearly always produces
best performance.
Several customer applications have been turned from unacceptable to acceptable
performance by blocking out manual invocations of the GC. One enterprise
application had more than four hundred System.gc() calls.

Frequently asked questions about the Garbage Collector
Examples of subjects that have answers in this section include default values,
Garbage Collector (GC) policies, GC helper threads, Mark Stack Overflow, heap
operation, and out of memory conditions.
What are the default heap and native stack sizes?
See Appendix E, “Default settings for the JVM,” on page 461.
What is the difference between the GC policies optavgpause, optthruput,
gencon, and subpool?
optthruput disables concurrent mark. If you do not have pause time problems
(indicated by erratic application response times), you can expect to get the best
throughput with this option.
optavgpause enables concurrent mark. If you have problems with erratic
application response times in garbage collection, you can alleviate them at the
cost of some throughput when running with this option.
gencon requests the combined use of concurrent and generational GC to help
minimize the time that is spent in any garbage collection pause.
subpool disables concurrent mark but employs an object allocation algorithm
that is more suitable for multiple processor systems, commonly 16 processors
or more. Applications that must scale on large systems can benefit from this
policy. This policy is available on AIX, Linux PPC and zSeries, z/OS, and
i5/OS only.
What is the default GC mode (optavgpause, optthruput, gencon, or subpool)?
optthruput - that is, generational collector and concurrent marking are off.
How many GC helper threads are created or “spawned”? What is their work?
A platform with n processors has n-1 helper threads. These threads work along
with the main GC thread during:
v Parallel mark phase
v Parallel bitwise sweep phase
v Parallel compaction phase
You can control the number of GC helper threads with the -Xgcthreads option.
Passing the -Xgcthreads1 option to Java results in no helper threads at all.
You gain little by setting -Xgcthreads to more than n-1 other than possibly
alleviating mark-stack overflows, if you suffer from them.
What is Mark Stack Overflow (MSO)? Why is MSO bad for performance?
Work packets are used for tracing all object reference chains from the roots.
Each such reference that is found is pushed onto the mark stack so that it can
be traced later. The number of work packets allocated is based on the heap size
and therefore is finite and can overflow. This situation is called Mark Stack

26

IBM SDK for Java: Diagnostics Guide

Overflow (MSO). The algorithms to handle this situation are expensive in
processing terms, and therefore MSO has a large impact on GC performance.
How can I prevent Mark Stack Overflow?
The following suggestions are not guaranteed to avoid MSO:
v Increase the number of GC helper threads using -Xgcthreads command-line
option
v Decrease the size of the Java heap using the -Xmx setting.
v Use a small initial value for the heap or use the default.
v Reduce the number of objects the application allocates.
v If MSO occurs, you see entries in the verbose gc as follows:


Where  is the number of times MSO has occurred and
 is the number of work packets that were allocated. By
specifying a larger number, say 50% more, with -Xgcworkpackets,
the likelihood of MSO can be reduced.
When and why does the Java heap expand?
The JVM starts with a small default Java heap, and it expands the heap based
on the allocation requests made by an application until it reaches the value
specified by -Xmx. Expansion occurs after GC if GC is unable to free enough
heap storage for an allocation request. Expansion also occurs if the JVM
determines that expanding the heap is required for better performance.
When does the Java heap shrink?
Heap shrinkage occurs when GC determines that there is heap storage space
available, and releasing some heap memory is beneficial for system
performance. Heap shrinkage occurs after GC, but when all the threads are still
suspended.
Does GC guarantee that it clears all the unreachable objects?
GC guarantees only that all the objects that were not reachable at the
beginning of the mark phase are collected. While running concurrently, our GC
guarantees only that all the objects that were unreachable when concurrent
mark began are collected. Some objects might become unreachable during
concurrent mark, but they are not guaranteed to be collected.
I am getting an OutOfMemoryError. Does this mean that the Java heap is
exhausted?
Not necessarily. Sometimes the Java heap has free space but an
OutOfMemoryError can occur. The error might occur for several reasons:
v Shortage of memory for other operations of the JVM.
v Some other memory allocation failing. The JVM throws an OutOfMemoryError
in such situations.
v Excessive memory allocation in other parts of the application, unrelated to
the JVM, if the JVM is just a part of the process, rather than the entire
process (JVM through JNI, for instance).
v The heap has been fully expanded, and an excessive amount of time (95%) is
being spent in the GC. This check can be disabled using the option
-Xdisableexcessivegc.
When I see an OutOfMemoryError, does that mean that the Java program exits?
Not always. Java programs can catch the exception thrown when OutOfMemory
occurs, and (possibly after freeing up some of the allocated objects) continue to
run.
Chapter 2. Memory management

27

In verbose:gc output, sometimes I see more than one GC for one allocation
failure. Why?
You see this message when GC decides to clear all soft references. The GC is
called once to do the regular garbage collection, and might run again to clear
soft references. Therefore, you might see more than one GC cycle for one
allocation failure.

28

IBM SDK for Java: Diagnostics Guide

Chapter 3. Class loading
The Java 2 JVM introduced a new class loading mechanism with a
parent-delegation model. The parent-delegation architecture to class loading was
implemented to aid security and to help programmers to write custom class
loaders.
Class loading loads, verifies, prepares and resolves, and initializes a class from a
Java class file.
v Loading involves obtaining the byte array representing the Java class file.
v Verification of a Java class file is the process of checking that the class file is
structurally well-formed and then inspecting the class file contents to ensure that
the code does not attempt to perform operations that are not permitted.
v Preparation involves the allocation and default initialization of storage space for
static class fields. Preparation also creates method tables, which speed up virtual
method calls, and object templates, which speed up object creation.
v Initialization involves the processing of the class's class initialization method, if
defined, at which time static class fields are initialized to their user-defined
initial values (if specified).
Symbolic references in a Java class file, such as to classes or object fields that
reference a field's value, are resolved at runtime to direct references only. This
resolution might occur either:
v After preparation but before initialization
v Or, more typically, at some point following initialization, but before the first
reference to that symbol.
The delay is generally to increase processing speed. Not all symbols in a class file
are referenced during processing; by delaying resolution, fewer symbols might
have to be resolved. The cost of resolution is gradually reduced over the total
processing time.

The parent-delegation model
The delegation model requires that any request for a class loader to load a given
class is first delegated to its parent class loader before the requested class loader
tries to load the class itself. The parent class loader, in turn, goes through the same
process of asking its parent. This chain of delegation continues through to the
bootstrap class loader (also known as the primordial or system class loader). If a
class loader's parent can load a given class, it returns that class. Otherwise, the
class loader attempts to load the class itself.
The JVM has three class loaders, each possessing a different scope from which it
can load classes. As you descend the hierarchy, the scope of available class
repositories widens, and typically the repositories are less trusted:
Bootstrap
|
Extensions
|
Application

© Copyright IBM Corp. 2003, 2010

29

At the top of the hierarchy is the bootstrap class loader. This class loader is
responsible for loading only the classes that are from the core Java API. These
classes are the most trusted and are used to bootstrap the JVM.
The extensions class loader can load classes that are standard extensions packages
in the extensions directory.
The application class loader can load classes from the local file system, and will
load files from the CLASSPATH. The application class loader is the parent of any
custom class loader or hierarchy of custom class loaders.
Because class loading is always delegated first to the parent of the class loading
hierarchy, the most trusted repository (the core API) is checked first, followed by
the standard extensions, then the local files that are on the class path. Finally,
classes that are located in any repository that your own class loader can access, are
accessible. This system prevents code from less-trusted sources from replacing
trusted core API classes by assuming the same name as part of the core API.

OutOfMemoryError exception when using delegated class
loaders
When you use delegated class loaders, the JVM can create a large number of
ClassLoader objects. For Java 5.0, up to and including Service Refresh 4, the
number of class loaders that are permitted is limited and an OutOfMemoryError
exception is thrown when this limit is exceeded. Use the -Xmxcl parameter to
increase the number of class loaders allowed, to avoid this problem. On affected
JVMs, the default limit us 8192, so if this problem occurs, increase this number, for
example to 15000, by setting -Xmxcl15000, until the problem is resolved.
Examine the Javadump to recognize this problem. At the top of the Javadump
there is an OutOfMemoryError exception like:
1TISIGINFO

Dump Event "systhrow" (00040000) Detail "java/lang/OutOfMemoryError" received

Further down, the current thread stack shows that a class loader is being loaded:
1XMCURTHDINFO
NULL
3XMTHREADINFO
4XESTACKTRACE
4XESTACKTRACE
4XESTACKTRACE

Current Thread Details
---------------------"ORB.thread.pool : 1" (TID:0x0000002ADD1FE300, sys_thread_t:0x0000002ACFE19998,
state:R, native ID:0x0000000042080960) prio=5
at com/ibm/oti/vm/VM.initializeClassLoader(Native Method)
at java/lang/ClassLoader.(ClassLoader.java:120)
at sun/reflect/DelegatingClassLoader.(ClassDefiner.java:71)

Namespaces and the runtime package
Loaded classes are identified by both the class name and the class loader that
loaded it. This separates loaded classes into namespaces that the class loader
identifies.
A namespace is a set of class names that are loaded by a specific class loader.
When an entry for a class has been added into a namespace, it is impossible to
load another class of the same name into that namespace. Multiple copies of any
given class can be loaded because a namespace is created for each class loader.
Namespaces cause classes to be segregated by class loader, thereby preventing
less-trusted code loaded from the application or custom class loaders from
interacting directly with more trusted classes. For example, the core API is loaded

30

IBM SDK for Java: Diagnostics Guide

by the bootstrap class loader, unless a mechanism is specifically provided to allow
them to interact. This prevents possibly malicious code from having guaranteed
access to all the other classes.
You can grant special access privileges between classes that are in the same
package by the use of package or protected access. This gives access rights
between classes of the same package, but only if they were loaded by the same
class loader. This stops code from an untrusted source trying to insert a class into a
trusted package. As discussed above, the delegation model prevents the possibility
of replacing a trusted class with a class of the same name from an untrusted
source. The use of namespaces prevents the possibility of using the special access
privileges that are given to classes of the same package to insert code into a
trusted package.

Custom class loaders
You might want to write your own class loader so that you can load classes from
an alternate repository, partition user code, or unload classes.
There are three main reasons why you might want to write your own class loader.
1. To allow class loading from alternative repositories.
This is the most common case, in which an application developer might want
to load classes from other locations, for example, over a network connection.
2. To partition user code.
This case is less frequently used by application developers, but widely used in
servlet engines.
3. To allow the unloading of classes.
This case is useful if the application creates large numbers of classes that are
used for only a finite period. Because a class loader maintains a cache of the
classes that it has loaded, these classes cannot be unloaded until the class
loader itself has been dereferenced. For this reason, system and extension
classes are never unloaded, but application classes can be unloaded when their
classloader is.
For much more detailed information about the classloader, see
http://www.ibm.com/developerworks/java/library/j-dclp1/. This article is the
first in a series that helps you to write your own class loader.

Chapter 3. Class loading

31

32

IBM SDK for Java: Diagnostics Guide

Chapter 4. Class data sharing
Class sharing in the IBM Version 5.0 SDK offers a transparent and dynamic means
of sharing all loaded classes, both application classes and system classes, and
placing no restrictions on Java Virtual Machines (JVMs) that are sharing the class
data (unless runtime bytecode modification is being used).
This form of class sharing is an advance on earlier JVMs that have offered some
form of class sharing between multiple JVMs; for example, the IBM Persistent
Reusable JVM on z/OS, Sun Microsystems "CDS" feature in their Java 5.0 release,
and the bytecode verification cache in the i5/OS Classic VM.
You turn on shared classes with the -Xshareclasses command-line option. For
reference information about -Xshareclasses, see “JVM command-line options” on
page 444.
For diagnostics information about shared classes, see Chapter 30, “Shared classes
diagnostics,” on page 351.
Sharing all immutable class data for an application between multiple JVMs has the
following benefits:
v The amount of physical memory used can be significantly less when using more
than one JVM instance.
v Loading classes from a populated cache is faster than loading classes from disk,
because the classes are already in memory and are already partially verified.
Therefore, class sharing also benefits applications that regularly start new JVM
instances doing similar tasks. The cost to populate an empty cache with a single
JVM is minimal and, when more than one JVM is populating the cache
concurrently, this activity is typically faster than both JVMs loading the classes
from disk.
Key points to note about the IBM class sharing feature are:
v Class data sharing is available on all the platforms that IBM supports in Java
v5.0, apart from the Sun Solaris and HP hybrids.
v Classes are stored in a named “class cache”, which is either a memory-mapped
file or an area of shared memory, allocated by the first JVM that needs to use it.
v Any JVM can read from or update the cache, although a JVM can connect to
only one cache at a time.
v The cache persists beyond the lifetime of any JVM connected to it, until it is
explicitly destroyed or until the operating system is shut down.
v When a JVM loads a class, it looks first for the class in the cache to which it is
connected and, if it finds the class it needs, it loads the class from the cache.
Otherwise, it loads the class from disk and adds it to the cache where possible.
v When a cache becomes full, classes in the cache can still be shared, but no new
data can be added.
v Because the class cache persists beyond the lifetime of any JVM connected to it,
if changes are made to classes on the file system, some classes in the cache
might become out-of-date (or “stale”). This situation is managed transparently;
the updated version of the class is detected by the next JVM that loads it and
the class cache is updated where possible.
© Copyright IBM Corp. 2003, 2010

33

v Sharing of bytecode that is modified at runtime is supported, but must be used
with care.
v Access to the class data cache is protected by Java permissions if a security
manager is installed.
v Classes generated using reflection cannot be shared.
v Only class data that does not change can be shared. Resources, objects, JIT
compiled code, and similar items cannot be stored in the cache.

34

IBM SDK for Java: Diagnostics Guide

Chapter 5. The JIT compiler
The Just-In-Time (JIT) compiler is a component of the Java Runtime Environment.
It improves the performance of Java applications by compiling bytecodes to native
machine code at run time. This section summarizes the relationship between the
JVM and the JIT compiler and gives a short description of how the compiler
works.

JIT compiler overview
The Just-In-Time (JIT) compiler is a component of the Java Runtime Environment
that improves the performance of Java applications at run time.
Java programs consists of classes, which contain platform-neutral bytecodes that
can be interpreted by a JVM on many different computer architectures. At run
time, the JVM loads the class files, determines the semantics of each individual
bytecode, and performs the appropriate computation. The additional processor and
memory usage during interpretation means that a Java application performs more
slowly than a native application. The JIT compiler helps improve the performance
of Java programs by compiling bytecodes into native machine code at run time.
The JIT compiler is enabled by default, and is activated when a Java method is
called. The JIT compiler compiles the bytecodes of that method into native machine
code, compiling it “just in time” to run. When a method has been compiled, the
JVM calls the compiled code of that method directly instead of interpreting it.
Theoretically, if compilation did not require processor time and memory usage,
compiling every method could allow the speed of the Java program to approach
that of a native application.
JIT compilation does require processor time and memory usage. When the JVM
first starts up, thousands of methods are called. Compiling all of these methods
can significantly affect startup time, even if the program eventually achieves very
good peak performance.
In practice, methods are not compiled the first time they are called. For each
method, the JVM maintains a call count, which is incremented every time the
method is called. The JVM interprets a method until its call count exceeds a JIT
compilation threshold. Therefore, often-used methods are compiled soon after the
JVM has started, and less-used methods are compiled much later, or not at all. The
JIT compilation threshold helps the JVM start quickly and still have improved
performance. The threshold has been carefully selected to obtain an optimal
balance between startup times and long term performance.
After a method is compiled, its call count is reset to zero and subsequent calls to
the method continue to increment its count. When the call count of a method
reaches a JIT recompilation threshold, the JIT compiler compiles it a second time,
applying a larger selection of optimizations than on the previous compilation. This
process is repeated until the maximum optimization level is reached. The busiest
methods of a Java program are always optimized most aggressively, maximizing
the performance benefits of using the JIT compiler. The JIT compiler can also
measure operational data at run time, and use that data to improve the quality of
further recompilations.
© Copyright IBM Corp. 2003, 2010

35

The JIT compiler can be disabled, in which case the entire Java program will be
interpreted. Disabling the JIT compiler is not recommended except to diagnose or
work around JIT compilation problems.

How the JIT compiler optimizes code
When a method is chosen for compilation, the JVM feeds its bytecodes to the
Just-In-Time compiler (JIT). The JIT needs to understand the semantics and syntax
of the bytecodes before it can compile the method correctly.
To help the JIT compiler analyze the method, its bytecodes are first reformulated in
an internal representation called trees, which resembles machine code more closely
than bytecodes. Analysis and optimizations are then performed on the trees of the
method. At the end, the trees are translated into native code. The remainder of this
section provides a brief overview of the phases of JIT compilation. For more
information, see Chapter 26, “JIT problem determination,” on page 317.
The compilation consists of the following phases:
1. Inlining
2. Local optimizations
3. Control flow optimizations
4. Global optimizations
5. Native code generation
All phases except native code generation are cross-platform code.

Phase 1 - inlining
Inlining is the process by which the trees of smaller methods are merged, or
"inlined", into the trees of their callers. This speeds up frequently executed method
calls.
Two inlining algorithms with different levels of aggressiveness are used, depending
on the current optimization level. Optimizations performed in this phase include:
v Trivial inlining
v Call graph inlining
v Tail recursion elimination
v Virtual call guard optimizations

Phase 2 - local optimizations
Local optimizations analyze and improve a small section of the code at a time.
Many local optimizations implement tried and tested techniques used in classic
static compilers.
The optimizations include:
v Local data flow analyses and optimizations
v Register usage optimization
v Simplifications of Java idioms
These techniques are applied repeatedly, especially after global optimizations,
which might have pointed out more opportunities for improvement.

36

IBM SDK for Java: Diagnostics Guide

Phase 3 - control flow optimizations
Control flow optimizations analyze the flow of control inside a method (or specific
sections of it) and rearrange code paths to improve their efficiency.
The optimizations are:
v Code reordering, splitting, and removal
v Loop reduction and inversion
v
v
v
v
v

Loop striding and loop-invariant code motion
Loop unrolling and peeling
Loop versioning and specialization
Exception-directed optimization
Switch analysis

Phase 4 - global optimizations
Global optimizations work on the entire method at once. They are more
"expensive", requiring larger amounts of compilation time, but can provide a great
increase in performance.
The optimizations are:
v Global data flow analyses and optimizations
v Partial redundancy elimination
v Escape analysis
v GC and memory allocation optimizations
v Synchronization optimizations

Phase 5 - native code generation
Native code generation processes vary, depending on the platform architecture.
Generally, during this phase of the compilation, the trees of a method are
translated into machine code instructions; some small optimizations are performed
according to architecture characteristics.
The compiled code is placed into a part of the JVM process space called the code
cache; the location of the method in the code cache is recorded, so that future calls
to it will call the compiled code. At any given time, the JVM process consists of the
JVM executable files and a set of JIT-compiled code that is linked dynamically to
the bytecode interpreter in the JVM.

Frequently asked questions about the JIT compliler
Examples of subjects that have answers in this section include disabling the JIT
compiler, use of alternative JIT compilers, control of JIT compilation and dynamic
control of the JIT compiler.
Can I disable the JIT compiler?
Yes. The JIT compiler is turned on by default, but you can set the appropriate
command-line parameter to disable it. (See “Disabling the JIT compiler” on
page 317.)
Can I use another vendor's JIT compiler?
No.

Chapter 5. The JIT compiler

37

Can I use any version of the JIT compiler with the JVM?
No. The two are tightly coupled. You must use the version of the JIT compiler
that comes with the JVM package that you use.
Can the JIT compiler “decompile” methods?
No. After a method has been compiled by the JIT compiler, the native code is
used instead for the remainder of the execution of the program. An exception
to this rule is a method in a class that was loaded with a custom (user-written)
class loader, which has since been unloaded (garbage-collected). In fact, when a
class loader is garbage-collected, the compiled methods of all classes loaded by
that class loader are discarded.
Can I control the JIT compilation?
Yes. See Chapter 26, “JIT problem determination,” on page 317. In addition,
advanced diagnostics are available to IBM engineers.
Can I dynamically control the JIT compiler?
No. You can pass options to the JIT compiler to modify its behavior, but only
at JVM startup time, because the JIT compiler is started up at the same time as
the JVM. However, a Java program can use the java.lang.Compiler API to
enable and disable the JIT compiler at runtime.
How much memory does the code cache consume?
The JIT compiler uses memory intelligently. When the code cache is initialized,
it consumes relatively little memory. As more methods are compiled into native
code, the code cache is grown dynamically to accommodate the needs of the
program. Space previously occupied by discarded or recompiled methods is
reclaimed and reused. When the size of the code cache reaches a predefined
upper limit, it stops growing. The JIT compiler will stop all future attempts to
compile methods, to avoid exhausting the system memory and affecting the
stability of the application or the operating system.

38

IBM SDK for Java: Diagnostics Guide

Chapter 6. Java Remote Method Invocation
Java Remote Method Invocation (Java RMI) enables you to create distributed Java
technology-based applications that can communicate with other such applications.
Methods of remote Java objects can be run from other Java virtual machines
(JVMs), possibly on different hosts.
RMI uses object serialization to marshal and unmarshal parameters and does not
truncate types, supporting object-oriented polymorphism. The RMI registry is a
lookup service for ports.

The RMI implementation
The RMI implementation consists of three abstraction layers.
These abstraction layers are:
1. The Stub and Skeleton layer, which intercepts method calls made by the client
to the interface reference variable and redirects these calls to a remote RMI
service.
2. The Remote Reference layer understands how to interpret and manage
references made from clients to the remote service objects.
3. The bottom layer is the Transport layer, which is based on TCP/IP connections
between machines in a network. It provides basic connectivity, as well as some
firewall penetration strategies.

RMI
System

Client Program

Server Program

Stubs and Skeletons

Stubs and Skeletons

Remote Reference
Layer

Remote Reference
Layer

Transport Layer

On top of the TCP/IP layer, RMI uses a wire-level protocol called Java Remote
Method Protocol (JRMP), which works like this:
1. Objects that require remote behavior should extend the RemoteObject class,
typically through the UnicastRemoteObject subclass.
a. The UnicastRemoteObject subclass exports the remote object to make it
available for servicing incoming RMI calls.
b. Exporting the remote object creates a new server socket, which is bound to
a port number.
c. A thread is also created that listens for connections on that socket. The
server is registered with a registry.
© Copyright IBM Corp. 2003, 2010

39

d. A client obtains details of connecting to the server from the registry.
e. Using the information from the registry, which includes the hostname and
the port details of the server's listening socket, the client connects to the
server.
2. When the client issues a remote method invocation to the server, it creates a
TCPConnection object, which opens a socket to the server on the port specified
and sends the RMI header information and the marshalled arguments through
this connection using the StreamRemoteCall class.
3. On the server side:
a. When a client connects to the server socket, a new thread is assigned to
deal with the incoming call. The original thread can continue listening to
the original socket so that additional calls from other clients can be made.
b. The server reads the header information and creates a RemoteCall object of
its own to deal with unmarshalling the RMI arguments from the socket.
c. The serviceCall() method of the Transport class services the incoming call by
dispatching it
d. The dispatch() method calls the appropriate method on the object and
pushes the result back down the wire.
e. If the server object throws an exception, the server catches it and marshals it
down the wire instead of the return value.
4. Back on the client side:
a. The return value of the RMI is unmarshalled and returned from the stub
back to the client code itself.
b. If an exception is thrown from the server, that is unmarshalled and thrown
from the stub.

Thread pooling for RMI connection handlers
When a client connects to the server socket, a new thread is forked to deal with
the incoming call. The IBM SDK implements thread pooling in the
sun.rmi.transport.tcp.TCPTransport class.
Thread pooling is not enabled by default. Enable it with this command-line setting:
-Dsun.rmi.transport.tcp.connectionPool=true

Alternatively, you could use a non-null value instead of true.
With the connectionPool enabled, threads are created only if there is no thread in
the pool that can be reused. In the current implementation of the connection Pool,
the RMI connectionHandler threads are added to a pool and are never removed.
Enabling thread pooling is not recommended for applications that have only
limited RMI usage. Such applications have to live with these threads during the
RMI off-peak times as well. Applications that are mostly RMI intensive can benefit
by enabling the thread pooling because the connection handlers will be reused,
avoiding the additional memory usage when creating these threads for every RMI
call.

Understanding distributed garbage collection
The RMI subsystem implements reference counting based Distributed Garbage
Collection (DGC) to provide automatic memory management facilities for remote
server objects.

40

IBM SDK for Java: Diagnostics Guide

When the client creates (unmarshalls) a remote reference, it calls dirty() on the
server-side DGC. After the client has finished with the remote reference, it calls the
corresponding clean() method.
A reference to a remote object is leased for a time by the client holding the
reference. The lease period starts when the dirty() call is received. The client must
renew the leases by making additional dirty() calls on the remote references it
holds before such leases expire. If the client does not renew the lease before it
expires, the distributed garbage collector assumes that the remote object is no
longer referenced by that client.
DGCClient implements the client side of the RMI distributed garbage collection
system. The external interface to DGCClient is the registerRefs() method. When a
LiveRef to a remote object enters the JVM, it must be registered with the
DGCClient to participate in distributed garbage collection. When the first LiveRef
to a particular remote object is registered, a dirty() call is made to the server-side
DGC for the remote object. The call returns a lease guaranteeing that the
server-side DGC will not collect the remote object for a certain time. While LiveRef
instances to remote objects on a particular server exist, the DGCClient periodically
sends more dirty calls to renew its lease. The DGCClient tracks the local
availability of registered LiveRef instances using phantom references. When the
LiveRef instance for a particular remote object is garbage collected locally, a clean()
call is made to the server-side DGC. The call indicates that the server does not
need to keep the remote object alive for this client. The RenewCleanThread handles
the asynchronous client-side DGC activity by renewing the leases and making
clean calls. So this thread waits until the next lease renewal or until any phantom
reference is queued for generating clean requests as necessary.

Debugging applications involving RMI
When debugging applications involving RMI you need information on exceptions
and properties settings, solutions to common problems, answers to frequently
asked questions, and useful tools.
The list of exceptions that can occur when using RMI and their context is included
in the RMI Specification document at: http://java.sun.com/j2se/1.5.0/docs/guide/
rmi/spec/rmi-exceptions.html#3601
Properties settings that are useful for tuning, logging, or tracing RMI servers and
clients can be found at: http://java.sun.com/j2se/1.5.0/docs/guide/rmi/
javarmiproperties.html
Solutions to some common problems and answers to frequently asked questions
related to RMI and object serialization can be found at: http://java.sun.com/j2se/
1.5.0/docs/guide/rmi/faq.html
Network monitoring tools like netstat and tcpdump are useful for debugging RMI
problems because they enable you to see the traffic at the network level.

Chapter 6. Java Remote Method Invocation

41

42

IBM SDK for Java: Diagnostics Guide

Chapter 7. The ORB
This description of the Object Request Broker (ORB) provides background
information to help you diagnose problems with the ORB.
The topics in this chapter are:
v “Using the ORB” on page 51
v “How the ORB works” on page 54
v
v
v
v
v
v

“Additional features of the ORB” on page 61
“CORBA”
“RMI and RMI-IIOP” on page 44
“Java IDL or RMI-IIOP?” on page 44
“RMI-IIOP limitations” on page 44
“Further reading” on page 45

v “Examples of client–server applications” on page 45
The IBM ORB ships with the JVM and is used by the IBM WebSphere® Application
Server. It is one of the enterprise features of the Java 2 Standard Edition. The ORB
is both a tool and a runtime component. It provides distributed computing through
the CORBA Internet Inter-Orb Protocol (IIOP) communication protocol. The
protocol is defined by the Object Management Group (OMG). The ORB runtime
consists of a Java implementation of a CORBA ORB. The ORB toolkit provides
APIs and tools for both the Remote Method Invocation (RMI) programming model
and the Interface Definition Language (IDL) programming model.

CORBA
The Common Object Request Broker Architecture (CORBA) is an open,
vendor-independent specification for distributed computing. It is published by the
Object Management Group (OMG).
Most applications need different objects on various platforms and operating
systems to communicate with each other across networks. CORBA enables objects
to interoperate in this way, using the Internet Inter-ORB Protocol (IIOP). To help
objects understand the operations available, and the syntax required to invoke
them, an Interface Definition Language (IDL) is used. The IDL is
programming-language independent, to increase the interoperability between
objects.
When an application developer defines an object, they also define other aspects.
The aspects include the position of the object in an overall hierarchy, object
attributes, and possible operations. Next, the aspects are all described in the IDL.
The description is then converted into an implementation by using an IDL
compiler. For example, IDLJ is an IDL compiler for the Java language, and converts
an IDL description into a Java source code. The benefit of this is that the object
implementation is “encapsulated” by the IDL definition. Any other objects wanting
to interoperate can do so using mechanisms defined using the shared IDL.
Developers enable this interoperability by defining the hierarchy, attributes, and
operations of objects using IDL. They then use an IDL compiler (such as IDLJ for
© Copyright IBM Corp. 2003, 2010

43

Java) to map the definition onto an implementation in a programming language.
The implementation of an object is encapsulated. Clients of the object can see only
its external IDL interface. The OMG has produced specifications for mappings
from IDL to many common programming languages, including C, C++, and Java
An essential part of the CORBA specification is the Object Request Broker (ORB).
The ORB routes requests from a client object to a remote object. The ORB then
returns any responses to the required destinations. Java contains an
implementation of the ORB that communicates by using IIOP.

RMI and RMI-IIOP
This description compares the two types of remote communication in Java; Remote
Method Invocation (RMI) and RMI-IIOP.
RMI is Java's traditional form of remote communication. It is an object-oriented
version of Remote Procedure Call (RPC). It uses the nonstandardized Java Remote
Method Protocol (JRMP) to communicate between Java objects. This provides an
easy way to distribute objects, but does not allow for interoperability between
programming languages.
RMI-IIOP is an extension of traditional Java RMI that uses the IIOP protocol. This
protocol allows RMI objects to communicate with CORBA objects. Java programs
can therefore interoperate transparently with objects that are written in other
programming languages, provided that those objects are CORBA-compliant.
Objects can still be exported to traditional RMI (JRMP) and the two protocols can
communicate.
A terminology difference exists between the two protocols. In RMI (JRMP), the
server objects are called skeletons; in RMI-IIOP, they are called ties. Client objects
are called stubs in both protocols.

Java IDL or RMI-IIOP?
There are circumstances in which you might choose to use RMI-IIOP and others in
which you might choose to use Java IDL.
RMI-IIOP is the method that is chosen by Java programmers who want to use the
RMI interfaces, but use IIOP as the transport. RMI-IIOP requires that all remote
interfaces are defined as Java RMI interfaces. Java IDL is an alternative solution,
intended for CORBA programmers who want to program in Java to implement
objects that are defined in IDL. The general rule that is suggested by Sun is to use
Java IDL when you are using Java to access existing CORBA resources, and
RMI-IIOP to export RMI resources to CORBA.

RMI-IIOP limitations
You must understand the limitations of RMI-IIOP when you develop an RMI-IIOP
application, and when you deploy an existing CORBA application in a Java-IIOP
environment.
In a Java-only application, RMI (JRMP) is more lightweight and efficient than
RMI-IIOP, but less scalable. Because it has to conform to the CORBA specification
for interoperability, RMI-IIOP is a more complex protocol. Developing an RMI-IIOP
application is much more similar to CORBA than it is to RMI (JRMP).

44

IBM SDK for Java: Diagnostics Guide

You must take care if you try to deploy an existing CORBA application in a Java
RMI-IIOP environment. An RMI-IIOP client cannot necessarily access every
existing CORBA object. The semantics of CORBA objects that are defined in IDL
are a superset of those of RMI-IIOP objects. That is why the IDL of an existing
CORBA object cannot always be mapped into an RMI-IIOP Java interface. It is only
when the semantics of a specific CORBA object are designed to relate to those of
RMI-IIOP that an RMI-IIOP client can call a CORBA object.

Further reading
There are links to CORBA specifications, CORBA basics, and the RMI-IIOP
Programmer's Guide.
Object Management Group Web site: http://www.omg.org contains CORBA
specifications that are available to download.
OMG - CORBA Basics: http://www.omg.org/gettingstarted/corbafaq.htm.
Remember that some features discussed here are not implemented by all ORBs.
You can find the RMI-IIOP Programmer's Guide in your SDK installation directory
under docs/common/rmi-iiop.html. Example programs are provided in
demo/rmi-iiop.

Examples of client–server applications
CORBA, RMI (JRMP), and RMI-IIOP approaches are used to present three
client-server example applications. All the applications use the RMI-IIOP IBM ORB.

Interfaces
The interfaces to be implemented are CORBA IDL and Java RMI.
The two interfaces are:
v CORBA IDL Interface (Sample.idl):
interface Sample { string message(); };

v Java RMI Interface (Sample.java):
public interface Sample extends java.rmi.Remote
{ public String message() throws java.rmi.RemoteException; }

These two interfaces define the characteristics of the remote object. The remote
object implements a method, named message. The method does not need any
parameter, and it returns a string. For further information about IDL and its
mapping to Java, see the OMG specifications (http://www.omg.org).

Remote object implementation (or servant)
This description shows possible implementations of the object.
The possible RMI(JRMP) and RMI-IIOP implementations (SampleImpl.java) of this
object could be:
public class SampleImpl extends javax.rmi.PortableRemoteObject implements Sample {
public SampleImpl() throws java.rmi.RemoteException { super(); }
public String message() { return "Hello World!"; }
}

Chapter 7. The ORB

45

You can use the class PortableRemoteObject for both RMI over JRMP and IIOP. The
effect is to make development of the remote object effectively independent of the
protocol that is used. The object implementation does not need to extend
PortableRemoteObject, especially if it already extends another class (single-class
inheritance). Instead, the remote object instance must be exported in the server
implementation. Exporting a remote object makes the object available to accept
incoming remote method requests. When you extend
javax.rmi.PortableRemoteObject, your class is exported automatically on creation.
The CORBA or Java IDL implementation of the remote object (servant) is:
public class SampleImpl extends _SamplePOA {
public String message() { return "Hello World"; }
}

The POA is the Portable Object Adapter, described in “Portable object adapter” on
page 61.
The implementation conforms to the Inheritance model, in which the servant
extends directly the IDL-generated skeleton SamplePOA. You might want to use
the Tie or Delegate model instead of the typical Inheritance model if your
implementation must inherit from some other implementation. In the Tie model,
the servant implements the IDL-generated operations interface (such as
SampleOperations). The Tie model introduces a level of indirection, so that one
extra method call occurs when you invoke a method. The server code describes the
extra work that is required in the Tie model, so that you can decide whether to use
the Tie or the Delegate model. In RMI-IIOP, you can use only the Tie or Delegate
model.

Stubs and ties generation
The RMI-IIOP code provides the tools to generate stubs and ties for whatever
implementation exists of the client and server.
The following table shows what command to run to get the stubs and ties (or
skeletons) for each of the three techniques:
CORBA

RMI(JRMP)

RMI-IIOP

idlj Sample.idl

rmic SampleImpl

rmic -iiop Sample

Compilation generates the files that are shown in the following table. To keep the
intermediate .java files, run the rmic command with the -keep option.
CORBA

RMI(JRMP)

RMI-IIOP

Sample.java

SampleImpl_Skel.class

_SampleImpl_Tie.class

SampleHolder.java

SampleImpl_Stub.class

_Sample_Stub.class

SampleHelper.java

Sample.class (Sample.java
present)

Sample.class (Sample.java
present)

SampleOperations.java

SampleImpl.class (only
compiled)

SampleImpl.class (only
compiled)

_SampleStub.java
SamplePOA.java (-fserver,
-fall, -fserverTie, -fallTie)

46

IBM SDK for Java: Diagnostics Guide

CORBA

RMI(JRMP)

RMI-IIOP

SamplePOATie.java
(-fserverTie, -fallTie)
_SampleImplBase.java
(-oldImplBase)

Since the Java v1.4 ORB, the default object adapter (see the OMG CORBA
specification v.2.3) is the Portable Object Adapter (POA). Therefore, the default
skeletons and ties that the IDL compiler generates can be used by a server that is
using the POA model and interfaces. By using the idlj -oldImplBase option, you
can generate older versions of the server-side skeletons that are compatible with
servers that are written in Java v1.3 and earlier.

Server code
The server application has to create an instance of the remote object and publish it
in a naming service. The Java Naming and Directory Interface (JNDI) defines a set
of standard interfaces. The interfaces are used to query a naming service, or to
bind an object to that service.
The implementation of the naming service can be a CosNaming service in the
Common Object Request Broker Architecture (CORBA) environment. A CosNaming
service is a collection of naming services, and implemented as a set of interfaces
defined by CORBA. Alternatively, the naming service can be implemented using a
Remote Method Invocation (RMI) registry for an RMI(JRMP) application. You can
use JNDI in CORBA and in RMI cases. The effect is to make the server
implementation independent of the naming service that is used. For example, you
could use the following code to obtain a naming service and bind an object
reference in it:
Context ctx = new InitialContext(...); // get hold of the initial context
ctx.bind("sample", sampleReference); // bind the reference to the name "sample"
Object obj = ctx.lookup("sample"); // obtain the reference

To tell the application which naming implementation is in use, you must set one of
the following Java properties:
java.naming.factory.initial
Defined also as javax.naming.Context.INITIAL_CONTEXT_FACTORY, this
property specifies the class name of the initial context factory for the
naming service provider. For RMI registry, the class name is
com.sun.jndi.rmi.registry.RegistryContextFactory. For the CosNaming
Service, the class name is com.sun.jndi.cosnaming.CNCtxFactory.
java.naming.provider.url
This property configures the root naming context, the Object Request
Broker (ORB), or both. It is used when the naming service is stored in a
different host, and it can take several URI schemes:
v rmi
v corbaname
v corbaloc
v IOR
v iiop
v iiopname
For example:

Chapter 7. The ORB

47

rmi://[[:]][/] for RMI registry
iiop://[[:]][/] for COSNaming

To get the previous properties in the environment, you could code:
Hashtable env = new Hashtable();
Env.put(Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.cosnaming.CNCtxFactory");

and pass the hash table as an argument to the constructor of InitialContext.
For example, with RMI(JRMP), you create an instance of the servant then follow
the previous steps to bind this reference in the naming service.
With CORBA (Java IDL), however, you must do some extra work because you
have to create an ORB. The ORB has to make the servant reference available for
remote calls. This mechanism is typically controlled by the object adapter of the
ORB.
public class Server {
public static void main (String args []) {
try {
ORB orb = ORB.init(args, null);
// Get reference to the root poa & activate the POAManager
POA poa = (POA)orb.resolve_initial_references("RootPOA");
poa.the_POAManager().activate();
// Create a servant and register with the ORB
SampleImpl sample = new SampleImpl();
sample.setORB(orb);
// TIE model ONLY
// create a tie, with servant being the delegate and
// obtain the reference ref for the tie
SamplePOATie tie = new SamplePOATie(sample, poa);
Sample ref = tie._this(orb);
// Inheritance model ONLY
// get object reference from the servant
org.omg.CORBA.Object ref = poa.servant_to_reference(sample);
Sample ref = SampleHelper.narrow(ref);
// bind the object reference ref to the naming service using JNDI
..........(see previous code) .....
orb.run();
}
catch(Exception e) {}
}
}

For RMI-IIOP:
public class Server {
public static void main (String args []) {
try {
ORB orb = ORB.init(args, null);
// Get reference to the root poa & activate the POAManager
POA poa = (POA)orb.resolve_initial_references("RootPOA");
poa.the_POAManager().activate();
// Create servant and its tie
SampleImpl sample = new SampleImpl();
_SampleImpl_Tie tie = (_SampleImpl_Tie)Util.getTie(sample);

48

IBM SDK for Java: Diagnostics Guide

// get an usable object reference
org.omg.CORBA.Object ref = poa.servant_to_reference((Servant)tie);
// bind the object reference ref to the naming service using JNDI
..........(see previous code) .....
}
catch(Exception e) {}
}
}

To use the previous Portable Object Adapter (POA) server code, you must use the
-iiop -poa options together to enable rmic to generate the tie. If you do not use the
POA, the RMI(IIOP) server code can be reduced to instantiating the servant
(SampleImpl sample = new SampleImpl()). You then bind the servant to a naming
service as is typically done in the RMI(JRMP) environment. In this case, you need
use only the -iiop option to enable rmic to generate the RMI-IIOP tie. If you omit
-iiop, the RMI(JRMP) skeleton is generated.
When you export an RMI-IIOP object on your server, you do not necessarily have
to choose between JRMP and IIOP. If you need a single server object to support
JRMP and IIOP clients, you can export your RMI-IIOP object to JRMP and to IIOP
simultaneously. In RMI-IIOP terminology, this action is called dual export.
RMI Client example:
public class SampleClient {
public static void main(String [] args) {
try{
Sample sampleref
//Look-up the naming service using JNDI and get the reference
.........
// Invoke method
System.out.println(sampleRef.message());
}
catch(Exception e) {}
}
}

CORBA Client example:
public class SampleClient {
public static void main (String [] args) {
try {
ORB orb = ORB.init(args, null);
// Look-up the naming service using JNDI
......
// Narrowing the reference to the right class
Sample sampleRef = SampleHelper.narrow(o);
// Method Invocation
System.out.println(sampleRef.message());
}
catch(Exception e) {}
}
}

RMI-IIOP Client example:
public class SampleClient {
public static void main (String [] args) {
try{
ORB orb = ORB.init(args, null);
// Retrieving reference from naming service
........
// Narrowing the reference to the correct class
Sample sampleRef = (Sample)PortableRemoteObject.narrow(o, Sample.class);
Chapter 7. The ORB

49

// Method Invocation
System.out.println(sampleRef.message());
}
catch(Exception e) {}
}
}

Summary of major differences between RMI (JRMP) and
RMI-IIOP
There are major differences in development procedures between RMI (JRMP) and
RMI-IIOP. The points discussed here also represent work items that are necessary
when you convert RMI (JRMP) code to RMI-IIOP code.
Because the usual base class of RMI-IIOP servers is PortableRemoteObject, you
must change this import statement accordingly, in addition to the derivation of the
implementation class of the remote object. After completing the Java coding, you
must generate a tie for IIOP by using the rmic compiler with the -iiop option.
Next, run the CORBA CosNaming tnameserv as a name server instead of
rmiregistry.
For CORBA clients, you must also generate IDL from the RMI Java interface by
using the rmic compiler with the -idl option.
All the changes in the import statements for server development apply to client
development. In addition, you must also create a local object reference from the
registered object name. The lookup() method returns a java.lang.Object, and you
must then use the narrow() method of PortableRemoteObject to cast its type. You
generate stubs for IIOP using the rmic compiler with the -iiop option.

Summary of differences in server development
There are a number of differences in server development.
v Import statement:
import javax.rmi.PortableRemoteObject;

v Implementation class of a remote object:
public class SampleImpl extends PortableRemoteObject implements Sample

v Name registration of a remote object:
NamingContext.rebind("Sample",ObjRef);

v Generate a tie for IIOP using the command:
rmic -iiop

v Run tnameserv as a name server.
v Generate IDL for CORBA clients using the command:
rmic -idl

Summary of differences in client development
There are a number of differences in client development.
v Import statement:
import javax.rmi.PortableRemoteObject;

v Identify a remote object by name:
Object obj = ctx.lookup("Sample")
MyObject myobj = (MyObject)PortableRemoteObject.narrow(obj,MyObject.class);

v Generate a stub for IIOP using the command:
rmic -iiop

50

IBM SDK for Java: Diagnostics Guide

Using the ORB
To use the Object Request Broker (ORB) effectively, you must understand the
properties that the ORB contains. These properties change the behavior of the ORB.
The property values are listed as follows. All property values are specified as
strings.
v com.ibm.CORBA.AcceptTimeout: (range: 0 through 5000) (default: 0=infinite
timeout)
The maximum number of milliseconds for which the ServerSocket waits in a call
to accept(). If this property is not set, the default 0 is used. If it is not valid,
5000 is used.
v com.ibm.CORBA.AllowUserInterrupt:
Set this property to true so that you can call Thread.interrupt() on a thread
that is currently involved in a remote method call. The result is to stop that
thread waiting for the call to return. Interrupting a call in this way causes a
RemoteException to be thrown, containing a CORBA.NO_RESPONSE runtime
exception with the RESPONSE_INTERRUPTED minor code.
If this property is not set, the default behavior is to ignore any Thread.interrupt()
received while waiting for a call to finish.
v com.ibm.CORBA.ConnectTimeout: (range: 0 through 300) (default: 0=infinite
timeout)
The maximum number of seconds that the ORB waits when opening a
connection to another ORB. By default, no timeout is specified.
v com.ibm.CORBA.BootstrapHost:
The value of this property is a string. This string can be the host name or the IP
address of the host, such as 9.5.88.112. If this property is not set, the local host is
retrieved by calling one of the following methods:
– For applications: InetAddress.getLocalHost().getHostAddress()
– For applets: .getCodeBase().getHost()
The host name is the name of the system on which the initial server contact for
this client is installed.
Note: This property is deprecated. It is replaced by -ORBInitRef and
-ORBDefaultInitRef.
v com.ibm.CORBA.BootstrapPort: (range: 0 through 2147483647=Java max int)
(default: 2809)
The port of the system on which the initial server contact for this client is
listening.
Note: This property is deprecated. It is replaced by -ORBInitRef and
-ORBDefaultInitRef.
v com.ibm.CORBA.BufferSize: (range: 0 through 2147483647=Java max int)
(default: 2048)
The number of bytes of a General Inter-ORB Protocol (GIOP) message that is
read from a socket on the first attempt. A larger buffer size increases the
probability of reading the whole message in one attempt. Such an action might
improve performance. The minimum size used is 24 bytes.
v com.ibm.CORBA.ConnectionMultiplicity: (range: 0 through 2147483647)
(default: 1)

Chapter 7. The ORB

51

Setting this value to a number n greater than one causes a client ORB to
multiplex communications to each server ORB. There can be no more than n
concurrent sockets to each server ORB at any one time. This value might
increase throughput under certain circumstances, particularly when a
long-running, multithreaded process is acting as a client. The number of parallel
connections can never exceed the number of requesting threads. The number of
concurrent threads is therefore a sensible upper limit for this property.
v com.ibm.CORBA.enableLocateRequest: (default: false)
If this property is set, the ORB sends a LocateRequest before the actual Request.
v com.ibm.CORBA.FragmentSize: (range: 0 through 2147483647=Java max int)
(default:1024)
Controls GIOP 1.2 fragmentation. The size specified is rounded down to the
nearest multiple of 8, with a minimum size of 64 bytes. You can disable message
fragmentation by setting the value to 0.
v com.ibm.CORBA.FragmentTimeout: (range: 0 through 600000 ms) (default:
300000)
The maximum length of time for which the ORB waits for second and
subsequent message fragments before timing out. Set this property to 0 if
timeout is not required.
v com.ibm.CORBA.GIOPAddressingDisposition: (range: 0 through 2) (default: 0)
When a GIOP 1.2 Request, LocateRequest, Reply, or LocateReply is created, the
addressing disposition is set depending on the value of this property:
– 0 = Object Key
– 1 = GIOP Profile
– 2 = full IOR
If this property is not set or is passed an invalid value, the default 0 is used.
v com.ibm.CORBA.InitialReferencesURL:
The format of the value of this property is a correctly formed URL; for example,
http://w3.mycorp.com/InitRefs.file. The actual file contains a name and value
pair like: NameService=. If you specify this property, the ORB
does not attempt the bootstrap approach. Use this property if you do not have a
bootstrap server and want to have a file on the webserver that serves the
purpose.
Note: This property is deprecated.
v com.ibm.CORBA.ListenerPort: (range: 0 through 2147483647=Java max int)
(default: next available system assigned port number)
The port on which this server listens for incoming requests. If this property is
specified, the ORB starts to listen during ORB.init().
v com.ibm.CORBA.LocalHost:
The value of this property is a string. This string can be a host name or the IP
address (ex. 9.5.88.112). If this property is not set, retrieve the local host by
calling: InetAddress.getLocalHost().getHostAddress(). This property represents
the host name (or IP address) of the system on which the ORB is running. The
local host name is used by the server-side ORB to place the host name of the
server into the IOR of a remote-able object.
v com.ibm.CORBA.LocateRequestTimeout: (range: 0 through 2147483647)
(default: 0=infinity)
Defines the number of seconds to wait before timing out on a LocateRequest
message.

52

IBM SDK for Java: Diagnostics Guide

v com.ibm.CORBA.MaxOpenConnections: (range: 0 through 2147483647) (default:
240)
Determines the maximum number of in-use connections that are to be kept in
the connection cache table at any one time.
v com.ibm.CORBA.MinOpenConnections: (range: 0 through 2147483647) (default:
100)

v

v
v

v

v

The ORB cleans up only connections that are not busy from the connection cache
table, if the size is of the table is higher than the MinOpenConnections.
com.ibm.CORBA.NoLocalInterceptors: (default: false)
If this property is set to true, no local portable interceptors are used. The
expected result is improved performance if interceptors are not required when
connecting to a co-located object.
com.ibm.CORBA.ORBCharEncoding: (default: ISO8859_1)
Specifies the native encoding set used by the ORB for character data.
com.ibm.CORBA.ORBWCharDefault: (default: UCS2)
Indicates that wchar code set UCS2 is to be used with other ORBs that do not
publish a wchar code set.
com.ibm.CORBA.RequestTimeout: (range: 0 through 2147483647) (default:
0=infinity)
Defines the number of seconds to wait before timing out on a Request message.
com.ibm.CORBA.SendingContextRunTimeSupported: (default: true)
Set this property to false to disable the CodeBase SendingContext RunTime
service. This means that the ORB does not attach a SendingContextRunTime
service context to outgoing messages.

v com.ibm.CORBA.SendVersionIdentifier: (default: false)
Tells the ORB to send an initial dummy request before it starts to send any real
requests to a remote server. This action determines the partner version of the
remote server ORB, based on the response from that ORB.
v com.ibm.CORBA.ServerSocketQueueDepth: (range: 50 through 2147483647)
(default: 0)
The maximum queue length for incoming connection indications. A connect
indication is a request to connect. If a connection indication arrives when the
queue is full, the connection is refused. If the property is not set, the default 0 is
used. If the property is not valid, 50 is used.
v com.ibm.CORBA.ShortExceptionDetails: (default: false)
When a CORBA SystemException reply is created, the ORB, by default, includes
the Java stack trace of the exception in an associated ExceptionDetailMessage
service context. If you set this property to any value, the ORB includes a
toString of the Exception instead.
v com.ibm.tools.rmic.iiop.Debug: (default: false)
The rmic tool automatically creates import statements in the classes that it
generates. If set to true, this property causes rmic to report the mappings of fully
qualified class names to short names.
v com.ibm.tools.rmic.iiop.SkipImports: (default: false)
If this property is set to true, classes are generated with rmic using fully
qualified names only.
v org.omg.CORBA.ORBId
Uniquely identifies an ORB in its address space. For example, the address space
might be the server containing the ORB. The ID can be any String. The default
value is a randomly generated number that is unique in the JVM of the ORB.
Chapter 7. The ORB

53

v org.omg.CORBA.ORBListenEndpoints
Identifies the set of endpoints on which the ORB listens for requests. Each
endpoint consists of a host name or IP address, and optionally a port. The value
you specify is a string of the form hostname:portnumber, where the :portnumber
component is optional. IPv6 addresses must be surrounded by square brackets
(for example, [::1]:1020). Specify multiple endpoints in a comma-separated list.
Note: Some versions of the ORB support only the first endpoint in a multiple
endpoint list.
If this property is not set, the port number is set to 0 and the host address is
retrieved by calling InetAddress.getLocalHost().getHostAddress(). If you
specify only the host address, the port number is set to 0. If you want to set only
the port number, you must also specify the host. You can specify the host name
as the default host name of the ORB. The default host name is localhost.
v org.omg.CORBA.ORBServerId
Assign the same value for this property to all ORBs contained in the same
server. It is included in all IORs exported by the server. The integer value is in
the range 0 - 2147483647).
This table shows the Java properties defined by Sun Microsystems Inc. that are
now deprecated, and the IBM properties that have replaced them. These properties
are not OMG standard properties, despite their names:
Sun Microsystems Inc. property

IBM property

com.sun.CORBA.ORBServerHost

com.ibm.CORBA.LocalHost

com.sun.CORBA.ORBServerPort

com.ibm.CORBA.ListenerPort

org.omg.CORBA.ORBInitialHost

com.ibm.CORBA.BootstrapHost

org.omg.CORBA.ORBInitialPort

com.ibm.CORBA.BootstrapPort

org.omg.CORBA.ORBInitialServices

com.ibm.CORBA.InitialReferencesURL

How the ORB works
This description tells you how the ORB works, by explaining what the ORB does
transparently for the client. An important part of the work is performed by the
server side of the ORB.
This section describes a basic, typical RMI-IIOP session in which a client accesses a
remote object on a server. The access is made possible through an interface named
Sample. The client calls a simple method provided through the interface. The
method is called message(). The method returns a “Hello World” string. For
further examples, see “Examples of client–server applications” on page 45.

The client side
There are several steps to perform in order to enable an application client to use
the ORB.
The subjects discussed here are:
v “Stub creation” on page 55
v “ORB initialization” on page 55
v “Obtaining the remote object” on page 56
v “Remote method invocation” on page 57

54

IBM SDK for Java: Diagnostics Guide

Stub creation
For any distributed application, the client must know what object it is going to
contact, and which method of this object it must call. Because the ORB is a general
framework, you must give it general information about the method that you want
to call.
You provide the connection information by implementing a Java interface, for
example Sample. The interface contains basic information about the methods that
can be called in the remote object.

RMI
Java
client

RMI Java interface
(Sample.java)

Stub_Sample_Stub.java

rmic-iiop

RMI
Java
server

TIE_Sample_Tie.java

IIOP
ORB

ORB

The client relies on the existence of a server containing an object that implements
the Sample interface. You create a proxy object that is available on the client side
for the client application to use. The proxy object is called a stub. The stub that acts
as an interface between the client application and the ORB.
To create the stub, run the RMIC compiler on the Java interface:
rmic -iiop Sample

This command generates a file and object named _Sample_Stub.class.
The presence of a stub is not always mandatory for a client application to operate.
When you use particular CORBA features such as the Dynamic Invocation
Interface (DII), you do not require a stub. The reason is that the proxy code is
implemented directly by the client application. You can also upload a stub from
the server to which you are trying to connect. See the CORBA specification for
further details.

ORB initialization
In a stand-alone Java application, the client must create an instance of the ORB.
The ORB instance is created by calling the static method init(...). For example:
ORB orb = ORB.init(args,props);

The parameters that are passed to the method are:
v A string array containing property-value pairs.
v A Java Properties object.
A similar method is used for an applet. The difference is that a Java Applet is
passed instead of the string array.
Chapter 7. The ORB

55

The first step of ORB initialization is to process the ORB properties. The properties
are found by searching in the following sequence:
1. First, check in the applet parameter, or application string array.
2. Check in the properties parameter, if the parameter exists.
3. Check in the system properties.
4. Check in any orb.properties file that is found in the  directory.
5. Check in any orb.properties file that is found in the /lib
directory.
6. Finally, use hardcoded default behavior.
Two important properties are ORBClass and ORBSingletonClass. These properties
determine which ORB class is created and initialized, or “instantiated”.
After the ORB is instantiated, it starts and initializes the TCP transport layer. If the
ListenerPort property was set, the ORB also opens a server socket to listen for
incoming requests. The ListenerPort property is used by a server-side ORB. At the
end of the initialization performed by the init() method, the ORB is fully functional
and ready to support the client application.

Obtaining the remote object
Several methods exist by which the client can get a reference for the remote object.
Typically, this reference is a string, called an Interoperable Object Reference (IOR).
For example:
IOR:000000000000001d524d493a5......

This reference contains all the information required to find the remote object. It
also contains some details of the server settings to which the object belongs.
The client ORB does not have to understand the details of the IOR. The IOR is
used as a reference to the remote object, like a key. However, when client and
server are both using an IBM ORB, extra features are coded in the IOR. For
example, the IBM ORB adds a proprietary field into the IOR, called
IBM_PARTNER_VERSION. This field holds a value like the following example:
49424d0a 00000008 00000000 1400 0005

In the example:
v The three initial bytes counting from left to right are the ASCII code for IBM
v The next byte is 0x0A, which specifies that the following bytes provide
information about the partner version.
v The next 4 bytes encode the length of the remaining data. In this example, the
remaining data is 8 bytes long.
v The next 4 null bytes are reserved for future use.
v The next 2 bytes are for the Partner Version Major field. In this example, the
value is 0x1400, which means that release 1.4.0 of the ORB is being used.
v The final 2 bytes in this example have the value 0x0005 and represent the Minor
field. This field is used to distinguish service refreshes within the same release.
The service refreshes contain changes that affect compatibility with earlier
versions.
The final step is called the “bootstrap process”. This step is where the client
application tells the ORB where the remote object reference is located. The step is
necessary for two reasons:

56

IBM SDK for Java: Diagnostics Guide

v The IOR is not visible to application-level ORB programmers.
v The client ORB does not know where to look for the IOR.
A typical example of the bootstrap process takes place when you use a naming
service. First, the client calls the ORB method
resolve_initial_references("NameService"). The method which returns a reference to
the name server. The reference is in the form of a NamingContext object. The ORB
then looks for a corresponding name server in the local system at the default port
2809. If no name server exists, or the name server cannot be found because it is
listening on another port, the ORB returns an exception. The client application can
specify a different host, a different port, or both, by using the -ORBInitRef and
-ORBInitPort options.
Using the NamingContext and the name with which the Remote Object has been
bound in the name service, the client can retrieve a reference to the remote object.
The reference to the remote object that the client holds is always an instance of a
Stub object; for example _Sample_Stub.
Using ORB.resolve_initial_references() causes much system activity. The ORB
starts by creating a remote communication with the name server. This
communication might include several requests and replies. Typically, the client
ORB first checks whether a name server is listening. Next, the client ORB asks for
the specified remote reference. In an application where performance is important,
caching the remote reference is preferable to repetitive use of the naming service.
However, because the naming service implementation is a transient type, the
validity of the cached reference is limited to the time in which the naming service
is running.
The IBM ORB implements an Interoperable Naming Service as described in the
CORBA 2.3 specification. This service includes a new string format that can be
passed as a parameter to the ORB methods string_to_object() and
resolve_initial_references(). The methods are called with a string parameter that
has a corbaloc (or corbaname) format. For example:
corbaloc:iiop:1.0@aserver.aworld.aorg:1050/AService

In this example, the client ORB uses GIOP 1.0 to send a request with a simple
object key of AService to port 1050 at host aserver.aworld.aorg. There, the client
ORB expects to find a server for the requested Aservice. The server replies by
returning a reference to itself. You can then use this reference to look for the
remote object.
This naming service is transient. It means that the validity of the contained
references expires when the name service or the server for the remote object is
stopped.

Remote method invocation
The client holds a reference to the remote object that is an instance of the stub
class. The next step is to call the method on that reference. The stub implements
the Sample interface and therefore contains the message() method that the client
has called.
First, the stub code determines whether the implementation of the remote object is
located on the same ORB instance. If so, the object can be accessed without using
the Internet.

Chapter 7. The ORB

57

If the implementation of the remote object is located on the same ORB instance, the
performance improvement can be significant because a direct call to the object
implementation is done. If no local servant can be found, the stub first asks the
ORB to create a request by calling the _request() method, specifying the name of
the method to call and whether a reply is expected or not.
The CORBA specification imposes an extra layer of indirection between the ORB
code and the stub. This layer is commonly known as delegation. CORBA imposes
the layer using an interface named Delegate. This interface specifies a portable API
for ORB-vendor-specific implementation of the org.omg.CORBA.Object methods.
Each stub contains a delegate object, to which all org.omg.CORBA.Object method
invocations are forwarded. Using the delegate object means that a stub generated
by the ORB from one vendor is able to work with the delegate from the ORB of
another vendor.
When creating a request, the ORB first checks whether the enableLocateRequest
property is set to true, in which case, a LocateRequest is created. The steps of
creating this request are like the full Request case.
The ORB obtains the IOR of the remote object (the one that was retrieved by a
naming service, for example) and passes the information that is contained in the
IOR (Profile object) to the transport layer.
The transport layer uses the information that is in the IOR (IP address, port
number, and object key) to create a connection if it does not exist. The ORB
TCP/IP transport has an implementation of a table of cached connections for
improving performances, because the creation of a new connection is a
time-consuming process. The connection is not an open communication channel to
the server host. It is only an object that has the potential to create and deliver a
TCP/IP message to a location on the Internet. Typically, that involves the creation
of a Java socket and a reader thread that is ready to intercept the server reply. The
ORB.connect() method is called as part of this process.
When the ORB has the connection, it proceeds to create the Request message. The
message contains the header and the body of the request. The CORBA 2.3
specification specifies the exact format. The header contains these items:
v Local IP address
v Local port
v Remote IP address
v Remote port
v Message size
v Version of the CORBA stream format
v Byte sequence convention
v Request types
v IDs
See Chapter 17, “ORB problem determination,” on page 193 for a detailed
description and example.
The body of the request contains several service contexts and the name and
parameters of the method invocation. Parameters are typically serialized.
A service context is some extra information that the ORB includes in the request or
reply, to add several other functions. CORBA defines a few service contexts, such

58

IBM SDK for Java: Diagnostics Guide

as the codebase and the codeset service contexts. The first is used for the callback
feature which is described in the CORBA specification. The second context is used
to specify the encoding of strings.
In the next step, the stub calls _invoke(). The effect is to run the delegate invoke()
method. The ORB in this chain of events calls the send() method on the connection
that writes the request to the socket buffer and then flushes it away. The delegate
invoke() method waits for a reply to arrive. The reader thread that was spun
during the connection creation gets the reply message, processes it, and returns the
correct object.

The server side
In ORB terminology, a server is an application that makes one of its implemented
objects available through an ORB instance.
The subjects discussed here are:
v “Servant implementation”
v “Tie generation”
v “Servant binding”
v “Processing a request” on page 60

Servant implementation
The implementations of the remote object can either inherit from
javax.rmi.PortableRemoteObject, or implement a remote interface and use the
exportObject() method to register themselves as a servant object. In both cases, the
servant has to implement the Sample interface. Here, the first case is described.
From now, the servant is called SampleImpl.

Tie generation
You must put an interfacing layer between the servant and the ORB code. In the
old RMI (JRMP) naming convention, skeleton was the name given to the proxy that
was used on the server side between ORB and the object implementation. In the
RMI-IIOP convention, the proxy is called a Tie.
You generate the RMI-IIOP tie class at the same time as the stub, by calling the
rmic compiler. These classes are generated from the compiled Java programming
language classes that contain remote object implementations. For example, the
command:
rmic -iiop SampleImpl

generates the stub _Sample_Stub.class and the tie _Sample_Tie.class.

Servant binding
The steps required to bind the servant are described.
The server implementation is required to do the following tasks:
1. Create an ORB instance; that is, ORB.init(...)
2. Create a servant instance; that is, new SampleImpl(...)
3. Create a Tie instance from the servant instance; that is, Util.getTie(...)
4. Export the servant by binding it to a naming service
As described for the client side, you must create the ORB instance by calling the
ORB static method init(...). The typical steps performed by the init(...) method are:
Chapter 7. The ORB

59

1.
2.
3.
4.

Retrieve properties
Get the system class loader
Load and instantiate the ORB class as specified in the ORBClass property
Initialize the ORB as determined by the properties

Next, the server must create an instance of the servant class SampleImpl.class.
Something more than the creation of an instance of a class happens under the
cover. Remember that the servant SampleImpl extends the PortableRemoteObject
class, so the constructor of PortableRemoteObject is called. This constructor calls
the static method exportObject(...) with the parameter that is the same servant
instance that you try to instantiate. If the servant does not inherit from
PortableRemoteObject, the application must call exportObject() directly.
The exportObject() method first tries to load an RMI-IIOP tie. The ORB implements
a cache of classes of ties for improving performance. If a tie class is not already
cached, the ORB loads a tie class for the servant. If it cannot find one, it goes up
the inheritance tree, trying to load the parent class ties. The ORB stops if it finds a
PortableRemoteObject class or the java.lang.Object, and returns a null value.
Otherwise, it returns an instance of that tie from a hashtable that pairs a tie with
its servant. If the ORB cannot find the tie, it assumes that an RMI (JRMP) skeleton
might be present and calls the exportObject() method of the UnicastRemoteObject
class. A null tie is registered in the cache and an exception is thrown. The servant
is now ready to receive remote methods invocations. However, it is not yet
reachable.
In the next step, the server code must find the tie itself (assuming the ORB has
already got hold of the tie) to be able to export it to a naming service. To do that,
the server passes the newly created instance of the servant into the static method
javax.rmi.CORBA.Util.getTie(). This method, in turn, gets the tie that is in the
hashtable that the ORB created. The tie contains the pair of tie-servant classes.
When in possession of the tie, the server must get hold of a reference for the
naming service and bind the tie to it. As in the client side, the server calls the ORB
method resolve_initial_references("NameService"). The server then creates a
NameComponent, which is a directory tree object identifying the path and the
name of the remote object reference in the naming service. The server binds the
NameComponent together with the tie. The naming service then makes the IOR for
the servant available to anyone requesting. During this process, the server code
sends a LocateRequest to get hold of the naming server address. It also sends a
Request that requires a rebind operation to the naming server.

Processing a request
The server ORB uses a single listener thread, and a reader thread for each
connection or client, to process an incoming message.
During the ORB initialization, a listener thread was created. The listener thread is
listening on a default port (the next available port at the time the thread was
created). You can specify the listener port by using the
com.ibm.CORBA.ListenerPort property. When a request comes in through that
port, the listener thread first creates a connection with the client side. In this case,
it is the TCP transport layer that takes care of the details of the connection. The
ORB caches all the connections that it creates.

60

IBM SDK for Java: Diagnostics Guide

By using the connection, the listener thread creates a reader thread to process the
incoming message. When dealing with multiple clients, the server ORB has a
single listener thread and one reader thread for each connection or client.
The reader thread does not fully read the request message, but instead creates an
input stream for the message to be piped into. Then, the reader thread picks up
one of the worker threads in the implemented pool, or creates one if none is
present. The work thread is given the task of reading the message. The worker
thread reads all the fields in the message and dispatches them to the tie. The tie
identifies any parameters, then calls the remote method.
The service contexts are then created and written to the response output stream
with the return value. The reply is sent back with a similar mechanism, as
described in the client side. Finally, the connection is removed from the reader
thread which stops.

Additional features of the ORB
Portable object adapter, fragmentation, portable interceptors, and Interoperable
Naming Service are described.
This section describes:
v
v
v
v

“Portable object adapter”
“Fragmentation” on page 63
“Portable interceptors” on page 63
“Interoperable Naming Service (INS)” on page 66

Portable object adapter
An object adapter is the primary way for an object to access ORB services such as
object reference generation. A portable object adapter exports standard interfaces to
the object.
The main responsibilities of an object adapter are:
v Generation and interpretation of object references.
v Enabling method calling.
v Object and implementation activation and deactivation.
v Mapping object references to the corresponding object implementations.

Chapter 7. The ORB

61

For CORBA 2.1 and earlier, all ORB vendors implemented an object adapter, which
was known as the basic object adapter. A basic object adapter could not be
specified with a standard CORBA IDL. Therefore, vendors implemented the
adapters in many different ways. The result was that programmers were not able
to write server implementations that were truly portable between different ORB
products. A first attempt to define a standard object adapter interface was done in
CORBA 2.1. With CORBA v.2.3, the OMG group released the final corrected
version of a standard interface for the object adapter. This adapter is known as the
Portable Object Adapter (POA).
Some of the main features of the POA specification are to:
v Allow programmers to construct object and server implementations that are
portable between different ORB products.
v Provide support for persistent objects. The support enables objects to persist
across several server lifetimes.
v Support transparent activation of objects.
v Associate policy information with objects.
v Allow multiple distinct instances of the POA to exist in one ORB.
For more details of the POA, see the CORBA v.2.3 (formal/99-10-07) specification.
From IBM SDK for Java v1.4, the ORB supports both the POA specification and the
proprietary basic object adapter that is already present in previous IBM ORB
versions. By default, the RMI compiler, when used with the -iiop option, generates
RMI-IIOP ties for servers. These ties are based on the basic object adapter. When a
server implementation uses the POA interface, you must add the -poa option to
the rmic compiler to generate the relevant ties.
To implement an object using the POA, the server application must obtain a POA
object. When the server application calls the ORB method
resolve_initial_reference("RootPOA"), the ORB returns the reference to the main
POA object that contains default policies. For a list of all the POA policies, see the
CORBA specification. You can create new POAs as child objects of the RootPOA.
These child objects can contain different policies. This structure allows you to
manage different sets of objects separately, and to partition the namespace of
objects IDs.
Ultimately, a POA handles Object IDs and active servants. An active servant is a
programming object that exists in memory. The servant is registered with the POA
because one or more associated object identities was used. The ORB and POA
cooperate to determine which servant starts the operation requested by the client.
By using the POA APIs, you can create a reference for the object, associate an
object ID, and activate the servant for that object. A map of object IDs and active
servants is stored inside the POA. A POA also provides a default servant that is
used when no active servant has been registered. You can register a particular
implementation of this default servant. You can also register a servant manager,
which is an object for managing the association of an object ID with a particular
servant.

62

IBM SDK for Java: Diagnostics Guide

RootPOA

POA Child1

Object ID

Default servant

User-supplied
servant

POA
manager

Object ID

User-supplied servant

Object ID

User-supplied servant

Object ID

User-supplied servant

Adapter activator
The POA manager is an object that encapsulates the processing state of one or
more POAs. You can control and change the state of all POAs by using operations
on the POA manager.
The adapter activator is an object that an application developer uses to activate
child POAs.

Fragmentation
The CORBA specification introduced the concept of fragmentation to handle the
growing complexity and size of marshalled objects in GIOP messages. Graphs of
objects are linearized and serialized inside a GIOP message under the IDL
specification of valuetypes. Fragmentation specifies the way a message can be split
into several smaller messages (fragments) and sent over the net.
The system administrator can set the ORB properties FragmentSize and
FragmentTimeout to obtain best performance in the existing net traffic. As a
general rule, the default value of 1024 bytes for the fragment size is a good
trade-off in almost all conditions. The fragment timeout must not be set to too low
a value, or time-outs might occur unnecessarily.

Portable interceptors
You can include “interceptor” code in the ORB processing flow. The CORBA 2.4.2
specification standardizes this code mechanism under the name “portable
interceptor”.
CORBA implementations have mechanisms for users to insert their own code into
the ORB processing flow. The code is inserted into the flow at “interception
points”. The result is that the code, known as an interceptor, is called at particular
stages during the processing of requests. It can directly inspect and even
manipulate requests. Because this message filtering mechanism is flexible and
powerful, the OMG standardized interceptors in the CORBA 2.4.2 specification
under the name “portable interceptors”.
The idea of a portable interceptor is to define a standard interface. The interface
enables you to register and run application-independent code that, among other
things, takes care of passing service contexts. These interfaces are stored in the

Chapter 7. The ORB

63

package org.omg.PortableInterceptor.*. The implementation classes are in the
com.ibm.rmi.pi.* package of the IBM ORB. All the interceptors implement the
Interceptor interface.
Two classes of interceptors are defined:
Request interceptors
The ORB calls request interceptors on the client and the server side, during
request mediation. Request interceptors manipulate service context
information.
Interoperable Object Reference (IOR) interceptors
IOR interceptors are called when new object references are created. The
reason is that service-specific data, in the form of tagged components, can
be added to the newly created IOR.
Interceptors must register with the ORB for the interception points where they are
to run.
Five interception points are available on the client side:
v send_request(sending request)
v send_poll(sending request)
v receive_reply(receiving reply)
v receive_exception(receiving reply)
v receive_other(receiving reply)
Five interception points are available on the server side:
v
v
v
v

receive_request_service_contexts(receiving request)
receive_request(receiving request)
send_reply(sending reply)
send_exception(sending reply)

v send_other(sending reply)
The only interception point for IOR interceptors is establish_component(). The ORB
calls this interception point on all its registered IOR interceptors when it is
assembling the set of components that is to be included in the IOP profiles for a
new object reference.
A simple interceptor is shown in the following example:
public class MyInterceptor extends org.omg.CORBA.LocalObject
implements ClientRequestInterceptor, ServerRequestInterceptor
{
public String name() {
return "MyInterceptor";
}
public void destroy() {}
// ClientRequestInterceptor operations
public void send_request(ClientRequestInfo ri) {
logger(ri, "send_request");
}
public void send_poll(ClientRequestInfo ri) {
logger(ri, "send_poll");
}

64

IBM SDK for Java: Diagnostics Guide

public void receive_reply(ClientRequestInfo ri) {
logger(ri, "receive_reply");
}
public void receive_exception(ClientRequestInfo ri) {
logger(ri, "receive_exception");
}
public void receive_other(ClientRequestInfo ri) {
logger(ri, "receive_other");
}
// Server interceptor methods
public void receive_request_service_contexts(ServerRequestInfo ri) {
logger(ri, "receive_request_service_contexts");
}
public void receive_request(ServerRequestInfo ri) {
logger(ri, "receive_request");
}
public void send_reply(ServerRequestInfo ri) {
logger(ri, "send_reply");
}
public void send_exception(ServerRequestInfo ri) {
logger(ri, "send_exception");
}
public void send_other(ServerRequestInfo ri) {
logger(ri, "send_other");
}
// Trivial Logger
public void logger(RequestInfo ri, String point) {
System.out.println("Request ID:" + ri.request_id()
+ " at " + name() + "." + point);
}
}

The interceptor class extends org.omg.CORBA.LocalObject. The extension ensures
that an instance of this class does not get marshaled, because an interceptor
instance is tied to the ORB with which it is registered. This example interceptor
prints out a message at every interception point.
You cannot register an interceptor with an ORB instance after it has been created.
The reason is that interceptors are a means for ORB services to interact with ORB
processing. Therefore, by the time the init() method call on the ORB class returns
an ORB instance, the interceptors must already be registered. Otherwise, the
interceptors are not part of the ORB processing flow.
You register an interceptor by using an ORB initializer. First, you create a class that
implements the ORBInitializer interface. This class is called by the ORB during its
initialization.
public class MyInterceptorORBInitializer extends LocalObject
implements ORBInitializer
{
public static MyInterceptor interceptor;
public String name() {
return "";
}
public void pre_init(ORBInitInfo info) {
Chapter 7. The ORB

65

try {
interceptor = new MyInterceptor();
info.add_client_request_interceptor(interceptor);
info.add_server_request_interceptor(interceptor);
} catch (Exception ex) {}
}
public void post_init(ORBInitInfo info) {}
}

Then, in the server implementation, add the following code:
Properties p = new Properties();
p.put("org.omg.PortableInterceptor.ORBInitializerClass.pi.MyInterceptorORBInitializer", "");
...
orb = ORB.init((String[])null, p);

During the ORB initialization, the ORB run time code obtains the ORB properties
with names that begin with org.omg.PortableInterceptor.ORBInitializerClass. The
remaining portion of the name is extracted, and the corresponding class is
instantiated. Then, the pre_init() and post_init() methods are called on the
initializer object.

Interoperable Naming Service (INS)
The CORBA “CosNaming” Service follows the Object Management Group (OMG)
Interoperable Naming Service specification (INS, CORBA 2.3 specification).
CosNaming stands for Common Object Services Naming.
The name service maps names to CORBA object references. Object references are
stored in the namespace by name and each object reference-name pair is called a
name binding. Name bindings can be organized under naming contexts. Naming
contexts are themselves name bindings, and serve the same organizational function
as a file system subdirectory does. All bindings are stored under the initial naming
context. The initial naming context is the only persistent binding in the namespace.
This implementation includes string formats that can be passed as a parameter to
the ORB methods string_to_object() and resolve_initial_references(). The formats
are corbaname and corbaloc.
Corbaloc URIs allow you to specify object references that can be contacted by IIOP
or found through ORB::resolve_initial_references(). This format is easier to
manipulate than IOR. To specify an IIOP object reference, use a URI of the form:
corbaloc:iiop::/