Example

This Java program lists files from the current directory and tells you if they exist. It demonstrates that when Java encounters a file with a problematic name it does report it in listFiles, but any further operations on the file fail.

import java.io.File;
import java.io.IOException;

class Ls {
    public static void main(String[] args) throws IOException {
        File d = new File(".");
        for (File f : d.listFiles()) {
            System.out.printf("%s: %b\n", f.getName(), f.exists());
        }
    }
}

For example, when it encounters a file with a name encoded in latin1, this is what happens:

$ ls -b
ni\361o
$ java Ls
ni�: false

You can download Ls.java with an example file here.

Setting the default character encoding

You probably know that Java uses a “default character encoding” to convert binary data to Strings. To read or write text using another encoding you can use an InputStreamReader or OutputStreamWriter. But for data-to-text conversions deep in the API you have no choice but to change the default encoding.

Java reads the default character encoding from the system language settings. On Unix this means LANG and LC_CTYPE environment variables; changing one of these is sufficient. For example, to make Java use latin1 you could start the JVM with the following command:

$ LANG=en_US.iso88591 java Ls
ni�o: true

Or, if you want all programs you start from the terminal to use this locale:

export LANG=en_US.iso88591

The locale en_US.iso88591 has to be installed on the system for these to work, though. You can use the following command to list locales that are available on your system.

locale -a

Defining and installing a new locale

If you don’t have a locale with the appropriate encoding installed you can define and install a new one with the localedef program. For example, to create locale with the Windows Western character encoding you could use the following command.

sudo localedef -f CP1252 -i en_US en_US.cp1252

Under this locale Java would correctly process files with all kinds of names, including those whose name contains curly quotes or the euro character €.

What about file.encoding?

The file.encoding system property can also be used to set the default character encoding that Java uses for I/O. Unfortunately it seems to have no effect on how file names are decoded into Strings.

Programming in JNI starts with defining a class with methods declared as native. Next you generate a C header file that declares functions that implement. Then you define these functions in a separate file and compile it into a shared library. In this tutorial we’ll use Linux and the GCC compiler.

Suppose we need to know the name of the terminal device from which the JVM was launched. (A slightly silly example since you could just use /dev/tty.) From C you would do this by calling the POSIX functions isatty and ttyname. Let’s make a class that gives us access to them:

package ex;
public class TTYUtil {
    static { System.loadLibrary("ttyutil"); }
    public static native boolean isTTY();
    public static native String getTTYName();
}

The call to System.loadLibrary in the class initializer looks for a shared library and links it to the JVM. The file name depends on the operating system: on Windows this code would look for ttyutil.dll, on Linux and Solaris libttyutil.so.

The next step is compiling the Java code and generating the C header file:

$ javac ex/TTYUtil.java
$ javah ex.TTYUtil

The javah tool will create a C header file called ex_TTYUtil.h. This file contains the declarations for the C functions we have to define:

JNIEXPORT jboolean JNICALL Java_ex_TTYUtil_isTTY
  (JNIEnv *, jclass);

JNIEXPORT jstring JNICALL Java_ex_TTYUtil_getTTYName
  (JNIEnv *, jclass);

The idea is that the header file should be generated automatically during the build process so you should not modify it manually. If you need other declarations or #include statements you should use a different file.

Create ex_TTYUtil.c to define the C functions:

#include "ex_TTYUtil.h"
#include <unistd.h>

JNIEXPORT jstring JNICALL Java_ex_TTYUtil_getTTYName
  (JNIEnv *env, jclass cls)
{
    char *name = ttyname(STDOUT_FILENO);
    return (*env)->NewStringUTF(env, name);
}

JNIEXPORT jboolean JNICALL Java_ex_TTYUtil_isTTY
  (JNIEnv *env, jclass cls)
{
    return isatty(STDOUT_FILENO)? JNI_TRUE: JNI_FALSE;
}

These functions receive the JNI environment object as the first argument. The second argument is the class for static native methods and the object for non-static methods. The rest of the arguments, if any, are the method arguments from Java. The JNI environment is used for interacting with the virtual machine, like here the NewStringUTF function is used to create a new Java String object from a C string.

To compile and link the C code you can use:

$ gcc -fPIC -c ex_TTYUtil.c -I $JAVA_HOME/include
$ gcc ex_TTYUtil.o -shared -o libttyutil.so -Wl,-soname,ttyutil

Now you should have libttyutil.so in your working directory. Let’s try using the library.

import ex.TTYUtil;
public class Test {
    public static void main(String[] args) {
        if (TTYUtil.isTTY()) {
            System.out.println("TTY: "+TTYUtil.getTTYName());
        } else {
            System.out.println("Not a TTY");
        }
    }
}

Compile this class like you normally would and then run it:

$ export LD_LIBRARY_PATH=.
$ java Test
TTY: /dev/pts/3

And what if the output is not connected to a terminal?

$ java Test | cat
Not a TTY

The JVM looks for native libraries in the paths specified in the system property java.library.path in addition to what’s normal for the operating system. Here we made the shared library available to the JVM temporarily by adding the current directory to LD_LIBRARY_PATH. To permanently install a shared library on Linux you would copy the .so to /usr/lib (or any other directory mentioned in /etc/ld.so.conf) and then run ldconfig.

The problem is that these programs need to communicate with a TTY (teletypewriter) device to find the screen size and to be able to write anywhere on the terminal window. You don’t notice this when using them from a terminal because the shell sets up their stdin and stdout so they are connected to the terminal.

When you launch a program from Java using Runtime.exec the stdin and stdout are connected to pipes handled by the JVM, not to a TTY device: it is as if you tried to launch less with something like less file.txt <jvm.in >jvm.out. Needless to say that wouldn’t work even from a terminal.

What you can do is redirect the stdin and stdout streams back to the original terminal device. To find the actual TTY device we would have to call the POSIX ttyname function with JNI, but luckily that’s not necessary: we can use /dev/tty, which is the controlling terminal for the current process.

An interesting application of this is to use less as a pager to show lengthy messages to a user, like database result sets:

import java.io.OutputStream;

public class Test {
    public static void main(String[] args) throws Exception {
        Process p = Runtime.getRuntime().exec(new String[] {"sh", "-c",
                "less >/dev/tty"});
        OutputStream out = p.getOutputStream();
        out.write("Lengthy message".getBytes());
        out.close();
        System.out.println("=> "+p.waitFor());
    }
}

Object obj = new Object();
WeakReference<Object> ref = new WeakReference<Object>(obj);

List<byte[]> filler = new LinkedList<byte[]>();
while (ref.get() != null) {
    filler.add(new byte[1000]);
}
System.out.println("Filler size " + filler.size());

When executed it should always run out of memory: ref.get() will not return null because the referenced object cannot be garbage collected. The local variable obj still holds a reference to it. The filler increases in size indefinitely, and the program will ultimately crash with an OutOfMemoryError.

What really happens is this:

$ java test
Filler size 28186

Wait, what?!

It turns out that the Hotspot virtual machine analyzes the code, sees that the variable obj is not used after the while-loop, and rewrites the method while it is running so that the local variable is effectively removed. This is called OSR (On Stack Replacement) compilation in the Hotspot VM. If you added something like print(obj) after the loop you would get the expected OOME. Quoting Kris Mok in About Printcompilation:

OSR in HotSpot is used to help improve performance of Java methods stuck in loops [6]. Without OSR, a method running in the interpreter can’t transfer to its compiled version even if there is one available, until the next time this method is invoked. With OSR, though, a Java method with long-running loops can run in the interpreter, trigger an OSR compilation in one of its loops, keep running in the interpreter until the compilation completes, and jump right into the compiled version without having to wait for “the next invocation”.

The process of “jumping right into the compiled version” may sound simple but in reality is anything but. The new method body does not start from the beginning but from the “back edge” of the running loop. The stack frame created by the interpreter is replaced by the one created by the JIT compiler. It is this process that is capable of removing local variables from the method.

JLS 12.6.1 especially allows this:

Optimizing transformations of a program can be designed that reduce the number of objects that are reachable to be less than those which would naively be considered reachable. For example, a compiler or code generator may choose to set a variable or parameter that will no longer be used to null to cause the storage for such an object to be potentially reclaimable sooner.

This behaviour is really unreliable: the thresholds for compiling code depend on the hardware and VM options. If you make the filler grow faster by adding bigger arrays of bytes you get you get an OOME: you have to give the compiler enough loop iterations to be triggered.

On-Stack-Replacement can affect benchmarks in unexpected ways: the code you are running changes during the test. Cliff Click has written on this subject.

It also influences finalizers: Since obj is a local variable you would expect that its finalizer would not be called at least until after the method. But since the object is GC’d before the method ends, it is finalized as well. The lesson is you can’t depend in any way on when objects are finalized – it may be sooner than you think!

If you are wondering if you can see when OSR happens, you can use the -XX:+PrintCompilation flag:

$ java -XX:+PrintCompilation Test
    125   1       java.lang.String::hashCode (60 bytes)
    133   2       sun.nio.cs.UTF_8$Encoder::encodeArrayLoop (490 bytes)
    158   3       java.lang.String::charAt (33 bytes)
    159   4       java.lang.String::indexOf (151 bytes)
    174   5       java.lang.Object::<init> (1 bytes)
    182   6       java.util.LinkedList$Entry::<init> (20 bytes)
    183   7       java.util.LinkedList::add (12 bytes)
    185   8       java.util.LinkedList::addBefore (52 bytes)
    348   1 %     Test::main @ 25 (78 bytes)
Filler size 28082

The last line tells us that Hotspot compiled the Test.main method with OSR (the %-flag) 348ms into the execution.

(Inspired by the Stackoverflow question Are WeakHashMap Cleared During A Full GC? Thanks to berry120 and jalopaba for contributing detailed answers.)