Sunday Nov 20, 2005

Two fine demos

I was in New York last week, and attended a Java SE User Group meeting. After the scheduled talks there was open discussion on a wide range of topics. One of those topics related to tutorials, documentation, and sample code. It is always interesting to hear how people learn new APIs. Some people start with the API documentation, some google for sample code, and books continue to be popular. The JDK "demo" directory was mentioned and a number of people remarked that they hadn't checked it out in years because the demo directory appeared to be stale. There are indeed some old demos in there but there are a number of more recent examples too. Today I thought I might highlight two of the more useful examples.

The first is JTop. You'll find it in %JDK_HOME%\\demo\\management\\JTop (or $JDK_HOME/demo/management/JTop) where JDK_HOME is C:\\jdk1.6 or wherever you have installed the JDK. Mandy Chung added this demo in Mustang b59 and it will work on JDK5.0 too. There's a README.txt file in the directory which explains what it does. In brief, it monitors the CPU usage of the threads in a remote application. If you've ever had to deal with a looping process and you tried to figure out which thread is looping then you will relate to this.

In API terms, this example is a demonstration of the monitoring and management package. If the Java virtual machine is able to measure thread CPU time then getThreadCpuTime method can be used to obtain the CPU time for a thread.

To use JTop, we start the application with the JMX agent configured for remote management. For demonstration purposes both authentication and SSL are disabled (which you won't want to do in production).

        -jar Application.jar

JTop is connected by passing it the hostname and port number so that it can connect to the JMX agent:

   java -jar %JDK_HOME%\\demo\\management\\JTop\\JTop.jar localhost:7000

JTop uses a TimerTask to refresh the thread list every 2 seconds. It gets the CPU time for each thread and then sorts the list by CPU time. You should see something like this:

It is primitive but it serves as a useful demonstration of the APIs. The source is in the src directory and with a little bit of effort it could be turned into a nice tool. For example, it currently just sorts the threads by total CPU usage and it might be nicer to highlight the threads that were busy in the proceeding interval. Also, it might be interesting to sample the stack traces of the busy threads to get an idea of the code that is executing.

The second example is heapViewer. You'll find it in %JDK_HOME%\\demo\\jvmti\\heapViewer (or $JDK_HOME/demo/jvmti/heapViewer). This example has been included since JDK5.0. It's a native agent that uses the JVM Tool Interface to do some basic memory analysis. It uses IterateOverHeap to do a linear iteration over all objects in the heap. It then prints a summary in the form of a class-wise histogram to show which objects are taking up space in the heap.

The agent is an in-process agent that is started using the -agentlib or -agentpath command-line options. Here's one example:

java -agentpath:%JDK_HOME%\\demo\\jvmti\\heapViewer\\lib\\heapViewer.dll
     -jar Application.jar

When the VM exits or the agent gets a DataDumpRequest event then it will print a histogram to summarize the objects in the heap. A DataDumpRequest is triggered by a Ctrl-Break on Windows, or Ctrl-\\ (or SIGQUIT) on Solaris/Linux. Here is some sample output:

Heap View, Total of 123199 objects found.

Space      Count      Class Signature
---------- ---------- ----------------------
  19597872       7421 [I
   1420264      13037 [C
   1217872       2681 [B
   1194256       2381 Ljava/lang/Class;
    985624       3619 [S
    266688      11112 Ljava/lang/String;
    173576       4682 [Ljava/lang/Object;
    164800        824 Lsun/java2d/SunGraphics2D;
    123888       5162 Ljava/util/Hashtable$Entry;
    106560       4440 Ljava/awt/Rectangle;
     79552       2486 Ljavax/swing/text/html/parser/ContentModel;
     70816        818 [Ljava/util/Hashtable$Entry;
     67440        843 Ljavax/swing/text/html/InlineView;
     63504       2646 Ljavax/swing/SizeRequirements;
     57984        906 Ljava/awt/geom/AffineTransform;
     56600       1415 Ljava/util/WeakHashMap$Entry;
     55560       2315 Ljava/util/HashMap$Entry;
     52864        112 Ljavax/swing/plaf/metal/MetalScrollButton;
     46880       2930 Ljavax/swing/event/EventListenerList;
     45056        352 Ljavax/swing/text/html/LineView;
     44808       1867 Ljava/awt/Insets;
---------- ---------- ----------------------

In this example, there were 123199 objects in the heap, and integer arrays are taking up the most space. There are of course other ways to generate a heap histogram like this but this one is useful as it makes use of the standard APIs. The source for this example is in the src directory.

I hope you agree these are useful examples. There are a number of others in the demo/management and demo/jvmti directories which are worth checking out too.

Friday Oct 21, 2005 is finally here!

One of the most popular feature requests for J2SETM in recent times has been the request to improve console support and provide a way to enter passwords with echo disabled. Developers know this feature 4050435 as it has been skulking in the Top 25 RFEs list for some time.

The good news is that the feature has made it into Mustang thanks to Xueming Shen. It went into b57 and should show up be on the download site later today. The feature adds which provides methods to read lines and passwords from the console. It also provides useful methods to write formatted strings to the console too. Here's a little taster that prompts user to enter a password that is at least 8 characters in length. The password is not echoed to the console as it is entered.

static final int MIN_PASSWORD_LENGTH = 8;

char[] password;
do {
    password = System.console().readPassword(
      "Enter password (minimum of %d characters): ", MIN_PASSWORD_LENGTH);
} while (password.length < MIN_PASSWORD_LENGTH);

System.console() is used to obtain the unique Console for the Java virtual machine. There may not be a console of course - it depends on the platform, and also on how the Java virtual machine was started. If there isn't a console then the console() method returns null (the above code fragment doesn't check for this).

The readPassword method writes the prompt and reads the password. The prompt is provided as a format string and an argument list. If you've used the formatted printing support that was added in J2SE 5.0 then you'll recognize this.

Another thing about this code fragment is that it leaves you with a password in a character array. As with anything sensitive you don't want to have this in memory for a long time so it's good to zero the array as soon as you can.

So if you develop applications that need to access a character based console then you should find very useful (and very simple to use).

Friday Oct 14, 2005


One of the useful troubleshooting utilities in J2SETM 5.0 is jstack. It prints the stack traces of all java threads for a given process or core dump. The -m option will print a mixed-mode stack so that you can see native frames in addition to the java frames. jstack was originally created for troubleshooting problems involving hangs and crashes but developers have found it a useful utility to look at running applications too.

jstack isn't the only way to obtain a thread dump of a running application. Developers have long been accustomed to using Ctrl-\\ (or Ctrl-Break if you are on Windows) to get a thread dump of an application that is running interactively. An alternative to the key sequence on Solaris (or Linux) is to send a QUIT signal to the target process. In that case the target processs prints a thread dump to its standard output (which can be pain if you don't know where the log file is).

If you are lucky to be on Solaris 10, then yet another way to obtain a stack trace is using the the pstack utility. This has been updated in Solaris 10 so that it prints java method names for interpreted, compiled and inlined java methods. pstack prints a mixed-mode stack and the output is similar to jstack -m.

Mustang (Java SE 6.0) brings more improvements. For starters the default mode for jstack is to work a bit like a remote Ctrl-\\. This means that the output of the thread dump has changed a bit but there is more information on deadlocks and JNI Global References in additional to the thread stacks. If the VM is hung then a thread dump can still be forced using the -F option.

The second improvement is that jstack is included on Windows. It doesn't have all the features yet of the jstack utility on Solaris but it does solve a long standing requirement from developers to get a thread dump of an applications that run in the background as a Windows Service.

The third improvement is the "-l" option to print information about java.util.concurrent.locks. More specifically, it instructs the utility to look for ownable synchronizers in the heap. This should be useful for applications that make use of the concurrency APIs added in J2SE 5.0. Without the "-l" option the thread dump only includes information on monitors. One word of warning though, this option can be expensive if the heap is large.




Top Tags
« April 2014

No bookmarks in folder